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