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