Add support for blkio cgroups on Linux

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index aec00e84e548f1c9d65952e73803d8fcb5df53e9..7a7d14ea0816080d794d25f4d899603e2eee57a8 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -158,6 +158,9 @@ specify:
 
 $ fio --name=random-writers --ioengine=libaio --iodepth=4 --rw=randwrite --bs=32k --direct=0 --size=64m --numjobs=4
 
+4.1 Environment variables
+-------------------------
+
 fio also supports environment variable expansion in job files. Any
 substring of the form "${VARNAME}" as part of an option value (in other
 words, on the right of the `='), will be expanded to the value of the
@@ -188,6 +191,26 @@ numjobs=4
 fio ships with a few example job files, you can also look there for
 inspiration.
 
+4.2 Reserved keywords
+---------------------
+
+Additionally, fio has a set of reserved keywords that will be replaced
+internally with the appropriate value. Those keywords are:
+
+$pagesize      The architecture page size of the running system
+$mb_memory     Megabytes of total memory in the system
+$ncpus         Number of online available CPUs
+
+These can be used on the command line or in the job file, and will be
+automatically substituted with the current system values when the job
+is run. Simple math is also supported on these keywords, so you can
+perform actions like:
+
+size=8*$mb_memory
+
+and get that properly expanded to 8 times the size of memory in the
+machine.
+
 
 5.0 Detailed list of parameters
 -------------------------------
@@ -794,6 +817,8 @@ verify=str  If writing to a file, fio can verify the file contents
 
                        sha256  Use sha256 as the checksum function.
 
+                       sha1    Use optimized sha1 as the checksum function.
+
                        meta    Write extra information about each io
                                (timestamp, block number etc.). The block
                                number is verified.
@@ -804,7 +829,11 @@ verify=str If writing to a file, fio can verify the file contents
 
                This option can be used for repeated burn-in tests of a
                system to make sure that the written data is also
-               correctly read back.
+               correctly read back. If the data direction given is
+               a read or random read, fio will assume that it should
+               verify a previously written file. If the data direction
+               includes any form of write, the verify will be of the
+               newly written data.
 
 verifysort=bool        If set, fio will sort written verify blocks when it deems
                it faster to read them back in a sorted manner. This is
@@ -823,13 +852,14 @@ verify_interval=int       Write the verification header at a finer granularity
                        size of header_interval. blocksize should divide this
                        evenly.
 
-verify_pattern=int     If set, fio will fill the io buffers with this
+verify_pattern=str     If set, fio will fill the io buffers with this
                pattern. Fio defaults to filling with totally random
                bytes, but sometimes it's interesting to fill with a known
                pattern for io verification purposes. Depending on the
                width of the pattern, fio will fill 1/2/3/4 bytes of the
-               buffer at the time. The verify_pattern cannot be larger than
-               a 32-bit quantity.
+               buffer at the time(it can be either a decimal or a hex number).
+               The verify_pattern if larger than a 32-bit quantity has to
+               be a hex number that starts with either "0x" or "0X".
 
 verify_fatal=bool      Normally fio will keep checking the entire contents
                before quitting on a block verification failure. If this
@@ -964,6 +994,7 @@ gtod_cpu=int        Sometimes it's cheaper to dedicate a single thread of
                for doing these time calls will be excluded from other
                uses. Fio will manually clear it from the CPU mask of other
                jobs.
+
 continue_on_error=bool Normally fio will exit the job on the first observed
                failure. If this option is set, fio will continue the job when
                there is a 'non-fatal error' (EIO or EILSEQ) until the runtime
@@ -973,6 +1004,21 @@ continue_on_error=bool    Normally fio will exit the job on the first observed
                given in the stats is the first error that was hit during the
                run.
 
+cgroup_root=str        Root of the mounted blkio cgroup file systems. This is a Linux
+               specific IO controller. If your system doesn't have it mounted,
+               you can do so with:
+
+               # mount -t cgroup -o blkio none /cgroup
+
+               The cgroup_root defaults to /cgroup, if mounted elsewhere
+               please specify this option.
+
+cgroup=str     Add job to this control group. If it doesn't exist, it will
+               be created.
+
+cgroup_weight=int      Set the weight of the cgroup to this value. See
+               the documentation that comes with the kernel, allowed values
+               are in the range of 100..1000.
 
 6.0 Interpreting the output
 ---------------------------