3 Overview: libibmad provides the following functionalities:
4 * common declarations: IB structures, fields, and enumerations
5 * general IB mad interface encapsulation (init port, registration,
7 * IB mads marshaling and de-marshaling
8 * Reliable mad RPC mechanisms (solicited mads)
9 * Server side mad io functions (send, receive)
11 * General SA (queries) support
12 * Port performance class support
13 * IB addresses resolution (path record queries)
14 * Fields parsing and dump functions
17 Model of operation: libibmad is designed to easy the implementation of MAD
18 client and server tools and applications. Mad clients (i.e. application
19 that do not reply to requests) should use the mad RPC mechanism. Mad
20 servers should use the send/receive mechanisms. Applications are
21 assumed to be single threaded, but some multiple threading support
22 is provided. Most IO mechanisms may be blocking. Currently no
23 explicit asynchronous support is implemented.
25 Marshaling/De-marshaling model: libibmad handles two types of data - opaque
26 network data images and native host ordered fields. libibmad do
27 not define C structures to access MAD fields. Instead, it defines
28 a field structure for every separate field and implements a set
29 of conversion functions from the native types to the opaque
30 network image and back. The advantage of this approach is
31 that the marshaling/de-marshaling problems are transparent to most
32 of the application code resulting a clean, machine independent
33 code. Furthermore, even the marshaling/de-marshaling code itself
34 is extremely straight-forward due that fact that the library
35 automatically knows what marshaling/de-marshaling method it has
36 to apply to each field. The disadvantage of this approach is that
37 the marshaling/de-marshaling implementation itself is somehow less
38 efficient then manually crafted manipulations, but this seem a fair
39 tradeoff comparing to the simplicity and cleanness factors.
41 Field dump functions: a side benefit of the marshaling/de-marshaling model
42 (see above), is that the library is aware to the size and the type
43 of each field and therefore is able to print out a human readable
44 representation of the field value.
49 ib_field_t: IB field structure
51 ib_dr_path_t: direct routed address structure
53 ib_portid_t: (endpoint) address structure
55 ib_attr_t: mad attribute and modifier
57 ib_rpc_t: encapsulate information required for the RPC mechanism
59 ib_rmpp_hdr_t: RMPP information structure (currently not supported)
61 ib_sa_call_t: SA request structure
63 ib_vendor_call_t: vendor specific mad structure
71 void madrpc_init(char *dev_name, int dev_port,
72 int *mgmt_classes, int num_classes);
74 Description: library main initialization function. Open the user mad port
75 specified by 'dev_name' and 'dev_port', and registers the application as mad
76 client for the 'num_classes' management classes specified in 'mgmt_classes'
77 array. This function must be called before any other call to the library.
78 Initialization errors cause this function to panic.
83 void * madrpc(ib_rpc_t *rpc, ib_portid_t *dport,
84 void *payload, void *rcvdata);
86 Description: Perform RPC to the destination port specified by 'dport' using
87 'rpc' parameters. If 'payload' in non-null, copy the payload buffer to the
88 outgoing packet, while if the 'rcvdata' is non-null, copy the received packet
89 payload to the 'rcvdata' buffer. Both buffer must be big enough to contain the
90 maximal mad data payload length. If in doubt, use 256 bytes sized buffers.
91 Return rcvdata pointer on success, and null on errors.
96 void * madrpc_rmpp(ib_rpc_t *rpc, ib_portid_t *dport,
97 ib_rmpp_hdr_t *rmpp, void *data);
99 Description: Same as madrpc but supports also RMPP mads.
102 RMPP is not supported yet.
107 int madrpc_portid(void);
109 Description: return the portid the library uses. See libibumad:portid for
113 libibumad:umad_open_port
118 int madrpc_set_retries(int retries);
120 Description: Change the maximal number of retries attempted by the library
121 before it times out to 'retries'. Non-positive values are ignored. Return
122 the current retries count.
127 int madrpc_set_timeout(int timeout);
129 Description: Change the default timeout value used for solicited mads to
130 'timeout' milliseconds. Return 0 on success, -1 on errors. Note that the
131 'timeout' value is used per retry, meaning the total timeout value is acctualy
132 'timeout' * max_retries (see madrpc_set_retries()).
137 void madrpc_save_mad(void *madbuf, int len);
139 Description: Save the next replied mad image in 'madbuf', copying maximux 'len'
140 bytes. In fact, this function snoop a single incoming mad. To snoop several
141 packets, this function has to be called repeatedly after each RPC operation.
144 Not applicable to mad_receive
149 void madrpc_lock(void);
151 Description: Locks the mad RPC mechanism until madrpc_unlock() is called. Calls
152 to this function while the RPC mechanism is already locked cause the calling
153 process to be blocked until madrpc_unlock(). This function should be used
154 only by multiple-threaded applications.
162 void madrpc_unlock(void);
164 Description: Unlock the mad RPC mechanism. See madrpc_lock() for details.
169 void madrpc_show_errors(int set);
171 Description: If 'set' is non-null, print out warning messages on some error
172 events: retries, timeouts, replies with error status, etc. Zero 'set' value
173 causes the library to be quiet.
178 typedef void (ib_mad_dump_fn)(char *buf, int bufsz,
179 void *val, int valsz);
181 Description: Dump the value given in 'val' that have 'valsz' size (in bytes),
182 to the specified 'buf' buffer and limit the output to 'bufsz' bytes. The
183 output is expected to be human readable.
186 Management classes' registration functions:
189 int mad_register_client(int mgmt);
191 Description: Register the application as a client of the specified
192 'mgmt'. Return a non-negative agentid on success and -1 on errors.
193 Note that madrpc_init provides more efficient method to register to several
202 int mad_register_server(int mgmt, uint32 method_mask[4],
205 Description: Register the appication as the default responder of the class
206 methods specified by 'mngt' and 'method_mask' bitmap. Vendor classes in
207 range 2 require also non-zero 'class_oui'. Return a non-negative agentid on
208 success and -1 on errors.
213 int mad_class_agent(int mgmt);
215 Description: Map the given 'mgmt' class to agentid of the agent handling
216 this class. Return non-negative agentid or -1 if the specified class is
220 int mad_agent_class(int agent);
222 Description: Map the given 'agent' id to the management class registered
223 for it. Return positive class value on success, 0 if no management class
224 is registered for this agentid, or -1 if the agent id is invalid.
226 MAD client functions:
231 uint8 *ib_vendor_call(void *data, ib_portid_t *dport,
232 ib_vendor_call_t *call);
234 Description: Perform vendor specific RPC specified by 'call' to the destination
235 port specified by 'dport'. The buffer pointed by 'data' is used as payload
236 for the outgoing packet, and the received packet payload is copied back
237 to the 'data' buffer. The 'data' buffer must be big enough to contain the
238 replied data. Note that if the 'call' method is not get/set/trap, then a
239 simple send operation is performed and the function returns immediately.
240 Return the 'data' pointer on success, or null on errors.
242 mad_is_vendor_range1:
245 int mad_is_vendor_range1(int mgmt);
247 Description: return non-zero value if 'mgmt' is in the vendor specific range
248 1, and zero otherwise.
250 mad_is_vendor_range2:
253 int mad_is_vendor_range2(int mgmt);
255 Description: return non-zero value if 'mgmt' is in the vendor specific range
256 2, and zero otherwise.
261 uint8 * smp_query(void *buf, ib_portid_t *dport,
262 uint attrid, uint mod, uint timeout);
264 Description: Perform the SMP query (get) RPC specified by 'attrid' and 'mod'
265 to the destination port 'dport'. The data in 'buf' is used as the outgoing
266 SMP payload, and the replied packet's data is copied back to 'buf'. The
267 buffer pointed by 'buf' should be big enough to contain the reply - i.e. at
268 least 64 bytes. If timeout is non-zero then it is used as the query's
269 timeout. Otherwise the default timeout value is used.
277 uint8 * smp_set(void *buf, ib_portid_t *dport,
278 uint attrid, uint mod, uint timeout);
280 Description: Same as smp_query() but a set method is used instead of get.
281 Note that SMP sets may lead to many (desired or less desired) results.
282 Specifically it may cause the destination port to malfunction, confuse the
283 current master SM, and lead to non-functioning network. Do not use this
284 function unless you really know what you are doing.
290 very dangerous. Shouldn't be allowed to non-privileged applications
293 uint8 * safe_smp_query(void *rcvbuf, ib_portid_t *portid,
294 uint attrid, uint mod, uint timeout)
296 Description: Thread-safe version of smp_query().
304 uint8 * safe_smp_set(void *rcvbuf, ib_portid_t *portid,
305 uint attrid, uint mod, uint timeout)
307 Description: Thread-safe version of smp_set().
315 uint8 * sa_call(void *data, ib_portid_t *dport,
316 ib_sa_call_t *sa, uint timeout);
318 Description: Perform SA RPC specified by 'sa' to the specified port
319 'dport'. The 'data' buffer is used as the outgoing mad payload, and the
320 returned packet's payload is copied back to the 'data' buffer. The buffer
321 must be big enough to contain the response. If timeout is non-zero then it
322 is used as the query's timeout. Otherwise the default timeout value is used.
323 Return 'data' pointer on success, and null on errors.
326 smp_query, smp_set_timeout
329 RMPP support is missing, not all methods are supported
334 int ib_path_query(ib_gid_t srcgid, ib_gid_t destgid,
335 ib_portid_t *sm_id, void *buf);
337 Description: Perform a simple path record get query using the 'srcgid' and the
338 'destgid' arguments. The query is targeted to the SM specified by 'sm_id'.
339 Copy the query's result to the buffer 'buf' and returns the destination
340 LID. If the query fails return -1.
344 uint8 * safe_sa_call(void *rcvbuf, ib_portid_t *portid,
345 ib_sa_call_t *sa, uint timeout);
347 Description: Thread-safe version of sa_call().
352 port_performance_query:
355 uint8 *port_performance_query(void *rcvbuf, ib_portid_t *dport,
356 int portnum, uint timeout);
358 Description: Perform a port counters get query to the destination port(s)
359 specified by 'dport' and portnum. Use portnum of 0xff to get the aggregated
360 counters of the entire node. The query result is copied to the 'rcvbuf' that
361 must be big enough to contain the response. If timeout is non-zero then it
362 is used as the query's timeout. Otherwise the default timeout value is used.
363 Return 'rcvbuf' pointer on success, and null on errors.
365 port_performance_reset:
368 uint8 *port_performance_reset(void *rcvbuf, ib_portid_t *dest,
369 int portnum, uint mask, uint timeout);
371 Description: Perform a port counters set operation to clear the counters of the
372 destination port(s) specified by 'dport' and 'portnum'. the 'mask' bit-field
373 is used to specify which counters are cleared. Use 'portnum' of 0xff to clear
374 the aggregated counters of the entire node. The operation result is copied
375 to the 'rcvbuf' that must be big enough to contain the response. If timeout
376 is non-zero then it is used as the query's timeout. Otherwise the default
377 timeout value is used. Return 'rcvbuf' pointer on success, and null on errors.
379 Mad server functions:
384 int mad_send(ib_rpc_t *rpc, ib_portid_t *dport,
385 ib_rmpp_hdr_t *rmpp, void *data);
387 Description: Send a single mad to the destination port specified by
388 'dport'. The mad is build using 'rpc' and rmpp arguments and the payload
389 'data'. Note that this function operates similarly to send part of madrpc
390 and madrpc_rmpp returns immediately after the send without retrying or
391 waiting for the response (if any). Note that if solicited mads are send
392 using this function, it is the caller responsibility to handle retries and
393 timeouts. Return zero on success, -1 on errors.
401 void * mad_receive(void *umad, int timeout_ms);
403 Description: Wait 'timeout_ms' milliseconds for a packet to be received. Once
404 a packet is received, it is copied to the specified 'umad' buffer allocated
405 by mad_alloc() or to a internally allocated umad buffer if 'umad' is null. In
406 any case it is the caller responsibility to free the received packet using
407 mad_free(). Negative 'timeout_ms' value makes the function to block until
408 a packet is received. Zero 'timeout_ms' guarantees non blocking read,
409 i.e. either the function returns immediately with new received packet,
410 or it will return with error. Return a pointer to the received umad buffer
411 or null in case of errors.
416 int mad_respond(void *umad, ib_portid_t *portid, uint32 rstatus);
418 Description: Respond to the request mad specified by 'umad'. Send the
419 response mad to the port specified by 'portid' or the original caller of
420 'umad' if 'portid' is null. The status 'rstatus' is used to fill the mad
421 status field. The following outgoing fields are set by the function using the
422 original 'umad' fields: mgt_class, method, attribute_id, attribute_modifier,
423 SA attribute offset, vendor class OUI, mad transaction id (only the relevant
424 fields are set). Return zero on success, -1 on errors.
429 void * mad_alloc(void);
431 Description: Allocate a user mad buffer. This buffer should be de-allocated
432 using mad_free(). The mad buffer (umad) should be used be used as opaque.
433 Return a pointer to the buffer, or null if the allocation fails.
439 void mad_free(void *umad);
441 Description: Free a umad buffer previously allocated by mad_alloc
446 Address resolving functions:
451 int ib_resolve_smlid(ib_portid_t *sm_id, int timeout);
453 Description: Resolve the current SM address (LID) and copy it to
454 'sm_id'. Internally this function queries the local port for the smlid
455 field. 'timeout' is used similarly to madrpc(). Return zero on success,
461 int ib_resolve_guid(ib_portid_t *portid, uint64_t *guid,
462 ib_portid_t *sm_id, int timeout);
464 Description: Resolve the given 'guid' to find the port lid and set 'portid'
465 accordingly. The resolving process is done by sending a path record query
466 to the SM using the specified address 'sm_id'. If the 'sm_id' is null, the
467 SM address is resolved using ib_resove_smlid(). 'timeout' is used similary
468 to madrpc(). Return zero on success, -1 on errors.
471 ib_resolve_smlid, ib_path_query, madrpc
473 ib_resolve_portid_str:
476 int ib_resolve_portid_str(ib_portid_t *portid, char *addr_str,
477 int dest_type, ib_portid_t *sm_id);
479 Description: Resolve the port address specified by the string 'addr_str'
480 and the type 'dest_type' and set 'portid' accordingly. If the dest_type
481 is IB_DEST_GUID, then a path record query is sent to the SM specified by
482 'sm_id' or to the SM address found by ib_resolve_smlid() if sm_id is null. The
483 following string formats are supported:
485 IB_DEST_LID: (Decimal/Hex) integer (see strtoul for details)
486 IB_DEST_DRPATH out-ports vector "p1,p2,p3" (e.g. "0,1,6,5,20,1")
487 IB_DEST_GUID: 64 bit integer (see strtoll for details)
488 Return zero on success, -1 on errors.
491 str2drpath, ib_resolve_smlid, ib_resolve_guid
496 int ib_resolve_self(ib_portid_t *portid, int *portnum,
499 Description: Resolve the local port address and set 'portid', 'portnum' and
500 'gid' accordingly. The resolve process is done by issuing a NodeInfo and
501 PortInfo to the local port. Return zero on success, -1 on errors.
503 Port ID helper functions:
508 char * portid2str(ib_portid_t *portid);
510 Description: Return a string representation of the specified 'portid'.
513 uses a static string buffer and therefore not thread safe.
518 int portid2portnum(ib_portid_t *portid);
520 Description: Return the port number of the destination port specified by
521 the direct routed address 'portid'. Return -1 if the portid is not directed
522 route address, and 0 if it is local port address (vector [0]).
527 int str2drpath(ib_dr_path_t *path, char *routepath,
528 int drslid, int drdlid);
530 Description: Parse the 'routepath' string, and use the given 'drslid' and
531 'drdlid' set the given 'path'. Return path count or -1 on invalid string.
536 int ib_portid_set(ib_portid_t *portid, int lid, int qp, int qkey);
538 Description: Set the given 'portid' fields using the 'lid', 'qp' and 'qkey'
541 Mad fields manipulation functions:
546 uint32 mad_get_field(void *buf, int base_offset, int field);
548 Description: Return the value of 'field' from the mad buffer specified by
549 'buf' and the offset 'base_offset' within. The result is in host order.
552 ib_mad_f fields array, model of operation
557 void mad_set_field(void *buf, int base_offs, int field, uint32 val);
559 Description: Set the value of 'field' in the mad buffer specified by 'buf'
560 and the offset 'base_offset' within, using host ordered 'val'.
563 ib_mad_f fields array, model of operation
568 uint64 mad_get_field64(void *buf, int base_offs, int field);
570 Description: Same as mad_get_field, but for 64 bit fields.
575 void mad_set_field64(void *buf, int base_offs,
576 int field, uint64 val);
578 Description: Same as mad_set_field, but for 64 bit fields.
583 void mad_set_array(void *buf, int base_offs, int field, void *val);
585 Description: Same as mad_get_field, but for opaque byte arrays.
590 void mad_get_array(void *buf, int base_offs, int field, void *val);
592 Description: Same as mad_set_field, but for opaque byte arrays.
597 void mad_decode_field(uint8 *buf, int field, void *val);
599 Description: Decode 'field' within the mad buffer specified by 'buf' and
600 return it in 'val'. The result is in host order. Note that the buffer pointer
601 by 'val' must be big enough to contain the value.
604 ib_mad_f fields array, model of operation
609 void mad_encode_field(uint8 *buf, int field, void *val);
611 Description: Encode the 'field' within the mad buffer specified by 'buf'
612 using the host ordered value 'val'.
615 ib_mad_f fields array, model of operation
620 void * mad_encode(void *buf, ib_rpc_t *rpc,
621 ib_dr_path_t *drpath, void *data);
622 Description: Encode an outgoing mad headers in 'buf' using the given 'rpc',
623 the optional direct routed address 'drpath', and the optional payload
624 'data'. Return a pointer to the first byte after the mad image, or null
630 uint64 mad_trid(void);
632 Description: Set the given 'portid' fields using the 'lid', 'qp' and 'qkey'
637 int mad_build_pkt(void *umad, ib_rpc_t *rpc, ib_portid_t *dport,
638 ib_rmpp_hdr_t *rmpp, void *data);
640 Description: Encode a mad in the buffer 'umad' given the structures 'rpc',
641 'dport', the optional 'rmpp' structure and the payload 'data'. Return
642 number of encode bytes or a negative number if failed.
649 int mad_print_field(int field, char *name, void *val);
651 Description: Print a human readable format of the 'field' given the value
652 'val' to the standard output. If 'name' is non-null, it is printed as the
653 field name. Otherwise the default field name is used. Return the number of
657 ib_mad_f fields array, model of operation
662 char * mad_dump_field(int field, char *buf, int bufsz, void *val);
664 Description: Print a human readable format of the 'field' given the value
665 'val' to the given buffer 'buf'. The default field name is used. No more than
666 'bufsz' bytes are printed. Return the number of printed bytes.
671 char * mad_dump_val(int field, char *buf, int bufsz, void *val);
673 Description: Same as mad_print_field, but only the field value is printed.
682 Description: Control the library debugging level. The following levels
685 1 - print debugging information
686 2 - as level 1 but also xdump the umad IO