1---
2layout: page
3title: fi_pingpong(1)
4tagline: Libfabric Programmer's Manual
5---
6{% include JB/setup %}
7
8
9# NAME
10
11fi_pingpong  \- Quick and simple pingpong test for libfabric
12
13
14# SYNOPSIS
15```
16 fi_pingpong [OPTIONS]						start server
17 fi_pingpong [OPTIONS] <server address>		connect to server
18```
19
20
21# DESCRIPTION
22
23fi_pingpong is a pingpong test for the core feature of the libfabric library:
24transmitting data between two processes. fi_pingpong also displays aggregated
25statistics after each test run, and can additionally verify data integrity upon
26receipt.
27
28By default, the datagram (FI_EP_DGRAM) endpoint is used for the test, unless
29otherwise specified via `-e`.
30
31# HOW TO RUN TESTS
32
33Two copies of the program must be launched: first, one copy must be launched as
34the server. Second, another copy is launched with the address of the server.
35
36As a client-server test, each have the following usage model:
37
38## Start the server
39```
40server$ fi_pingpong
41```
42
43## Start the client
44```
45client$ fi_pingpong <server address>
46```
47
48
49# OPTIONS
50
51The server and client must be able to communicate properly for the fi_pingpong
52utility to function. If any of the `-e`, `-I`, `-S`, or `-p` options are used,
53then they must be specified on the invocation for both the server and the
54client process. If the `-d` option is specified on the server, then the client
55will select the appropriate domain if no hint is provided on the client side.
56If the `-d` option is specified on the client, then it must also be specified
57on the server. If both the server and client specify the `-d` option and the
58given domains cannot communicate, then the application will fail.
59
60## Control Messaging
61
62*-B \<src_port\>*
63: The non-default source port number of the control socket. If this is not
64  provided then the server will bind to port 47592 by default and the client
65  will allow the port to be selected automatically.
66
67*-P \<dest_port\>*
68: The non-default destination port number of the control socket. If this is not
69  provided then the client will connect to 47592 by default. The server ignores
70  this option.
71
72## Fabric Filtering
73
74*-p \<provider_name\>*
75: The name of the underlying fabric provider (e.g., sockets, psm, usnic, etc.).
76  If a provider is not specified via the -p switch, the test will pick one from
77  the list of available providers (as returned by fi_getinfo(3)).
78
79*-e \<endpoint\>*
80: The type of endpoint to be used for data messaging between the two processes.
81  Supported values are dgram, rdm, and msg. For more information on endpoint
82  types, see fi_endpoint(3).
83
84*-d \<domain\>*
85: The name of the specific domain to be used.
86
87## Test Options
88
89*-I \<iter\>*
90: The number of iterations of the test will run.
91
92*-S \<msg_size\>*
93: The specific size of the message in bytes the test will use or 'all' to run
94  all the default sizes.
95
96*-c*
97: Activate data integrity checks at the receiver (note: this will degrade
98  performance).
99
100## Utility
101
102*-v*
103: Activate output debugging (warning: highly verbose)
104
105*-h*
106: Displays help output for the pingpong test.
107
108
109# USAGE EXAMPLES
110
111## A simple example
112
113### Server: `fi_pingpong -p <provider_name>`
114`server$ fi_pingpong -p sockets`
115
116### Client: `fi_pingpong -p <provider_name> <server_addr>`
117`client$ fi_pingpong -p sockets 192.168.0.123`
118
119## An example with various options
120
121### Server:
122`server$ fi_pingpong -p usnic -I 1000 -S 1024`
123
124### Client:
125`client$ fi_pingpong -p usnic -I 1000 -S 1024 192.168.0.123`
126
127
128Specifically, this will run a pingpong test with:
129
130- usNIC provider
131- 1000 iterations
132- 1024 bytes message size
133- server node as 192.168.0.123
134
135## A longer test
136
137### Server:
138`server$ fi_pingpong -p usnic -I 10000 -S all`
139
140### Client:
141`client$ fi_pingpong -p usnic -I 10000 -S all 192.168.0.123`
142
143
144# DEFAULTS
145
146There is no default provider; if a provider is not specified via the `-p`
147switch, the test will pick one from the list of available providers (as
148returned by fi_getinfo(3)).
149
150If no endpoint type is specified, 'dgram' is used.
151
152The default tested sizes are:  64, 256, 1024, 4096, 65536, and 1048576. The
153test will only test sizes that are within the selected endpoints maximum
154message size boundary.
155
156# OUTPUT
157
158Each test generates data messages which are accounted for. Specifically, the
159displayed statistics at the end are :
160
161 - *bytes*          : number of bytes per message sent
162 - *#sent*          : number of messages (ping) sent from the client to the
163                      server
164 - *#ack*           : number of replies (pong) of the server received by the
165                      client
166 - *total*          : amount of memory exchanged between the processes
167 - *time*           : duration of this single test
168 - *MB/sec*         : throughput computed from *total* and *time*
169 - *usec/xfer*      : average time for transferring a message outbound (ping or
170                      pong) in microseconds
171 - *Mxfers/sec*     : average amount of transfers of message outbound per
172                      second
173
174# SEE ALSO
175
176[`fi_getinfo`(3)](fi_getinfo.3.html),
177[`fi_endpoint`(3)](fi_endpoint.3.html)
178[`fabric`(7)](fabric.7.html),
179