HOWTO/man: improve descriptions of max open zones options

The options max_open_zones and job_max_open_zones control the number of
open zones for zonemode=zbd. However, descriptions in HOWTO and man
about these options are not clear enough since it is not well described
what an open zone is. Improve the description by adding explanation of
the open zone state. Also explain the default values for these options.

Signed-off-by: Shin'ichiro Kawasaki <shinichiro.kawasaki@wdc.com>
Link: https://lore.kernel.org/r/20221215015606.2767187-3-shinichiro.kawasaki@wdc.com
[axboe: apply wording suggestion from Damien]
Signed-off-by: Jens Axboe <axboe@kernel.dk>

diff --git a/HOWTO.rst b/HOWTO.rst
index 5a5263c3491f3e02a598e4ed79ecfc3554e04581..97fe53504d90b3d52a7db466541212289cb0e6ce 100644 (file)
--- a/HOWTO.rst
+++ b/HOWTO.rst
@@ -1052,16 +1052,29 @@ Target file/device
 
 .. option:: max_open_zones=int
 
-       When running a random write test across an entire drive many more
-       zones will be open than in a typical application workload. Hence this
-       command line option that allows one to limit the number of open zones. The
-       number of open zones is defined as the number of zones to which write
-       commands are issued.
+       A zone of a zoned block device is in the open state when it is partially
+       written (i.e. not all sectors of the zone have been written). Zoned
+       block devices may have a limit on the total number of zones that can
+       be simultaneously in the open state, that is, the number of zones that
+       can be written to simultaneously. The :option:`max_open_zones` parameter
+       limits the number of zones to which write commands are issued by all fio
+       jobs, that is, limits the number of zones that will be in the open
+       state. This parameter is relevant only if the :option:`zonemode` =zbd is
+       used. The default value is always equal to maximum number of open zones
+       of the target zoned block device and a value higher than this limit
+       cannot be specified by users unless the option
+       :option:`ignore_zone_limits` is specified. When
+       :option:`ignore_zone_limits` is specified or the target device has no
+       limit on the number of zones that can be in an open state,
+       :option:`max_open_zones` can specify 0 to disable any limit on the
+       number of zones that can be simultaneously written to by all jobs.
 
 .. option:: job_max_open_zones=int
 
-       Limit on the number of simultaneously opened zones per single
-       thread/process.
+       In the same manner as :option:`max_open_zones`, limit the number of open
+       zones per fio job, that is, the number of zones that a single job can
+       simultaneously write to. A value of zero indicates no limit.
+       Default: zero.
 
 .. option:: ignore_zone_limits=bool
 

diff --git a/fio.1 b/fio.1
index a0d765e59ae59aa061703a732256eaad787e7bd5..1074b52a384bce643f5d4e6ddc797de13cbceb6f 100644 (file)
--- a/fio.1
+++ b/fio.1
@@ -828,14 +828,25 @@ numbers fio only reads beyond the write pointer if explicitly told to do
 so. Default: false.
 .TP
 .BI max_open_zones \fR=\fPint
-When running a random write test across an entire drive many more zones will be
-open than in a typical application workload. Hence this command line option
-that allows one to limit the number of open zones. The number of open zones is
-defined as the number of zones to which write commands are issued by all
-threads/processes.
+A zone of a zoned block device is in the open state when it is partially written
+(i.e. not all sectors of the zone have been written). Zoned block devices may
+have limit a on the total number of zones that can be simultaneously in the
+open state, that is, the number of zones that can be written to simultaneously.
+The \fBmax_open_zones\fR parameter limits the number of zones to which write
+commands are issued by all fio jobs, that is, limits the number of zones that
+will be in the open state. This parameter is relevant only if the
+\fBzonemode=zbd\fR is used. The default value is always equal to maximum number
+of open zones of the target zoned block device and a value higher than this
+limit cannot be specified by users unless the option \fBignore_zone_limits\fR is
+specified. When \fBignore_zone_limits\fR is specified or the target device has
+no limit on the number of zones that can be in an open state,
+\fBmax_open_zones\fR can specify 0 to disable any limit on the number of zones
+that can be simultaneously written to by all jobs.
 .TP
 .BI job_max_open_zones \fR=\fPint
-Limit on the number of simultaneously opened zones per single thread/process.
+In the same manner as \fBmax_open_zones\fR, limit the number of open zones per
+fio job, that is, the number of zones that a single job can simultaneously write
+to. A value of zero indicates no limit. Default: zero.
 .TP
 .BI ignore_zone_limits \fR=\fPbool
 If this option is used, fio will ignore the maximum number of open zones limit