Skip to content

Commit f226575

Browse files
JulianKunkelJulianKunkel
committed
Update user documentation with command line arguments #499 
1 parent 37a6c5c commit f226575

File tree

2 files changed

+111
-111
lines changed

2 files changed

+111
-111
lines changed

‎doc/USER_GUIDE

+55-54
Original file line numberDiff line numberDiff line change
@@ -62,60 +62,61 @@ Two ways to run IOR:
6262
* 3. OPTIONS *
6363
**************
6464
These options are to be used on the command line. E.g., 'IOR -a POSIX -b 4K'.
65-
-a S api -- API for I/O, e.g., POSIX
66-
-A N refNum -- user reference number to include in long summary
67-
-b N blockSize -- contiguous bytes to write per task (e.g.: 8, 4k, 2m, 1g)
68-
-c collective -- collective I/O
69-
-C reorderTasksConstant -- changes task ordering to n+1 ordering for readback
70-
-d N interTestDelay -- delay between reps in seconds
71-
-D N deadlineForStonewalling -- seconds before stopping write or read phase
72-
-e fsync -- perform fsync upon POSIX write close
73-
-E useExistingTestFile -- do not remove test file before write access
74-
-f S scriptFile -- test script name
75-
-F filePerProc -- file-per-process
76-
-g intraTestBarriers -- use barriers between open, write/read, and close
77-
-G N setTimeStampSignature -- set value for time stamp signature
78-
-h showHelp -- displays options and help
79-
-H showHints -- show hints
80-
-i N repetitions -- number of repetitions of test
81-
-I individualDataSets -- datasets not shared by all procs [not working]
82-
-j N outlierThreshold -- warn on outlier N seconds from mean
83-
-J N setAlignment -- HDF5 alignment in bytes (e.g.: 8, 4k, 2m, 1g)
84-
-k keepFile -- don't remove the test file(s) on program exit
85-
-K keepFileWithError -- keep error-filled file(s) after data-checking
86-
-l data packet type-- type of packet that will be created [offset|incompressible|timestamp|o|i|t]
87-
-m multiFile -- use number of reps (-i) for multiple file count
88-
-M N memoryPerNode -- hog memory on the node (e.g.: 2g, 75%)
89-
-n noFill -- no fill in HDF5 file creation
90-
-N N numTasks -- number of tasks that should participate in the test
91-
-o S testFile -- full name for test
92-
-O S string of IOR directives (e.g. -O checkRead=1,GPUid=2)
93-
-p preallocate -- preallocate file size
94-
-P useSharedFilePointer -- use shared file pointer [not working]
95-
-q quitOnError -- during file error-checking, abort on error
96-
-Q N taskPerNodeOffset for read tests use with -C & -Z options (-C constant N, -Z at least N) [!HDF5]
97-
-r readFile -- read existing file
98-
-R checkRead -- check read after read
99-
-s N segmentCount -- number of segments
100-
-S useStridedDatatype -- put strided access into datatype [not working]
101-
-t N transferSize -- size of transfer in bytes (e.g.: 8, 4k, 2m, 1g)
102-
-T N maxTimeDuration -- max time in minutes to run tests
103-
-u uniqueDir -- use unique directory name for each file-per-process
104-
-U S hintsFileName -- full name for hints file
105-
-v verbose -- output information (repeating flag increases level)
106-
-V useFileView -- use MPI_File_set_view
107-
-w writeFile -- write file
108-
-W checkWrite -- check read after write
109-
-x singleXferAttempt -- do not retry transfer if incomplete
110-
-X N reorderTasksRandomSeed -- random seed for -Z option
111-
-Y fsyncPerWrite -- perform fsync after each POSIX write
112-
-z randomOffset -- access is to random, not sequential, offsets within a file
113-
-Z reorderTasksRandom -- changes task ordering to random ordering for readback
114-
115-
116-
NOTES: * S is a string, N is an integer number.
117-
* For transfer and block sizes, the case-insensitive K, M, and G
118-
suffices are recognized. I.e., '4k' or '4K' is accepted as 4096.
65+
Flags
66+
-c, --collective Use collective I/O
67+
-C reorderTasks -- changes task ordering for readback (useful to avoid client cache)
68+
-e fsync -- perform a fsync() operation at the end of each read/write phase
69+
-E useExistingTestFile -- do not remove test file before write access
70+
-F filePerProc -- file-per-process
71+
-g intraTestBarriers -- use barriers between open, write/read, and close
72+
-k keepFile -- don't remove the test file(s) on program exit
73+
-K keepFileWithError -- keep error-filled file(s) after data-checking
74+
-m multiFile -- use number of reps (-i) for multiple file count
75+
-r readFile -- read existing file
76+
-R checkRead -- verify that the output of read matches the expected signature (used with -G)
77+
-u uniqueDir -- use unique directory name for each file-per-process
78+
-v verbose -- output information (repeating flag increases level)
79+
-w writeFile -- write file
80+
-W checkWrite -- check read after write
81+
-x singleXferAttempt -- do not retry transfer if incomplete
82+
-y dualMount -- use dual mount points for a filesystem
83+
-Y fsyncPerWrite -- perform sync operation after every write operation
84+
-z randomOffset -- access is to random, not sequential, offsets within a file
85+
-Z reorderTasksRandom -- changes task ordering to random ordering for readback
86+
--warningAsErrors Any warning should lead to an error.
87+
--dryRun do not perform any I/Os just run evtl. inputs print dummy output
88+
89+
Optional arguments
90+
-a=POSIX API for I/O [POSIX|DUMMY|MPIIO|MMAP]
91+
-A=0 refNum -- user supplied reference number to include in the summary
92+
-b=1048576 blockSize -- contiguous bytes to write per task (e.g.: 8, 4k, 2m, 1g)
93+
-d=0 interTestDelay -- delay between reps in seconds
94+
-D=0 deadlineForStonewalling -- seconds before stopping write or read phase
95+
-O stoneWallingWearOut=1 -- once the stonewalling timeout is over, all process finish to access the amount of data
96+
-O stoneWallingWearOutIterations=N -- stop after processing this number of iterations, needed for reading data back written with stoneWallingWearOut
97+
-O stoneWallingStatusFile=FILE -- this file keeps the number of iterations from stonewalling during write and allows to use them for read
98+
-O minTimeDuration=0 -- minimum Runtime for the run (will repeat from beginning of the file if time is not yet over)
99+
-O allocateBufferOnGPU=X -- allocate I/O buffers on the GPU: X=1 uses managed memory - verifications are run on CPU; X=2 managed memory - verifications on GPU; X=3 device memory with verifications on GPU.
100+
-O GPUid=X -- select the GPU to use.
101+
-f=STRING scriptFile -- test script name
102+
-G=0 setTimeStampSignature -- set value for time stamp signature/random seed
103+
-i=1 repetitions -- number of repetitions of test
104+
-j=0 outlierThreshold -- warn on outlier N seconds from mean
105+
-l, --dataPacketType=STRING datapacket type-- type of packet that will be created [offset|incompressible|timestamp|random|o|i|t|r]
106+
-M=STRING memoryPerNode -- hog memory on the node (e.g.: 2g, 75%)
107+
-N=-1 numTasks -- number of tasks that are participating in the test (overrides MPI)
108+
-o=testFile testFile -- full name for test
109+
-O=STRING string of IOR directives (e.g. -O checkRead=1,GPUid=2)
110+
-Q=1 taskPerNodeOffset for read tests use with -C & -Z options (-C constant N, -Z at least N)
111+
-s=1 segmentCount -- number of segments
112+
-t=262144 transferSize -- size of transfer in bytes (e.g.: 8, 4k, 2m, 1g)
113+
-T=0 maxTimeDuration -- max time in minutes executing repeated test; it aborts only between iterations and not within a test!
114+
-X=0 reorderTasksRandomSeed -- random seed for -Z option
115+
--randomPrefill=0 For random -z access only: Prefill the file with this blocksize, e.g., 2m
116+
--random-offset-seed=-1 The seed for -z
117+
-O summaryFile=FILE -- store result data into this file
118+
-O summaryFormat=[default,JSON,CSV] -- use the format for outputting the summary
119+
-O saveRankPerformanceDetailsCSV=<FILE> -- store the performance of each rank into the named CSV file.
119120

