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