X-Git-Url: https://git.kernel.dk/?p=fio.git;a=blobdiff_plain;f=HOWTO;h=47eff96a9158989f0b178ae168ec25faf7fd2f98;hp=eb2ed25403cb8dfe2ae96e8a93d5e99aa98c8b39;hb=c3afb7639f41e58e44481151e3aa4caa6be789f6;hpb=4db089f5dd8a00eb4efdc8694735ef2cc3843998

diff --git a/HOWTO b/HOWTO
index eb2ed254..47eff96a 100644
--- a/HOWTO
+++ b/HOWTO
@@ -223,7 +223,8 @@ a string. The following types are used:
 str	String. This is a sequence of alpha characters.
 time	Integer with possible time suffix. In seconds unless otherwise
 	specified, use eg 10m for 10 minutes. Accepts s/m/h for seconds,
-	minutes, and hours.
+	minutes, and hours, and accepts 'ms' (or 'msec') for milliseconds,
+	and 'us' (or 'usec') for microseconds.
 int	SI integer. A whole number value, which may contain a suffix
 	describing the base of the number. Accepted suffixes are k/m/g/t/p,
 	meaning kilo, mega, giga, tera, and peta. The suffix is not case
@@ -261,7 +262,8 @@ description=str	Text description of the job. Doesn't do anything except
 		not parsed.
 
 directory=str	Prefix filenames with this directory. Used to place files
-		in a different location than "./".
+		in a different location than "./". See the 'filename' option
+		for escaping certain characters.
 
 filename=str	Fio normally makes up a filename based on the job name,
 		thread number, and file number. If you want to share
@@ -384,6 +386,11 @@ unified_rw_reporting=bool	Fio normally reports statistics on a per
 randrepeat=bool	For random IO workloads, seed the generator in a predictable
 		way so that results are repeatable across repetitions.
 
+randseed=int	Seed the random number generators based on this seed value, to
+		be able to control what sequence of output is being generated.
+		If not set, the random sequence depends on the randrepeat
+		setting.
+
 use_os_rand=bool Fio can either use the random generator supplied by the OS
 		to generator random offsets, or it can use it's own internal
 		generator (based on Tausworthe). Default is to use the
@@ -428,6 +435,12 @@ filesize=int	Individual file sizes. May be a range, in which case fio
 		and limited to 'size' in total (if that is given). If not
 		given, each created file is the same size.
 
+file_append=bool	Perform IO after the end of the file. Normally fio will
+		operate within the size of a file. If this option is set, then
+		fio will append to the file instead. This has identical
+		behavior to setting offset to the size of a file. This option
+		is ignored on non-regular files.
+
 fill_device=bool
 fill_fs=bool	Sets size to something really large and waits for ENOSPC (no
 		space left on device) as the terminating condition. Only makes
@@ -512,6 +525,8 @@ bs_is_seq_rand	If this option is set, fio will use the normal read,write
 
 zero_buffers	If this option is given, fio will init the IO buffers to
 		all zeroes. The default is to fill them with random data.
+		The resulting IO buffers will not be completely zeroed,
+		unless scramble_buffers is also turned off.
 
 refill_buffers	If this option is given, fio will refill the IO buffers
 		on every submit. The default is to only fill it at init
@@ -542,6 +557,11 @@ buffer_compress_chunk=int	See buffer_compress_percentage. This
 		alternate random and zeroed data throughout the IO
 		buffer.
 
+buffer_pattern=str	If set, fio will fill the io buffers with this pattern.
+		If not set, the contents of io buffers is defined by the other
+		options related to buffer contents. The setting can be any
+		pattern of bytes, and can be prefixed with 0x for hex values.
+
 nrfiles=int	Number of files to use for this job. Defaults to 1.
 
 openfiles=int	Number of files to keep open at the same time. Defaults to
@@ -695,6 +715,11 @@ direct=bool	If value is true, use non-buffered io. This is usually
 		O_DIRECT. Note that ZFS on Solaris doesn't support direct io.
 		On Windows the synchronous ioengines don't support direct io.
 
