allow a percent value for the offset parameter

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index 15ed42549580a659c82cd5febb7e4be6a441addc..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 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:
 
 
 .. _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
        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
 
 
 .. option:: pre_read=bool
 


@@ -1069,10 +1072,11 @@ I/O type
 
 .. option:: offset=int
 
 
 .. 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
 
 
 .. 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
        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
 
 .. option:: fdatasync=int
 
        Like :option:`fsync` but uses :manpage:`fdatasync(2)` to only sync data and

-       not metadata blocks.  In FreeBSD and Windows there is no
+       not metadata blocks.  In Windows, FreeBSD, and DragonFlyBSD there is no

        :manpage:`fdatasync(2)`, this falls back to using :manpage:`fsync(2)`.
        :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
 
 
 .. 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
 .. 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
 
 
 .. option:: sync=bool
 


@@ -1461,6 +1469,9 @@ Buffers and memory
                **mmapshared**
                        Same as mmap, but use a MMAP_SHARED mapping.
 
                **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
        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


@@ -1513,7 +1524,7 @@ I/O size
        Fio will divide this size between the available files determined by options
        such as :option:`nrfiles`, :option:`filename`, unless :option:`filesize` is
        specified by the job. If the result of division happens to be 0, the size is
        Fio will divide this size between the available files determined by options
        such as :option:`nrfiles`, :option:`filename`, unless :option:`filesize` is
        specified by the job. If the result of division happens to be 0, the size is

-       set to the physical size of the given files or devices.
+       set to the physical size of the given files or devices if they exist.

        If this option is not specified, fio will use the full size of the given
        files or devices.  If the files do not exist, size must be given. It is also
        possible to give size as a percentage between 1 and 100. If ``size=20%`` is
        If this option is not specified, fio will use the full size of the given
        files or devices.  If the files do not exist, size must be given. It is also
        possible to give size as a percentage between 1 and 100. If ``size=20%`` is


@@ -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.
                **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
 
                **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).
 
                        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.
                **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]
 
 
 .. 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]
 
 
 .. 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`.
 
        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
 .. option:: write_bw_log=str
 
        If given, write a bandwidth log for this job. Can be used to store data of