contrib/ofed/management/doc/libibumad.txt

   1 libibumad:
   2
   3 Overview: libibumad provides the following functionality:
   4         * Provide information about the IB devices installed. This includes
   5                 list of IB devices names, list of port, device and port
   6                 attributes.
   7         * Basic user mode mad functions: open/close port,
   8                 register/unregister, send/receive/poll mad, etc.
   9         * Umad packet helper functions.
  10         * debugging support.
  11
  12
  13 Library objects:
  14
  15 umad_ca: encapsulate an IB device. Identified by CA_NAME.
  16
  17 umad_port: encapsulate an IB port within an IB device. Identified by CA_NAME
  18         and port number.
  19
  20 ib_umad_addr: IB destination address structure.
  21
  22 portid (int): opened port handle.
  23
  24 agentid (int): mad multiplexing agent handle.
  25
  26
  27 Module management functions:
  28
  29 umad_init:
  30
  31 Synopsis:
  32         int umad_init(void)
  33
  34 Description: library main initialization function. Must be called before any
  35 other call to the library. Return zero on success, -1 if the infiniband mad
  36 class can't be opened, or the abi version doesn't match.
  37
  38 umad_done:
  39
  40 Synopsis:
  41         int umad_done(void)
  42
  43 Description: library main destruction function. library should not be called after calling this function. Return zero on success, -1 on errors.
  44
  45
  46 IB devices and ports information functions:
  47
  48 umad_get_cas_names:
  49
  50 Synopsis:
  51         int     umad_get_cas_names(char cas[][UMAD_CA_NAME_LEN], int max);
  52
  53 Description: Fill 'cas' array with up to 'max' local ib devices (CAs) names.
  54 The return value is the number of entries actually filled, or -1 on errors.
  55
  56 umad_get_ca_portguids:
  57
  58 Synopsis:
  59         int     umad_get_ca_portguids(char *ca_name, uint64_t *portguids,
  60                                       int max);
  61
  62 Description: Fill 'portguids' array with up to 'max' port GUIDs belonging the
  63 specified IB device 'ca_name', or to the default ib device if 'ca_name' is null.
  64 The return value is the number of entries actually filled, or -1 on errors.
  65
  66 umad_get_ca:
  67
  68 Synopsis:
  69         int     umad_get_ca(char *ca_name, umad_ca_t *ca);
  70
  71 Description: Fill 'ca' structure with the ib device attributes specified by
  72 'ca_name', or with the default ib device attributes if 'ca_name' is null.
  73 Return zero on success, -1 on error.
  74 Note that the library allocates memory for some of the 'ca' fields, and
  75 therefore umad_release_ca() should be used to free these fields before the
  76 'ca' structure can be de-allocated.
  77
  78 See also:
  79         umad_release_ca
  80
  81 umad_release_ca:
  82
  83 Synopsis:
  84         int     umad_release_ca(umad_ca_t *ca);
  85
  86 Description: de-allocated any fields within 'ca' that were allocated by
  87 umad_get_ca(). Return zero on success, -1 on error.
  88
  89 See also:
  90         umad_get_ca
  91
  92 umad_get_port:
  93
  94 Synopsis:
  95         int     umad_get_port(char *ca_name, int portnum, umad_port_t *port);
  96
  97 Description: Fill the 'port' structure with the specified ib port attributes
  98 specified by 'ca_name' and 'portnum', or the default port if 'ca_name' is null
  99 and 'portnum' is zero. If only one of the 'ca_name' and 'portnum' are specified,
 100 the other is used as a filter. For example, passing a null ca_name and 2 for the
 101 portnum means - get a port from any of the local ib devices, as long as it is
 102 the second port. Return zero on success, -1 on error.
 103 Note that the library may use some reference scheme to support port caching
 104 therefore umad_release_port() should be called before the 'port' structure can
 105 be deallocated.
 106
 107 See also:
 108         umad_release_port
 109
 110 umad_release_port:
 111
 112 Synopsis:
 113         int     umad_release_port(umad_port_t *port);
 114
 115 Description: Notify the library that the 'port' that was filled by
 116 umad_get_port() is not required anymore. Return zero on success, -1 on error.
 117
 118 See also:
 119         umad_get_port
 120
 121
 122 Port oriented functions:
 123
 124 umad_open_port:
 125
 126 Synopsis:
 127         int     umad_open_port(char *ca_name, int portnum);
 128
 129 Description: Open the port specified by 'ca_name' and 'portnum' for umad IO.
 130 The port is selected by the library if not all parameters are provided (see
 131 umad_get_port() for details). Return non-negative portid handle (int) or
 132 negative value on errors.
 133
 134 Errors:
 135         -ENODEV ib device can't be resolved
 136         -EINVAL port is not valid (bad 'portnum' or no umad device)
 137         -EIO    umad device for this port can't be opened
 138
 139 See also:
 140         umad_get_port
 141
 142 umad_close_port:
 143
 144 Synopsis:
 145         int     umad_close_port(int portid);
 146
 147 Description: Close the port specified by the handle 'portid'. Return 0 on
 148 success and -EINVAL if the portid is not a handle to a valid (open) port.
 149
 150 See also:
 151         umad_open_port
 152
 153 Register/unregister functions:
 154
 155 umad_register:
 156
 157 Synopsis:
 158         int     umad_register(int portid, int mgmt_class,
 159                               int mgmt_version, uint32_t method_mask[4]);
 160
 161 Description: Register to the specified management class and version in the port
 162 specified by the 'portid' handle. If 'method_mask' array is provided, the caller
 163 is registered as a replier (server) for the methods having their coresponding
 164 bit on in the 'method_mask'. If 'method_mask' is null, the caller is registered
 165 as a mad client, meaning that it can only receive replies on mads it sent
 166 (solicited mads).
 167 Return non-negative agent id number on success, and a negative value on errors.
 168
 169 Errors:
 170         -EINVAL invalid port handle
 171         -EPERM  registration failed
 172
 173 umad_register_oui:
 174
 175 Synopsis:
 176         int     umad_register_oui(int portid, int mgmt_class, uint8_t
 177 rmpp_version,
 178                                   uint8 oui[3], uint32 method_mask[4]);
 179
 180 Description: Register to the specified vendor class range 2, the specified
 181 oui, and whether rmpp is being used. Otherwise operate similarly to
 182 umad_register().
 183
 184 Errors:
 185         -EINVAL invalid port handle or class is not in the vendor class 2 range
 186         -EPERM  registration failed
 187
 188 umad_unregister:
 189
 190 Synopsis:
 191         int     umad_unregister(int portid, int agentid);
 192
 193 Description: Unregister the specified 'agentid' previously registered using
 194 umad_register() or umad_register_oui(). Returns 0 on success and negative
 195 value on errors.
 196
 197 Errors:
 198         -EINVAL invalid port handle or agentid
 199         *       (kernel error codes)
 200
 201
 202 Port IO functions:
 203
 204 umad_send:
 205
 206 Synopsis:
 207         int     umad_send(int portid, int agentid, void *umad,
 208                           int timeout_ms, int retries);
 209
 210 Description: Send the specified 'umad' buffer from the port specified by
 211 'portid' and using the agent specified by 'agentid'. 'timeout_ms' controls
 212 solicited mads behavior as follows: zero value means not solicited. Positive
 213 value makes the kernel indicate timeout if the reply is not received within the
 214 specified value, and return the original buffer in the read channel with
 215 the status field set (non zero). Negative 'timeout_ms' value makes the kernel
 216 wait forever for the reply. Returns 0 on success and negative value on errors.
 217
 218 Errors:
 219         -EINVAL invalid port handle or agentid
 220         -EIO    send operation failed
 221
 222 umad_recv:
 223
 224 Synopsis:
 225         int     umad_recv(int portid, void *umad, int timeout_ms);
 226
 227 Description: Wait up to 'timeout_ms' for a packet to be received from the
 228 port specified by 'portid'. The packet is copied to the 'umad' buffer.
 229 Negative 'timeout_ms' value makes the function block until a packet
 230 is received. Zero 'timeout_ms' indicates a non blocking read.
 231 Return non negative receiving agentid on success and negative value on errors.
 232
 233 Errors:
 234         -EINVAL         invalid port handle or agentid
 235         -EIO            receive operation failed
 236         -EWOULDBLOCK    non blocking read can't be fulfilled
 237
 238 umad_poll:
 239
 240 Synopsis:
 241         int     umad_poll(int portid, int timeout_ms);
 242
 243 Description: Wait up to 'timeout_ms' for a packet to be received from the
 244 port specified by 'portid'. Once a packet is ready to be read the function
 245 returns 0 after that the packet can be read using umad_recv(). Otherwise
 246 -ETIMEDOUT is returned. Note that successfully polling a port does not guarantee
 247 that the following umad_recv will be non blocking when several threads are using
 248 the same port. Instead, use timeout_ms parameter of zero to umad_recv to ensure
 249 a non-blocking read.
 250
 251 Errors:
 252         -EINVAL         invalid port handle or agentid
 253         -ETIMEDOUT      poll operation timed out
 254         -EIO            poll operation failed
 255
 256 umad_get_fd:
 257
 258 Synopsis:
 259         int     umad_get_fd(int portid)
 260
 261 Description: Return umad fd for port specified by 'portid'. Returns fd
 262 for port or -EINVAL if portid is invalid.
 263
 264 Errors:
 265         -EINVAL         invalid port handle
 266
 267
 268 umad helper functions:
 269
 270 umad_get_mad:
 271
 272 Synopsis:
 273         void *  umad_get_mad(void *umad);
 274
 275 Description: Return a pointer to the mad image within the 'umad' buffer.
 276
 277 umad_size:
 278
 279 Synopsis:
 280         size_t  umad_size(void);
 281
 282 Description: Return the size of umad buffer (in bytes).
 283
 284 umad_status:
 285
 286 Synopsis:
 287         int     umad_status(void *umad);
 288
 289 Description: Return the internal 'umad' status field. After a packet is
 290 received, a non zero status means the packet had a send-timeout
 291 indication. Otherwise, it is a valid packet.
 292
 293 umad_get_mad_addr:
 294
 295 Synopsis:
 296         ib_mad_addr_t   *umad_get_mad_addr(void *umad);
 297
 298 Description: Return a pointer to the ib_mad_addr struct within 'umad' buffer.
 299
 300 umad_set_grh_net:
 301
 302 Synopsis:
 303         int     umad_set_grh_net(void *umad, void *grh);
 304
 305 Description: set the GRH fields within the 'umad' buffer. The given 'grh'
 306 fields are expected to be in network order. Returns 0 on success, -1 on errors.
 307
 308 BUGS:
 309         not implemented.
 310
 311 umad_set_grh:
 312
 313 Synopsis:
 314         int     umad_set_grh(void *umad, void *grh);
 315
 316 Description: set the GRH fields within the 'umad' buffer. The given 'grh'
 317 fields are expected to be in host order. Returns 0 on success, -1 on errors.
 318
 319 umad_set_addr_net:
 320
 321 Synopsis:
 322         int     umad_set_addr_net(void *umad, int dlid, int dqp,
 323                                   int sl, int qkey);
 324
 325 Description: Set the mad address fields within the 'umad' buffer using
 326 the given network ordered fields. Return 0 on success, -1 on errors.
 327
 328 umad_set_addr:
 329
 330 Synopsis:
 331         int     umad_set_addr(void *umad, int dlid, int dqp, int sl, int qkey);
 332
 333 Description: Set the mad address fields within the 'umad' buffer using
 334 the given host ordered fields. Return 0 on success, -1 on errors.
 335
 336 umad_set_pkey:
 337
 338 Synopsis:
 339         int     umad_set_pkey(void *umad, int pkey_index);
 340
 341 Description: Set the pkey within the 'umad' buffer.  Return 0 on success,
 342 -1 on errors.
 343
 344 BUGS:
 345         not implemented.
 346
 347 umad_alloc:
 348
 349 Synopsis:
 350         void *umad_alloc(int num);
 351
 352 Description: Allocate memory for 'num' umad buffers array. Return null if
 353 out of memory.
 354
 355 umad_free:
 356
 357 Synopsis:
 358         void umad_free(void *umad);
 359
 360 Description: Deallocate memory previously allocated with uamd_alloc().
 361
 362 See also:
 363         umad_alloc
 364
 365
 366 Debugging support functions:
 367
 368 umad_debug:
 369
 370 Synopsis:
 371         int     umad_debug(int level);
 372
 373 Description: Set the library internal debugging level to 'level'. The following
 374 debugging levels are supported: 0 - no debugging (the default),
 375 1 - basic debugging information, 2 - verbose debugging. Negative values are
 376 ignored. Returns the new level. Note that the current debugging level can
 377 be queried by passing negative values.
 378
 379 umad_addr_dump:
 380
 381 Synopsis:
 382         void    umad_addr_dump(ib_mad_addr_t *addr);
 383
 384 Description: Dump the given 'addr' structure to the stderr.
 385
 386 umad_dump:
 387
 388 Synopsis:
 389         void    umad_dump(void *umad);
 390
 391 Description: Dump the given 'umad' buffer to the stderr.
 392