+atomic=bool	If value is true, attempt to use atomic direct IO. Atomic
+		writes are guaranteed to be stable once acknowledged by
+		the operating system. Only Linux supports O_ATOMIC right
+		now.
+
 buffered=bool	If value is true, use buffered io. This is the opposite
 		of the 'direct' option. Defaults to true.
 
@@ -876,6 +901,20 @@ rate_iops_min=int If fio doesn't meet this rate of IO, it will cause
 		the job to exit. The same format as rate is used for read vs
 		write separation.
 
+latency_target=int	If set, fio will attempt to find the max performance
+		point that the given workload will run at while maintaining a
+		latency below this target. The values is given in microseconds.
+		See latency_window and latency_percentile
+
+latency_window=int	Used with latency_target to specify the sample window
+		that the job is run at varying queue depths to test the
+		performance. The value is given in microseconds.
+
+latency_percentile=float	The percentage of IOs that must fall within the
+		criteria specified by latency_target and latency_window. If not
+		set, this defaults to 100.0, meaning that all IOs must be equal
+		or below to the value set by latency_target.
+
 max_latency=int	If set, fio will exit the job if it exceeds this maximum
 		latency. It will exit with an ETIME error.
 
@@ -898,6 +937,18 @@ cpus_allowed=str Controls the same options as cpumask, but it allows a text
 		allows a range of CPUs. Say you wanted a binding to CPUs
 		1, 5, and 8-15, you would set cpus_allowed=1,5,8-15.
 
+cpus_allowed_policy=str Set the policy of how fio distributes the CPUs
+		specified by cpus_allowed or cpumask. Two policies are
+		supported:
+
+		shared	All jobs will share the CPU set specified.
+		split	Each job will get a unique CPU from the CPU set.
+
+		'shared' is the default behaviour, if the option isn't
+		specified. If split is specified, then fio will will assign
+		one cpu per job. If not enough CPUs are given for the jobs
+		listed, then fio will roundrobin the CPUs in the set.
+
 numa_cpu_nodes=str Set this job running on spcified NUMA nodes' CPUs. The
 		arguments allow comma delimited list of cpu numbers,
 		A-B ranges, or 'all'. Note, to enable numa options support,
@@ -1039,6 +1090,13 @@ loops=int	Run the specified number of iterations of this job. Used
 		to repeat the same workload a given number of times. Defaults
 		to 1.
 
+verify_only	Do not perform specified workload---only verify data still
+		matches previous invocation of this workload. This option
+		allows one to check data multiple times at a later date
+		without overwriting it. This option makes sense only for
+		workloads that write data, and does not support workloads
+		with the time_based option set.
+
 do_verify=bool	Run the verify phase after a write phase. Only makes sense if
 		verify is set. Defaults to 1.
 
@@ -1069,6 +1127,10 @@ verify=str	If writing to a file, fio can verify the file contents
 			crc7	Use a crc7 sum of the data area and store
 				it in the header of each block.
 
+			xxhash	Use xxhash as the checksum function. Generally
+				the fastest software checksum that fio
+				supports.
+
 			sha512	Use sha512 as the checksum function.
 
 			sha256	Use sha256 as the checksum function.
@@ -1077,7 +1139,9 @@ verify=str	If writing to a file, fio can verify the file contents
 
 			meta	Write extra information about each io
 				(timestamp, block number etc.). The block
-				number is verified. See also verify_pattern.
+				number is verified. The io sequence number is
+				verified for workloads that write data.
+				See also verify_pattern.
 
 			null	Only pretend to verify. Useful for testing
 				internals with ioengine=null, not for much
@@ -1467,7 +1531,9 @@ that defines them is selected.
 [net] proto=str	The network protocol to use. Accepted values are:
 
 			tcp	Transmission control protocol
+			tcpv6	Transmission control protocol V6
 			udp	User datagram protocol
+			udpv6	User datagram protocol V6
 			unix	UNIX domain socket
 
 		When the protocol is TCP or UDP, the port must also be given,