X-Git-Url: https://git.kernel.dk/?p=fio.git;a=blobdiff_plain;f=HOWTO;h=9ac485b6147ae278f15b474e3b9bac1af932d967;hp=6d541afb412632fdc290b6d5d0b6453b5601be99;hb=8ea39c32d29428b17bfe9c806fc33f0c8adfe118;hpb=e8b1961dd3470be277d31d3ddd6eeef885c1cfe2 diff --git a/HOWTO b/HOWTO index 6d541afb..9ac485b6 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 @@ -769,7 +776,7 @@ random_generator=str Fio supports the following engines for generating 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 @@ -844,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: @@ -1225,12 +1230,6 @@ exec_postrun=str After the job completes, issue the command specified ioscheduler=str Attempt to switch the device hosting the file to the specified io scheduler before running. -cpuload=int If the job is a CPU cycle eater, attempt to use the specified - percentage of CPU cycles. - -cpuchunks=int If the job is a CPU cycle eater, split the load into - cycles of the given time. In microseconds. - disk_util=bool Generate disk utilization statistics, if the platform supports it. Defaults to on. @@ -1262,6 +1261,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 @@ -1374,6 +1389,11 @@ that defines them is selected. enabled when polling for a minimum of 0 events (eg when iodepth_batch_complete=0). +[cpu] cpuload=int Attempt to use the specified percentage of CPU cycles. + +[cpu] cpuchunks=int Split the load into cycles of the given time. In + microseconds. + [netsplice] hostname=str [net] hostname=str The host name or IP address to use for TCP or UDP based IO. If the job is a TCP listener or UDP reader, the hostname is not @@ -1382,6 +1402,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 @@ -1399,6 +1422,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 @@ -1664,3 +1696,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.