[3/4] block, documentation: Explain the word 'segments'
diff mbox series

Message ID 20190628200745.206110-4-bvanassche@acm.org
State New
Headers show
Series
  • Improve block layer request queue sysfs parameter documentation
Related show

Commit Message

Bart Van Assche June 28, 2019, 8:07 p.m. UTC
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(-)

Comments

Martin K. Petersen June 28, 2019, 8:14 p.m. UTC | #1
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>

Patch
diff mbox series

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)
 --------------------