Skip to content

Commit 62b4f12

Browse files
MarkZhang81shefty
MarkZhang81
authored and
shefty
committed
librdmacm: Document new address resolution APIs
Add manual pages for new APIs rdma_resolve_addrinfo(), rdma_query_addrinfo(), rdma_write_cm_event(), and RAI_DNS, RAI_SA flags. Signed-off-by: Mark Zhang <[email protected]>
1 parent 78dd9e8 commit 62b4f12

File tree

7 files changed

+204
-2
lines changed

7 files changed

+204
-2
lines changed

‎librdmacm/man/CMakeLists.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,15 +51,18 @@ rdma_man_pages(
5151
rdma_post_ud_send.3
5252
rdma_post_write.3
5353
rdma_post_writev.3
54+
rdma_query_addrinfo.3.in.rst
5455
rdma_reg_msgs.3
5556
rdma_reg_read.3
5657
rdma_reg_write.3
5758
rdma_reject.3
5859
rdma_resolve_addr.3
60+
rdma_resolve_addrinfo.3.in.rst
5961
rdma_resolve_route.3
6062
rdma_server.1
6163
rdma_set_local_ece.3.md
6264
rdma_set_option.3
65+
rdma_write_cm_event.3.in.rst
6366
rdma_xclient.1
6467
rdma_xserver.1
6568
riostream.1

‎librdmacm/man/rdma_cm.7

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -229,14 +229,17 @@ rdma_post_sendv(3),
229229
rdma_post_ud_send(3),
230230
rdma_post_write(3),
231231
rdma_post_writev(3),
232+
rdma_query_addrinfo(3),
232233
rdma_reg_msgs(3),
233234
rdma_reg_read(3),
234235
rdma_reg_write(3),
235236
rdma_reject(3),
236237
rdma_resolve_addr(3),
238+
rdma_resolve_addrinfo(3),
237239
rdma_resolve_route(3),
238240
rdma_get_remote_ece(3),
239241
rdma_set_option(3),
242+
rdma_write_cm_event(3),
240243
mckey(1),
241244
rdma_client(1),
242245
rdma_server(1),

‎librdmacm/man/rdma_get_cm_event.3

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -162,7 +162,16 @@ The QP associated with a connection has exited its timewait state and is now
162162
ready to be re-used. After a QP has been disconnected, it is maintained in
163163
a timewait state to allow any in flight packets to exit the network. After
164164
the timewait state has completed, the rdma_cm will report this event.
165+
.IP RDMA_CM_EVENT_ADDRINFO_RESOLVED
166+
Address information resolution (rdma_resolve_addrinfo) completed successfully.
167+
.IP RDMA_CM_EVENT_ADDRINFO_ERROR
168+
Address information resolution (rdma_resolve_addrinfo) failed.
169+
.IP RDMA_CM_EVENT_USER
170+
This allows a user-defined event to be written to the RDMA CM event channel.
171+
Event details are specified by the user and not interpreted by the librdmacm.
172+
This event is useful for a multi-threaded application to signal a thread which
173+
may be waiting on the RDMA CM event channel.
165174
.SH "SEE ALSO"
166175
rdma_ack_cm_event(3), rdma_create_event_channel(3), rdma_resolve_addr(3),
167176
rdma_resolve_route(3), rdma_connect(3), rdma_listen(3), rdma_join_multicast(3),
168-
rdma_destroy_id(3), rdma_event_str(3)
177+
rdma_destroy_id(3), rdma_event_str(3),rdma_write_cm_event(3)

‎librdmacm/man/rdma_getaddrinfo.3

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,14 @@ If set, this flag suppresses any lengthy route resolution.
8181
.IP "RAI_FAMILY" 12
8282
If set, the ai_family setting should be used as an input hint for interpretting
8383
the node parameter.
84+
.IP "RAI_DNS" 12
85+
Indicates that address resolution should use DNS to map the node and service
86+
names to addresses. Flag is mutually exclusive with RAI_SA. DNS resolution
87+
is the default option.
88+
.IP "RAI_SA" 12
89+
Indicates that address resolution should query the Infiniband SA to map node
90+
and service names to addresses. Flag is mutually exclusive with RAI_DNS. SA
91+
resolution only applies to Infiniband ports. Non-Infiniband ports will be skipped.
8492
.IP "ai_family" 12
8593
Address family for the source and destination address. Supported families
8694
are: AF_INET, AF_INET6, and AF_IB.
@@ -131,4 +139,5 @@ Pointer to the next rdma_addrinfo structure in the list. Will be NULL
131139
if no more structures exist.
132140
.SH "SEE ALSO"
133141
rdma_create_id(3), rdma_resolve_route(3), rdma_connect(3), rdma_create_qp(3),
134-
rdma_bind_addr(3), rdma_create_ep(3), rdma_freeaddrinfo(3)
142+
rdma_bind_addr(3), rdma_create_ep(3), rdma_freeaddrinfo(3),
143+
rdma_resolve_addrinfo(3),rdma_query_addrinfo(3)

‎librdmacm/man/rdma_query_addrinfo.3.in.rst

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
===================
2+
RDMA_QUERY_ADDRINFO
3+
===================
4+
5+
---------------------------------------
6+
Query the resolved address information.
7+
---------------------------------------
8+
9+
:Date: 2025-02-06
10+
:Manual section: 3
11+
:Manual group: Librdmacm Programmer's Manual
12+
13+
14+
SYNOPSIS
15+
========
16+
17+
#include <rdma/rdma_cma.h>
18+
19+
int rdma_query_addrinfo(struct rdma_cm_id \*id, struct rdma_addrinfo \*\*info);
20+
21+
ARGUMENTS
22+
=========
23+
24+
id RDMA identifier.
25+
26+
info A pointer to a linked list of rdma_addrinfo structures containing resolved information.
27+
28+
DESCRIPTION
29+
===========
30+
31+
This function retrieves the resulting rdma_addrinfo structures from a successful rdma_resolve_addrinfo() operation.
32+
33+
RETURN VALUE
34+
============
35+
36+
On success 0 is returned, info contains a resolved address information
37+
On error -1 is returned, errno will be set to indicate the failure reason.
38+
39+
NOTES
40+
=====
41+
42+
The info must be released with rdma_freeaddrinfo(3)
43+
44+
45+
SEE ALSO
46+
========
47+
48+
rdma_getaddrinfo(3), rdma_freeaddrinfo(3), rdma_resolve_addrinfo(3)
49+
50+
AUTHOR
51+
======
52+
53+
Mark Zhang <[email protected]>

‎librdmacm/man/rdma_resolve_addrinfo.3.in.rst

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
=====================
2+
RDMA_RESOLVE_ADDRINFO
3+
=====================
4+
5+
---------------------------------------------------------
6+
Resolve RDMA addresses which supports both DNS and IB SA.
7+
---------------------------------------------------------
8+
9+
:Date: 2025-02-06
10+
:Manual section: 3
11+
:Manual group: Librdmacm Programmer's Manual
12+
13+
14+
SYNOPSIS
15+
========
16+
17+
#include <rdma/rdma_cma.h>
18+
19+
int rdma_resolve_addrinfo(struct rdma_cm_id \*id, const char \*node, const char \*service, const struct rdma_addrinfo \*hints);
20+
21+
ARGUMENTS
22+
=========
23+
24+
id RDMA identifier.
25+
26+
node Optional, name, dotted-decimal IPv4, or IPv6 hex address to resolve.
27+
28+
service The service name or port number of address.
29+
30+
hints Reference to an rdma_addrinfo structure containing hints about the type of service the caller supports.
31+
32+
DESCRIPTION
33+
===========
34+
35+
This call submits an asynchronous address resolution request. The behavior is similar to rdma_getaddrinfo(),
36+
except that the operation is asynchronous, generating an event on the RDMA CM event channel that is
37+
associated with the specified rdma_cm_id when complete. The %node, %service, and %hints parameters are defined
38+
similarly to rdma_getaddrinfo().
39+
40+
RETURN VALUE
41+
============
42+
43+
Returns 0 on success. Success indicates that asynchronous address resolution was initiated. The result of
44+
the resolution, whether successful or failed, will be reported as an event on the related event channel.
45+
46+
Returns -1 on error, errno will be set to indicate the failure reason. The address resolution was not
47+
started, and no event will be generated on the event channel.
48+
49+
NOTES
50+
=====
51+
52+
This call supports both DNS and IB SA resolution, depends on the hints.ai_flags:
53+
- RAI_DNS: Performs address resolution using DNS.
54+
- RAI_SA: Performs address resolution using the Infiniband SA. The rdma_cm_id associated with the call must be bound to an Infiniband port, or an error will occur. The %node parameter must be null (not supported). %Service should be an IB service name or ID.
55+
56+
These 2 flags are mutual-exclusive; If none of them is set then DNS is the default.
57+
58+
The cm event RDMA_CM_EVENT_ADDRINFO_RESOLVED (on success) or RDMA_CM_EVENT_ADDRINFO_ERROR (on failure) is generated.
59+
60+
SEE ALSO
61+
========
62+
63+
rdma_getaddrinfo(3), rdma_query_addrinfo(3)
64+
65+
AUTHOR
66+
======
67+
68+
Mark Zhang <[email protected]>

‎librdmacm/man/rdma_write_cm_event.3.in.rst

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
===================
2+
RDMA_WRITE_CM_EVENT
3+
===================
4+
5+
-------------------------
6+
Write an event into a CM.
7+
-------------------------
8+
9+
:Date: 2025-02-06
10+
:Manual section: 3
11+
:Manual group: Librdmacm Programmer's Manual
12+
13+
14+
SYNOPSIS
15+
========
16+
17+
#include <rdma/rdma_cma.h>
18+
19+
int rdma_write_cm_event(struct rdma_cm_id \*id, enum rdma_cm_event_type event, int status, uint64_t arg);
20+
21+
ARGUMENTS
22+
=========
23+
24+
id The RDMA identifier associated with the reported rdma_cm_event.
25+
26+
event The communication event value to report. This should be set to RDMA_CM_EVENT_USER.
27+
28+
status The status value reported in the rdma_cm_event.
29+
30+
arg A user-specified value reported in the rdma_cm_event.
31+
32+
DESCRIPTION
33+
===========
34+
35+
Write an event into a CM, with a status and an argument.
36+
37+
RETURN VALUE
38+
============
39+
40+
On success 0 is returned, on error -1 is returned, errno will be set to indicate the failure reason.
41+
42+
NOTES
43+
=====
44+
45+
This call allows an application to write a user-defined event to the event channel associated with the
46+
specified rdma_cm_id. Valid user events are: RDMA_CM_EVENT_USER. Applications may use this for internal
47+
signaling purposes, such as waking a thread blocked on the event channel.
48+
49+
SEE ALSO
50+
========
51+
52+
rdma_get_cm_event(3)
53+
54+
AUTHOR
55+
======
56+
57+
Mark Zhang <[email protected]>

0 commit comments

Comments
 (0)