[PATCH 2/4] HOWTO/man: improve descriptions of max open zones options

[Shin'ichiro Kawasaki <shinichiro.kawasaki@wdc.com>]

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>
---
 HOWTO.rst | 27 ++++++++++++++++++++-------
 fio.1     | 23 +++++++++++++++++------
 2 files changed, 37 insertions(+), 13 deletions(-)

diff --git a/HOWTO.rst b/HOWTO.rst
index 5a5263c3..ad43d162 100644
--- 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 limitation 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 a0d765e5..d6ad0e27 100644
--- 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 limitation 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
-- 
2.37.1