[ofa-general] [PATCH] librdmacm/man: fix-up man pages
Sean Hefty
sean.hefty at intel.com
Thu Nov 1 11:30:38 PDT 2007
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 <sean.hefty at intel.com>
---
I've tried to address all comments regarding missing or unclear
documentation. I also added IB specific areas to the man pages
in a few areas to clarify how calls are operating over IB.
If anyone knows of any iWarp specific notes to add to the
documentation, please let me know. I've added a comment to
rdma_connect() indicating that the active side must send the
first message.
man/rdma_accept.3 | 25 +++++++++++++++----------
man/rdma_connect.3 | 23 +++++++++++++++++------
man/rdma_get_cm_event.3 | 4 ++--
man/rdma_resolve_addr.3 | 6 +++++-
man/rdma_resolve_route.3 | 4 +++-
5 files changed, 42 insertions(+), 20 deletions(-)
diff --git a/man/rdma_accept.3 b/man/rdma_accept.3
index c0c12d8..f604c0e 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,11 @@ 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 the maximum delay of 655 ms.
+The local ACK timeout is calculated based on the packet lifetime and local
+HCA ACK delay.
.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 71d5594..c27a3f4 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,15 @@ 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 the maximum delay of 655 ms.
+The local ACK timeout is calculated based on the packet lifetime and local
+HCA ACK delay.
+.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 987ead5..1ba8797 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 11d737d..bbba230 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
@@ -31,6 +31,10 @@ 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 8fb1826..ac1b3bc 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)
More information about the general
mailing list