block: Update topology documentation

Update topology comments and sysfs documentation based upon discussions
with Neil Brown.

Signed-off-by: Martin K. Petersen <martin.petersen@oracle.com>
Signed-off-by: Jens Axboe <jens.axboe@oracle.com>

1 files changed, 23 insertions, 14 deletions

diff --git a/Documentation/ABI/testing/sysfs-block b/Documentation/ABI/testing/sysfs-block
index cbbd3e069945..5f3bedaf8e35 100644
--- a/Documentation/ABI/testing/sysfs-block
+++ b/Documentation/ABI/testing/sysfs-block
@@ -94,28 +94,37 @@ What:		/sys/block/<disk>/queue/physical_block_size
 Date:           May 2009
 Contact:        Martin K. Petersen <martin.petersen@oracle.com>
 Description:
-                This is the smallest unit the storage device can write
-                without resorting to read-modify-write operation.  It is
-                usually the same as the logical block size but may be
-                bigger.  One example is SATA drives with 4KB sectors
-                that expose a 512-byte logical block size to the
-                operating system.
+                This is the smallest unit a physical storage device can
+                write atomically.  It is usually the same as the logical
+                block size but may be bigger.  One example is SATA
+                drives with 4KB sectors that expose a 512-byte logical
+                block size to the operating system.  For stacked block
+                devices the physical_block_size variable contains the
+                maximum physical_block_size of the component devices.
 
 What:           /sys/block/<disk>/queue/minimum_io_size
 Date:           April 2009
 Contact:        Martin K. Petersen <martin.petersen@oracle.com>
 Description:
-                Storage devices may report a preferred minimum I/O size,
-                which is the smallest request the device can perform
-                without incurring a read-modify-write penalty.  For disk
-                drives this is often the physical block size.  For RAID
-                arrays it is often the stripe chunk size.
+                Storage devices may report a granularity or preferred
+                minimum I/O size which is the smallest request the
+                device can perform without incurring a performance
+                penalty.  For disk drives this is often the physical
+                block size.  For RAID arrays it is often the stripe
+                chunk size.  A properly aligned multiple of
+                minimum_io_size is the preferred request size for
+                workloads where a high number of I/O operations is
+                desired.
 
 What:           /sys/block/<disk>/queue/optimal_io_size
 Date:           April 2009
 Contact:        Martin K. Petersen <martin.petersen@oracle.com>
 Description:
                 Storage devices may report an optimal I/O size, which is
-                the device's preferred unit of receiving I/O.  This is
-                rarely reported for disk drives.  For RAID devices it is
-                usually the stripe width or the internal block size.
+                the device's preferred unit for sustained I/O.  This is
+                rarely reported for disk drives.  For RAID arrays it is
+                usually the stripe width or the internal track size.  A
+                properly aligned multiple of optimal_io_size is the
+                preferred request size for workloads where sustained
+                throughput is desired.  If no optimal I/O size is
+                reported this file contains 0.