120121
Various options are only valid for specific modules, you can see details when running $ ./ior -h
121122
These options are typically prefixed with the module name, an example is: --posix.odirect

‎doc/sphinx/userDoc/options.rst

+56-57
Original file line numberDiff line numberDiff line change
@@ -18,59 +18,62 @@ Command line options
1818
--------------------
1919

2020
These options are to be used on the command line (e.g., ``./ior -a POSIX -b 4K``).
21-
22-
-a S api -- API for I/O [POSIX|MPIIO|HDF5|HDFS|S3|S3_EMC|NCMPI|RADOS]
23-
-A N refNum -- user reference number to include in long summary
24-
-b N blockSize -- contiguous bytes to write per task (e.g.: 8, 4k, 2m, 1g)
25-
-c collective -- collective I/O
26-
-C reorderTasksConstant -- changes task ordering to n+1 ordering for readback
27-
-d N interTestDelay -- delay between reps in seconds
28-
-D N deadlineForStonewalling -- seconds before stopping write or read phase
29-
-e fsync -- perform fsync upon POSIX write close
30-
-E useExistingTestFile -- do not remove test file before write access
31-
-f S scriptFile -- test script name
32-
-F filePerProc -- file-per-process
33-
-g intraTestBarriers -- use barriers between open, write/read, and close
34-
-G N setTimeStampSignature -- set value for time stamp signature
35-
-h showHelp -- displays options and help
36-
-H showHints -- show hints
37-
-i N repetitions -- number of repetitions of test
38-
-I individualDataSets -- datasets not shared by all procs [not working]
39-
-j N outlierThreshold -- warn on outlier N seconds from mean
40-
-J N setAlignment -- HDF5 alignment in bytes (e.g.: 8, 4k, 2m, 1g)
41-
-k keepFile -- don't remove the test file(s) on program exit
42-
-K keepFileWithError -- keep error-filled file(s) after data-checking
43-
-l data packet type-- type of packet that will be created [offset|incompressible|timestamp|o|i|t]
44-
-m multiFile -- use number of reps (-i) for multiple file count
45-
-M N memoryPerNode -- hog memory on the node (e.g.: 2g, 75%)
46-
-n noFill -- no fill in HDF5 file creation
47-
-N N numTasks -- number of tasks that should participate in the test
48-
-o S testFile -- full name for test
49-
-O S string of IOR directives (e.g. -O checkRead=1,GPUid=2)
50-
-p preallocate -- preallocate file size
51-
-P useSharedFilePointer -- use shared file pointer [not working]
52-
-q quitOnError -- during file error-checking, abort on error
53-
-Q N taskPerNodeOffset for read tests use with -C & -Z options (-C constant N, -Z at least N) [!HDF5]
54-
-r readFile -- read existing file
55-
-R checkRead -- check read after read
56-
-s N segmentCount -- number of segments
57-
-S useStridedDatatype -- put strided access into datatype [not working]
58-
-t N transferSize -- size of transfer in bytes (e.g.: 8, 4k, 2m, 1g)
59-
-T N maxTimeDuration -- max time in minutes to run tests
60-
-u uniqueDir -- use unique directory name for each file-per-process
61-
-U S hintsFileName -- full name for hints file
62-
-v verbose -- output information (repeating flag increases level)
63-
-V useFileView -- use MPI_File_set_view
64-
-w writeFile -- write file
65-
-W checkWrite -- check read after write
66-
-x singleXferAttempt -- do not retry transfer if incomplete
67-
-X N reorderTasksRandomSeed -- random seed for -Z option
68-
-Y fsyncPerWrite -- perform fsync after each POSIX write
69-
-z randomOffset -- access is to random, not sequential, offsets within a file
70-
-Z reorderTasksRandom -- changes task ordering to random ordering for readback
71-
72-
73-
* S is a string, N is an integer number.
21+
Flags
22+
-c, --collective Use collective I/O
23+
-C reorderTasks -- changes task ordering for readback (useful to avoid client cache)
24+
-e fsync -- perform a fsync() operation at the end of each read/write phase
25+
-E useExistingTestFile -- do not remove test file before write access
26+
-F filePerProc -- file-per-process
27+
-g intraTestBarriers -- use barriers between open, write/read, and close
28+
-k keepFile -- don't remove the test file(s) on program exit
29+
-K keepFileWithError -- keep error-filled file(s) after data-checking
30+
-m multiFile -- use number of reps (-i) for multiple file count
31+
-r readFile -- read existing file
32+
-R checkRead -- verify that the output of read matches the expected signature (used with -G)
33+
-u uniqueDir -- use unique directory name for each file-per-process
34+
-v verbose -- output information (repeating flag increases level)
35+
-w writeFile -- write file
36+
-W checkWrite -- check read after write
37+
-x singleXferAttempt -- do not retry transfer if incomplete
38+
-y dualMount -- use dual mount points for a filesystem
39+
-Y fsyncPerWrite -- perform sync operation after every write operation
40+
-z randomOffset -- access is to random, not sequential, offsets within a file
41+
-Z reorderTasksRandom -- changes task ordering to random ordering for readback
42+
--warningAsErrors Any warning should lead to an error.
43+
--dryRun do not perform any I/Os just run evtl. inputs print dummy output
44+
45+
Optional arguments
46+
-a=POSIX API for I/O [POSIX|DUMMY|MPIIO|MMAP]
47+
-A=0 refNum -- user supplied reference number to include in the summary
48+
-b=1048576 blockSize -- contiguous bytes to write per task (e.g.: 8, 4k, 2m, 1g)
49+
-d=0 interTestDelay -- delay between reps in seconds
50+
-D=0 deadlineForStonewalling -- seconds before stopping write or read phase
51+
-O stoneWallingWearOut=1 -- once the stonewalling timeout is over, all process finish to access the amount of data
52+
-O stoneWallingWearOutIterations=N -- stop after processing this number of iterations, needed for reading data back written with stoneWallingWearOut
53+
-O stoneWallingStatusFile=FILE -- this file keeps the number of iterations from stonewalling during write and allows to use them for read
54+
-O minTimeDuration=0 -- minimum Runtime for the run (will repeat from beginning of the file if time is not yet over)
55+
-O allocateBufferOnGPU=X -- allocate I/O buffers on the GPU: X=1 uses managed memory - verifications are run on CPU; X=2 managed memory - verifications on GPU; X=3 device memory with verifications on GPU.
56+
-O GPUid=X -- select the GPU to use.
57+
-f=STRING scriptFile -- test script name
58+
-G=0 setTimeStampSignature -- set value for time stamp signature/random seed
59+
-i=1 repetitions -- number of repetitions of test
60+
-j=0 outlierThreshold -- warn on outlier N seconds from mean
61+
-l, --dataPacketType=STRING datapacket type-- type of packet that will be created [offset|incompressible|timestamp|random|o|i|t|r]
62+
-M=STRING memoryPerNode -- hog memory on the node (e.g.: 2g, 75%)
63+
-N=-1 numTasks -- number of tasks that are participating in the test (overrides MPI)
64+
-o=testFile testFile -- full name for test
65+
-O=STRING string of IOR directives (e.g. -O checkRead=1,GPUid=2)
66+
-Q=1 taskPerNodeOffset for read tests use with -C & -Z options (-C constant N, -Z at least N)
67+
-s=1 segmentCount -- number of segments
68+
-t=262144 transferSize -- size of transfer in bytes (e.g.: 8, 4k, 2m, 1g)
69+
-T=0 maxTimeDuration -- max time in minutes executing repeated test; it aborts only between iterations and not within a test!
70+
-X=0 reorderTasksRandomSeed -- random seed for -Z option
71+
--randomPrefill=0 For random -z access only: Prefill the file with this blocksize, e.g., 2m
72+
--random-offset-seed=-1 The seed for -z
73+
-O summaryFile=FILE -- store result data into this file
74+
-O summaryFormat=[default,JSON,CSV] -- use the format for outputting the summary
75+
-O saveRankPerformanceDetailsCSV=<FILE> -- store the performance of each rank into the named CSV file.
76+
ing to random ordering for readback
7477

7578
* For transfer and block sizes, the case-insensitive K, M, and G
7679
suffices are recognized. I.e., '4k' or '4K' is accepted as 4096.
@@ -120,10 +123,6 @@ GENERAL
120123
* When > 0, use the same seed for all iterations
121124
* When < 0, different seed for each iteration
122125

123-
* ``quitOnError`` - upon error encountered on ``checkWrite`` or ``checkRead``,
124-
display current error and then stop execution. Otherwise, count errors and
125-
continue (default: 0)
126-
127126
* ``numTasks`` - number of tasks that should participate in the test. 0
128127
denotes all tasks. (default: 0)
129128

0 commit comments

Comments
 (0)