From 23a846b389235e5aa0058042319922b7ef7c01fa Mon Sep 17 00:00:00 2001 From: Shin'ichiro Kawasaki Date: Wed, 19 Jul 2023 19:57:47 +0900 Subject: [PATCH] docs: modify max_open_zones option description A recent commit modified the max_open_zones option to improve handling of zoned block devices with max_active_zones limit. Modify description of the option to meet the change. For that purpose, explain the relation between the max_open_zones option and the device side limits max_active_zones and max_open_zones. Also mention about three zone conditions 'implicit open', 'explict open' and 'closed'. And replace the word 'zone state' with 'zone condition'. Signed-off-by: Shin'ichiro Kawasaki Reviewed-by: Niklas Cassel Link: https://lore.kernel.org/r/20230719105756.553146-5-shinichiro.kawasaki@wdc.com Signed-off-by: Vincent Fu --- HOWTO.rst | 44 ++++++++++++++++++++++++++++---------------- fio.1 | 36 ++++++++++++++++++++++++------------ 2 files changed, 52 insertions(+), 28 deletions(-) diff --git a/HOWTO.rst b/HOWTO.rst index 7ae8ea7b..7fe70fbd 100644 --- a/HOWTO.rst +++ b/HOWTO.rst @@ -1056,22 +1056,34 @@ Target file/device .. option:: max_open_zones=int - 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. + When a zone of a zoned block device is partially written (i.e. not all + sectors of the zone have been written), the zone is in one of three + conditions: 'implicit open', 'explicit open' or 'closed'. Zoned block + devices may have a limit called 'max_open_zones' (same name as the + parameter) on the total number of zones that can simultaneously be in + the 'implicit open' or 'explicit open' conditions. Zoned block devices + may have another limit called 'max_active_zones', on the total number of + zones that can simultaneously be in the three conditions. 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 conditions. When the device has the + max_open_zones limit and does not have the max_active_zones limit, the + :option:`max_open_zones` parameter limits the number of zones in the two + open conditions up to the limit. In this case, fio includes zones in the + two open conditions to the write target zones at fio start. When the + device has both the max_open_zones and the max_active_zones limits, the + :option:`max_open_zones` parameter limits the number of zones in the + three conditions up to the limit. In this case, fio includes zones in + the three conditions to the write target zones at fio start. + + This parameter is relevant only if the :option:`zonemode` =zbd is used. + The default value is always equal to the max_open_zones limit 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 does not have the max_open_zones limit, :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 diff --git a/fio.1 b/fio.1 index da875276..20acd081 100644 --- a/fio.1 +++ b/fio.1 @@ -832,18 +832,30 @@ numbers fio only reads beyond the write pointer if explicitly told to do so. Default: false. .TP .BI max_open_zones \fR=\fPint -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, +When a zone of a zoned block device is partially written (i.e. not all sectors +of the zone have been written), the zone is in one of three +conditions: 'implicit open', 'explicit open' or 'closed'. Zoned block devices +may have a limit called 'max_open_zones' (same name as the parameter) on the +total number of zones that can simultaneously be in the 'implicit open' +or 'explicit open' conditions. Zoned block devices may have another limit +called 'max_active_zones', on the total number of zones that can simultaneously +be in the three conditions. 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 conditions. When the device has +the max_open_zones limit and does not have the max_active_zones limit, the +\fBmax_open_zones\fR parameter limits the number of zones in the two open +conditions up to the limit. In this case, fio includes zones in the two open +conditions to the write target zones at fio start. When the device has both the +max_open_zones and the max_active_zones limits, the \fBmax_open_zones\fR +parameter limits the number of zones in the three conditions up to the limit. +In this case, fio includes zones in the three conditions to the write target +zones at fio start. + +This parameter is relevant only if the \fBzonemode=zbd\fR is used. The default +value is always equal to the max_open_zones limit 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 does not have the max_open_zones limit, \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 -- 2.25.1