libibumad: Overview: libibumad provides the following functionality: * Provide information about the IB devices installed. This includes list of IB devices names, list of port, device and port attributes. * Basic user mode mad functions: open/close port, register/unregister, send/receive/poll mad, etc. * Umad packet helper functions. * debugging support. Library objects: umad_ca: encapsulate an IB device. Identified by CA_NAME. umad_port: encapsulate an IB port within an IB device. Identified by CA_NAME and port number. ib_umad_addr: IB destination address structure. portid (int): opened port handle. agentid (int): mad multiplexing agent handle. Module management functions: umad_init: Synopsis: int umad_init(void) Description: library main initialization function. Must be called before any other call to the library. Return zero on success, -1 if the infiniband mad class can't be opened, or the abi version doesn't match. umad_done: Synopsis: int umad_done(void) Description: library main destruction function. library should not be called after calling this function. Return zero on success, -1 on errors. IB devices and ports information functions: umad_get_cas_names: Synopsis: int umad_get_cas_names(char cas[][UMAD_CA_NAME_LEN], int max); Description: Fill 'cas' array with up to 'max' local ib devices (CAs) names. The return value is the number of entries actually filled, or -1 on errors. umad_get_ca_portguids: Synopsis: int umad_get_ca_portguids(char *ca_name, uint64_t *portguids, int max); Description: Fill 'portguids' array with up to 'max' port GUIDs belonging the specified IB device 'ca_name', or to the default ib device if 'ca_name' is null. The return value is the number of entries actually filled, or -1 on errors. umad_get_ca: Synopsis: int umad_get_ca(char *ca_name, umad_ca_t *ca); Description: Fill 'ca' structure with the ib device attributes specified by 'ca_name', or with the default ib device attributes if 'ca_name' is null. Return zero on success, -1 on error. Note that the library allocates memory for some of the 'ca' fields, and therefore umad_release_ca() should be used to free these fields before the 'ca' structure can be de-allocated. See also: umad_release_ca umad_release_ca: Synopsis: int umad_release_ca(umad_ca_t *ca); Description: de-allocated any fields within 'ca' that were allocated by umad_get_ca(). Return zero on success, -1 on error. See also: umad_get_ca umad_get_port: Synopsis: int umad_get_port(char *ca_name, int portnum, umad_port_t *port); Description: Fill the 'port' structure with the specified ib port attributes specified by 'ca_name' and 'portnum', or the default port if 'ca_name' is null and 'portnum' is zero. If only one of the 'ca_name' and 'portnum' are specified, the other is used as a filter. For example, passing a null ca_name and 2 for the portnum means - get a port from any of the local ib devices, as long as it is the second port. Return zero on success, -1 on error. Note that the library may use some reference scheme to support port caching therefore umad_release_port() should be called before the 'port' structure can be deallocated. See also: umad_release_port umad_release_port: Synopsis: int umad_release_port(umad_port_t *port); Description: Notify the library that the 'port' that was filled by umad_get_port() is not required anymore. Return zero on success, -1 on error. See also: umad_get_port Port oriented functions: umad_open_port: Synopsis: int umad_open_port(char *ca_name, int portnum); Description: Open the port specified by 'ca_name' and 'portnum' for umad IO. The port is selected by the library if not all parameters are provided (see umad_get_port() for details). Return non-negative portid handle (int) or negative value on errors. Errors: -ENODEV ib device can't be resolved -EINVAL port is not valid (bad 'portnum' or no umad device) -EIO umad device for this port can't be opened See also: umad_get_port umad_close_port: Synopsis: int umad_close_port(int portid); Description: Close the port specified by the handle 'portid'. Return 0 on success and -EINVAL if the portid is not a handle to a valid (open) port. See also: umad_open_port Register/unregister functions: umad_register: Synopsis: int umad_register(int portid, int mgmt_class, int mgmt_version, uint32_t method_mask[4]); Description: Register to the specified management class and version in the port specified by the 'portid' handle. If 'method_mask' array is provided, the caller is registered as a replier (server) for the methods having their coresponding bit on in the 'method_mask'. If 'method_mask' is null, the caller is registered as a mad client, meaning that it can only receive replies on mads it sent (solicited mads). Return non-negative agent id number on success, and a negative value on errors. Errors: -EINVAL invalid port handle -EPERM registration failed umad_register_oui: Synopsis: int umad_register_oui(int portid, int mgmt_class, uint8_t rmpp_version, uint8 oui[3], uint32 method_mask[4]); Description: Register to the specified vendor class range 2, the specified oui, and whether rmpp is being used. Otherwise operate similarly to umad_register(). Errors: -EINVAL invalid port handle or class is not in the vendor class 2 range -EPERM registration failed umad_unregister: Synopsis: int umad_unregister(int portid, int agentid); Description: Unregister the specified 'agentid' previously registered using umad_register() or umad_register_oui(). Returns 0 on success and negative value on errors. Errors: -EINVAL invalid port handle or agentid * (kernel error codes) Port IO functions: umad_send: Synopsis: int umad_send(int portid, int agentid, void *umad, int timeout_ms, int retries); Description: Send the specified 'umad' buffer from the port specified by 'portid' and using the agent specified by 'agentid'. 'timeout_ms' controls solicited mads behavior as follows: zero value means not solicited. Positive value makes the kernel indicate timeout if the reply is not received within the specified value, and return the original buffer in the read channel with the status field set (non zero). Negative 'timeout_ms' value makes the kernel wait forever for the reply. Returns 0 on success and negative value on errors. Errors: -EINVAL invalid port handle or agentid -EIO send operation failed umad_recv: Synopsis: int umad_recv(int portid, void *umad, int timeout_ms); Description: Wait up to 'timeout_ms' for a packet to be received from the port specified by 'portid'. The packet is copied to the 'umad' buffer. Negative 'timeout_ms' value makes the function block until a packet is received. Zero 'timeout_ms' indicates a non blocking read. Return non negative receiving agentid on success and negative value on errors. Errors: -EINVAL invalid port handle or agentid -EIO receive operation failed -EWOULDBLOCK non blocking read can't be fulfilled umad_poll: Synopsis: int umad_poll(int portid, int timeout_ms); Description: Wait up to 'timeout_ms' for a packet to be received from the port specified by 'portid'. Once a packet is ready to be read the function returns 0 after that the packet can be read using umad_recv(). Otherwise -ETIMEDOUT is returned. Note that successfully polling a port does not guarantee that the following umad_recv will be non blocking when several threads are using the same port. Instead, use timeout_ms parameter of zero to umad_recv to ensure a non-blocking read. Errors: -EINVAL invalid port handle or agentid -ETIMEDOUT poll operation timed out -EIO poll operation failed umad_get_fd: Synopsis: int umad_get_fd(int portid) Description: Return umad fd for port specified by 'portid'. Returns fd for port or -EINVAL if portid is invalid. Errors: -EINVAL invalid port handle umad helper functions: umad_get_mad: Synopsis: void * umad_get_mad(void *umad); Description: Return a pointer to the mad image within the 'umad' buffer. umad_size: Synopsis: size_t umad_size(void); Description: Return the size of umad buffer (in bytes). umad_status: Synopsis: int umad_status(void *umad); Description: Return the internal 'umad' status field. After a packet is received, a non zero status means the packet had a send-timeout indication. Otherwise, it is a valid packet. umad_get_mad_addr: Synopsis: ib_mad_addr_t *umad_get_mad_addr(void *umad); Description: Return a pointer to the ib_mad_addr struct within 'umad' buffer. umad_set_grh_net: Synopsis: int umad_set_grh_net(void *umad, void *grh); Description: set the GRH fields within the 'umad' buffer. The given 'grh' fields are expected to be in network order. Returns 0 on success, -1 on errors. BUGS: not implemented. umad_set_grh: Synopsis: int umad_set_grh(void *umad, void *grh); Description: set the GRH fields within the 'umad' buffer. The given 'grh' fields are expected to be in host order. Returns 0 on success, -1 on errors. umad_set_addr_net: Synopsis: int umad_set_addr_net(void *umad, int dlid, int dqp, int sl, int qkey); Description: Set the mad address fields within the 'umad' buffer using the given network ordered fields. Return 0 on success, -1 on errors. umad_set_addr: Synopsis: int umad_set_addr(void *umad, int dlid, int dqp, int sl, int qkey); Description: Set the mad address fields within the 'umad' buffer using the given host ordered fields. Return 0 on success, -1 on errors. umad_set_pkey: Synopsis: int umad_set_pkey(void *umad, int pkey_index); Description: Set the pkey within the 'umad' buffer. Return 0 on success, -1 on errors. BUGS: not implemented. umad_alloc: Synopsis: void *umad_alloc(int num); Description: Allocate memory for 'num' umad buffers array. Return null if out of memory. umad_free: Synopsis: void umad_free(void *umad); Description: Deallocate memory previously allocated with uamd_alloc(). See also: umad_alloc Debugging support functions: umad_debug: Synopsis: int umad_debug(int level); Description: Set the library internal debugging level to 'level'. The following debugging levels are supported: 0 - no debugging (the default), 1 - basic debugging information, 2 - verbose debugging. Negative values are ignored. Returns the new level. Note that the current debugging level can be queried by passing negative values. umad_addr_dump: Synopsis: void umad_addr_dump(ib_mad_addr_t *addr); Description: Dump the given 'addr' structure to the stderr. umad_dump: Synopsis: void umad_dump(void *umad); Description: Dump the given 'umad' buffer to the stderr.