X-Git-Url: https://git.kernel.dk/?p=fio.git;a=blobdiff_plain;f=HOWTO;h=e39111fa620ce20cbba070f536d44a01925a069c;hp=15ed42549580a659c82cd5febb7e4be6a441addc;hb=89978a6b26f81bdbd63228e2e2a86f604ee46c56;hpb=ae3a5accfdbe1fbfde6ba4ab583887a7d3d779ac diff --git a/HOWTO b/HOWTO index 15ed4254..e39111fa 100644 --- 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 `. + 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 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)`. + 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 @@ -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 - 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 @@ -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