← Back to branch summary

~ubuntu-branches/ubuntu/karmic/netpipe/karmic

« back to all changes in this revision

Viewing changes to debian/netpipe.1

  • Committer: Bazaar Package Importer
  • Author(s): Camm Maguire
  • Date: 2004-10-26 20:28:24 UTC
  • mfrom: (1.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20041026202824-fdmack9iksv54eqe
Tags: 3.6.2-1
New upstream release

Show diffs side-by-side

added added

removed removed

Lines of Context:
debian/netpipe.1
 
1
.\" -*- nroff -*-
 
2
.\"
 
3
.\" NetPIPE -- Network Protocol Independent Performance Evaluator.
 
4
.\" Copyright 1997, 1998 Iowa State University Research Foundation, Inc.
 
5
.\"
 
6
.\" This program is free software; you can redistribute it and/or modify
 
7
.\" it under the terms of the GNU General Public License as published by
 
8
.\" the Free Software Foundation.  You should have received a copy of the
 
9
.\" GNU General Public License along with this program; if not, write to the
 
10
.\" Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 
11
.\"
 
12
.\" netpipe.1
 
13
.\" Created: Mon Jun 15 1998 by Guy Helmer
 
14
.\" Rewritten:   Jun  1 2004 by Dave Turner
 
15
.\"
 
16
.\" $Id: netpipe.1,v 1.3 1998/09/24 16:23:59 ghelmer Exp $
 
17
.\"
 
18
.TH netpipe 1 "June 1, 2004" "NetPIPE" "netpipe"
 
19
 
 
20
.SH NAME
 
21
NetPIPE \- 
 
22
.IB Net work
 
23
.IB P rotocol
 
24
.IB I ndependent
 
25
.IB P erformance
 
26
.IB E valuator
 
27
 
 
28
.SH SYNOPSIS
 
29
.B NPtcp
 
30
[\c
 
31
.BI \-h \ receiver_hostname\fR\c
 
32
]
 
33
[\c
 
34
.BI \-b \ TCP_buffer_sizes\fR\c
 
35
]
 
36
[options]
 
37
 
 
38
.PP
 
39
 
 
40
mpirun
 
41
[\c
 
42
.BI \-machinefile \ hostlist\fR\c
 
43
]
 
44
-np 2
 
45
.B NPmpi
 
46
[-a] [-S] [-z] [options]
 
47
 
 
48
.PP
 
49
 
 
50
mpirun
 
51
[\c
 
52
.BI \-machinefile \ hostlist\fR\c
 
53
]
 
54
-np 2
 
55
.B NPmpi2
 
56
[-f] [-g] [options]
 
57
 
 
58
 
 
59
.PP
 
60
 
 
61
.B NPpvm
 
62
[options]
 
63
 
 
64
See the TESTING sections below for a more complete description of
 
65
how to run NetPIPE in each environment.
 
66
The OPTIONS section describes the general options available for
 
67
all modules.
 
68
See the README file from the tar-ball at 
 
69
http://www.scl.ameslab.gov/Projects/NetPIPE/ for documentation on
 
70
the InfiniBand, GM, SHMEM, LAPI, and memcpy modules.
 
71
 
 
72
.SH DESCRIPTION
 
73
.PP
 
74
 
 
75
.B NetPIPE
 
76
uses a simple series of ping-pong tests over a range of message
 
77
sizes to provide a complete measure of the performance of a network.
 
78
It bounces messages of increasing size between two processes, whether across a 
 
79
network or within an SMP system. 
 
80
Message sizes are chosen at regular intervals, and with slight perturbations, 
 
81
to provide a complete evaluation of the communication system. 
 
82
Each data point involves many ping-pong tests to provide an accurate timing. 
 
83
Latencies are calculated by dividing the round trip time in half for small 
 
84
messages ( less than 64 Bytes ). 
 
85
.PP
 
86
The communication time for small messages is dominated by the 
 
87
overhead in the communication layers, meaning that the transmission
 
88
is latency bound.
 
89
For larger messages, the communication rate becomes bandwidth limited by 
 
90
some component in
 
91
the communication subsystem (PCI bus, network card link, network switch).
 
92
.PP
 
93
These measurements can be done at the message-passing layer 
 
94
(MPI, MPI-2, and PVM) or at the native communications layers
 
95
that that run upon (TCP/IP, GM for Myrinet cards, InfiniBand,
 
96
SHMEM for the Cray T3E systems, and LAPI for IBM SP systems).
 
97
Recent work is being aimed at measuring some internal system properties
 
98
such as the memcpy module that measures the internal memory copy rates,
 
99
or a disk module under development that measures the performance
 
100
to various I/O devices.
 
101
.PP
 
102
 
 
103
Some uses for NetPIPE include:
 
104
.RS
 
105
.PP
 
106
Comparing the latency and maximum throughput of various network cards.
 
107
.PP
 
108
Comparing the performance between different types of networks.
 
109
.PP
 
110
Looking for inefficiencies in the message-passing layer by comparing it
 
111
to the native communication layer.
 
112
.PP
 
113
Optimizing the message-passing layer and tune OS and driver parameters
 
114
for optimal performance of the communication subsystem.
 
115
 
 
116
.RE
 
117
.PP
 
118
 
 
119
.B NetPIPE
 
120
is provided with many modules allowing it to interface with a wide
 
121
variety of communication layers.
 
122
It is fairly easy to write new interfaces for other reliable protocols
 
123
by using the existing modules as examples.
 
124
 
 
125
 
 
126
 
 
127
.SH TESTING TCP
 
128
.PP
 
129
NPtcp can now be launched in two ways, by manually starting NPtcp on
 
130
both systems or by using a nplaunch script.  To manually start NPtcp,
 
131
the NetPIPE receiver must be 
 
132
started first on the remote system using the command:
 
133
.PP
 
134
.Ex
 
135
NPtcp [options]
 
136
.Ee
 
137
.PP
 
138
then the primary transmitter is started on the local system with the
 
139
command
 
140
.PP
 
141
.Ex
 
142
NPtcp \-h 
 
143
.I receiver_hostname
 
144
[options]
 
145
.Ee
 
146
.PP
 
147
Any options used must be the same on both sides.
 
148
 
 
149
The nplaunch script uses ssh to launch the remote receiver
 
150
before starting the local transmitter.  To use rsh, simply change
 
151
the nplaunch script.
 
152
.PP
 
153
.Ex
 
154
nplaunch NPtcp -h 
 
155
.I receiver_hostname
 
156
[options]
 
157
.Ee
 
158
.PP
 
159
The
 
160
.BI \-b \ TCP_buffer_sizes\fR\c
 
161
 option sets the TCP socket buffer size, which can greatly influence
 
162
the maximum throughput on some systems.  A throughput graph that
 
163
flattens out suddenly may be a sign of the performance being limited
 
164
by the socket buffer sizes.
 
165
 
 
166
 
 
167
.SH TESTING MPI and MPI-2
 
168
.PP
 
169
Use of the MPI interface for NetPIPE depends on the MPI implementation
 
170
being used.  
 
171
All will require the number of processes to be specified, usually
 
172
with a 
 
173
.I -np 2 
 
174
argument.  Clusters environments may require a list of the 
 
175
hosts being used, either during initialization of MPI (during lamboot
 
176
for LAM-MPI) or when each job is run (using a -machinefile argument
 
177
for MPICH).
 
178
For LAM-MPI, for example, put the list of hosts in hostlist then boot LAM 
 
179
and run NetPIPE using:
 
180
.PP
 
181
.Ex
 
182
lamboot -v -b 
 
183
.I hostlist
 
184
.PP
 
185
mpirun \-np 2 NPmpi [NetPIPE options]
 
186
.Ee
 
187
.PP
 
188
 
 
189
For MPICH use a command like:
 
190
.PP
 
191
.Ex
 
192
mpirun \-machinefile 
 
193
.I hostlist 
 
194
\-np 2 NPmpi [NetPIPE options]
 
195
.Ee
 
196
.PP
 
197
 
 
198
To test the 1-sided communications of the MPI-2 standard, compile
 
199
using:
 
200
.PP
 
201
.Ex
 
202
.B make mpi2
 
203
.Ee
 
204
.PP
 
205
Running as described above and MPI will use 1-sided MPI_Put()
 
206
calls in both directions, with each receiver blocking until the
 
207
last byte has been overwritten before bouncing the message back.
 
208
Use the 
 
209
.I -f
 
210
option to force usage of a fence to block rather than an overwrite
 
211
of the last byte.
 
212
The 
 
213
.I -g
 
214
option will use MP_Get() functions to transfer the data rather than
 
215
MP_Put().
 
216
 
 
217
 
 
218
.SH TESTING PVM
 
219
.PP
 
220
Start the pvm system using:
 
221
.PP
 
222
.Ex
 
223
pvm
 
224
.Ee
 
225
.PP
 
226
and adding a second machine with the PVM command
 
227
.PP
 
228
.Ex
 
229
add 
 
230
.I receiver_hostname
 
231
.Ee
 
232
.PP
 
233
Exit the PVM command line interface using quit, then run the PVM NetPIPE
 
234
receiver on one system with the command:
 
235
.PP
 
236
.Ex
 
237
NPpvm [options]
 
238
.Ee
 
239
.PP
 
240
and run the TCP NetPIPE transmitter on the other system with the
 
241
command:
 
242
.PP
 
243
.Ex
 
244
NPpvm -h 
 
245
.I receiver hostname
 
246
[options]
 
247
.Ee
 
248
.PP
 
249
Any options used must be the same on both sides.
 
250
The nplaunch script may also be used with NPpvm as described above
 
251
for NPtcp.
 
252
 
 
253
.SH TESTING METHODOLOGY
 
254
.PP
 
255
.B NetPIPE
 
256
tests network performance by sending a number of messages at each
 
257
block size, starting from the lower bound on the message sizes.
 
258
 
 
259
The message size is incremented until the upper bound on the message size is
 
260
reached or the time to transmit a block exceeds one second, which ever
 
261
occurs first.  Message sizes are chosen at regular intervals, and for
 
262
slight perturbations from them to provide a more complete evaluation
 
263
of the communication subsystem.
 
264
.PP
 
265
The 
 
266
.B NetPIPE\c
 
267
 output file may be graphed using a program such as
 
268
.B gnuplot(1)\.
 
269
The output file contains three columns: the number of bytes in the block,
 
270
the transfer rate in bits per second, and
 
271
the time to transfer the block (half the round-trip time).
 
272
The first two columns are normally used to graph the throughput
 
273
vs block size, while the third column provides the latency.
 
274
For example, the 
 
275
.B throughput versus block size
 
276
graph can be created by graphing bytes versus bits per second.
 
277
Sample
 
278
.B gnuplot(1)
 
279
commands for such a graph would be
 
280
.PP
 
281
.Ex
 
282
set logscale x
 
283
.Ee
 
284
.PP
 
285
.Ex
 
286
plot "np.out"
 
287
.Ee
 
288
 
 
289
.ne 5
 
290
.SH OPTIONS
 
291
.TP
 
292
.B \-a
 
293
asynchronous mode: prepost receives (MPI, IB modules)
 
294
.ne 3
 
295
.TP
 
296
.BI \-b \ \fITCP_buffer_sizes\fR
 
297
Set the send and receive TCP buffer sizes (TCP module only).
 
298
.ne 3
 
299
 
 
300
.TP
 
301
.B \-B
 
302
Burst mode where all receives are preposted at once (MPI, IB modules).
 
303
.ne 3
 
304
 
 
305
.TP
 
306
.B \-f
 
307
Use a fence to block for completion (MPI2 module only).
 
308
.ne 3
 
309
 
 
310
.TP
 
311
.B \-g
 
312
Use MPI_Get() instead of MPI_Put() (MPI2 module only).
 
313
.ne 3
 
314
 
 
315
.TP
 
316
.BI \-h \ \fIhostname\fR
 
317
Specify the name of the receiver host to connect to (TCP, PVM, IB, GM).
 
318
.ne 3
 
319
 
 
320
.TP
 
321
.B \-I
 
322
Invalidate cache to measure performance without cache effects (mostly affects 
 
323
IB and memcpy modules).
 
324
.ne 3
 
325
 
 
326
.TP
 
327
.B \-i
 
328
Do an integrity check instead of a performance evaluation.
 
329
.ne 3
 
330
 
 
331
.TP
 
332
.BI \-l \ \fIstarting_msg_size\fR
 
333
Specify the lower bound for the size of messages to be tested.
 
334
.ne 3
 
335
.TP
 
336
 
 
337
.TP
 
338
.BI \-n \ \fInrepeats\fR
 
339
Set the number of repeats for each test to a constant.
 
340
Otherwise, the number of repeats is chosen to provide an accurate
 
341
timing for each test.  Be very careful if specifying a low number
 
342
so that the time for the ping-pong test exceeds the timer accuracy.
 
343
.ne 3
 
344
 
 
345
.TP
 
346
.BI \-O \ \fIsource_offset,dest_offset\fR
 
347
Specify the source and destination offsets of the buffers from perfect 
 
348
page alignment.
 
349
.ne 3
 
350
.TP
 
351
 
 
352
.BI \-o \ \fIoutput_filename\fR
 
353
Specify the output filename (default is np.out).
 
354
.ne 3
 
355
 
 
356
.TP
 
357
.BI \-p \ \fIperturbation_size\fR
 
358
NetPIPE chooses the message sizes at regular intervals, increasing them
 
359
exponentially from the lower boundary to the upper boundary.
 
360
At each point, it also tests perturbations of 3 bytes above and 3 bytes
 
361
below each test point to find idiosyncrasies in the system.
 
362
This perturbation value can be changed using the 
 
363
.I -p
 
364
option, or turned
 
365
off using
 
366
.I -p 
 
367
.I 0
 
368
.B .
 
369
.ne 3
 
370
 
 
371
.TP
 
372
.B \-r
 
373
This option resets the TCP sockets after every test (TCP module only).
 
374
It is necessary for some streaming tests to get good measurements
 
375
since the socket window size may otherwise collapse.
 
376
.ne 3
 
377
 
 
378
.TP
 
379
.B \-s
 
380
Set streaming mode where data is only transmitted in one direction. 
 
381
.ne 3
 
382
 
 
383
.TP
 
384
.B \-S
 
385
Use synchronous sends (MPI module only).
 
386
.ne 3
 
387
 
 
388
.TP
 
389
.BI \-u \ \fIupper_bound\fR
 
390
Specify the upper boundary to the size of message being tested.  
 
391
By default, NetPIPE will stop when
 
392
the time to transmit a block exceeds one second. 
 
393
 
 
394
.TP
 
395
.B \-z
 
396
Receive messages using MPI_ANY_SOURCE (MPI module only)
 
397
.ne 3
 
398
 
 
399
.TP
 
400
.B \-2
 
401
Set bi-directional mode where both sides send and receive at the
 
402
same time (supported by most modules).
 
403
You may need to use 
 
404
.I -a
 
405
to choose asynchronous communications for MPI to avoid freeze-ups.
 
406
For TCP, the maximum test size will be limited by the TCP
 
407
buffer sizes.
 
408
.ne 3
 
409
 
 
410
.ne 3
 
411
.SH FILES
 
412
.TP
 
413
.I np.out
 
414
Default output file for
 
415
.BR NetPIPE .
 
416
Overridden by the
 
417
.B \-o
 
418
option.
 
419
 
 
420
.SH AUTHOR
 
421
.PP
 
422
The original NetPIPE core plus TCP and MPI modules were written by 
 
423
Quinn Snell, Armin Mikler, Guy Helmer, and John Gustafson.
 
424
NetPIPE is currently being developed and maintained by Dave Turner
 
425
with contributions from many students (Bogdan Vasiliu, Adam Oline,
 
426
Xuehua Chen, and Brian Smith).  
 
427
 
 
428
.PP
 
429
Send comments/bug-reports to:
 
430
.I
 
431
<netpipe@scl.ameslab.gov>.
 
432
.PP
 
433
Additional information about
 
434
.B NetPIPE
 
435
can be found on the World Wide Web at
 
436
.I http://www.scl.ameslab.gov/Projects/NetPIPE/
 
437
 
 
438
.SH BUGS
 
439
As of version 3.6.1, there is a bug that causes NetPIPE to segfault on 
 
440
RedHat Enterprise systems. I will debug this as soon as I get access to a 
 
441
few such systems.  -Dave Turner (turner@ameslab.gov)