-
Notifications
You must be signed in to change notification settings - Fork 236
Command line and parameters
DiskSpd is a command-line utility that is invoked using the following syntax:
diskspd [options] target1 [ target2 [ target3 ...] ]
Test targets can be specified as follows:
- regular files: a normal filesystem path, e.g. C:\testfile.dat, \server\share\testfile.dat, etc.
- named partitions: DriveLetter:, e.g. C:, X:, etc.
- physical devices: #PhysicalDiskId, e.g. #1, #5, etc.
File and device targets are usually the most appropriate for any given situation. File targets exercise the entire filesystem and storage stack, while a device target focuses on device behavior. When using a device target it is a best practice to remove the filesystem and partitioning prior to doing a write test - see Clear-Disk.
Partition targets are a special case and, without a very specific goal, not the right entry point for normal DiskSpd work. If the partition is not formatted with a filesystem, behavior will be similar to the device case and the I/O path will be effectively that of a filesystem/storage utility - bounded by the partition and managed through the RAW pseudo-filesystem. If the partition is formatted with a filesystem, the filesystem may prevent writes through the partition view - this is defensive against I/O which would otherwise destroy the filesystem format. Respectively, using a device or file path would probably provide the most appropriate view of the storage behavior.
All available options and parameters are listed in the tables below and are further described in the Customizing tests, Threading and concurrency, and XML profiles sections. Parameters can either be specified as command line options or as part of an XML profile.
| Parameter | Description |
|---|---|
-? |
Display usage information. |
-:<flags> |
Experimental behaviors, as a bitmask of flags. Current flags: 1 — allow throughput rate limit sleeps >1ms if indicated by rate. |
-ag |
Group affinity — threads assigned round-robin to CPUs by processor groups, 0 - n. Groups are filled from lowest to highest processor before moving to the next. This is the default; use -n to disable default affinity. |
-a[g#,]#[,#,...] |
Advanced CPU affinity — threads assigned round-robin to the CPUs stated, in order of specification. The g# notation specifies the processor group for the following CPU core #s. If no group is specified, 0 is assumed. Additional groups/processors can be added, comma separated, on the same or separate -a parameters. Examples: -a0,1,2 and -ag0,0,1,2 are equivalent. -ag0,0,1,2,g1,0,1,2 specifies the first three CPUs in groups 0 and 1. -ag0,0,1,2 -ag1,0,1,2 is equivalent. |
-b<size> |
I/O size, defines the block b for sizes stated in units of blocks (default = 64K). |
-B<base>[:length] |
Bounds — specify the range of the target to issue I/O to: base offset and optional length. -Bbase -f(base+length) is the same as -Bbase:length. (Default: I/O is issued across the entire target.) |
-c<size> |
Create file targets of the given size. Conflicts with non-file target specifications. |
-C<seconds> |
Cool down time — duration of the test after measurements finished (default = 0s). |
-D<milliseconds> |
Capture IOPS statistics in intervals of <milliseconds>. These are per-thread per-target: text output provides IOPS standard deviation, XML provides the full IOPS time series in addition (default = 1000, 1 second). |
-d<seconds> |
Duration (in seconds) to run test (default = 10s). |
-f<size> |
Maximum target offset to issue I/O to (non-inclusive). -Bbase -f(base+length) is the same as -Bbase:length. For example, to test only the first sectors of a disk. |
-f<rst> |
Open file with one or more additional access hints: r — the FILE_FLAG_RANDOM_ACCESS hint, s — the FILE_FLAG_SEQUENTIAL_SCAN hint, t — the FILE_ATTRIBUTE_TEMPORARY hint. (Default: none.) |
-F<count> |
Total number of threads (conflicts with -t). |
-g<value>[i] |
Throughput per-thread per-target throttled to given value; defaults to bytes per millisecond. With the optional i qualifier the value is IOPS of the specified block size (-b). Throughput limits cannot be specified when using completion routines (-x). (Default: no limit.) |
-h |
Deprecated, see -Sh. |
-i<count> |
Number of I/Os per burst; see -j (default: inactive). |
-j<milliseconds> |
Interval in <milliseconds> between issuing I/O bursts; see -i (default: inactive). |
-I<priority> |
Set I/O priority to <priority>. Available values are: 1-very low, 2-low, 3-normal (default). |
-l |
Use large pages for I/O buffers. |
-L |
Measure latency statistics. |
-n |
Disable default affinity (-a). |
-N<vni> |
Specify the flush mode for memory mapped I/O: v — uses the FlushViewOfFile API, n — uses the RtlFlushNonVolatileMemory API, i — uses RtlFlushNonVolatileMemory without waiting for the flush to drain. (Default: none.) |
-o<count> |
Number of outstanding I/O requests per target per thread. (1 = synchronous I/O, unless more than 1 thread is specified with -F.) (Default = 2.) |
-O<count> |
Number of outstanding I/O requests per thread — for use with -F. (1 = synchronous I/O.) |
-p |
Start parallel sequential I/O operations with the same offset. (Ignored if -r is specified, makes sense only with -o2 or greater.) |
-P<count> |
Enable printing a progress dot after each <count> (default = 65536) completed I/O operations, counted separately by each thread. |
-r[align] |
Random I/O aligned to [align] byte offsets within the target range (overrides -s). (Default alignment = block size from -b.) |
-rd<dist>[params] |
Specify a non-uniform distribution for random I/O in the target (default: uniformly random). Distributions: pct, abs. In both, I/O% and %Target/Size are cumulative. If the sum of I/O% is less than 100% the remainder is applied to the remainder of the target. An I/O% of 0 indicates a gap — no I/O will be issued to that range.pct — parameter is a combination of IO%/%%Target separated by : (colon). Example: -rdpct90/10:0/10:5/20 specifies 90% of I/O in 10% of the target, no I/O in next 10%, 5% I/O in the next 20% and the remaining 5% of I/O in the last 60%.abs — parameter is a combination of IO%/Target Size separated by : (colon). If the actual target size is smaller than the distribution, the relative values of I/O% for the valid elements define the effective distribution. Example: -rdabs90/10G:0/10G:5/20G specifies 90% of I/O in 10GiB of the target, no I/O in next 10GiB, 5% I/O in the next 20GiB and the remaining 5% of I/O in the remaining capacity of the target. |
-rs<percentage> |
Percentage of requests which should be issued randomly; -r is used to specify I/O alignment. Sequential I/O runs are homogeneous when a mixed r/w ratio is specified (-w) and their lengths follow a geometric distribution based on the percentage (chance of next I/O being sequential). |
-R[p]<text|xml> |
Output format. With the p prefix, the input profile (command line or XML) is validated and re-output in the specified format without running load, useful for checking or building complex profiles. (Default: text.) |
-s[i][align] |
Stride size of [align] bytes, alignment and offset between operations. (Default = non-interlocked, default alignment = block size from -b.) By default threads track independent sequential I/O offsets starting at the base offset of the target. With multiple threads this results in threads overlapping their I/Os — see -T to divide them into multiple separate sequential streams on the target. With the optional i qualifier (-si) threads interlock on a shared sequential offset. Interlocked operations may introduce overhead but make it possible to issue a single sequential stream to a target which responds faster than one thread can drive. (Ignored if -r specified. -si conflicts with -p, -rs and -T.) |
-S[bhmruw] |
Control caching behavior (default: caching is enabled, no write-through). Non-conflicting flags may be combined in any order; ex: -Sbw, -Suw, -Swu. |
-S |
Equivalent to -Su. |
-Sb |
Enable caching (default, explicitly stated). |
-Sh |
Equivalent to -Suw. |
-Sm |
Enable memory mapped I/O. |
-Su |
Disable software caching, equivalent to FILE_FLAG_NO_BUFFERING. |
-Sr |
Disable local caching, with remote sw caching enabled; only valid for remote filesystems. |
-Sw |
Enable write-through (no hardware write caching), equivalent to FILE_FLAG_WRITE_THROUGH or non-temporal writes for memory mapped I/O (-Sm). |
-t<count> |
Number of threads per target (conflicts with -F). |
-T<offs> |
Starting separation between I/O operations performed on the same target by different threads. (Default = 0; starting offset = base target offset + (thread number * <offs>).) Only applies to -s sequential I/O with #threads > 1. Conflicts with -r and -si. |
-v[s] |
Verbose mode. With the s qualifier, only provides additional summary statistics. |
-w<percentage> |
Percentage of write requests (-w and -w0 are equivalent and result in a read-only workload). Absence of this switch indicates 100% reads. IMPORTANT: a write test will destroy existing data without a warning. |
-W<seconds> |
Warm up time — duration of the test before measurements start (default = 5s). |
-x |
Use completion routines instead of I/O Completion Ports. |
-X<filepath> |
Use an XML file to configure the workload. Profile defaults for -W/-d/-C (durations) and -R/-v/-z (output format, verbosity, random seed) may be overridden by direct specification. Targets can be defined in XML profiles as template paths of the form *<integer> (*1, *2, ...). When run, specify the paths to substitute for the template paths in order on the command line. The first specified target is *1, second is *2, and so on. Example: diskspd -d60 -Xprof.xml first.bin second.bin (prof.xml using *1 and *2, 60s run). |
-z[seed] |
Set random seed. With no -z, seed=0. With plain -z, seed is based on system run time. |
Table 1. Command line parameters
| Parameter | Description |
|---|---|
-Z |
Zero buffers used for write tests. |
-Zr |
Per-I/O random buffers used for write tests. This incurs additional run-time overhead to create random content and shouldn't be compared to results run without -Zr. |
-Z<size> |
Use a <size> buffer filled with random data as a source for write operations. |
-Z<size>,<file> |
Use a <size> buffer filled with data from <file> as a source for write operations. |
By default, write source buffers are filled with a repeating pattern (0, 1, 2, ..., 255, 0, 1, ...).
Table 2. Write buffer parameters
The following parameters specify events that can be used to start, end, cancel, or send notifications for a DiskSpd test run.
| Parameter | Description |
|---|---|
-ys<eventname> |
Signals event <eventname> before starting the actual run (no warm up). Creates a notification event if <eventname> does not exist. |
-yf<eventname> |
Signals event <eventname> after the actual run finishes (no cool-down). Creates a notification event if <eventname> does not exist. |
-yr<eventname> |
Waits on event <eventname> before starting the run (including warm up). Creates a notification event if <eventname> does not exist. |
-yp<eventname> |
Stops the run when event <eventname> is set; CTRL+C is bound to this event. Creates a notification event if <eventname> does not exist. |
-ye<eventname> |
Sets event <eventname> and quits. |
Table 3. Synchronization parameters
Using these parameters, DiskSpd can display data concerning events from an NT Kernel Logger trace session. Because event tracing (ETW) carries additional overhead, this is turned off by default.
| Parameter | Description |
|---|---|
-e<q|c|s> |
Use query perf timer (QPC), cycle count, or system timer respectively. (Default = q, query perf timer (QPC).) |
-ep |
Use paged memory for the NT Kernel Logger (default = non-paged memory). |
-ePROCESS |
Process start and end. |
-eTHREAD |
Thread start and end. |
-eIMAGE_LOAD |
Image load. |
-eDISK_IO |
Physical disk I/O. |
-eMEMORY_PAGE_FAULTS |
All page faults. |
-eMEMORY_HARD_FAULTS |
Hard faults only. |
-eNETWORK |
TCP/IP, UDP/IP send and receive. |
-eREGISTRY |
Registry calls. |
Table 4. Event Tracing for Windows (ETW) parameters
DiskSpd options take sizes and offsets specified as bytes or as a multiple of kilobytes, megabytes, gigabytes, terabytes, or blocks.
Conventions used for referring to multiples of bytes are a common source of confusion. In networking and communication these multiples are universally in powers of ten: a 'GB' is 109 (1 billion) bytes and a 'Gb' is a billion bits. By comparison a 'GB' of RAM is universally understood to be 230 (1,073,741,824) bytes. Storage has historically been in a gray area where file sizes are assumed to be stated in powers of two, but storage system manufacturers refer to total capacity in powers of ten. Since storage is always accessed over at least one (SAS, SATA) or more (PCIe, Ethernet, WiFi) communication links, this adds complexity into the already challenging exercise of understanding end-to-end flows.
Wherever appropriate DiskSpd uses iB notation, an international convention which unambiguously refers to power of two-based sizing for numbers of bytes, as distinct from powers of ten which continue to use KB/MB/GB notation.
- 1KiB = 210 = 1,024 bytes
- 1MiB = 1024 KiB = 220 = 1,048,576 bytes
- 1GiB = 1024 MiB = 230 = 1,073,741,824 bytes
- 1TiB = 1024 GiB = 240 = 1,099,511,627,776 bytes
Values reported in XML results are always in plain bytes.
To specify sizes to DiskSpd:
- bytes: use a plain number (65536)
- KiB / MiB / GiB / TiB: suffix a number with 'KMGT' respectively (case insensitive) (e.g. 64k)
- multiples of blocks: suffix a number with 'b' (e.g. 5b) — multiplying the block size specified with
-b
Fractional sizes with decimal points such as 10.5 are not allowed.