[PATCH 0/4] Improve block layer request queue sysfs parameter documentation

[PATCH 0/4] Improve block layer request queue sysfs parameter documentation

[Bart Van Assche]

Hi Jens,

While reviewing Documentation/block/queue-sysfs.txt I noticed one spelling
issue, that the parameters are not listed alphabetically, that the word
'segments' needs clarification and also that documentation for some
parameters is missing. These patches address all four these issues. Please
consider these patches for kernel v5.3.

Thanks,

Bart.

Bart Van Assche (4):
  block, documentation: Fix wbt_lat_usec documentation
  block, documentation: Sort queue sysfs attribute names alphabetically
  block, documentation: Explain the word 'segments'
  block, documentation: Document discard_zeroes_data, fua,
    max_discard_segments and write_zeroes_max_bytes

 Documentation/block/queue-sysfs.txt | 64 +++++++++++++++++++----------
 1 file changed, 43 insertions(+), 21 deletions(-)

-- 
2.22.0.410.gd8fdbe21b5-goog

[PATCH 1/4] block, documentation: Fix wbt_lat_usec documentation

[Bart Van Assche]

Fix the spelling of the wbt_lat_usec sysfs attribute.

Fixes: 87760e5eef35 ("block: hook up writeback throttling") # v4.10.
Signed-off-by: Bart Van Assche <bvanassche@acm.org>
---
 Documentation/block/queue-sysfs.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/block/queue-sysfs.txt b/Documentation/block/queue-sysfs.txt
index 83b457e24bba..3eaf86806621 100644
--- a/Documentation/block/queue-sysfs.txt
+++ b/Documentation/block/queue-sysfs.txt
@@ -185,8 +185,8 @@ This is the number of bytes the device can write in a single write-same
 command.  A value of '0' means write-same is not supported by this
 device.
 
-wb_lat_usec (RW)
-----------------
+wbt_lat_usec (RW)
+-----------------
 If the device is registered for writeback throttling, then this file shows
 the target minimum read latency. If this latency is exceeded in a given
 window of time (see wb_window_usec), then the writeback throttling will start
-- 
2.22.0.410.gd8fdbe21b5-goog

[PATCH 2/4] block, documentation: Sort queue sysfs attribute names alphabetically

[Bart Van Assche]

Commit f9824952ee1c ("block: update sysfs documentation") # v5.0 broke the
alphabetical order of the sysfs attribute names. List queue sysfs attribute
names alphabetically.

Cc: Damien Le Moal <damien.lemoal@wdc.com>
Signed-off-by: Bart Van Assche <bvanassche@acm.org>
---
 Documentation/block/queue-sysfs.txt | 30 ++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/Documentation/block/queue-sysfs.txt b/Documentation/block/queue-sysfs.txt
index 3eaf86806621..f6da2efe2105 100644
--- a/Documentation/block/queue-sysfs.txt
+++ b/Documentation/block/queue-sysfs.txt
@@ -14,6 +14,15 @@ add_random (RW)
 This file allows to turn off the disk entropy contribution. Default
 value of this file is '1'(on).
 
+chunk_sectors (RO)
+------------------
+This has different meaning depending on the type of the block device.
+For a RAID device (dm-raid), chunk_sectors indicates the size in 512B sectors
+of the RAID volume stripe segment. For a zoned block device, either host-aware
+or host-managed, chunk_sectors indicates the size in 512B sectors of the zones
+of the device, with the eventual exception of the last zone of the device which
+may be smaller.
+
 dax (RO)
 --------
 This file indicates whether the device supports Direct Access (DAX),
@@ -132,6 +141,12 @@ per-block-cgroup request pool.  IOW, if there are N block cgroups,
 each request queue may have up to N request pools, each independently
 regulated by nr_requests.
 
+nr_zones (RO)
+-------------
+For zoned block devices (zoned attribute indicating "host-managed" or
+"host-aware"), this indicates the total number of zones of the device.
+This is always 0 for regular block devices.
+
 optimal_io_size (RO)
 --------------------
 This is the optimal IO size reported by the device.
@@ -213,19 +228,4 @@ devices are described in the ZBC (Zoned Block Commands) and ZAC
 do not support zone commands, they will be treated as regular block devices
 and zoned will report "none".
 
-nr_zones (RO)
--------------
-For zoned block devices (zoned attribute indicating "host-managed" or
-"host-aware"), this indicates the total number of zones of the device.
-This is always 0 for regular block devices.
-
-chunk_sectors (RO)
-------------------
-This has different meaning depending on the type of the block device.
-For a RAID device (dm-raid), chunk_sectors indicates the size in 512B sectors
-of the RAID volume stripe segment. For a zoned block device, either host-aware
-or host-managed, chunk_sectors indicates the size in 512B sectors of the zones
-of the device, with the eventual exception of the last zone of the device which
-may be smaller.
-
 Jens Axboe <jens.axboe@oracle.com>, February 2009
-- 
2.22.0.410.gd8fdbe21b5-goog

[PATCH 3/4] block, documentation: Explain the word 'segments'

[Bart Van Assche]

Several block layer users who are not kernel developers do not know that
the word 'segment' refers to an element in a DMA scatter/gather list. Make
the block layer documentation easier to understand by stating explicitly
what the word 'segment' stands for.

Cc: Martin K. Petersen <martin.petersen@oracle.com>
Signed-off-by: Bart Van Assche <bvanassche@acm.org>
---
 Documentation/block/queue-sysfs.txt | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/Documentation/block/queue-sysfs.txt b/Documentation/block/queue-sysfs.txt
