1219820Sjefflibibumad: 2219820Sjeff 3219820SjeffOverview: libibumad provides the following functionality: 4219820Sjeff * Provide information about the IB devices installed. This includes 5219820Sjeff list of IB devices names, list of port, device and port 6219820Sjeff attributes. 7219820Sjeff * Basic user mode mad functions: open/close port, 8219820Sjeff register/unregister, send/receive/poll mad, etc. 9219820Sjeff * Umad packet helper functions. 10219820Sjeff * debugging support. 11219820Sjeff 12219820Sjeff 13219820SjeffLibrary objects: 14219820Sjeff 15219820Sjeffumad_ca: encapsulate an IB device. Identified by CA_NAME. 16219820Sjeff 17219820Sjeffumad_port: encapsulate an IB port within an IB device. Identified by CA_NAME 18219820Sjeff and port number. 19219820Sjeff 20219820Sjeffib_umad_addr: IB destination address structure. 21219820Sjeff 22219820Sjeffportid (int): opened port handle. 23219820Sjeff 24219820Sjeffagentid (int): mad multiplexing agent handle. 25219820Sjeff 26219820Sjeff 27219820SjeffModule management functions: 28219820Sjeff 29219820Sjeffumad_init: 30219820Sjeff 31219820SjeffSynopsis: 32219820Sjeff int umad_init(void) 33219820Sjeff 34219820SjeffDescription: library main initialization function. Must be called before any 35219820Sjeffother call to the library. Return zero on success, -1 if the infiniband mad 36219820Sjeffclass can't be opened, or the abi version doesn't match. 37219820Sjeff 38219820Sjeffumad_done: 39219820Sjeff 40219820SjeffSynopsis: 41219820Sjeff int umad_done(void) 42219820Sjeff 43219820SjeffDescription: library main destruction function. library should not be called after calling this function. Return zero on success, -1 on errors. 44219820Sjeff 45219820Sjeff 46219820SjeffIB devices and ports information functions: 47219820Sjeff 48219820Sjeffumad_get_cas_names: 49219820Sjeff 50219820SjeffSynopsis: 51219820Sjeff int umad_get_cas_names(char cas[][UMAD_CA_NAME_LEN], int max); 52219820Sjeff 53219820SjeffDescription: Fill 'cas' array with up to 'max' local ib devices (CAs) names. 54219820SjeffThe return value is the number of entries actually filled, or -1 on errors. 55219820Sjeff 56219820Sjeffumad_get_ca_portguids: 57219820Sjeff 58219820SjeffSynopsis: 59219820Sjeff int umad_get_ca_portguids(char *ca_name, uint64_t *portguids, 60219820Sjeff int max); 61219820Sjeff 62219820SjeffDescription: Fill 'portguids' array with up to 'max' port GUIDs belonging the 63219820Sjeffspecified IB device 'ca_name', or to the default ib device if 'ca_name' is null. 64219820SjeffThe return value is the number of entries actually filled, or -1 on errors. 65219820Sjeff 66219820Sjeffumad_get_ca: 67219820Sjeff 68219820SjeffSynopsis: 69219820Sjeff int umad_get_ca(char *ca_name, umad_ca_t *ca); 70219820Sjeff 71219820SjeffDescription: Fill 'ca' structure with the ib device attributes specified by 72219820Sjeff'ca_name', or with the default ib device attributes if 'ca_name' is null. 73219820SjeffReturn zero on success, -1 on error. 74219820SjeffNote that the library allocates memory for some of the 'ca' fields, and 75219820Sjefftherefore umad_release_ca() should be used to free these fields before the 76219820Sjeff'ca' structure can be de-allocated. 77219820Sjeff 78219820SjeffSee also: 79219820Sjeff umad_release_ca 80219820Sjeff 81219820Sjeffumad_release_ca: 82219820Sjeff 83219820SjeffSynopsis: 84219820Sjeff int umad_release_ca(umad_ca_t *ca); 85219820Sjeff 86219820SjeffDescription: de-allocated any fields within 'ca' that were allocated by 87219820Sjeffumad_get_ca(). Return zero on success, -1 on error. 88219820Sjeff 89219820SjeffSee also: 90219820Sjeff umad_get_ca 91219820Sjeff 92219820Sjeffumad_get_port: 93219820Sjeff 94219820SjeffSynopsis: 95219820Sjeff int umad_get_port(char *ca_name, int portnum, umad_port_t *port); 96219820Sjeff 97219820SjeffDescription: Fill the 'port' structure with the specified ib port attributes 98219820Sjeffspecified by 'ca_name' and 'portnum', or the default port if 'ca_name' is null 99219820Sjeffand 'portnum' is zero. If only one of the 'ca_name' and 'portnum' are specified, 100219820Sjeffthe other is used as a filter. For example, passing a null ca_name and 2 for the 101219820Sjeffportnum means - get a port from any of the local ib devices, as long as it is 102219820Sjeffthe second port. Return zero on success, -1 on error. 103219820SjeffNote that the library may use some reference scheme to support port caching 104219820Sjefftherefore umad_release_port() should be called before the 'port' structure can 105219820Sjeffbe deallocated. 106219820Sjeff 107219820SjeffSee also: 108219820Sjeff umad_release_port 109219820Sjeff 110219820Sjeffumad_release_port: 111219820Sjeff 112219820SjeffSynopsis: 113219820Sjeff int umad_release_port(umad_port_t *port); 114219820Sjeff 115219820SjeffDescription: Notify the library that the 'port' that was filled by 116219820Sjeffumad_get_port() is not required anymore. Return zero on success, -1 on error. 117219820Sjeff 118219820SjeffSee also: 119219820Sjeff umad_get_port 120219820Sjeff 121219820Sjeff 122219820SjeffPort oriented functions: 123219820Sjeff 124219820Sjeffumad_open_port: 125219820Sjeff 126219820SjeffSynopsis: 127219820Sjeff int umad_open_port(char *ca_name, int portnum); 128219820Sjeff 129219820SjeffDescription: Open the port specified by 'ca_name' and 'portnum' for umad IO. 130219820SjeffThe port is selected by the library if not all parameters are provided (see 131219820Sjeffumad_get_port() for details). Return non-negative portid handle (int) or 132219820Sjeffnegative value on errors. 133219820Sjeff 134219820SjeffErrors: 135219820Sjeff -ENODEV ib device can't be resolved 136219820Sjeff -EINVAL port is not valid (bad 'portnum' or no umad device) 137219820Sjeff -EIO umad device for this port can't be opened 138219820Sjeff 139219820SjeffSee also: 140219820Sjeff umad_get_port 141219820Sjeff 142219820Sjeffumad_close_port: 143219820Sjeff 144219820SjeffSynopsis: 145219820Sjeff int umad_close_port(int portid); 146219820Sjeff 147219820SjeffDescription: Close the port specified by the handle 'portid'. Return 0 on 148219820Sjeffsuccess and -EINVAL if the portid is not a handle to a valid (open) port. 149219820Sjeff 150219820SjeffSee also: 151219820Sjeff umad_open_port 152219820Sjeff 153219820SjeffRegister/unregister functions: 154219820Sjeff 155219820Sjeffumad_register: 156219820Sjeff 157219820SjeffSynopsis: 158219820Sjeff int umad_register(int portid, int mgmt_class, 159219820Sjeff int mgmt_version, uint32_t method_mask[4]); 160219820Sjeff 161219820SjeffDescription: Register to the specified management class and version in the port 162219820Sjeffspecified by the 'portid' handle. If 'method_mask' array is provided, the caller 163219820Sjeffis registered as a replier (server) for the methods having their coresponding 164219820Sjeffbit on in the 'method_mask'. If 'method_mask' is null, the caller is registered 165219820Sjeffas a mad client, meaning that it can only receive replies on mads it sent 166219820Sjeff(solicited mads). 167219820SjeffReturn non-negative agent id number on success, and a negative value on errors. 168219820Sjeff 169219820SjeffErrors: 170219820Sjeff -EINVAL invalid port handle 171219820Sjeff -EPERM registration failed 172219820Sjeff 173219820Sjeffumad_register_oui: 174219820Sjeff 175219820SjeffSynopsis: 176219820Sjeff int umad_register_oui(int portid, int mgmt_class, uint8_t 177219820Sjeffrmpp_version, 178219820Sjeff uint8 oui[3], uint32 method_mask[4]); 179219820Sjeff 180219820SjeffDescription: Register to the specified vendor class range 2, the specified 181219820Sjeffoui, and whether rmpp is being used. Otherwise operate similarly to 182219820Sjeffumad_register(). 183219820Sjeff 184219820SjeffErrors: 185219820Sjeff -EINVAL invalid port handle or class is not in the vendor class 2 range 186219820Sjeff -EPERM registration failed 187219820Sjeff 188219820Sjeffumad_unregister: 189219820Sjeff 190219820SjeffSynopsis: 191219820Sjeff int umad_unregister(int portid, int agentid); 192219820Sjeff 193219820SjeffDescription: Unregister the specified 'agentid' previously registered using 194219820Sjeffumad_register() or umad_register_oui(). Returns 0 on success and negative 195219820Sjeffvalue on errors. 196219820Sjeff 197219820SjeffErrors: 198219820Sjeff -EINVAL invalid port handle or agentid 199219820Sjeff * (kernel error codes) 200219820Sjeff 201219820Sjeff 202219820SjeffPort IO functions: 203219820Sjeff 204219820Sjeffumad_send: 205219820Sjeff 206219820SjeffSynopsis: 207219820Sjeff int umad_send(int portid, int agentid, void *umad, 208219820Sjeff int timeout_ms, int retries); 209219820Sjeff 210219820SjeffDescription: Send the specified 'umad' buffer from the port specified by 211219820Sjeff'portid' and using the agent specified by 'agentid'. 'timeout_ms' controls 212219820Sjeffsolicited mads behavior as follows: zero value means not solicited. Positive 213219820Sjeffvalue makes the kernel indicate timeout if the reply is not received within the 214219820Sjeffspecified value, and return the original buffer in the read channel with 215219820Sjeffthe status field set (non zero). Negative 'timeout_ms' value makes the kernel 216219820Sjeffwait forever for the reply. Returns 0 on success and negative value on errors. 217219820Sjeff 218219820SjeffErrors: 219219820Sjeff -EINVAL invalid port handle or agentid 220219820Sjeff -EIO send operation failed 221219820Sjeff 222219820Sjeffumad_recv: 223219820Sjeff 224219820SjeffSynopsis: 225219820Sjeff int umad_recv(int portid, void *umad, int timeout_ms); 226219820Sjeff 227219820SjeffDescription: Wait up to 'timeout_ms' for a packet to be received from the 228219820Sjeffport specified by 'portid'. The packet is copied to the 'umad' buffer. 229219820SjeffNegative 'timeout_ms' value makes the function block until a packet 230219820Sjeffis received. Zero 'timeout_ms' indicates a non blocking read. 231219820SjeffReturn non negative receiving agentid on success and negative value on errors. 232219820Sjeff 233219820SjeffErrors: 234219820Sjeff -EINVAL invalid port handle or agentid 235219820Sjeff -EIO receive operation failed 236219820Sjeff -EWOULDBLOCK non blocking read can't be fulfilled 237219820Sjeff 238219820Sjeffumad_poll: 239219820Sjeff 240219820SjeffSynopsis: 241219820Sjeff int umad_poll(int portid, int timeout_ms); 242219820Sjeff 243219820SjeffDescription: Wait up to 'timeout_ms' for a packet to be received from the 244219820Sjeffport specified by 'portid'. Once a packet is ready to be read the function 245219820Sjeffreturns 0 after that the packet can be read using umad_recv(). Otherwise 246219820Sjeff-ETIMEDOUT is returned. Note that successfully polling a port does not guarantee 247219820Sjeffthat the following umad_recv will be non blocking when several threads are using 248219820Sjeffthe same port. Instead, use timeout_ms parameter of zero to umad_recv to ensure 249219820Sjeffa non-blocking read. 250219820Sjeff 251219820SjeffErrors: 252219820Sjeff -EINVAL invalid port handle or agentid 253219820Sjeff -ETIMEDOUT poll operation timed out 254219820Sjeff -EIO poll operation failed 255219820Sjeff 256219820Sjeffumad_get_fd: 257219820Sjeff 258219820SjeffSynopsis: 259219820Sjeff int umad_get_fd(int portid) 260219820Sjeff 261219820SjeffDescription: Return umad fd for port specified by 'portid'. Returns fd 262219820Sjefffor port or -EINVAL if portid is invalid. 263219820Sjeff 264219820SjeffErrors: 265219820Sjeff -EINVAL invalid port handle 266219820Sjeff 267219820Sjeff 268219820Sjeffumad helper functions: 269219820Sjeff 270219820Sjeffumad_get_mad: 271219820Sjeff 272219820SjeffSynopsis: 273219820Sjeff void * umad_get_mad(void *umad); 274219820Sjeff 275219820SjeffDescription: Return a pointer to the mad image within the 'umad' buffer. 276219820Sjeff 277219820Sjeffumad_size: 278219820Sjeff 279219820SjeffSynopsis: 280219820Sjeff size_t umad_size(void); 281219820Sjeff 282219820SjeffDescription: Return the size of umad buffer (in bytes). 283219820Sjeff 284219820Sjeffumad_status: 285219820Sjeff 286219820SjeffSynopsis: 287219820Sjeff int umad_status(void *umad); 288219820Sjeff 289219820SjeffDescription: Return the internal 'umad' status field. After a packet is 290219820Sjeffreceived, a non zero status means the packet had a send-timeout 291219820Sjeffindication. Otherwise, it is a valid packet. 292219820Sjeff 293219820Sjeffumad_get_mad_addr: 294219820Sjeff 295219820SjeffSynopsis: 296219820Sjeff ib_mad_addr_t *umad_get_mad_addr(void *umad); 297219820Sjeff 298219820SjeffDescription: Return a pointer to the ib_mad_addr struct within 'umad' buffer. 299219820Sjeff 300219820Sjeffumad_set_grh_net: 301219820Sjeff 302219820SjeffSynopsis: 303219820Sjeff int umad_set_grh_net(void *umad, void *grh); 304219820Sjeff 305219820SjeffDescription: set the GRH fields within the 'umad' buffer. The given 'grh' 306219820Sjefffields are expected to be in network order. Returns 0 on success, -1 on errors. 307219820Sjeff 308219820SjeffBUGS: 309219820Sjeff not implemented. 310219820Sjeff 311219820Sjeffumad_set_grh: 312219820Sjeff 313219820SjeffSynopsis: 314219820Sjeff int umad_set_grh(void *umad, void *grh); 315219820Sjeff 316219820SjeffDescription: set the GRH fields within the 'umad' buffer. The given 'grh' 317219820Sjefffields are expected to be in host order. Returns 0 on success, -1 on errors. 318219820Sjeff 319219820Sjeffumad_set_addr_net: 320219820Sjeff 321219820SjeffSynopsis: 322219820Sjeff int umad_set_addr_net(void *umad, int dlid, int dqp, 323219820Sjeff int sl, int qkey); 324219820Sjeff 325219820SjeffDescription: Set the mad address fields within the 'umad' buffer using 326219820Sjeffthe given network ordered fields. Return 0 on success, -1 on errors. 327219820Sjeff 328219820Sjeffumad_set_addr: 329219820Sjeff 330219820SjeffSynopsis: 331219820Sjeff int umad_set_addr(void *umad, int dlid, int dqp, int sl, int qkey); 332219820Sjeff 333219820SjeffDescription: Set the mad address fields within the 'umad' buffer using 334219820Sjeffthe given host ordered fields. Return 0 on success, -1 on errors. 335219820Sjeff 336219820Sjeffumad_set_pkey: 337219820Sjeff 338219820SjeffSynopsis: 339219820Sjeff int umad_set_pkey(void *umad, int pkey_index); 340219820Sjeff 341219820SjeffDescription: Set the pkey within the 'umad' buffer. Return 0 on success, 342219820Sjeff-1 on errors. 343219820Sjeff 344219820SjeffBUGS: 345219820Sjeff not implemented. 346219820Sjeff 347219820Sjeffumad_alloc: 348219820Sjeff 349219820SjeffSynopsis: 350219820Sjeff void *umad_alloc(int num); 351219820Sjeff 352219820SjeffDescription: Allocate memory for 'num' umad buffers array. Return null if 353219820Sjeffout of memory. 354219820Sjeff 355219820Sjeffumad_free: 356219820Sjeff 357219820SjeffSynopsis: 358219820Sjeff void umad_free(void *umad); 359219820Sjeff 360219820SjeffDescription: Deallocate memory previously allocated with uamd_alloc(). 361219820Sjeff 362219820SjeffSee also: 363219820Sjeff umad_alloc 364219820Sjeff 365219820Sjeff 366219820SjeffDebugging support functions: 367219820Sjeff 368219820Sjeffumad_debug: 369219820Sjeff 370219820SjeffSynopsis: 371219820Sjeff int umad_debug(int level); 372219820Sjeff 373219820SjeffDescription: Set the library internal debugging level to 'level'. The following 374219820Sjeffdebugging levels are supported: 0 - no debugging (the default), 375219820Sjeff1 - basic debugging information, 2 - verbose debugging. Negative values are 376219820Sjeffignored. Returns the new level. Note that the current debugging level can 377219820Sjeffbe queried by passing negative values. 378219820Sjeff 379219820Sjeffumad_addr_dump: 380219820Sjeff 381219820SjeffSynopsis: 382219820Sjeff void umad_addr_dump(ib_mad_addr_t *addr); 383219820Sjeff 384219820SjeffDescription: Dump the given 'addr' structure to the stderr. 385219820Sjeff 386219820Sjeffumad_dump: 387219820Sjeff 388219820SjeffSynopsis: 389219820Sjeff void umad_dump(void *umad); 390219820Sjeff 391219820SjeffDescription: Dump the given 'umad' buffer to the stderr. 392219820Sjeff 393