docs: sysfs-block: Clarify integrity sysfs attributes

The /sys/block/<disk>/integrity fields are historically set
if T10 protection Information is enabled.

It is not set if some upper layer uses integrity metadata.
Document it.

Signed-off-by: Milan Broz <gmazyland@gmail.com>
Co-developed-by: Martin K. Petersen <martin.petersen@oracle.com>
Reviewed-by: Christoph Hellwig <hch@lst.de>
Link: https://lore.kernel.org/r/20250318154447.370786-1-gmazyland@gmail.com
Signed-off-by: Jens Axboe <axboe@kernel.dk>

diff --git a/Documentation/ABI/stable/sysfs-block b/Documentation/ABI/stable/sysfs-block
index 890cde28bf90d92f4f86f6f260397b1d5e1f59f1..3879963f0f01e5f291e40bb7cf3fb638e7a61d6b 100644 (file)
--- a/Documentation/ABI/stable/sysfs-block
+++ b/Documentation/ABI/stable/sysfs-block
@@ -109,6 +109,10 @@ Contact:   Martin K. Petersen <martin.petersen@oracle.com>
 Description:
                Indicates whether a storage device is capable of storing
                integrity metadata. Set if the device is T10 PI-capable.
+               This flag is set to 1 if the storage media is formatted
+               with T10 Protection Information. If the storage media is
+               not formatted with T10 Protection Information, this flag
+               is set to 0.
 
 
 What:          /sys/block/<disk>/integrity/format
@@ -117,6 +121,13 @@ Contact:   Martin K. Petersen <martin.petersen@oracle.com>
 Description:
                Metadata format for integrity capable block device.
                E.g. T10-DIF-TYPE1-CRC.
+               This field describes the type of T10 Protection Information
+               that the block device can send and receive.
+               If the device can store application integrity metadata but
+               no T10 Protection Information profile is used, this field
+               contains "nop".
+               If the device does not support integrity metadata, this
+               field contains "none".
 
 
 What:          /sys/block/<disk>/integrity/protection_interval_bytes
@@ -142,7 +153,17 @@ Date:              June 2008
 Contact:       Martin K. Petersen <martin.petersen@oracle.com>
 Description:
                Number of bytes of integrity tag space available per
-               512 bytes of data.
+               protection_interval_bytes, which is typically
+               the device's logical block size.
+               This field describes the size of the application tag
+               if the storage device is formatted with T10 Protection
+               Information and permits use of the application tag.
+               The tag_size is reported in bytes and indicates the
+               space available for adding an opaque tag to each block
+               (protection_interval_bytes).
+               If the device does not support T10 Protection Information
+               (even if the device provides application integrity
+               metadata space), this field is set to 0.
 
 
 What:          /sys/block/<disk>/integrity/write_generate