block: Add sysfs documentation for the discard topology parameters

Add documentation for the discard I/O topology parameters exported in
sysfs.

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

1 files changed, 64 insertions, 0 deletions

diff --git a/Documentation/ABI/testing/sysfs-block b/Documentation/ABI/testing/sysfs-block
index 4873c759d535..c1eb41cb9876 100644
--- a/Documentation/ABI/testing/sysfs-block
+++ b/Documentation/ABI/testing/sysfs-block
@@ -142,3 +142,67 @@ Description:
                 with the previous I/O request are enabled. When set to 2,
                 all merge tries are disabled. The default value is 0 -
                 which enables all types of merge tries.
+
+What:           /sys/block/<disk>/discard_alignment
+Date:           May 2011
+Contact:        Martin K. Petersen <martin.petersen@oracle.com>
+Description:
+                Devices that support discard functionality may
+                internally allocate space in units that are bigger than
+                the exported logical block size. The discard_alignment
+                parameter indicates how many bytes the beginning of the
+                device is offset from the internal allocation unit's
+                natural alignment.
+
+What:           /sys/block/<disk>/<partition>/discard_alignment
+Date:           May 2011
+Contact:        Martin K. Petersen <martin.petersen@oracle.com>
+Description:
+                Devices that support discard functionality may
+                internally allocate space in units that are bigger than
+                the exported logical block size. The discard_alignment
+                parameter indicates how many bytes the beginning of the
+                partition is offset from the internal allocation unit's
+                natural alignment.
+
+What:           /sys/block/<disk>/queue/discard_granularity
+Date:           May 2011
+Contact:        Martin K. Petersen <martin.petersen@oracle.com>
+Description:
+                Devices that support discard functionality may
+                internally allocate space using units that are bigger
+                than the logical block size. The discard_granularity
+                parameter indicates the size of the internal allocation
+                unit in bytes if reported by the device. Otherwise the
+                discard_granularity will be set to match the device's
+                physical block size. A discard_granularity of 0 means
+                that the device does not support discard functionality.
+
+What:           /sys/block/<disk>/queue/discard_max_bytes
+Date:           May 2011
+Contact:        Martin K. Petersen <martin.petersen@oracle.com>
+Description:
+                Devices that support discard functionality may have
+                internal limits on the number of bytes that can be
+                trimmed or unmapped in a single operation. Some storage
+                protocols also have inherent limits on the number of
+                blocks that can be described in a single command. The
+                discard_max_bytes parameter is set by the device driver
+                to the maximum number of bytes that can be discarded in
+                a single operation. Discard requests issued to the
+                device must not exceed this limit. A discard_max_bytes
+                value of 0 means that the device does not support
+                discard functionality.
+
+What:           /sys/block/<disk>/queue/discard_zeroes_data
+Date:           May 2011
+Contact:        Martin K. Petersen <martin.petersen@oracle.com>
+Description:
+                Devices that support discard functionality may return
+                stale or random data when a previously discarded block
+                is read back. This can cause problems if the filesystem
+                expects discarded blocks to be explicitly cleared. If a
+                device reports that it deterministically returns zeroes
+                when a discarded area is read the discard_zeroes_data
+                parameter will be set to one. Otherwise it will be 0 and
+                the result of reading a discarded area is undefined.