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