allow a percent value for the offset parameter

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index 6d903bba0cb372745767ca7f81afcd19aefbc544..e39111fa620ce20cbba070f536d44a01925a069c 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -543,6 +543,8 @@ Parameter types
 
        If the option accepts an upper and lower range, use a colon ':' or
        minus '-' to separate such values. See :ref:`irange <irange>`.
+       If the lower value specified happens to be larger than the upper value,
+       two values are swapped.
 
 .. _bool:
 
@@ -886,7 +888,8 @@ Target file/device
        If this isn't set, fio will abort jobs that are destructive (e.g. that write)
        to what appears to be a mounted device or partition. This should help catch
        creating inadvertently destructive tests, not realizing that the test will
-       destroy data on the mounted file system. Default: false.
+       destroy data on the mounted file system. Note that some platforms don't allow
+       writing against a mounted device regardless of this option. Default: false.
 
 .. option:: pre_read=bool
 
@@ -1069,10 +1072,11 @@ I/O type
 
 .. option:: offset=int
 
-       Start I/O at the given offset in the file. The data before the given offset
-       will not be touched. This effectively caps the file size at `real_size -
-       offset`. Can be combined with :option:`size` to constrain the start and
-       end range that I/O will be done within.
+       Start I/O at the provided offset in the file, given as either a fixed size or
+       a percentage. If a percentage is given, the next ``blockalign``-ed offset
+       will be used. Data before the given offset will not be touched. This
+       effectively caps the file size at `real_size - offset`. Can be combined with
+       :option:`size` to constrain the start and end range of the I/O workload.
 
 .. option:: offset_increment=int
 
@@ -1099,13 +1103,15 @@ I/O type
        blocks given. For example, if you give 32 as a parameter, fio will sync the
        file for every 32 writes issued. If fio is using non-buffered I/O, we may
        not sync the file. The exception is the sg I/O engine, which synchronizes
-       the disk cache anyway.
+       the disk cache anyway. Defaults to 0, which means no sync every certain
+       number of writes.
 
 .. option:: fdatasync=int
 
        Like :option:`fsync` but uses :manpage:`fdatasync(2)` to only sync data and
        not metadata blocks.  In Windows, FreeBSD, and DragonFlyBSD there is no
        :manpage:`fdatasync(2)`, this falls back to using :manpage:`fsync(2)`.
+       Defaults to 0, which means no sync data every certain number of writes.
 
 .. option:: write_barrier=int
 
@@ -1426,7 +1432,9 @@ Buffers and memory
 .. option:: invalidate=bool
 
        Invalidate the buffer/page cache parts for this file prior to starting
-       I/O. Defaults to true.
+       I/O if the platform and file type support it. Defaults to true.
+       This will be ignored if :option:`pre_read` is also specified for the
+       same job.
 
 .. option:: sync=bool
 
@@ -1461,6 +1469,9 @@ Buffers and memory
                **mmapshared**
                        Same as mmap, but use a MMAP_SHARED mapping.
 
+               **cudamalloc**
+                       Use GPU memory as the buffers for GPUDirect RDMA benchmark.
+
        The area allocated is a function of the maximum allowed bs size for the job,
        multiplied by the I/O depth given. Note that for **shmhuge** and
        **mmaphuge** to work, the system must have free huge pages allocated. This
@@ -1568,6 +1579,7 @@ I/O engine
                **sync**
                        Basic :manpage:`read(2)` or :manpage:`write(2)`
                        I/O. :manpage:`lseek(2)` is used to position the I/O location.
+                       See :option:`fsync` and :option:`fdatasync` for syncing write I/Os.
 
                **psync**
                        Basic :manpage:`pread(2)` or :manpage:`pwrite(2)` I/O.  Default on
@@ -1667,6 +1679,11 @@ I/O engine
                        DDIR_TRIM
                                does fallocate(,mode = FALLOC_FL_KEEP_SIZE|FALLOC_FL_PUNCH_HOLE).
 
+               **ftruncate**
+                       I/O engine that sends :manpage:`ftruncate(2)` operations in response
+                       to write (DDIR_WRITE) events. Each ftruncate issued sets the file's
+                       size to the current block offset. Block size is ignored.
+
                **e4defrag**
                        I/O engine that does regular EXT4_IOC_MOVE_EXT ioctls to simulate
                        defragment activity in request to DDIR_WRITE event.
@@ -1745,7 +1762,8 @@ caveat that when used on the command line, they must come after the
 
 .. option:: cpuload=int : [cpuio]
 
-       Attempt to use the specified percentage of CPU cycles.
+       Attempt to use the specified percentage of CPU cycles. This is a mandatory
+       option when using cpuio I/O engine.
 
 .. option:: cpuchunks=int : [cpuio]
 
@@ -2590,6 +2608,12 @@ Measurements and reporting
        all jobs in a file will be part of the same reporting group, unless
        separated by a :option:`stonewall`.
 
+.. option:: stats
+
+       By default, fio collects and shows final output results for all jobs
+       that run. If this option is set to 0, then fio will ignore it in
+       the final stat output.
+
 .. option:: write_bw_log=str
 
        If given, write a bandwidth log for this job. Can be used to store data of