in CmdLineParser/CmdLineParser.cpp [150:330]
void CmdLineParser::_DisplayUsageInfo(const char *pszFilename) const
{
// ISSUE-REVIEW: this formats badly in the default 80 column command prompt
printf("\n");
printf("Usage: %s [options] target1 [ target2 [ target3 ...] ]\n", pszFilename);
printf("version %s (%s)\n", DISKSPD_NUMERIC_VERSION_STRING, DISKSPD_DATE_VERSION_STRING);
printf("\n");
printf(
"Valid targets:\n"
" file_path\n"
" #<physical drive number>\n"
" <drive_letter>:\n"
"\n"
"Available options:\n"
" -? display usage information\n"
" -ag group affinity - affinitize threads round-robin to cores in Processor Groups 0 - n.\n"
" Group 0 is filled before Group 1, and so forth.\n"
" [default; use -n to disable default affinity]\n"
" -ag#,#[,#,...]> advanced CPU affinity - affinitize threads round-robin to the CPUs provided. The g# notation\n"
" specifies Processor Groups for the following CPU core #s. Multiple Processor Groups\n"
" may be specified, and groups/cores may be repeated. If no group is specified, 0 is assumed.\n"
" Additional groups/processors may be added, comma separated, or on separate parameters.\n"
" Examples: -a0,1,2 and -ag0,0,1,2 are equivalent.\n"
" -ag0,0,1,2,g1,0,1,2 specifies the first three cores in groups 0 and 1.\n"
" -ag0,0,1,2 -ag1,0,1,2 is equivalent.\n"
" -b<size>[KMGT] block size in bytes or KiB/MiB/GiB/TiB [default=64K]\n"
" -B<offs>[KMGTb] base target offset in bytes or KiB/MiB/GiB/TiB/blocks [default=0]\n"
" (offset from the beginning of the file)\n"
" -c<size>[KMGTb] create files of the given size.\n"
" Size can be stated in bytes or KiB/MiB/GiB/TiB/blocks\n"
" -C<seconds> cool down time - duration of the test after measurements finished [default=0s].\n"
" -D<milliseconds> Capture IOPs statistics in intervals of <milliseconds>; these are per-thread\n"
" per-target: text output provides IOPs standard deviation, XML provides the full\n"
" IOPs time series in addition. [default=1000, 1 second].\n"
" -d<seconds> duration (in seconds) to run test [default=10s]\n"
" -f<size>[KMGTb] target size - use only the first <size> bytes or KiB/MiB/GiB/TiB/blocks of the file/disk/partition,\n"
" for example to test only the first sectors of a disk\n"
" -f<rst> open file with one or more additional access hints\n"
" r : the FILE_FLAG_RANDOM_ACCESS hint\n"
" s : the FILE_FLAG_SEQUENTIAL_SCAN hint\n"
" t : the FILE_ATTRIBUTE_TEMPORARY hint\n"
" [default: none]\n"
" -F<count> total number of threads (conflicts with -t)\n"
" -g<value>[i] throughput per-thread per-target throttled to given value; defaults to bytes per millisecond\n"
" With the optional i qualifier the value is IOPS of the specified block size (-b).\n"
" Throughput limits cannot be specified when using completion routines (-x)\n"
" [default: no limit]\n"
" -h deprecated, see -Sh\n"
" -i<count> number of IOs per burst; see -j [default: inactive]\n"
" -j<milliseconds> interval in <milliseconds> between issuing IO bursts; see -i [default: inactive]\n"
" -I<priority> Set IO priority to <priority>. Available values are: 1-very low, 2-low, 3-normal (default)\n"
" -l Use large pages for IO buffers\n"
" -L measure latency statistics\n"
" -n disable default affinity (-a)\n"
" -N<vni> specify the flush mode for memory mapped I/O\n"
" v : uses the FlushViewOfFile API\n"
" n : uses the RtlFlushNonVolatileMemory API\n"
" i : uses RtlFlushNonVolatileMemory without waiting for the flush to drain\n"
" [default: none]\n"
" -o<count> number of outstanding I/O requests per target per thread\n"
" (1=synchronous I/O, unless more than 1 thread is specified with -F)\n"
" [default=2]\n"
" -O<count> number of outstanding I/O requests per thread - for use with -F\n"
" (1=synchronous I/O)\n"
" -p start parallel sequential I/O operations with the same offset\n"
" (ignored if -r is specified, makes sense only with -o2 or greater)\n"
" -P<count> enable printing a progress dot after each <count> [default=65536]\n"
" completed I/O operations, counted separately by each thread \n"
" -r[align[KMGTb]] random I/O aligned to <align> in bytes/KiB/MiB/GiB/TiB/blocks (overrides -s)\n"
" [default alignment=block size (-b)]\n"
" -rd<dist>[params] specify an non-uniform distribution for random IO in the target\n"
" [default uniformly random]\n"
" distributions: pct, abs\n"
" all: IO%% and %%Target/Size are cumulative. If the sum of IO%% is less than 100%% the\n"
" remainder is applied to the remainder of the target. An IO%% of 0 indicates a gap -\n"
" no IO will be issued to that range of the target.\n"
" pct : parameter is a combination of IO%%/%%Target separated by : (colon)\n"
" Example: -rdpct90/10:0/10:5/20 specifies 90%% of IO in 10%% of the target, no IO\n"
" next 10%%, 5%% IO in the next 20%% and the remaining 5%% of IO in the last 60%%\n"
" abs : parameter is a combination of IO%%/Target Size separated by : (colon)\n"
" If the actual target size is smaller than the distribution, the relative values of IO%%\n"
" for the valid elements define the effective distribution.\n"
" Example: -rdabs90/10G:0/10G:5/20G specifies 90%% of IO in 10GiB of the target, no IO\n"
" next 10GiB, 5%% IO in the next 20GiB and the remaining 5%% of IO in the remaining\n"
" capacity of the target. If the target is only 20G, the distribution truncates at\n"
" 90/10G:0:10G and all IO is directed to the first 10G (equivalent to -f10G).\n"
" -rs<percentage> percentage of requests which should be issued randomly. When used, -r may be used to\n"
" specify IO alignment (applies to both the random and sequential portions of the load).\n"
" Sequential IO runs will be homogeneous if a mixed ratio is specified (-w), and run\n"
" lengths will follow a geometric distribution based on the percentage split.\n"
" -R[p]<text|xml> output format. With the p prefix, the input profile (command line or XML) is validated and\n"
" re-output in the specified format without running load, useful for checking or building\n"
" complex profiles.\n"
" [default: text]\n"
" -s[i][align[KMGTb]] stride size of <align> in bytes/KiB/MiB/GiB/TiB/blocks, alignment/offset between operations\n"
" [default=non-interlocked, default alignment=block size (-b)]\n"
" By default threads track independent sequential IO offsets starting at offset 0 of the target.\n"
" With multiple threads this results in threads overlapping their IOs - see -T to divide\n"
" them into multiple separate sequential streams on the target.\n"
" With the optional i qualifier (-si) threads interlock on a shared sequential offset.\n"
" Interlocked operations may introduce overhead but make it possible to issue a single\n"
" sequential stream to a target which responds faster than a one thread can drive.\n"
" (ignored if -r specified, -si conflicts with -p, -rs and -T)\n"
" -S[bhmruw] control caching behavior [default: caching is enabled, no writethrough]\n"
" non-conflicting flags may be combined in any order; ex: -Sbw, -Suw, -Swu\n"
" -S equivalent to -Su\n"
" -Sb enable caching (default, explicitly stated)\n"
" -Sh equivalent -Suw\n"
" -Sm enable memory mapped I/O\n"
" -Su disable software caching, equivalent to FILE_FLAG_NO_BUFFERING\n"
" -Sr disable local caching, with remote sw caching enabled; only valid for remote filesystems\n"
" -Sw enable writethrough (no hardware write caching), equivalent to FILE_FLAG_WRITE_THROUGH or\n"
" non-temporal writes for memory mapped I/O (-Sm)\n"
" -t<count> number of threads per target (conflicts with -F)\n"
" -T<offs>[KMGTb] starting stride between I/O operations performed on the same target by different threads\n"
" [default=0] (starting offset = base file offset + (thread number * <offs>)\n"
" only applies with #threads > 1\n"
" -v verbose mode\n"
" -w<percentage> percentage of write requests (-w and -w0 are equivalent and result in a read-only workload).\n"
" absence of this switch indicates 100%% reads\n"
" IMPORTANT: a write test will destroy existing data without a warning\n"
" -W<seconds> warm up time - duration of the test before measurements start [default=5s]\n"
" -x use completion routines instead of I/O Completion Ports\n"
" -X<filepath> use an XML file to configure the workload. Combine with -R, -v and -z to override profile defaults.\n"
" Targets can be defined in XML profiles as template paths of the form *<integer> (*1, *2, ...).\n"
" When run, specify the paths to substitute for the template paths in order on the command line.\n"
" The first specified target is *1, second is *2, and so on.\n"
" Example: diskspd -Xprof.xml first.bin second.bin (prof.xml using *1 and *2)\n"
" -z[seed] set random seed [with no -z, seed=0; with plain -z, seed is based on system run time]\n"
"\n"
"Write buffers:\n"
" -Z zero buffers used for write tests\n"
" -Zr per IO random buffers used for write tests - this incurrs additional run-time\n"
" overhead to create random content and shouln't be compared to results run\n"
" without -Zr\n"
" -Z<size>[KMGb] use a <size> buffer filled with random data as a source for write operations.\n"
" -Z<size>[KMGb],<file> use a <size> buffer filled with data from <file> as a source for write operations.\n"
"\n"
" By default, the write buffers are filled with a repeating pattern (0, 1, 2, ..., 255, 0, 1, ...)\n"
"\n"
"Synchronization:\n"
" -ys<eventname> signals event <eventname> before starting the actual run (no warmup)\n"
" (creates a notification event if <eventname> does not exist)\n"
" -yf<eventname> signals event <eventname> after the actual run finishes (no cooldown)\n"
" (creates a notification event if <eventname> does not exist)\n"
" -yr<eventname> waits on event <eventname> before starting the run (including warmup)\n"
" (creates a notification event if <eventname> does not exist)\n"
" -yp<eventname> stops the run when event <eventname> is set; CTRL+C is bound to this event\n"
" (creates a notification event if <eventname> does not exist)\n"
" -ye<eventname> sets event <eventname> and quits\n"
"\n"
"Event Tracing:\n"
" -e<q|c|s> Use query perf timer (qpc), cycle count, or system timer respectively.\n"
" [default = q, query perf timer (qpc)]\n"
" -ep use paged memory for the NT Kernel Logger [default=non-paged memory]\n"
" -ePROCESS process start & end\n"
" -eTHREAD thread start & end\n"
" -eIMAGE_LOAD image load\n"
" -eDISK_IO physical disk IO\n"
" -eMEMORY_PAGE_FAULTS all page faults\n"
" -eMEMORY_HARD_FAULTS hard faults only\n"
" -eNETWORK TCP/IP, UDP/IP send & receive\n"
" -eREGISTRY registry calls\n"
"\n\n");
printf("Examples:\n\n");
printf("Create 8192KB file and run read test on it for 1 second:\n\n");
printf(" %s -c8192K -d1 testfile.dat\n", pszFilename);
printf("\n");
printf("Set block size to 4KB, create 2 threads per file, 32 overlapped (outstanding)\n");
printf("I/O operations per thread, disable all caching mechanisms and run block-aligned random\n");
printf("access read test lasting 10 seconds:\n\n");
printf(" %s -b4K -t2 -r -o32 -d10 -Sh testfile.dat\n\n", pszFilename);
printf("Create two 1GB files, set block size to 4KB, create 2 threads per file, affinitize threads\n");
printf("to CPUs 0 and 1 (each file will have threads affinitized to both CPUs) and run read test\n");
printf("lasting 10 seconds:\n\n");
printf(" %s -c1G -b4K -t2 -d10 -a0,1 testfile1.dat testfile2.dat\n", pszFilename);
printf("\n");
}