From da6ff4668f3785682f8d5268f9415f2565ac1988 Mon Sep 17 00:00:00 2001 From: Sean Hefty Date: Tue, 6 Nov 2007 11:07:55 -0800 Subject: [PATCH] librdmacm/man: fix-up man pages Fix a couple of errors in the man page documentation and add infiniband specific text about QP configuration settings. This is in response to user questions about various settings based on feedback from Or. Signed-off-by: Sean Hefty --- man/rdma_accept.3 | 28 ++++++++++++++++++---------- man/rdma_connect.3 | 25 +++++++++++++++++++------ man/rdma_get_cm_event.3 | 4 ++-- man/rdma_resolve_addr.3 | 10 ++++++++-- man/rdma_resolve_route.3 | 4 +++- 5 files changed, 50 insertions(+), 21 deletions(-) diff --git a/man/rdma_accept.3 b/man/rdma_accept.3 index c0c12d88..e47ceb0f 100644 --- a/man/rdma_accept.3 +++ b/man/rdma_accept.3 @@ -1,4 +1,4 @@ -.TH "RDMA_ACCEPT" 3 "2007-05-15" "librdmacm" "Librdmacm Programmer's Manual" librdmacm +.TH "RDMA_ACCEPT" 3 "2007-10-31" "librdmacm" "Librdmacm Programmer's Manual" librdmacm .SH NAME rdma_accept \- Called to accept a connection request. .SH SYNOPSIS @@ -53,17 +53,16 @@ This value must be less than or equal to the local RDMA device attribute max_qp_init_rd_atom and the initiator_depth value reported in the connect request event. .IP flow_control -Specifies if hardware flow control should be used. Applies only to RDMA_PS_TCP. +Specifies if hardware flow control is available. This value is exchanged +with the remote peer and is not used to configure the QP. Applies only to +RDMA_PS_TCP. .IP retry_count -The maximum number of times that a data transfer operation should be retried -on the connection when an error occurs. This setting controls the number of -times to retry send, RDMA, and atomic operations when timeouts occur. -Applies only to RDMA_PS_TCP. +This value is ignored. .IP rnr_retry_count -The maximum number of times that a send operation should be retried on a -connection after receiving a receiver not ready (RNR) error. RNR errors are -generated when a send request arrives before a buffer has been posted to -receive the incoming data. Applies only to RDMA_PS_TCP. +The maximum number of times that a send operation from the remote peer +should be retried on a connection after receiving a receiver not ready (RNR) +error. RNR errors are generated when a send request arrives before a buffer +has been posted to receive the incoming data. Applies only to RDMA_PS_TCP. .IP srq Specifies if the QP associated with the connection is using a shared receive queue. This field is ignored by the library if a QP has been created on the @@ -71,5 +70,14 @@ rdma_cm_id. Applies only to RDMA_PS_TCP. .IP qp_num Specifies the QP number associated with the connection. This field is ignored by the library if a QP has been created on the rdma_cm_id. +.SH "INFINIBAND SPECIFIC" +In addition to the connection properties defined above, InfiniBand QPs are +configured with minimum RNR NAK timer and local ACK timeout values. The +minimum RNR NAK timer value is set to 0, for a delay of 655 ms. +The local ACK timeout is calculated based on the packet lifetime and local +HCA ACK delay. The packet lifetime is determined by the InfiniBand Subnet +Administrator and is part of the route (path record) information obtained +by the active side of the connection. The HCA ACK delay is a property of +the locally used HCA. .SH "SEE ALSO" rdma_listen(3), rdma_reject(3), rdma_get_cm_event(3) diff --git a/man/rdma_connect.3 b/man/rdma_connect.3 index 71d55948..ed6a1908 100644 --- a/man/rdma_connect.3 +++ b/man/rdma_connect.3 @@ -1,4 +1,4 @@ -.TH "RDMA_CONNECT" 3 "2007-05-15" "librdmacm" "Librdmacm Programmer's Manual" librdmacm +.TH "RDMA_CONNECT" 3 "2007-10-31" "librdmacm" "Librdmacm Programmer's Manual" librdmacm .SH NAME rdma_connect \- Initiate an active connection request. .SH SYNOPSIS @@ -44,17 +44,19 @@ This value must be less than or equal to the local RDMA device attribute max_qp_init_rd_atom and remote RDMA device attribute max_qp_rd_atom. The remote endpoint can adjust this value when accepting the connection. .IP flow_control -Specifies if hardware flow control should be used. Applies only to RDMA_PS_TCP. +Specifies if hardware flow control is available. This value is exchanged +with the remote peer and is not used to configure the QP. Applies only to +RDMA_PS_TCP. .IP retry_count The maximum number of times that a data transfer operation should be retried on the connection when an error occurs. This setting controls the number of times to retry send, RDMA, and atomic operations when timeouts occur. Applies only to RDMA_PS_TCP. .IP rnr_retry_count -The maximum number of times that a send operation should be retried on a -connection after receiving a receiver not ready (RNR) error. RNR errors are -generated when a send request arrives before a buffer has been posted to -receive the incoming data. Applies only to RDMA_PS_TCP. +The maximum number of times that a send operation from the remote peer +should be retried on a connection after receiving a receiver not ready (RNR) +error. RNR errors are generated when a send request arrives before a buffer +has been posted to receive the incoming data. Applies only to RDMA_PS_TCP. .IP srq Specifies if the QP associated with the connection is using a shared receive queue. This field is ignored by the library if a QP has been created on the @@ -63,6 +65,17 @@ rdma_cm_id. Applies only to RDMA_PS_TCP. Specifies the QP number associated with the connection. This field is ignored by the library if a QP has been created on the rdma_cm_id. Applies only to RDMA_PS_TCP. +.SH "INFINIBAND SPECIFIC" +In addition to the connection properties defined above, InfiniBand QPs are +configured with minimum RNR NAK timer and local ACK timeout values. The +minimum RNR NAK timer value is set to 0, for a delay of 655 ms. +The local ACK timeout is calculated based on the packet lifetime and local +HCA ACK delay. The packet lifetime is determined by the InfiniBand Subnet +Administrator and is part of the resolved route (path record) information. +The HCA ACK delay is a property of the locally used HCA. +.SH "IWARP SPECIFIC" +Connections established over iWarp RDMA devices currently require that the +active side of the connection send the first message. .SH "SEE ALSO" rdma_cm(7), rdma_create_id(3), rdma_resolve_route(3), rdma_disconnect(3), rdma_listen(3), rdma_get_cm_event(3) diff --git a/man/rdma_get_cm_event.3 b/man/rdma_get_cm_event.3 index 987ead56..1ba8797a 100644 --- a/man/rdma_get_cm_event.3 +++ b/man/rdma_get_cm_event.3 @@ -1,4 +1,4 @@ -.TH "RDMA_GET_CM_EVENT" 3 "2007-05-15" "librdmacm" "Librdmacm Programmer's Manual" librdmacm +.TH "RDMA_GET_CM_EVENT" 3 "2007-10-31" "librdmacm" "Librdmacm Programmer's Manual" librdmacm .SH NAME rdma_get_cm_event \- Retrieves the next pending communication event. .SH SYNOPSIS @@ -91,7 +91,7 @@ that the recipient may have outstanding. This field matches the responder resources specified by the remote node when calling rdma_connect and rdma_accept. .IP "flow_control" 12 -Indicates if hardware level flow control is provided. +Indicates if hardware level flow control is provided by the sender. .IP "retry_count" 12 For RDMA_CM_EVENT_CONNECT_REQUEST events only, indicates the number of times that the recipient should retry send operations. diff --git a/man/rdma_resolve_addr.3 b/man/rdma_resolve_addr.3 index 11d737de..e612606b 100644 --- a/man/rdma_resolve_addr.3 +++ b/man/rdma_resolve_addr.3 @@ -1,4 +1,4 @@ -.TH "RDMA_RESOLVE_ADDR" 3 "2007-05-15" "librdmacm" "Librdmacm Programmer's Manual" librdmacm +.TH "RDMA_RESOLVE_ADDR" 3 "2007-10-31" "librdmacm" "Librdmacm Programmer's Manual" librdmacm .SH NAME rdma_resolve_addr \- Resolve destination and optional source addresses. .SH SYNOPSIS @@ -24,13 +24,19 @@ to an RDMA address. If successful, the specified rdma_cm_id will be bound to a local device. .SH "NOTES" This call is used to map a given destination IP address to a usable RDMA -address. If a source address is given, the rdma_cm_id is bound to that +address. The IP to RDMA address mapping is done using the local routing +tables, or via ARP. +If a source address is given, the rdma_cm_id is bound to that address, the same as if rdma_bind_addr were called. If no source address is given, and the rdma_cm_id has not yet been bound to a device, then the rdma_cm_id will be bound to a source address based on the local routing tables. After this call, the rdma_cm_id will be bound to an RDMA device. This call is typically made from the active side of a connection before calling rdma_resolve_route and rdma_connect. +.SH "INFINIBAND SPECIFIC" +This call maps the destination and, if given, source IP addresses to GIDs. +In order to perform the mapping, IPoIB must be running on both the local +and remote nodes. .SH "SEE ALSO" rdma_create_id(3), rdma_resolve_route(3), rdma_connect(3), rdma_create_qp(3), rdma_get_cm_event(3), rdma_bind_addr(3), rdma_get_src_port(3), diff --git a/man/rdma_resolve_route.3 b/man/rdma_resolve_route.3 index 8fb18260..ac1b3bcc 100644 --- a/man/rdma_resolve_route.3 +++ b/man/rdma_resolve_route.3 @@ -1,4 +1,4 @@ -.TH "RDMA_RESOLVE_ROUTE" 3 "2007-05-15" "librdmacm" "Librdmacm Programmer's Manual" librdmacm +.TH "RDMA_RESOLVE_ROUTE" 3 "2007-10-31" "librdmacm" "Librdmacm Programmer's Manual" librdmacm .SH NAME rdma_resolve_route \- Resolve the route information needed to establish a connection. .SH SYNOPSIS @@ -19,5 +19,7 @@ by calling rdma_resolve_addr. .SH "NOTES" This is called on the client side of a connection after calling rdma_resolve_addr, but before calling rdma_connect. +.SH "INFINIBAND SPECIFIC" +This call obtains a path record that is used by the connection. .SH "SEE ALSO" rdma_resolve_addr(3), rdma_connect(3), rdma_get_cm_event(3) -- 2.46.0