X-Git-Url: https://git.kernel.dk/?p=fio.git;a=blobdiff_plain;f=HOWTO;h=2c5896d2c212149e65c108f931a589bc681aca29;hp=6952c84e84b141fb81b6c649ec0fb054d8bcc248;hb=99955d3d3e290ccb06583a821a8112210e4b332d;hpb=5c4ef02e212df7cc536680ac44dd01f34bfb74a2 diff --git a/HOWTO b/HOWTO index 6952c84e..2c5896d2 100644 --- a/HOWTO +++ b/HOWTO @@ -53,8 +53,8 @@ bottom, it contains the following basic parameters: IO engine How do we issue io? We could be memory mapping the file, we could be using regular read/write, we - could be using splice, async io, syslet, or even - SG (SCSI generic sg). + could be using splice, async io, or even SG + (SCSI generic sg). IO depth If the io engine is async, how large a queuing depth do we want to maintain? @@ -329,18 +329,15 @@ directory=str Prefix filenames with this directory. Used to place files filename=str Fio normally makes up a filename based on the job name, thread number, and file number. If you want to share files between threads in a job or several jobs, specify - a filename for each of them to override the default. If - the ioengine used is 'net', the filename is the host, port, - and protocol to use in the format of =host,port,protocol. - See ioengine=net for more. If the ioengine is file based, you - 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). + a filename for each of them to override the default. + If the ioengine is file based, you 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 @@ -374,6 +371,11 @@ filename_format=str default of $jobname.$jobnum.$filenum will be used if no other format specifier is given. +unique_filename=bool To avoid collisions between networked clients, fio + defaults to prefixing any generated filenames (with a directory + specified) with the source of the client connecting. To disable + this behavior, set this option to 0. + opendir=str Tell fio to recursively add any file it can find in this directory and down the file system tree. @@ -403,6 +405,7 @@ rw=str Type of io pattern. Accepted values are: trimwrite Mixed trims and writes. Blocks will be trimmed first, then written to. + Fio defaults to read if the option is not specified. For the mixed io types, the default is to split them 50/50. For certain types of io the result may still be skewed a bit, since the speed may be different. It is possible to specify @@ -673,10 +676,23 @@ file_service_type=str Defines how fio decides which file from a job to the next. Multiple files can still be open depending on 'openfiles'. - The string can have a number appended, indicating how - often to switch to a new file. So if option random:4 is - given, fio will switch to a new random file after 4 ios - have been issued. + zipf Use a zipfian distribution to decide what file + to access. + + pareto Use a pareto distribution to decide what file + to access. + + gauss Use a gaussian (normal) distribution to decide + what file to access. + + For random, roundrobin, and sequential, a postfix can be + appended to tell fio how many I/Os to issue before switching + to a new file. For example, specifying + 'file_service_type=random:8' would cause fio to issue 8 I/Os + before selecting a new file at random. For the non-uniform + distributions, a floating point postfix can be given to + influence how the distribution is skewed. See + 'random_distribution' for a description of how that would work. ioengine=str Defines how the job issues io to the file. The following types are defined: @@ -684,11 +700,14 @@ ioengine=str Defines how the job issues io to the file. The following sync Basic read(2) or write(2) io. lseek(2) is used to position the io location. - psync Basic pread(2) or pwrite(2) io. + psync Basic pread(2) or pwrite(2) io. Default on all + supported operating systems except for Windows. vsync Basic readv(2) or writev(2) IO. - psyncv Basic preadv(2) or pwritev(2) IO. + pvsync Basic preadv(2) or pwritev(2) IO. + + pvsync2 Basic preadv2(2) or pwritev2(2) IO. libaio Linux native asynchronous io. Note that Linux may only support queued behaviour with @@ -700,6 +719,7 @@ ioengine=str Defines how the job issues io to the file. The following solarisaio Solaris native asynchronous io. windowsaio Windows native asynchronous io. + Default on Windows. mmap File is memory mapped and data copied to/from using memcpy(3). @@ -708,9 +728,6 @@ ioengine=str Defines how the job issues io to the file. The following vmsplice(2) to transfer data from user space to the kernel. - syslet-rw Use the syslet system calls to make - regular read/write async. - sg SCSI generic sg v3 io. May either be synchronous using the SG_IO ioctl, or if the target is an sg character device @@ -735,12 +752,13 @@ ioengine=str Defines how the job issues io to the file. The following cpuio Doesn't transfer any data, but burns CPU cycles according to the cpuload= and - cpucycle= options. Setting cpuload=85 + cpuchunks= options. Setting cpuload=85 will cause that job to do nothing but burn 85% of the CPU. In case of SMP machines, use numjobs= to get desired CPU usage, as the cpuload only loads a single - CPU at the desired rate. + CPU at the desired rate. A job never finishes + unless there is at least one non-cpuio job. guasi The GUASI IO engine is the Generic Userspace Asyncronous Syscall Interface approach @@ -1050,7 +1068,8 @@ 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 a positive value between 0 and 7, with 0 being the highest. - See man ionice(1). + See man ionice(1). Refer to an appropriate manpage for + other operating systems since meaning of priority may differ. prioclass=int Set the io priority class. See man ionice(1). @@ -1206,6 +1225,7 @@ mem=str Fio can use various types of memory as the io unit buffer. The allowed values are: malloc Use memory from malloc(3) as the buffers. + Default memory type. shm Use shared memory as the buffers. Allocated through shmget(2). @@ -1266,10 +1286,14 @@ exitall_on_error When one job finishes in error, terminate the rest. The default is to wait for each job to finish. bwavgtime=int Average the calculated bandwidth over the given time. Value - is specified in milliseconds. + is specified in milliseconds. If the job also does bandwidth + logging through 'write_bw_log', then the minimum of this option + and 'log_avg_msec' will be used. Default: 500ms. iopsavgtime=int Average the calculated IOPS over the given time. Value - is specified in milliseconds. + is specified in milliseconds. If the job also does IOPS logging + through 'write_iops_log', then the minimum of this option and + 'log_avg_msec' will be used. Default: 500ms. create_serialize=bool If true, serialize the file creating for the jobs. This may be handy to avoid interleaving of data @@ -1816,12 +1840,12 @@ that defines them is selected. [psyncv2] hipri Set RWF_HIPRI on IO, indicating to the kernel that it's of higher priority than normal. -[cpu] cpuload=int Attempt to use the specified percentage of CPU cycles. +[cpuio] cpuload=int Attempt to use the specified percentage of CPU cycles. -[cpu] cpuchunks=int Split the load into cycles of the given time. In +[cpuio] cpuchunks=int Split the load into cycles of the given time. In microseconds. -[cpu] exit_on_io_done=bool Detect when IO threads are done, then exit. +[cpuio] exit_on_io_done=bool Detect when IO threads are done, then exit. [netsplice] hostname=str [net] hostname=str The host name or IP address to use for TCP or UDP based IO.