Add man pages for libibverbs example programs

Signed-off-by: Roland Dreier <rolandd@cisco.com>

10 files changed, 340 insertions, 1 deletions

diff --git a/ChangeLog b/ChangeLog
index 8fb0f81..8b4848b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
 2005-08-30  Roland Dreier  <roland@cisco.com>
 
+	* man/ibv_asyncwatch.1, man/ibv_devices.1, man/ibv_devinfo.1,
+	man/ibv_rc_pingpong.1, man/ibv_srq_pingpong.1,
+	man/ibv_uc_pingpong.1, man/ibv_ud_pingpong.1: Add man pages for
+	example programs.
+
 	* examples/devinfo.c: Merge with Dotan Barak's vstat tool.
diff --git a/Makefile.am b/Makefile.am
index ca1b6be..c93dc33 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -42,13 +42,17 @@ libibverbsincludedir = $(includedir)/infiniband
 libibverbsinclude_HEADERS = include/infiniband/arch.h include/infiniband/driver.h \
     include/infiniband/kern-abi.h include/infiniband/opcode.h include/infiniband/verbs.h
 
+man_MANS = man/ibv_asyncwatch.1 man/ibv_devices.1 man/ibv_devinfo.1 \
+    man/ibv_rc_pingpong.1 man/ibv_uc_pingpong.1 man/ibv_ud_pingpong.1 \
+    man/ibv_srq_pingpong.1
+
 DEBIAN = debian/changelog debian/compat debian/control debian/copyright \
     debian/ibverbs-examples.install debian/libibverbs1.install \
     debian/libibverbs-dev.install debian/rules
 
 EXTRA_DIST = include/infiniband/driver.h include/infiniband/kern-abi.h \
     include/infiniband/opcode.h include/infiniband/verbs.h src/ibverbs.h \
-    src/libibverbs.map libibverbs.spec.in $(DEBIAN)
+    src/libibverbs.map libibverbs.spec.in $(man_MANS) $(DEBIAN)
 
 dist-hook: libibverbs.spec
 	cp libibverbs.spec $(distdir)
diff --git a/debian/ibverbs-examples.install b/debian/ibverbs-examples.install
index e772481..98d1583 100644
--- a/debian/ibverbs-examples.install
+++ b/debian/ibverbs-examples.install
@@ -1 +1,2 @@
 usr/bin
