Documentation/ABI/testing/sysfs-block

   1 What:           /sys/block/<disk>/stat
   2 Date:           February 2008
   3 Contact:        Jerome Marchand <jmarchan@redhat.com>
   4 Description:
   5                 The /sys/block/<disk>/stat files displays the I/O
   6                 statistics of disk <disk>. They contain 11 fields:
   7                  1 - reads completed successfully
   8                  2 - reads merged
   9                  3 - sectors read
  10                  4 - time spent reading (ms)
  11                  5 - writes completed
  12                  6 - writes merged
  13                  7 - sectors written
  14                  8 - time spent writing (ms)
  15                  9 - I/Os currently in progress
  16                 10 - time spent doing I/Os (ms)
  17                 11 - weighted time spent doing I/Os (ms)
  18                 12 - discards completed
  19                 13 - discards merged
  20                 14 - sectors discarded
  21                 15 - time spent discarding (ms)
  22                 16 - flush requests completed
  23                 17 - time spent flushing (ms)
  24                 For more details refer Documentation/admin-guide/iostats.rst
  25
  26
  27 What:           /sys/block/<disk>/<part>/stat
  28 Date:           February 2008
  29 Contact:        Jerome Marchand <jmarchan@redhat.com>
  30 Description:
  31                 The /sys/block/<disk>/<part>/stat files display the
  32                 I/O statistics of partition <part>. The format is the
  33                 same as the above-written /sys/block/<disk>/stat
  34                 format.
  35
  36
  37 What:           /sys/block/<disk>/integrity/format
  38 Date:           June 2008
  39 Contact:        Martin K. Petersen <martin.petersen@oracle.com>
  40 Description:
  41                 Metadata format for integrity capable block device.
  42                 E.g. T10-DIF-TYPE1-CRC.
  43
  44
  45 What:           /sys/block/<disk>/integrity/read_verify
  46 Date:           June 2008
  47 Contact:        Martin K. Petersen <martin.petersen@oracle.com>
  48 Description:
  49                 Indicates whether the block layer should verify the
  50                 integrity of read requests serviced by devices that
  51                 support sending integrity metadata.
  52
  53
  54 What:           /sys/block/<disk>/integrity/tag_size
  55 Date:           June 2008
  56 Contact:        Martin K. Petersen <martin.petersen@oracle.com>
  57 Description:
  58                 Number of bytes of integrity tag space available per
  59                 512 bytes of data.
  60
  61
  62 What:           /sys/block/<disk>/integrity/device_is_integrity_capable
  63 Date:           July 2014
  64 Contact:        Martin K. Petersen <martin.petersen@oracle.com>
  65 Description:
  66                 Indicates whether a storage device is capable of storing
  67                 integrity metadata. Set if the device is T10 PI-capable.
  68
  69 What:           /sys/block/<disk>/integrity/protection_interval_bytes
  70 Date:           July 2015
  71 Contact:        Martin K. Petersen <martin.petersen@oracle.com>
  72 Description:
  73                 Describes the number of data bytes which are protected
  74                 by one integrity tuple. Typically the device's logical
  75                 block size.
  76
  77 What:           /sys/block/<disk>/integrity/write_generate
  78 Date:           June 2008
  79 Contact:        Martin K. Petersen <martin.petersen@oracle.com>
  80 Description:
  81                 Indicates whether the block layer should automatically
  82                 generate checksums for write requests bound for
  83                 devices that support receiving integrity metadata.
  84
  85 What:           /sys/block/<disk>/alignment_offset
  86 Date:           April 2009
  87 Contact:        Martin K. Petersen <martin.petersen@oracle.com>
  88 Description:
  89                 Storage devices may report a physical block size that is
  90                 bigger than the logical block size (for instance a drive
  91                 with 4KB physical sectors exposing 512-byte logical
  92                 blocks to the operating system).  This parameter
  93                 indicates how many bytes the beginning of the device is
  94                 offset from the disk's natural alignment.
  95
  96 What:           /sys/block/<disk>/<partition>/alignment_offset
  97 Date:           April 2009
  98 Contact:        Martin K. Petersen <martin.petersen@oracle.com>
  99 Description:
 100                 Storage devices may report a physical block size that is
 101                 bigger than the logical block size (for instance a drive
 102                 with 4KB physical sectors exposing 512-byte logical
 103                 blocks to the operating system).  This parameter
 104                 indicates how many bytes the beginning of the partition
 105                 is offset from the disk's natural alignment.
 106
 107 What:           /sys/block/<disk>/queue/logical_block_size
 108 Date:           May 2009
 109 Contact:        Martin K. Petersen <martin.petersen@oracle.com>
 110 Description:
 111                 This is the smallest unit the storage device can
 112                 address.  It is typically 512 bytes.
 113
 114 What:           /sys/block/<disk>/queue/physical_block_size
 115 Date:           May 2009
 116 Contact:        Martin K. Petersen <martin.petersen@oracle.com>
 117 Description:
 118                 This is the smallest unit a physical storage device can
 119                 write atomically.  It is usually the same as the logical
 120                 block size but may be bigger.  One example is SATA
 121                 drives with 4KB sectors that expose a 512-byte logical
 122                 block size to the operating system.  For stacked block
 123                 devices the physical_block_size variable contains the
 124                 maximum physical_block_size of the component devices.
 125
 126 What:           /sys/block/<disk>/queue/minimum_io_size
 127 Date:           April 2009
 128 Contact:        Martin K. Petersen <martin.petersen@oracle.com>
 129 Description:
 130                 Storage devices may report a granularity or preferred
 131                 minimum I/O size which is the smallest request the
 132                 device can perform without incurring a performance
 133                 penalty.  For disk drives this is often the physical
 134                 block size.  For RAID arrays it is often the stripe
 135                 chunk size.  A properly aligned multiple of
 136                 minimum_io_size is the preferred request size for
 137                 workloads where a high number of I/O operations is
 138                 desired.
 139
 140 What:           /sys/block/<disk>/queue/optimal_io_size
 141 Date:           April 2009
 142 Contact:        Martin K. Petersen <martin.petersen@oracle.com>
 143 Description:
 144                 Storage devices may report an optimal I/O size, which is
 145                 the device's preferred unit for sustained I/O.  This is
 146                 rarely reported for disk drives.  For RAID arrays it is
 147                 usually the stripe width or the internal track size.  A
 148                 properly aligned multiple of optimal_io_size is the
 149                 preferred request size for workloads where sustained
 150                 throughput is desired.  If no optimal I/O size is
 151                 reported this file contains 0.
 152
 153 What:           /sys/block/<disk>/queue/nomerges
 154 Date:           January 2010
 155 Contact:
 156 Description:
 157                 Standard I/O elevator operations include attempts to
 158                 merge contiguous I/Os. For known random I/O loads these
 159                 attempts will always fail and result in extra cycles
 160                 being spent in the kernel. This allows one to turn off
 161                 this behavior on one of two ways: When set to 1, complex
 162                 merge checks are disabled, but the simple one-shot merges
 163                 with the previous I/O request are enabled. When set to 2,
 164                 all merge tries are disabled. The default value is 0 -
 165                 which enables all types of merge tries.
 166
 167 What:           /sys/block/<disk>/discard_alignment
 168 Date:           May 2011
 169 Contact:        Martin K. Petersen <martin.petersen@oracle.com>
 170 Description:
 171                 Devices that support discard functionality may
 172                 internally allocate space in units that are bigger than
 173                 the exported logical block size. The discard_alignment
 174                 parameter indicates how many bytes the beginning of the
 175                 device is offset from the internal allocation unit's
 176                 natural alignment.
 177
 178 What:           /sys/block/<disk>/<partition>/discard_alignment
 179 Date:           May 2011
 180 Contact:        Martin K. Petersen <martin.petersen@oracle.com>
 181 Description:
 182                 Devices that support discard functionality may
 183                 internally allocate space in units that are bigger than
 184                 the exported logical block size. The discard_alignment
 185                 parameter indicates how many bytes the beginning of the
 186                 partition is offset from the internal allocation unit's
 187                 natural alignment.
 188
 189 What:           /sys/block/<disk>/queue/discard_granularity
 190 Date:           May 2011
 191 Contact:        Martin K. Petersen <martin.petersen@oracle.com>
 192 Description:
 193                 Devices that support discard functionality may
 194                 internally allocate space using units that are bigger
 195                 than the logical block size. The discard_granularity
 196                 parameter indicates the size of the internal allocation
 197                 unit in bytes if reported by the device. Otherwise the
 198                 discard_granularity will be set to match the device's
 199                 physical block size. A discard_granularity of 0 means
 200                 that the device does not support discard functionality.
 201
 202 What:           /sys/block/<disk>/queue/discard_max_bytes
 203 Date:           May 2011
 204 Contact:        Martin K. Petersen <martin.petersen@oracle.com>
 205 Description:
 206                 Devices that support discard functionality may have
 207                 internal limits on the number of bytes that can be
 208                 trimmed or unmapped in a single operation. Some storage
 209                 protocols also have inherent limits on the number of
 210                 blocks that can be described in a single command. The
 211                 discard_max_bytes parameter is set by the device driver
 212                 to the maximum number of bytes that can be discarded in
 213                 a single operation. Discard requests issued to the
 214                 device must not exceed this limit. A discard_max_bytes
 215                 value of 0 means that the device does not support
 216                 discard functionality.
 217
 218 What:           /sys/block/<disk>/queue/discard_zeroes_data
 219 Date:           May 2011
 220 Contact:        Martin K. Petersen <martin.petersen@oracle.com>
 221 Description:
 222                 Will always return 0.  Don't rely on any specific behavior
 223                 for discards, and don't read this file.
 224
 225 What:           /sys/block/<disk>/queue/write_same_max_bytes
 226 Date:           January 2012
 227 Contact:        Martin K. Petersen <martin.petersen@oracle.com>
 228 Description:
 229                 Some devices support a write same operation in which a
 230                 single data block can be written to a range of several
 231                 contiguous blocks on storage. This can be used to wipe
 232                 areas on disk or to initialize drives in a RAID
 233                 configuration. write_same_max_bytes indicates how many
 234                 bytes can be written in a single write same command. If
 235                 write_same_max_bytes is 0, write same is not supported
 236                 by the device.
 237
 238 What:           /sys/block/<disk>/queue/write_zeroes_max_bytes
 239 Date:           November 2016
 240 Contact:        Chaitanya Kulkarni <chaitanya.kulkarni@wdc.com>
 241 Description:
 242                 Devices that support write zeroes operation in which a
 243                 single request can be issued to zero out the range of
 244                 contiguous blocks on storage without having any payload
 245                 in the request. This can be used to optimize writing zeroes
 246                 to the devices. write_zeroes_max_bytes indicates how many
 247                 bytes can be written in a single write zeroes command. If
 248                 write_zeroes_max_bytes is 0, write zeroes is not supported
 249                 by the device.
 250
 251 What:           /sys/block/<disk>/queue/zoned
 252 Date:           September 2016
 253 Contact:        Damien Le Moal <damien.lemoal@wdc.com>
 254 Description:
 255                 zoned indicates if the device is a zoned block device
 256                 and the zone model of the device if it is indeed zoned.
 257                 The possible values indicated by zoned are "none" for
 258                 regular block devices and "host-aware" or "host-managed"
 259                 for zoned block devices. The characteristics of
 260                 host-aware and host-managed zoned block devices are
 261                 described in the ZBC (Zoned Block Commands) and ZAC
 262                 (Zoned Device ATA Command Set) standards. These standards
 263                 also define the "drive-managed" zone model. However,
 264                 since drive-managed zoned block devices do not support
 265                 zone commands, they will be treated as regular block
 266                 devices and zoned will report "none".
 267
 268 What:           /sys/block/<disk>/queue/nr_zones
 269 Date:           November 2018
 270 Contact:        Damien Le Moal <damien.lemoal@wdc.com>
 271 Description:
 272                 nr_zones indicates the total number of zones of a zoned block
 273                 device ("host-aware" or "host-managed" zone model). For regular
 274                 block devices, the value is always 0.
 275
 276 What:           /sys/block/<disk>/queue/max_active_zones
 277 Date:           July 2020
 278 Contact:        Niklas Cassel <niklas.cassel@wdc.com>
 279 Description:
 280                 For zoned block devices (zoned attribute indicating
 281                 "host-managed" or "host-aware"), the sum of zones belonging to
 282                 any of the zone states: EXPLICIT OPEN, IMPLICIT OPEN or CLOSED,
 283                 is limited by this value. If this value is 0, there is no limit.
 284
 285 What:           /sys/block/<disk>/queue/max_open_zones
 286 Date:           July 2020
 287 Contact:        Niklas Cassel <niklas.cassel@wdc.com>
 288 Description:
 289                 For zoned block devices (zoned attribute indicating
 290                 "host-managed" or "host-aware"), the sum of zones belonging to
 291                 any of the zone states: EXPLICIT OPEN or IMPLICIT OPEN,
 292                 is limited by this value. If this value is 0, there is no limit.
 293
 294 What:           /sys/block/<disk>/queue/chunk_sectors
 295 Date:           September 2016
 296 Contact:        Hannes Reinecke <hare@suse.com>
 297 Description:
 298                 chunk_sectors has different meaning depending on the type
 299                 of the disk. For a RAID device (dm-raid), chunk_sectors
 300                 indicates the size in 512B sectors of the RAID volume
 301                 stripe segment. For a zoned block device, either
 302                 host-aware or host-managed, chunk_sectors indicates the
 303                 size in 512B sectors of the zones of the device, with
 304                 the eventual exception of the last zone of the device
 305                 which may be smaller.
 306
 307 What:           /sys/block/<disk>/queue/io_timeout
 308 Date:           November 2018
 309 Contact:        Weiping Zhang <zhangweiping@didiglobal.com>
 310 Description:
 311                 io_timeout is the request timeout in milliseconds. If a request
 312                 does not complete in this time then the block driver timeout
 313                 handler is invoked. That timeout handler can decide to retry
 314                 the request, to fail it or to start a device recovery strategy.