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
7 * Basic user mode mad functions: open/close port,
8 register/unregister, send/receive/poll mad, etc.
9 * Umad packet helper functions.
15 umad_ca: encapsulate an IB device. Identified by CA_NAME.
17 umad_port: encapsulate an IB port within an IB device. Identified by CA_NAME
20 ib_umad_addr: IB destination address structure.
22 portid (int): opened port handle.
24 agentid (int): mad multiplexing agent handle.
27 Module management functions:
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.
43 Description: library main destruction function. library should not be called after calling this function. Return zero on success, -1 on errors.
46 IB devices and ports information functions:
51 int umad_get_cas_names(char cas[][UMAD_CA_NAME_LEN], int max);
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.
56 umad_get_ca_portguids:
59 int umad_get_ca_portguids(char *ca_name, uint64_t *portguids,
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.
69 int umad_get_ca(char *ca_name, umad_ca_t *ca);
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.
84 int umad_release_ca(umad_ca_t *ca);
86 Description: de-allocated any fields within 'ca' that were allocated by
87 umad_get_ca(). Return zero on success, -1 on error.
95 int umad_get_port(char *ca_name, int portnum, umad_port_t *port);
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
113 int umad_release_port(umad_port_t *port);
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.
122 Port oriented functions:
127 int umad_open_port(char *ca_name, int portnum);
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.
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
145 int umad_close_port(int portid);
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.
153 Register/unregister functions:
158 int umad_register(int portid, int mgmt_class,
159 int mgmt_version, uint32_t method_mask[4]);
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
167 Return non-negative agent id number on success, and a negative value on errors.
170 -EINVAL invalid port handle
171 -EPERM registration failed
176 int umad_register_oui(int portid, int mgmt_class, uint8_t
178 uint8 oui[3], uint32 method_mask[4]);
180 Description: Register to the specified vendor class range 2, the specified
181 oui, and whether rmpp is being used. Otherwise operate similarly to
185 -EINVAL invalid port handle or class is not in the vendor class 2 range
186 -EPERM registration failed
191 int umad_unregister(int portid, int agentid);
193 Description: Unregister the specified 'agentid' previously registered using
194 umad_register() or umad_register_oui(). Returns 0 on success and negative
198 -EINVAL invalid port handle or agentid
199 * (kernel error codes)
207 int umad_send(int portid, int agentid, void *umad,
208 int timeout_ms, int retries);
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.
219 -EINVAL invalid port handle or agentid
220 -EIO send operation failed
225 int umad_recv(int portid, void *umad, int timeout_ms);
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.
234 -EINVAL invalid port handle or agentid
235 -EIO receive operation failed
236 -EWOULDBLOCK non blocking read can't be fulfilled
241 int umad_poll(int portid, int timeout_ms);
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
252 -EINVAL invalid port handle or agentid
253 -ETIMEDOUT poll operation timed out
254 -EIO poll operation failed
259 int umad_get_fd(int portid)
261 Description: Return umad fd for port specified by 'portid'. Returns fd
262 for port or -EINVAL if portid is invalid.
265 -EINVAL invalid port handle
268 umad helper functions:
273 void * umad_get_mad(void *umad);
275 Description: Return a pointer to the mad image within the 'umad' buffer.
280 size_t umad_size(void);
282 Description: Return the size of umad buffer (in bytes).
287 int umad_status(void *umad);
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.
296 ib_mad_addr_t *umad_get_mad_addr(void *umad);
298 Description: Return a pointer to the ib_mad_addr struct within 'umad' buffer.
303 int umad_set_grh_net(void *umad, void *grh);
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.
314 int umad_set_grh(void *umad, void *grh);
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.
322 int umad_set_addr_net(void *umad, int dlid, int dqp,
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.
331 int umad_set_addr(void *umad, int dlid, int dqp, int sl, int qkey);
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.
339 int umad_set_pkey(void *umad, int pkey_index);
341 Description: Set the pkey within the 'umad' buffer. Return 0 on success,
350 void *umad_alloc(int num);
352 Description: Allocate memory for 'num' umad buffers array. Return null if
358 void umad_free(void *umad);
360 Description: Deallocate memory previously allocated with uamd_alloc().
366 Debugging support functions:
371 int umad_debug(int level);
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.
382 void umad_addr_dump(ib_mad_addr_t *addr);
384 Description: Dump the given 'addr' structure to the stderr.
389 void umad_dump(void *umad);
391 Description: Dump the given 'umad' buffer to the stderr.