+usr/share/man/man1
diff --git a/man/ibv_asyncwatch.1 b/man/ibv_asyncwatch.1
new file mode 100644
index 0000000..b94b9cd
--- /dev/null
+++ b/man/ibv_asyncwatch.1
@@ -0,0 +1,17 @@
+.\" Copyright (C) 2005 Cisco Systems.
+.TH IBV_ASYNCWATCH 1 "August 30, 2005" "OpenIB" "USER COMMANDS"
+
+.SH NAME
+ibv_asyncwatch \- display asynchronous events
+
+.SH SYNOPSIS
+.B ibv_asyncwatch
+
+.SH DESCRIPTION
+.PP
+Display asynchronous events forwarded to userspace for an InfiniBand device.
+
+.SH AUTHORS
+.TP
+Roland Dreier
+.RI < rolandd@cisco.com >
diff --git a/man/ibv_devices.1 b/man/ibv_devices.1
new file mode 100644
index 0000000..9b398fa
--- /dev/null
+++ b/man/ibv_devices.1
@@ -0,0 +1,20 @@
+.\" Copyright (C) 2005 Cisco Systems.
+.TH IBV_DEVICES 1 "August 30, 2005" "OpenIB" "USER COMMANDS"
+
+.SH NAME
+ibv_devices \- list InfiniBand devices
+
+.SH SYNOPSIS
+.B ibv_devices
+
+.SH DESCRIPTION
+.PP
+List InfiniBand devices available for use from userspace.
+
+.SH SEE ALSO
+.BR ibv_devinfo (1)
+
+.SH AUTHORS
+.TP
+Roland Dreier
+.RI < rolandd@cisco.com >
diff --git a/man/ibv_devinfo.1 b/man/ibv_devinfo.1
new file mode 100644
index 0000000..332b939
--- /dev/null
+++ b/man/ibv_devinfo.1
@@ -0,0 +1,40 @@
+.\" Copyright (C) 2005 Cisco Systems.
+.TH IBV_DEVINFO 1 "August 30, 2005" "OpenIB" "USER COMMANDS"
+
+.SH NAME
+ibv_devinfo \- query InfiniBand devices
+
+.SH SYNOPSIS
+.B ibv_devinfo
+[\-d device] [\-i port] [\-l] [\-v]
+
+.SH DESCRIPTION
+.PP
+Print information about InfiniBand devices available for use from userspace.
+
+.SH OPTIONS
+
+.PP
+.TP
+\fB\-d\fR, \fB\-\-ib\-dev\fR=\fIDEVICE\fR
+use IB device \fIDEVICE\fR (default first device found)
+
+\fB\-i\fR, \fB\-\-ib\-port\fR=\fIPORT\fR
+query port \fIPORT\fR (default all ports)
+
+\fB\-l\fR, \fB\-\-list\fR
+only list names of InfiniBand devices
+
+\fB\-v\fR, \fB\-\-verbose\fR
+print all available information about InfiniBand devices
+
+.SH SEE ALSO
+.BR ibv_devices (1)
+
+.SH AUTHORS
+.TP
+Dotan Barak
+.RI < dotanb@mellanox.co.il >
+.TP
+Roland Dreier
+.RI < rolandd@cisco.com >
diff --git a/man/ibv_rc_pingpong.1 b/man/ibv_rc_pingpong.1
new file mode 100644
index 0000000..31c0a66
--- /dev/null
+++ b/man/ibv_rc_pingpong.1
@@ -0,0 +1,62 @@
+.\" Copyright (C) 2005 Cisco Systems.
+.TH IBV_RC_PINGPONG 1 "August 30, 2005" "OpenIB" "USER COMMANDS"
+
+.SH NAME
+ibv_rc_pingpong \- simple InfiniBand RC transport test
+
+.SH SYNOPSIS
+.B ibv_rc_pingpong
+[\-p port] [\-d device] [\-i ib port] [\-s size] [\-r rx depth]
+[\-n iters] [\-e] \fBHOSTNAME\fR
+
+.B ibv_rc_pingpong
+[\-p port] [\-d device] [\-i ib port] [\-s size] [\-r rx depth]
+[\-n iters] [\-e]
+
+.SH DESCRIPTION
+.PP
+Run a simple ping-pong test over InfiniBand via the reliable
+connected (RC) transport.
+
+.SH OPTIONS
+
+.PP
+.TP
+\fB\-p\fR, \fB\-\-port\fR=\fIPORT\fR
+use TCP port \fIPORT\fR for initial synchronization (default 18515)
+
+\fB\-d\fR, \fB\-\-ib\-dev\fR=\fIDEVICE\fR
+use IB device \fIDEVICE\fR (default first device found)
+
+\fB\-i\fR, \fB\-\-ib\-port\fR=\fIPORT\fR
+use IB port \fIPORT\fR (default port 1)
+
+\fB\-s\fR, \fB\-\-size\fR=\fISIZE\fR
+ping-pong messages of size \fISIZE\fR (default 4096)
+
+\fB\-r\fR, \fB\-\-rx\-depth\fR=\fIDEPTH\fR
+post \fIDEPTH\fR receives at a time (default 1000)
+
+\fB\-n\fR, \fB\-\-iters\fR=\fIITERS\fR
+perform \fIITERS\fR message exchanges (default 1000)
+
+\fB\-e\fR, \fB\-\-events\fR
+sleep while waiting for work completion events (default is to poll for
+completions)
+
+.SH SEE ALSO
+.BR ibv_uc_pingpong (1),
+.BR ibv_ud_pingpong (1),
+.BR ibv_srq_pingpong (1)
+
+.SH AUTHORS
+.TP
+Roland Dreier
+.RI < rolandd@cisco.com >
+
+.SH BUGS
+The network synchronization between client and server instances is
+weak, and does not prevent incompatible options from being used on the
+two instances.  The method used for retrieving work completions is not
+strictly correct, and race conditions may cause failures on some
+systems.
diff --git a/man/ibv_srq_pingpong.1 b/man/ibv_srq_pingpong.1
new file mode 100644
index 0000000..ac0185d
--- /dev/null
+++ b/man/ibv_srq_pingpong.1
@@ -0,0 +1,66 @@
+.\" Copyright (C) 2005 Cisco Systems.
+.TH IBV_SRQ_PINGPONG 1 "August 30, 2005" "OpenIB" "USER COMMANDS"
+
+.SH NAME
+ibv_srq_pingpong \- simple InfiniBand shared receive queue test
+
+.SH SYNOPSIS
+.B ibv_srq_pingpong
+[\-p port] [\-d device] [\-i ib port] [\-s size] [\-q num QPs] [\-r rx depth]
+[\-n iters] [\-e] \fBHOSTNAME\fR
+
+.B ibv_srq_pingpong
+[\-p port] [\-d device] [\-i ib port] [\-s size] [\-q num QPs] [\-r rx depth]
+[\-n iters] [\-e]
+
+.SH DESCRIPTION
+.PP
+Run a simple ping-pong test over InfiniBand via the reliable
+connected (RC) transport, using multiple queue pairs (QPs) and a
+single shared receive queue (SRQ).
+
+.SH OPTIONS
+
+.PP
+.TP
+\fB\-p\fR, \fB\-\-port\fR=\fIPORT\fR
+use TCP port \fIPORT\fR for initial synchronization (default 18515)
+
+\fB\-d\fR, \fB\-\-ib\-dev\fR=\fIDEVICE\fR
+use IB device \fIDEVICE\fR (default first device found)
+
+\fB\-i\fR, \fB\-\-ib\-port\fR=\fIPORT\fR
+use IB port \fIPORT\fR (default port 1)
+
+\fB\-s\fR, \fB\-\-size\fR=\fISIZE\fR
+ping-pong messages of size \fISIZE\fR (default 4096)
+
+\fB\-q\fR, \fB\-\-num\-qp\fR=\fINUM\fR
+use \fINUM\fR queue pairs for test (default 16)
+
+\fB\-r\fR, \fB\-\-rx\-depth\fR=\fIDEPTH\fR
+post \fIDEPTH\fR receives at a time (default 1000)
+
+\fB\-n\fR, \fB\-\-iters\fR=\fIITERS\fR
+perform \fIITERS\fR message exchanges (default 1000)
+
+\fB\-e\fR, \fB\-\-events\fR
+sleep while waiting for work completion events (default is to poll for
+completions)
+
+.SH SEE ALSO
+.BR ibv_rc_pingpong (1),
+.BR ibv_uc_pingpong (1),
+.BR ibv_ud_pingpong (1)
+
+.SH AUTHORS
+.TP
+Roland Dreier
+.RI < rolandd@cisco.com >
+
+.SH BUGS
+The network synchronization between client and server instances is
+weak, and does not prevent incompatible options from being used on the
+two instances.  The method used for retrieving work completions is not
+strictly correct, and race conditions may cause failures on some
+systems.
diff --git a/man/ibv_uc_pingpong.1 b/man/ibv_uc_pingpong.1
new file mode 100644
index 0000000..a8c0d78
--- /dev/null
+++ b/man/ibv_uc_pingpong.1
@@ -0,0 +1,62 @@
+.\" Copyright (C) 2005 Cisco Systems.
+.TH IBV_UC_PINGPONG 1 "August 30, 2005" "OpenIB" "USER COMMANDS"
+
+.SH NAME
+ibv_uc_pingpong \- simple InfiniBand UC transport test
+
+.SH SYNOPSIS
+.B ibv_uc_pingpong
+[\-p port] [\-d device] [\-i ib port] [\-s size] [\-r rx depth]
+[\-n iters] [\-e] \fBHOSTNAME\fR
+
+.B ibv_uc_pingpong
+[\-p port] [\-d device] [\-i ib port] [\-s size] [\-r rx depth]
+[\-n iters] [\-e]
+
+.SH DESCRIPTION
+.PP
+Run a simple ping-pong test over InfiniBand via the reliable
+connected (RC) transport.
+
+.SH OPTIONS
+
+.PP
+.TP
+\fB\-p\fR, \fB\-\-port\fR=\fIPORT\fR
+use TCP port \fIPORT\fR for initial synchronization (default 18515)
+
+\fB\-d\fR, \fB\-\-ib\-dev\fR=\fIDEVICE\fR
+use IB device \fIDEVICE\fR (default first device found)
+
+\fB\-i\fR, \fB\-\-ib\-port\fR=\fIPORT\fR
+use IB port \fIPORT\fR (default port 1)
+
+\fB\-s\fR, \fB\-\-size\fR=\fISIZE\fR
+ping-pong messages of size \fISIZE\fR (default 4096)
+
+\fB\-r\fR, \fB\-\-rx\-depth\fR=\fIDEPTH\fR
+post \fIDEPTH\fR receives at a time (default 1000)
+
+\fB\-n\fR, \fB\-\-iters\fR=\fIITERS\fR
+perform \fIITERS\fR message exchanges (default 1000)
+
+\fB\-e\fR, \fB\-\-events\fR
+sleep while waiting for work completion events (default is to poll for
+completions)
+
+.SH SEE ALSO
+.BR ibv_rc_pingpong (1),
+.BR ibv_ud_pingpong (1),
+.BR ibv_srq_pingpong (1)
+
+.SH AUTHORS
+.TP
+Roland Dreier
+.RI < rolandd@cisco.com >
+
+.SH BUGS
+The network synchronization between client and server instances is
+weak, and does not prevent incompatible options from being used on the
+two instances.  The method used for retrieving work completions is not
+strictly correct, and race conditions may cause failures on some
+systems.
diff --git a/man/ibv_ud_pingpong.1 b/man/ibv_ud_pingpong.1
new file mode 100644
index 0000000..493a89d
--- /dev/null
+++ b/man/ibv_ud_pingpong.1
@@ -0,0 +1,62 @@
+.\" Copyright (C) 2005 Cisco Systems.
+.TH IBV_UD_PINGPONG 1 "August 30, 2005" "OpenIB" "USER COMMANDS"
+
+.SH NAME
+ibv_ud_pingpong \- simple InfiniBand UD transport test
+
+.SH SYNOPSIS
+.B ibv_ud_pingpong
+[\-p port] [\-d device] [\-i ib port] [\-s size] [\-r rx depth]
+[\-n iters] [\-e] \fBHOSTNAME\fR
+
+.B ibv_ud_pingpong
+[\-p port] [\-d device] [\-i ib port] [\-s size] [\-r rx depth]
+[\-n iters] [\-e]
+
+.SH DESCRIPTION
+.PP
+Run a simple ping-pong test over InfiniBand via the unreliable
+datagram (UD) transport.
+
+.SH OPTIONS
+
+.PP
+.TP
+\fB\-p\fR, \fB\-\-port\fR=\fIPORT\fR
+use TCP port \fIPORT\fR for initial synchronization (default 18515)
+
+\fB\-d\fR, \fB\-\-ib\-dev\fR=\fIDEVICE\fR
+use IB device \fIDEVICE\fR (default first device found)
+
+\fB\-i\fR, \fB\-\-ib\-port\fR=\fIPORT\fR
+use IB port \fIPORT\fR (default port 1)
+
+\fB\-s\fR, \fB\-\-size\fR=\fISIZE\fR
+ping-pong messages of size \fISIZE\fR (default 2048)
+
+\fB\-r\fR, \fB\-\-rx\-depth\fR=\fIDEPTH\fR
+post \fIDEPTH\fR receives at a time (default 500)
+
+\fB\-n\fR, \fB\-\-iters\fR=\fIITERS\fR
+perform \fIITERS\fR message exchanges (default 1000)
+
+\fB\-e\fR, \fB\-\-events\fR
+sleep while waiting for work completion events (default is to poll for
+completions)
+
+.SH SEE ALSO
+.BR ibv_rc_pingpong (1),
+.BR ibv_uc_pingpong (1),
+.BR ibv_srq_pingpong (1)
+
+.SH AUTHORS
+.TP
+Roland Dreier
+.RI < rolandd@cisco.com >
+
+.SH BUGS
+The network synchronization between client and server instances is
+weak, and does not prevent incompatible options from being used on the
+two instances.  The method used for retrieving work completions is not
+strictly correct, and race conditions may cause failures on some
+systems.