[PATCH v2 4/8] doc: explain the option write_zone_remainder

Shin'ichiro Kawasaki
2026-02-16T08:00:49Z

The recent commit introduced the option write_zone_remainder. Explain
how it changes handling of zone end remainders. Also, amend the zbd
zone mode description to explain the default handling of zone end
remainders.

Signed-off-by: Shin'ichiro Kawasaki <shinichiro.kawasaki@wdc.com>
---
HOWTO.rst | 26 +++++++++++++++++++++++++-
fio.1 | 25 ++++++++++++++++++++++---
2 files changed, 47 insertions(+), 4 deletions(-)

diff --git a/HOWTO.rst b/HOWTO.rst
index d31851e9..148c650e 100644
--- a/HOWTO.rst
+++ b/HOWTO.rst
@@ -1034,7 +1034,14 @@ Target file/device
all zones instead of being restricted to a
single zone. The :option:`zoneskip` parameter
is ignored. :option:`zonerange` and
- :option:`zonesize` must be identical.
+ :option:`zonesize` must be identical. When the
+ specified block size is not aligned with the
+ zone size or the write pointer positions at
+ workload start, write workloads create unwritten
+ remainder areas at the ends of zones and keep
+ the zones in open conditions. To free up the
+ open zone resources, fio issues zone finish
+ operations to the zones with the remainders.
Trim is handled using a zone reset operation.
Trim only considers non-empty sequential write
required and sequential write preferred zones.
@@ -1167,6 +1174,23 @@ Target file/device
asynchronous IO engine and :option:`verify` workload are specified,
errors out. Default: false.

+.. option:: write_zone_remainders=bool
+
+ When the specified block size is not aligned with the zone size or the
+ write pointer positions at workload start, write workloads create
+ unwritten remainder areas at the ends of zones. By default, fio issues
+ zone finish operations on such zones, transitioning them to the full
+ condition and freeing up open zone resources. However, zone finish
+ operations introduces waits for in-flight writes, reducing overall write
+ throughput. If this option is specified, fio writes data to the
+ remainder areas instead of performing zone finish operations. This
+ improves write throughput by avoiding waits for in-flight writes,
+ particularly in asynchronous write workloads. The drawback of this
+ option is that it requires fio to perform writes smaller than the
+ minimum block size. Consequently, the option :option:`norandommap` must
+ be set. If :option:`norandommap` is not set, it is automatically set.
+ Default: false.
+
I/O type
~~~~~~~~

diff --git a/fio.1 b/fio.1
index bc3efa5f..36581d48 100644
--- a/fio.1
+++ b/fio.1
@@ -809,9 +809,14 @@ starts. The \fBzonecapacity\fR parameter is ignored.
.B zbd
Zoned block device mode. I/O happens sequentially in each zone, even if random
I/O has been selected. Random I/O happens across all zones instead of being
-restricted to a single zone.
-Trim is handled using a zone reset operation. Trim only considers non-empty
-sequential write required and sequential write preferred zones.
+restricted to a single zone. The \fBzoneskip\fR parameter is ignored.
+\fBzonerange\fR and \fBzonesize\fR must be identical. When the specified block
+size is not aligned with the zone size or the write pointer positions at
+workload start, write workloads create unwritten remainder areas at the ends of
+zones and keep the zones in open conditions. To free up the open zone resources,
+fio issues zone finish operations to the zones with the remainders. Trim is
+handled using a zone reset operation. Trim only considers non-empty sequential
+write required and sequential write preferred zones.
.RE
.RE
.TP
@@ -931,6 +936,20 @@ fail due to partial writes and unexpected write pointer positions. If
asynchronous, the write pointer move fills blocks with zero then breaks verify
data. If an asynchronous IO engine and \fBverify\fR workload are specified,
errors out. Default: false.
+.TP
+.BI write_zone_remainders \fR=\fPbool
+When the specified block size is not aligned with the zone size or the write
+pointer positions at workload start, write workloads create unwritten remainder
+areas at the ends of zones. By default, fio issues zone finish operations on
+such zones, transitioning them to the full condition and freeing up open zone
+resources. However, zone finish operations introduces waits for in-flight
+writes, reducing overall write throughput. If this option is specified, fio
+writes data to the remainder areas instead of performing zone finish operations.
+This improves write throughput by avoiding waits for in-flight writes,
+particularly in asynchronous write workloads. The drawback of this option is
+that it requires fio to perform writes smaller than the minimum block size.
+Consequently, the option \fBnorandommap\fR must be set. If \fBnorandommap\fR is
+not set, it is automatically set. Default: false.

.SS "I/O type"
.TP
--
2.49.0