index f6da2efe2105..1515dcf3dec4 100644
--- a/Documentation/block/queue-sysfs.txt
+++ b/Documentation/block/queue-sysfs.txt
@@ -98,8 +98,9 @@ This is the maximum number of kilobytes supported in a single data transfer.
 
 max_integrity_segments (RO)
 ---------------------------
-When read, this file shows the max limit of integrity segments as
-set by block layer which a hardware controller can handle.
+Maximum number of elements in a DMA scatter/gather list with integrity
+data that will be submitted by the block layer core to the associated
+block driver.
 
 max_sectors_kb (RW)
 -------------------
@@ -109,11 +110,12 @@ size allowed by the hardware.
 
 max_segments (RO)
 -----------------
-Maximum number of segments of the device.
+Maximum number of elements in a DMA scatter/gather list that is submitted
+to the associated block driver.
 
 max_segment_size (RO)
 ---------------------
-Maximum segment size of the device.
+Maximum size in bytes of a single element in a DMA scatter/gather list.
 
 minimum_io_size (RO)
 --------------------
-- 
2.22.0.410.gd8fdbe21b5-goog

[PATCH 4/4] block, documentation: Document discard_zeroes_data, fua, max_discard_segments and write_zeroes_max_bytes

[Bart Van Assche]

Signed-off-by: Bart Van Assche <bvanassche@acm.org>
---
 Documentation/block/queue-sysfs.txt | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/Documentation/block/queue-sysfs.txt b/Documentation/block/queue-sysfs.txt
index 1515dcf3dec4..b40b5b7cebd9 100644
--- a/Documentation/block/queue-sysfs.txt
+++ b/Documentation/block/queue-sysfs.txt
@@ -52,6 +52,16 @@ large discards are issued, setting this value lower will make Linux issue
 smaller discards and potentially help reduce latencies induced by large
 discard operations.
 
+discard_zeroes_data (RO)
+------------------------
+Obsolete. Always zero.
+
+fua (RO)
+--------
+Whether or not the block driver supports the FUA flag for write requests.
+FUA stands for Force Unit Access. If the FUA flag is set that means that
+write requests must bypass the volatile cache of the storage device.
+
 hw_sector_size (RO)
 -------------------
 This is the hardware sector size of the device, in bytes.
@@ -92,6 +102,10 @@ logical_block_size (RO)
 -----------------------
 This is the logical block size of the device, in bytes.
 
+max_discard_segments (RO)
+-------------------------
+The maximum number of DMA scatter/gather entries in a discard request.
+
 max_hw_sectors_kb (RO)
 ----------------------
 This is the maximum number of kilobytes supported in a single data transfer.
@@ -218,6 +232,12 @@ blk-throttle makes decision based on the samplings. Lower time means cgroups
 have more smooth throughput, but higher CPU overhead. This exists only when
 CONFIG_BLK_DEV_THROTTLING_LOW is enabled.
 
+write_zeroes_max_bytes (RO)
+---------------------------
+For block drivers that support REQ_OP_WRITE_ZEROES, the maximum number of
+bytes that can be zeroed at once. The value 0 means that REQ_OP_WRITE_ZEROES
+is not supported.
+
 zoned (RO)
 ----------
 This indicates if the device is a zoned block device and the zone model of the
-- 
2.22.0.410.gd8fdbe21b5-goog

Re: [PATCH 3/4] block, documentation: Explain the word 'segments'

[Martin K. Petersen]

Bart,

> Several block layer users who are not kernel developers do not know
> that the word 'segment' refers to an element in a DMA scatter/gather
> list. Make the block layer documentation easier to understand by
> stating explicitly what the word 'segment' stands for.

I don't have a problem clarifying the documentation. But the sysfs knobs
have a "segment" suffix so for better or for worse it is part of the
block layer lingo.

Reviewed-by: Martin K. Petersen <martin.petersen@oracle.com>

-- 
Martin K. Petersen	Oracle Linux Engineering

Re: [PATCH 1/4] block, documentation: Fix wbt_lat_usec documentation

[Martin K. Petersen]

Bart,

> Fix the spelling of the wbt_lat_usec sysfs attribute.

Reviewed-by: Martin K. Petersen <martin.petersen@oracle.com>

-- 
Martin K. Petersen	Oracle Linux Engineering

Re: [PATCH 2/4] block, documentation: Sort queue sysfs attribute names alphabetically

[Martin K. Petersen]

Bart,

> Commit f9824952ee1c ("block: update sysfs documentation") # v5.0 broke
> the alphabetical order of the sysfs attribute names. List queue sysfs
> attribute names alphabetically.

Reviewed-by: Martin K. Petersen <martin.petersen@oracle.com>

-- 
Martin K. Petersen	Oracle Linux Engineering

Re: [PATCH 4/4] block, documentation: Document discard_zeroes_data, fua, max_discard_segments and write_zeroes_max_bytes

[Martin K. Petersen]

Bart,

Looks fine.

Reviewed-by: Martin K. Petersen <martin.petersen@oracle.com>

-- 
Martin K. Petersen	Oracle Linux Engineering

Re: [PATCH 0/4] Improve block layer request queue sysfs parameter documentation

[Jens Axboe]

On 6/28/19 2:07 PM, Bart Van Assche wrote:
> Hi Jens,
> 
> While reviewing Documentation/block/queue-sysfs.txt I noticed one spelling
> issue, that the parameters are not listed alphabetically, that the word
> 'segments' needs clarification and also that documentation for some
> parameters is missing. These patches address all four these issues. Please
> consider these patches for kernel v5.3.

Thanks Bart, applied.

-- 
Jens Axboe