X-Git-Url: https://git.kernel.dk/?p=fio.git;a=blobdiff_plain;f=HOWTO;h=fbe8f7919988db293b921334268a424e887604fd;hp=32e5d668c89e42efec4704b2db8686afc32e17c2;hb=a64ea63f648e77d583b5287634f44bea7da79b4b;hpb=856b09c838bfd45a9d6d87a1ab03458c9b058d56 diff --git a/HOWTO b/HOWTO index 32e5d668..fbe8f791 100644 --- a/HOWTO +++ b/HOWTO @@ -9,6 +9,7 @@ Table of contents 6. Normal output 7. Terse output 8. Trace file format +9. CPU idleness profiling 1.0 Overview and history ------------------------ @@ -272,17 +273,17 @@ filename=str Fio normally makes up a filename based on the job name, can specify a number of files by separating the names with a ':' colon. So if you wanted a job to open /dev/sda and /dev/sdb as the two working files, you would use - filename=/dev/sda:/dev/sdb. On Windows, disk devices are accessed - as \\.\PhysicalDrive0 for the first device, \\.\PhysicalDrive1 - for the second etc. - Note: Windows and FreeBSD prevent write access to areas of the disk - containing in-use data (e.g. filesystems). - If the wanted filename does need to include a colon, then escape that - with a '\' character. - For instance, if the filename is "/dev/dsk/foo@3,0:c", - then you would use filename="/dev/dsk/foo@3,0\:c". - '-' is a reserved name, meaning stdin or stdout. Which of the - two depends on the read/write direction set. + filename=/dev/sda:/dev/sdb. On Windows, disk devices are + accessed as \\.\PhysicalDrive0 for the first device, + \\.\PhysicalDrive1 for the second etc. Note: Windows and + FreeBSD prevent write access to areas of the disk containing + in-use data (e.g. filesystems). + If the wanted filename does need to include a colon, then + escape that with a '\' character. For instance, if the filename + is "/dev/dsk/foo@3,0:c", then you would use + filename="/dev/dsk/foo@3,0\:c". '-' is a reserved name, meaning + stdin or stdout. Which of the two depends on the read/write + direction set. opendir=str Tell fio to recursively add any file it can find in this directory and down the file system tree. @@ -353,6 +354,12 @@ kb_base=int The base unit for a kilobyte. The defacto base is 2^10, 1024. ten unit instead, for obvious reasons. Allow values are 1024 or 1000, with 1024 being the default. +unified_rw_reporting=bool Fio normally reports statistics on a per + data direction basis, meaning that read, write, and trim are + accounted and reported separately. If this option is set, + the fio will sum the results and report them as "mixed" + instead. + randrepeat=bool For random IO workloads, seed the generator in a predictable way so that results are repeatable across repetitions. @@ -704,7 +711,7 @@ overwrite=bool If true, writes to a file will always overwrite existing and is large enough for the specified write phase, nothing will be done. -end_fsync=bool If true, fsync file contents when the job exits. +end_fsync=bool If true, fsync file contents when a write stage has completed. fsync_on_close=bool If true, fio will fsync() a dirty file on close. This differs from end_fsync in that it will happen on every @@ -753,6 +760,23 @@ softrandommap=bool See norandommap. If fio runs with the random block map will not be as complete as with random maps, this option is disabled by default. +random_generator=str Fio supports the following engines for generating + IO offsets for random IO: + + tausworthe Strong 2^88 cycle random number generator + lfsr Linear feedback shift register generator + + Tausworthe is a strong random number generator, but it + requires tracking on the side if we want to ensure that + blocks are only read or written once. LFSR guarantees + that we never generate the same offset twice, and it's + also less computationally expensive. It's not a true + random generator, however, though for IO purposes it's + typically good enough. LFSR only works with single + block sizes, not with workloads that use multiple block + sizes. If used with such a workload, fio may read or write + some blocks multiple times. + nice=int Run the job with the given nice value. See man nice(2). prio=int Set the io priority value of this job. Linux limits us to @@ -827,9 +851,7 @@ cpus_allowed=str Controls the same options as cpumask, but it allows a text numa_cpu_nodes=str Set this job running on spcified NUMA nodes' CPUs. The arguments allow comma delimited list of cpu numbers, A-B ranges, or 'all'. Note, to enable numa options support, - export the following environment variables, - export EXTFLAGS+=" -DFIO_HAVE_LIBNUMA " - export EXTLIBS+=" -lnuma " + fio must be built on a system with libnuma-dev(el) installed. numa_mem_policy=str Set this job's memory policy and corresponding NUMA nodes. Format of the argements: @@ -1245,6 +1267,22 @@ percentile_list=float_list Overwrite the default list of percentiles the values of completion latency below which 99.5% and 99.9% of the observed latencies fell, respectively. +clocksource=str Use the given clocksource as the base of timing. The + supported options are: + + gettimeofday gettimeofday(2) + + clock_gettime clock_gettime(2) + + cpu Internal CPU clock source + + cpu is the preferred clocksource if it is reliable, as it + is very fast (and fio is heavy on time calls). Fio will + automatically use this clocksource if it's supported and + considered reliable on the system it is running on, unless + another clocksource is specifically set. For x86/x86-64 CPUs, + this means supporting TSC Invariant. + gtod_reduce=bool Enable all of the gettimeofday() reducing options (disable_clat, disable_slat, disable_bw) plus reduce precision of the timeout somewhat to really shrink @@ -1365,6 +1403,9 @@ that defines them is selected. [netsplice] port=int [net] port=int The TCP or UDP port to bind to or connect to. +[netsplice] nodelay=bool +[net] nodelay=bool Set TCP_NODELAY on TCP connections. + [netsplice] protocol=str [netsplice] proto=str [net] protocol=str @@ -1382,6 +1423,15 @@ that defines them is selected. [net] listen For TCP network connections, tell fio to listen for incoming connections rather than initiating an outgoing connection. The hostname must be omitted if this option is used. +[net] pingpong Normal a network writer will just continue writing data, and + a network reader will just consume packages. If pingpong=1 + is set, a writer will send its normal payload to the reader, + then wait for the reader to send the same payload back. This + allows fio to measure network latencies. The submission + and completion latencies then measure local time spent + sending or receiving, and the completion latency measures + how long it took for the other end to receive and send back. + [e4defrag] donorname=str File will be used as a block donor(swap extents between files) [e4defrag] inplace=int @@ -1647,3 +1697,18 @@ write Write 'length' bytes beginning from 'offset' sync fsync() the file datasync fdatasync() the file trim trim the given file from the given 'offset' for 'length' bytes + + +9.0 CPU idleness profiling + +In some cases, we want to understand CPU overhead in a test. For example, +we test patches for the specific goodness of whether they reduce CPU usage. +fio implements a balloon approach to create a thread per CPU that runs at +idle priority, meaning that it only runs when nobody else needs the cpu. +By measuring the amount of work completed by the thread, idleness of each +CPU can be derived accordingly. + +An unit work is defined as touching a full page of unsigned characters. Mean +and standard deviation of time to complete an unit work is reported in "unit +work" section. Options can be chosen to report detailed percpu idleness or +overall system idleness by aggregating percpu stats.