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]>

Author: MarkZhang81

librdmacm/man/CMakeLists.txt

@@ -51,15 +51,18 @@ rdma_man_pages(
   rdma_post_ud_send.3
   rdma_post_write.3
   rdma_post_writev.3
+  rdma_query_addrinfo.3.in.rst
   rdma_reg_msgs.3
   rdma_reg_read.3
   rdma_reg_write.3
   rdma_reject.3
   rdma_resolve_addr.3
+  rdma_resolve_addrinfo.3.in.rst
   rdma_resolve_route.3
   rdma_server.1
   rdma_set_local_ece.3.md
   rdma_set_option.3
+  rdma_write_cm_event.3.in.rst
   rdma_xclient.1
   rdma_xserver.1
   riostream.1

librdmacm/man/rdma_cm.7

@@ -229,14 +229,17 @@ rdma_post_sendv(3),
 rdma_post_ud_send(3),
 rdma_post_write(3),
 rdma_post_writev(3),
+rdma_query_addrinfo(3),
 rdma_reg_msgs(3),
 rdma_reg_read(3),
 rdma_reg_write(3),
 rdma_reject(3),
 rdma_resolve_addr(3),
+rdma_resolve_addrinfo(3),
 rdma_resolve_route(3),
 rdma_get_remote_ece(3),
 rdma_set_option(3),
+rdma_write_cm_event(3),
 mckey(1),
 rdma_client(1),
 rdma_server(1),

librdmacm/man/rdma_get_cm_event.3

@@ -162,7 +162,16 @@ The QP associated with a connection has exited its timewait state and is now
 ready to be re-used.  After a QP has been disconnected, it is maintained in
 a timewait state to allow any in flight packets to exit the network.  After
 the timewait state has completed, the rdma_cm will report this event.
+.IP RDMA_CM_EVENT_ADDRINFO_RESOLVED
+Address information resolution (rdma_resolve_addrinfo) completed successfully.
+.IP RDMA_CM_EVENT_ADDRINFO_ERROR
+Address information resolution (rdma_resolve_addrinfo) failed.
+.IP RDMA_CM_EVENT_USER
+This allows a user-defined event to be written to the RDMA CM event channel.
+Event details are specified by the user and not interpreted by the librdmacm.
+This event is useful for a multi-threaded application to signal a thread which
+may be waiting on the RDMA CM event channel.
 .SH "SEE ALSO"
 rdma_ack_cm_event(3), rdma_create_event_channel(3), rdma_resolve_addr(3),
 rdma_resolve_route(3), rdma_connect(3), rdma_listen(3), rdma_join_multicast(3),
-rdma_destroy_id(3), rdma_event_str(3)
+rdma_destroy_id(3), rdma_event_str(3),rdma_write_cm_event(3)

librdmacm/man/rdma_getaddrinfo.3

@@ -81,6 +81,14 @@ If set, this flag suppresses any lengthy route resolution.
 .IP "RAI_FAMILY" 12
 If set, the ai_family setting should be used as an input hint for interpretting
 the node parameter.
+.IP "RAI_DNS" 12
+Indicates that address resolution should use DNS to map the node and service
+names to addresses. Flag is mutually exclusive with RAI_SA. DNS resolution
+is the default option.
+.IP "RAI_SA" 12
+Indicates that address resolution should query the Infiniband SA to map node
+and service names to addresses. Flag is mutually exclusive with RAI_DNS. SA
+resolution only applies to Infiniband ports. Non-Infiniband ports will be skipped.
 .IP "ai_family" 12
 Address family for the source and destination address.  Supported families
 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
 if no more structures exist.
 .SH "SEE ALSO"
 rdma_create_id(3), rdma_resolve_route(3), rdma_connect(3), rdma_create_qp(3),
-rdma_bind_addr(3), rdma_create_ep(3), rdma_freeaddrinfo(3)
+rdma_bind_addr(3), rdma_create_ep(3), rdma_freeaddrinfo(3),
+rdma_resolve_addrinfo(3),rdma_query_addrinfo(3)

librdmacm/man/rdma_query_addrinfo.3.in.rst

@@ -0,0 +1,53 @@
+===================
+RDMA_QUERY_ADDRINFO
+===================
+
+---------------------------------------
+Query the resolved address information.
+---------------------------------------
+
+:Date: 2025-02-06
+:Manual section: 3
+:Manual group: Librdmacm Programmer's Manual
+
+
+SYNOPSIS
+========
+
+#include <rdma/rdma_cma.h>
+
+int rdma_query_addrinfo(struct rdma_cm_id \*id, struct rdma_addrinfo \*\*info);
+
+ARGUMENTS
+=========
+
+id      RDMA identifier.
+
+info    A pointer to a linked list of rdma_addrinfo structures containing resolved information.
+
+DESCRIPTION
+===========
+
+This function retrieves the resulting rdma_addrinfo structures from a successful rdma_resolve_addrinfo() operation.
+
+RETURN VALUE
+============
+
+On success 0 is returned, info contains a resolved address information
+On error -1 is returned, errno will be set to indicate the failure reason.
+
+NOTES
+=====
+
+The info must be released with rdma_freeaddrinfo(3)
+
+
+SEE ALSO
+========
+
+rdma_getaddrinfo(3), rdma_freeaddrinfo(3), rdma_resolve_addrinfo(3)
+
+AUTHOR
+======
+
+Mark Zhang <[email protected]>

librdmacm/man/rdma_resolve_addrinfo.3.in.rst

@@ -0,0 +1,68 @@
+=====================
+RDMA_RESOLVE_ADDRINFO
+=====================
+
+---------------------------------------------------------
+Resolve RDMA addresses which supports both DNS and IB SA.
+---------------------------------------------------------
+
+:Date: 2025-02-06
+:Manual section: 3
+:Manual group: Librdmacm Programmer's Manual
+
+
+SYNOPSIS
+========
+
+#include <rdma/rdma_cma.h>
+
+int rdma_resolve_addrinfo(struct rdma_cm_id \*id, const char \*node, const char \*service, const struct rdma_addrinfo \*hints);
+
+ARGUMENTS
+=========
+
+id	RDMA identifier.
+
+node    Optional, name, dotted-decimal IPv4, or IPv6 hex address to resolve.
+
+service The service name or port number of address.
+
+hints   Reference to an rdma_addrinfo structure containing hints about the type of service the caller supports.
+
+DESCRIPTION
+===========
+
+This call submits an asynchronous address resolution request. The behavior is similar to rdma_getaddrinfo(),
+except that the operation is asynchronous, generating an event on the RDMA CM event channel that is
+associated with the specified rdma_cm_id when complete. The %node, %service, and %hints parameters are defined
+similarly to rdma_getaddrinfo().
+
+RETURN VALUE
+============
+
+Returns 0 on success. Success indicates that asynchronous address resolution was initiated. The result of
+the resolution, whether successful or failed, will be reported as an event on the related event channel.
+
+Returns -1 on error, errno will be set to indicate the failure reason. The address resolution was not
+started, and no event will be generated on the event channel.
+
+NOTES
+=====
+
+This call supports both DNS and IB SA resolution, depends on the hints.ai_flags:
+  - RAI_DNS: Performs address resolution using DNS.
+  - 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.
+
+These 2 flags are mutual-exclusive; If none of them is set then DNS is the default.
+
+The cm event RDMA_CM_EVENT_ADDRINFO_RESOLVED (on success) or RDMA_CM_EVENT_ADDRINFO_ERROR (on failure) is generated.
+
+SEE ALSO
+========
+
+rdma_getaddrinfo(3), rdma_query_addrinfo(3)
+
+AUTHOR
+======
+
+Mark Zhang <[email protected]>

librdmacm/man/rdma_write_cm_event.3.in.rst

@@ -0,0 +1,57 @@
+===================
+RDMA_WRITE_CM_EVENT
+===================
+
+-------------------------
+Write an event into a CM.
+-------------------------
+
+:Date: 2025-02-06
+:Manual section: 3
+:Manual group: Librdmacm Programmer's Manual
+
+
+SYNOPSIS
+========
+
+#include <rdma/rdma_cma.h>
+
+int rdma_write_cm_event(struct rdma_cm_id \*id, enum rdma_cm_event_type event, int status, uint64_t arg);
+
+ARGUMENTS
+=========
+
+id      The RDMA identifier associated with the reported rdma_cm_event.
+
+event   The communication event value to report. This should be set to RDMA_CM_EVENT_USER.
+
+status  The status value reported in the rdma_cm_event.
+
+arg     A user-specified value reported in the rdma_cm_event.
+
+DESCRIPTION
+===========
+
+Write an event into a CM, with a status and an argument.
+
+RETURN VALUE
+============
+
+On success 0 is returned, on error -1 is returned, errno will be set to indicate the failure reason.
+
+NOTES
+=====
+
+This call allows an application to write a user-defined event to the event channel associated with the
+specified rdma_cm_id. Valid user events are: RDMA_CM_EVENT_USER. Applications may use this for internal
+signaling purposes, such as waking a thread blocked on the event channel.
+
+SEE ALSO
+========
+
+rdma_get_cm_event(3)
+
+AUTHOR
+======
+
+Mark Zhang <[email protected]>