xref: /linux/Documentation/ABI/stable/sysfs-block (revision 3850e13f)
107c9093cSEric BiggersWhat:		/sys/block/<disk>/alignment_offset
207c9093cSEric BiggersDate:		April 2009
307c9093cSEric BiggersContact:	Martin K. Petersen <martin.petersen@oracle.com>
407c9093cSEric BiggersDescription:
507c9093cSEric Biggers		Storage devices may report a physical block size that is
607c9093cSEric Biggers		bigger than the logical block size (for instance a drive
707c9093cSEric Biggers		with 4KB physical sectors exposing 512-byte logical
807c9093cSEric Biggers		blocks to the operating system).  This parameter
907c9093cSEric Biggers		indicates how many bytes the beginning of the device is
1007c9093cSEric Biggers		offset from the disk's natural alignment.
1107c9093cSEric Biggers
1207c9093cSEric Biggers
1307c9093cSEric BiggersWhat:		/sys/block/<disk>/discard_alignment
1407c9093cSEric BiggersDate:		May 2011
1507c9093cSEric BiggersContact:	Martin K. Petersen <martin.petersen@oracle.com>
1607c9093cSEric BiggersDescription:
1707c9093cSEric Biggers		Devices that support discard functionality may
1807c9093cSEric Biggers		internally allocate space in units that are bigger than
1907c9093cSEric Biggers		the exported logical block size. The discard_alignment
2007c9093cSEric Biggers		parameter indicates how many bytes the beginning of the
2107c9093cSEric Biggers		device is offset from the internal allocation unit's
2207c9093cSEric Biggers		natural alignment.
2307c9093cSEric Biggers
2407c9093cSEric Biggers
2507c9093cSEric BiggersWhat:		/sys/block/<disk>/diskseq
2607c9093cSEric BiggersDate:		February 2021
2707c9093cSEric BiggersContact:	Matteo Croce <mcroce@microsoft.com>
2807c9093cSEric BiggersDescription:
2907c9093cSEric Biggers		The /sys/block/<disk>/diskseq files reports the disk
3007c9093cSEric Biggers		sequence number, which is a monotonically increasing
3107c9093cSEric Biggers		number assigned to every drive.
3207c9093cSEric Biggers		Some devices, like the loop device, refresh such number
3307c9093cSEric Biggers		every time the backing file is changed.
3407c9093cSEric Biggers		The value type is 64 bit unsigned.
3507c9093cSEric Biggers
3607c9093cSEric Biggers
3707c9093cSEric BiggersWhat:		/sys/block/<disk>/inflight
3807c9093cSEric BiggersDate:		October 2009
3907c9093cSEric BiggersContact:	Jens Axboe <axboe@kernel.dk>, Nikanth Karthikesan <knikanth@suse.de>
4007c9093cSEric BiggersDescription:
4107c9093cSEric Biggers		Reports the number of I/O requests currently in progress
4207c9093cSEric Biggers		(pending / in flight) in a device driver. This can be less
4307c9093cSEric Biggers		than the number of requests queued in the block device queue.
4407c9093cSEric Biggers		The report contains 2 fields: one for read requests
4507c9093cSEric Biggers		and one for write requests.
4607c9093cSEric Biggers		The value type is unsigned int.
4707c9093cSEric Biggers		Cf. Documentation/block/stat.rst which contains a single value for
4807c9093cSEric Biggers		requests in flight.
49849ab826SEric Biggers		This is related to /sys/block/<disk>/queue/nr_requests
5007c9093cSEric Biggers		and for SCSI device also its queue_depth.
5107c9093cSEric Biggers
5207c9093cSEric Biggers
5307c9093cSEric BiggersWhat:		/sys/block/<disk>/integrity/device_is_integrity_capable
5407c9093cSEric BiggersDate:		July 2014
5507c9093cSEric BiggersContact:	Martin K. Petersen <martin.petersen@oracle.com>
5607c9093cSEric BiggersDescription:
5707c9093cSEric Biggers		Indicates whether a storage device is capable of storing
5807c9093cSEric Biggers		integrity metadata. Set if the device is T10 PI-capable.
5907c9093cSEric Biggers
6007c9093cSEric Biggers
6107c9093cSEric BiggersWhat:		/sys/block/<disk>/integrity/format
6207c9093cSEric BiggersDate:		June 2008
6307c9093cSEric BiggersContact:	Martin K. Petersen <martin.petersen@oracle.com>
6407c9093cSEric BiggersDescription:
6507c9093cSEric Biggers		Metadata format for integrity capable block device.
6607c9093cSEric Biggers		E.g. T10-DIF-TYPE1-CRC.
6707c9093cSEric Biggers
6807c9093cSEric Biggers
6907c9093cSEric BiggersWhat:		/sys/block/<disk>/integrity/protection_interval_bytes
7007c9093cSEric BiggersDate:		July 2015
7107c9093cSEric BiggersContact:	Martin K. Petersen <martin.petersen@oracle.com>
7207c9093cSEric BiggersDescription:
7307c9093cSEric Biggers		Describes the number of data bytes which are protected
7407c9093cSEric Biggers		by one integrity tuple. Typically the device's logical
7507c9093cSEric Biggers		block size.
7607c9093cSEric Biggers
7707c9093cSEric Biggers
7807c9093cSEric BiggersWhat:		/sys/block/<disk>/integrity/read_verify
7907c9093cSEric BiggersDate:		June 2008
8007c9093cSEric BiggersContact:	Martin K. Petersen <martin.petersen@oracle.com>
8107c9093cSEric BiggersDescription:
8207c9093cSEric Biggers		Indicates whether the block layer should verify the
8307c9093cSEric Biggers		integrity of read requests serviced by devices that
8407c9093cSEric Biggers		support sending integrity metadata.
8507c9093cSEric Biggers
8607c9093cSEric Biggers
8707c9093cSEric BiggersWhat:		/sys/block/<disk>/integrity/tag_size
8807c9093cSEric BiggersDate:		June 2008
8907c9093cSEric BiggersContact:	Martin K. Petersen <martin.petersen@oracle.com>
9007c9093cSEric BiggersDescription:
9107c9093cSEric Biggers		Number of bytes of integrity tag space available per
9207c9093cSEric Biggers		512 bytes of data.
9307c9093cSEric Biggers
9407c9093cSEric Biggers
9507c9093cSEric BiggersWhat:		/sys/block/<disk>/integrity/write_generate
9607c9093cSEric BiggersDate:		June 2008
9707c9093cSEric BiggersContact:	Martin K. Petersen <martin.petersen@oracle.com>
9807c9093cSEric BiggersDescription:
9907c9093cSEric Biggers		Indicates whether the block layer should automatically
10007c9093cSEric Biggers		generate checksums for write requests bound for
10107c9093cSEric Biggers		devices that support receiving integrity metadata.
10207c9093cSEric Biggers
10307c9093cSEric Biggers
10407c9093cSEric BiggersWhat:		/sys/block/<disk>/<partition>/alignment_offset
10507c9093cSEric BiggersDate:		April 2009
10607c9093cSEric BiggersContact:	Martin K. Petersen <martin.petersen@oracle.com>
10707c9093cSEric BiggersDescription:
10807c9093cSEric Biggers		Storage devices may report a physical block size that is
10907c9093cSEric Biggers		bigger than the logical block size (for instance a drive
11007c9093cSEric Biggers		with 4KB physical sectors exposing 512-byte logical
11107c9093cSEric Biggers		blocks to the operating system).  This parameter
11207c9093cSEric Biggers		indicates how many bytes the beginning of the partition
11307c9093cSEric Biggers		is offset from the disk's natural alignment.
11407c9093cSEric Biggers
11507c9093cSEric Biggers
11607c9093cSEric BiggersWhat:		/sys/block/<disk>/<partition>/discard_alignment
11707c9093cSEric BiggersDate:		May 2011
11807c9093cSEric BiggersContact:	Martin K. Petersen <martin.petersen@oracle.com>
11907c9093cSEric BiggersDescription:
12007c9093cSEric Biggers		Devices that support discard functionality may
12107c9093cSEric Biggers		internally allocate space in units that are bigger than
12207c9093cSEric Biggers		the exported logical block size. The discard_alignment
12307c9093cSEric Biggers		parameter indicates how many bytes the beginning of the
12407c9093cSEric Biggers		partition is offset from the internal allocation unit's
12507c9093cSEric Biggers		natural alignment.
12607c9093cSEric Biggers
12707c9093cSEric Biggers
12807c9093cSEric BiggersWhat:		/sys/block/<disk>/<partition>/stat
12907c9093cSEric BiggersDate:		February 2008
13007c9093cSEric BiggersContact:	Jerome Marchand <jmarchan@redhat.com>
13107c9093cSEric BiggersDescription:
13207c9093cSEric Biggers		The /sys/block/<disk>/<partition>/stat files display the
13307c9093cSEric Biggers		I/O statistics of partition <partition>. The format is the
13407c9093cSEric Biggers		same as the format of /sys/block/<disk>/stat.
13507c9093cSEric Biggers
13607c9093cSEric Biggers
137849ab826SEric BiggersWhat:		/sys/block/<disk>/queue/add_random
138849ab826SEric BiggersDate:		June 2010
139849ab826SEric BiggersContact:	linux-block@vger.kernel.org
140849ab826SEric BiggersDescription:
141849ab826SEric Biggers		[RW] This file allows to turn off the disk entropy contribution.
142849ab826SEric Biggers		Default value of this file is '1'(on).
143849ab826SEric Biggers
144849ab826SEric Biggers
14507c9093cSEric BiggersWhat:		/sys/block/<disk>/queue/chunk_sectors
14607c9093cSEric BiggersDate:		September 2016
14707c9093cSEric BiggersContact:	Hannes Reinecke <hare@suse.com>
14807c9093cSEric BiggersDescription:
149849ab826SEric Biggers		[RO] chunk_sectors has different meaning depending on the type
15007c9093cSEric Biggers		of the disk. For a RAID device (dm-raid), chunk_sectors
151849ab826SEric Biggers		indicates the size in 512B sectors of the RAID volume stripe
152849ab826SEric Biggers		segment. For a zoned block device, either host-aware or
153849ab826SEric Biggers		host-managed, chunk_sectors indicates the size in 512B sectors
154849ab826SEric Biggers		of the zones of the device, with the eventual exception of the
155849ab826SEric Biggers		last zone of the device which may be smaller.
156849ab826SEric Biggers
157849ab826SEric Biggers
15820f01f16SEric BiggersWhat:		/sys/block/<disk>/queue/crypto/
15920f01f16SEric BiggersDate:		February 2022
16020f01f16SEric BiggersContact:	linux-block@vger.kernel.org
16120f01f16SEric BiggersDescription:
16220f01f16SEric Biggers		The presence of this subdirectory of /sys/block/<disk>/queue/
16320f01f16SEric Biggers		indicates that the device supports inline encryption.  This
16420f01f16SEric Biggers		subdirectory contains files which describe the inline encryption
16520f01f16SEric Biggers		capabilities of the device.  For more information about inline
16620f01f16SEric Biggers		encryption, refer to Documentation/block/inline-encryption.rst.
16720f01f16SEric Biggers
16820f01f16SEric Biggers
16920f01f16SEric BiggersWhat:		/sys/block/<disk>/queue/crypto/max_dun_bits
17020f01f16SEric BiggersDate:		February 2022
17120f01f16SEric BiggersContact:	linux-block@vger.kernel.org
17220f01f16SEric BiggersDescription:
17320f01f16SEric Biggers		[RO] This file shows the maximum length, in bits, of data unit
17420f01f16SEric Biggers		numbers accepted by the device in inline encryption requests.
17520f01f16SEric Biggers
17620f01f16SEric Biggers
17720f01f16SEric BiggersWhat:		/sys/block/<disk>/queue/crypto/modes/<mode>
17820f01f16SEric BiggersDate:		February 2022
17920f01f16SEric BiggersContact:	linux-block@vger.kernel.org
18020f01f16SEric BiggersDescription:
18120f01f16SEric Biggers		[RO] For each crypto mode (i.e., encryption/decryption
18220f01f16SEric Biggers		algorithm) the device supports with inline encryption, a file
18320f01f16SEric Biggers		will exist at this location.  It will contain a hexadecimal
18420f01f16SEric Biggers		number that is a bitmask of the supported data unit sizes, in
18520f01f16SEric Biggers		bytes, for that crypto mode.
18620f01f16SEric Biggers
18720f01f16SEric Biggers		Currently, the crypto modes that may be supported are:
18820f01f16SEric Biggers
18920f01f16SEric Biggers		   * AES-256-XTS
19020f01f16SEric Biggers		   * AES-128-CBC-ESSIV
19120f01f16SEric Biggers		   * Adiantum
19220f01f16SEric Biggers
19320f01f16SEric Biggers		For example, if a device supports AES-256-XTS inline encryption
19420f01f16SEric Biggers		with data unit sizes of 512 and 4096 bytes, the file
19520f01f16SEric Biggers		/sys/block/<disk>/queue/crypto/modes/AES-256-XTS will exist and
19620f01f16SEric Biggers		will contain "0x1200".
19720f01f16SEric Biggers
19820f01f16SEric Biggers
19920f01f16SEric BiggersWhat:		/sys/block/<disk>/queue/crypto/num_keyslots
20020f01f16SEric BiggersDate:		February 2022
20120f01f16SEric BiggersContact:	linux-block@vger.kernel.org
20220f01f16SEric BiggersDescription:
20320f01f16SEric Biggers		[RO] This file shows the number of keyslots the device has for
20420f01f16SEric Biggers		use with inline encryption.
20520f01f16SEric Biggers
20620f01f16SEric Biggers
207849ab826SEric BiggersWhat:		/sys/block/<disk>/queue/dax
208849ab826SEric BiggersDate:		June 2016
209849ab826SEric BiggersContact:	linux-block@vger.kernel.org
210849ab826SEric BiggersDescription:
211849ab826SEric Biggers		[RO] This file indicates whether the device supports Direct
212849ab826SEric Biggers		Access (DAX), used by CPU-addressable storage to bypass the
213849ab826SEric Biggers		pagecache.  It shows '1' if true, '0' if not.
21407c9093cSEric Biggers
21507c9093cSEric Biggers
21607c9093cSEric BiggersWhat:		/sys/block/<disk>/queue/discard_granularity
21707c9093cSEric BiggersDate:		May 2011
21807c9093cSEric BiggersContact:	Martin K. Petersen <martin.petersen@oracle.com>
21907c9093cSEric BiggersDescription:
220849ab826SEric Biggers		[RO] Devices that support discard functionality may internally
221849ab826SEric Biggers		allocate space using units that are bigger than the logical
222849ab826SEric Biggers		block size. The discard_granularity parameter indicates the size
223849ab826SEric Biggers		of the internal allocation unit in bytes if reported by the
224849ab826SEric Biggers		device. Otherwise the discard_granularity will be set to match
225849ab826SEric Biggers		the device's physical block size. A discard_granularity of 0
226849ab826SEric Biggers		means that the device does not support discard functionality.
22707c9093cSEric Biggers
22807c9093cSEric Biggers
22907c9093cSEric BiggersWhat:		/sys/block/<disk>/queue/discard_max_bytes
23007c9093cSEric BiggersDate:		May 2011
23107c9093cSEric BiggersContact:	Martin K. Petersen <martin.petersen@oracle.com>
23207c9093cSEric BiggersDescription:
233849ab826SEric Biggers		[RW] While discard_max_hw_bytes is the hardware limit for the
234849ab826SEric Biggers		device, this setting is the software limit. Some devices exhibit
235849ab826SEric Biggers		large latencies when large discards are issued, setting this
236849ab826SEric Biggers		value lower will make Linux issue smaller discards and
237849ab826SEric Biggers		potentially help reduce latencies induced by large discard
238849ab826SEric Biggers		operations.
239849ab826SEric Biggers
240849ab826SEric Biggers
241849ab826SEric BiggersWhat:		/sys/block/<disk>/queue/discard_max_hw_bytes
242849ab826SEric BiggersDate:		July 2015
243849ab826SEric BiggersContact:	linux-block@vger.kernel.org
244849ab826SEric BiggersDescription:
245849ab826SEric Biggers		[RO] Devices that support discard functionality may have
246849ab826SEric Biggers		internal limits on the number of bytes that can be trimmed or
247849ab826SEric Biggers		unmapped in a single operation.  The `discard_max_hw_bytes`
248849ab826SEric Biggers		parameter is set by the device driver to the maximum number of
249849ab826SEric Biggers		bytes that can be discarded in a single operation.  Discard
250849ab826SEric Biggers		requests issued to the device must not exceed this limit.  A
251849ab826SEric Biggers		`discard_max_hw_bytes` value of 0 means that the device does not
252849ab826SEric Biggers		support discard functionality.
25307c9093cSEric Biggers
25407c9093cSEric Biggers
25507c9093cSEric BiggersWhat:		/sys/block/<disk>/queue/discard_zeroes_data
25607c9093cSEric BiggersDate:		May 2011
25707c9093cSEric BiggersContact:	Martin K. Petersen <martin.petersen@oracle.com>
25807c9093cSEric BiggersDescription:
259849ab826SEric Biggers		[RO] Will always return 0.  Don't rely on any specific behavior
26007c9093cSEric Biggers		for discards, and don't read this file.
26107c9093cSEric Biggers
26207c9093cSEric Biggers
263*3850e13fSKeith BuschWhat:		/sys/block/<disk>/queue/dma_alignment
264*3850e13fSKeith BuschDate:		May 2022
265*3850e13fSKeith BuschContact:	linux-block@vger.kernel.org
266*3850e13fSKeith BuschDescription:
267*3850e13fSKeith Busch		Reports the alignment that user space addresses must have to be
268*3850e13fSKeith Busch		used for raw block device access with O_DIRECT and other driver
269*3850e13fSKeith Busch		specific passthrough mechanisms.
270*3850e13fSKeith Busch
271*3850e13fSKeith Busch
272849ab826SEric BiggersWhat:		/sys/block/<disk>/queue/fua
273849ab826SEric BiggersDate:		May 2018
274849ab826SEric BiggersContact:	linux-block@vger.kernel.org
275849ab826SEric BiggersDescription:
276849ab826SEric Biggers		[RO] Whether or not the block driver supports the FUA flag for
277849ab826SEric Biggers		write requests.  FUA stands for Force Unit Access. If the FUA
278849ab826SEric Biggers		flag is set that means that write requests must bypass the
279849ab826SEric Biggers		volatile cache of the storage device.
280849ab826SEric Biggers
281849ab826SEric Biggers
282849ab826SEric BiggersWhat:		/sys/block/<disk>/queue/hw_sector_size
283849ab826SEric BiggersDate:		January 2008
284849ab826SEric BiggersContact:	linux-block@vger.kernel.org
285849ab826SEric BiggersDescription:
286849ab826SEric Biggers		[RO] This is the hardware sector size of the device, in bytes.
287849ab826SEric Biggers
288849ab826SEric Biggers
289849ab826SEric BiggersWhat:		/sys/block/<disk>/queue/independent_access_ranges/
290849ab826SEric BiggersDate:		October 2021
291849ab826SEric BiggersContact:	linux-block@vger.kernel.org
292849ab826SEric BiggersDescription:
293849ab826SEric Biggers		[RO] The presence of this sub-directory of the
294849ab826SEric Biggers		/sys/block/xxx/queue/ directory indicates that the device is
295849ab826SEric Biggers		capable of executing requests targeting different sector ranges
296849ab826SEric Biggers		in parallel. For instance, single LUN multi-actuator hard-disks
297849ab826SEric Biggers		will have an independent_access_ranges directory if the device
298849ab826SEric Biggers		correctly advertizes the sector ranges of its actuators.
299849ab826SEric Biggers
300849ab826SEric Biggers		The independent_access_ranges directory contains one directory
301849ab826SEric Biggers		per access range, with each range described using the sector
302849ab826SEric Biggers		(RO) attribute file to indicate the first sector of the range
303849ab826SEric Biggers		and the nr_sectors (RO) attribute file to indicate the total
304849ab826SEric Biggers		number of sectors in the range starting from the first sector of
305849ab826SEric Biggers		the range.  For example, a dual-actuator hard-disk will have the
306849ab826SEric Biggers		following independent_access_ranges entries.::
307849ab826SEric Biggers
308849ab826SEric Biggers			$ tree /sys/block/<disk>/queue/independent_access_ranges/
309849ab826SEric Biggers			/sys/block/<disk>/queue/independent_access_ranges/
310849ab826SEric Biggers			|-- 0
311849ab826SEric Biggers			|   |-- nr_sectors
312849ab826SEric Biggers			|   `-- sector
313849ab826SEric Biggers			`-- 1
314849ab826SEric Biggers			    |-- nr_sectors
315849ab826SEric Biggers			    `-- sector
316849ab826SEric Biggers
317849ab826SEric Biggers		The sector and nr_sectors attributes use 512B sector unit,
318849ab826SEric Biggers		regardless of the actual block size of the device. Independent
319849ab826SEric Biggers		access ranges do not overlap and include all sectors within the
320849ab826SEric Biggers		device capacity. The access ranges are numbered in increasing
321849ab826SEric Biggers		order of the range start sector, that is, the sector attribute
322849ab826SEric Biggers		of range 0 always has the value 0.
323849ab826SEric Biggers
324849ab826SEric Biggers
325849ab826SEric BiggersWhat:		/sys/block/<disk>/queue/io_poll
326849ab826SEric BiggersDate:		November 2015
327849ab826SEric BiggersContact:	linux-block@vger.kernel.org
328849ab826SEric BiggersDescription:
329849ab826SEric Biggers		[RW] When read, this file shows whether polling is enabled (1)
330849ab826SEric Biggers		or disabled (0).  Writing '0' to this file will disable polling
331849ab826SEric Biggers		for this device.  Writing any non-zero value will enable this
332849ab826SEric Biggers		feature.
333849ab826SEric Biggers
334849ab826SEric Biggers
335849ab826SEric BiggersWhat:		/sys/block/<disk>/queue/io_poll_delay
336849ab826SEric BiggersDate:		November 2016
337849ab826SEric BiggersContact:	linux-block@vger.kernel.org
338849ab826SEric BiggersDescription:
339849ab826SEric Biggers		[RW] If polling is enabled, this controls what kind of polling
340849ab826SEric Biggers		will be performed. It defaults to -1, which is classic polling.
341849ab826SEric Biggers		In this mode, the CPU will repeatedly ask for completions
342849ab826SEric Biggers		without giving up any time.  If set to 0, a hybrid polling mode
343849ab826SEric Biggers		is used, where the kernel will attempt to make an educated guess
344849ab826SEric Biggers		at when the IO will complete. Based on this guess, the kernel
345849ab826SEric Biggers		will put the process issuing IO to sleep for an amount of time,
346849ab826SEric Biggers		before entering a classic poll loop. This mode might be a little
347849ab826SEric Biggers		slower than pure classic polling, but it will be more efficient.
348849ab826SEric Biggers		If set to a value larger than 0, the kernel will put the process
349849ab826SEric Biggers		issuing IO to sleep for this amount of microseconds before
350849ab826SEric Biggers		entering classic polling.
351849ab826SEric Biggers
352849ab826SEric Biggers
35307c9093cSEric BiggersWhat:		/sys/block/<disk>/queue/io_timeout
35407c9093cSEric BiggersDate:		November 2018
35507c9093cSEric BiggersContact:	Weiping Zhang <zhangweiping@didiglobal.com>
35607c9093cSEric BiggersDescription:
357849ab826SEric Biggers		[RW] io_timeout is the request timeout in milliseconds. If a
358849ab826SEric Biggers		request does not complete in this time then the block driver
359849ab826SEric Biggers		timeout handler is invoked. That timeout handler can decide to
360849ab826SEric Biggers		retry the request, to fail it or to start a device recovery
361849ab826SEric Biggers		strategy.
362849ab826SEric Biggers
363849ab826SEric Biggers
364849ab826SEric BiggersWhat:		/sys/block/<disk>/queue/iostats
365849ab826SEric BiggersDate:		January 2009
366849ab826SEric BiggersContact:	linux-block@vger.kernel.org
367849ab826SEric BiggersDescription:
368849ab826SEric Biggers		[RW] This file is used to control (on/off) the iostats
369849ab826SEric Biggers		accounting of the disk.
37007c9093cSEric Biggers
37107c9093cSEric Biggers
37207c9093cSEric BiggersWhat:		/sys/block/<disk>/queue/logical_block_size
37307c9093cSEric BiggersDate:		May 2009
37407c9093cSEric BiggersContact:	Martin K. Petersen <martin.petersen@oracle.com>
37507c9093cSEric BiggersDescription:
376849ab826SEric Biggers		[RO] This is the smallest unit the storage device can address.
377849ab826SEric Biggers		It is typically 512 bytes.
37807c9093cSEric Biggers
37907c9093cSEric Biggers
38007c9093cSEric BiggersWhat:		/sys/block/<disk>/queue/max_active_zones
38107c9093cSEric BiggersDate:		July 2020
38207c9093cSEric BiggersContact:	Niklas Cassel <niklas.cassel@wdc.com>
38307c9093cSEric BiggersDescription:
384849ab826SEric Biggers		[RO] For zoned block devices (zoned attribute indicating
38507c9093cSEric Biggers		"host-managed" or "host-aware"), the sum of zones belonging to
38607c9093cSEric Biggers		any of the zone states: EXPLICIT OPEN, IMPLICIT OPEN or CLOSED,
38707c9093cSEric Biggers		is limited by this value. If this value is 0, there is no limit.
38807c9093cSEric Biggers
389849ab826SEric Biggers		If the host attempts to exceed this limit, the driver should
390849ab826SEric Biggers		report this error with BLK_STS_ZONE_ACTIVE_RESOURCE, which user
391849ab826SEric Biggers		space may see as the EOVERFLOW errno.
392849ab826SEric Biggers
393849ab826SEric Biggers
394849ab826SEric BiggersWhat:		/sys/block/<disk>/queue/max_discard_segments
395849ab826SEric BiggersDate:		February 2017
396849ab826SEric BiggersContact:	linux-block@vger.kernel.org
397849ab826SEric BiggersDescription:
398849ab826SEric Biggers		[RO] The maximum number of DMA scatter/gather entries in a
399849ab826SEric Biggers		discard request.
400849ab826SEric Biggers
401849ab826SEric Biggers
402849ab826SEric BiggersWhat:		/sys/block/<disk>/queue/max_hw_sectors_kb
403849ab826SEric BiggersDate:		September 2004
404849ab826SEric BiggersContact:	linux-block@vger.kernel.org
405849ab826SEric BiggersDescription:
406849ab826SEric Biggers		[RO] This is the maximum number of kilobytes supported in a
407849ab826SEric Biggers		single data transfer.
408849ab826SEric Biggers
409849ab826SEric Biggers
410849ab826SEric BiggersWhat:		/sys/block/<disk>/queue/max_integrity_segments
411849ab826SEric BiggersDate:		September 2010
412849ab826SEric BiggersContact:	linux-block@vger.kernel.org
413849ab826SEric BiggersDescription:
414849ab826SEric Biggers		[RO] Maximum number of elements in a DMA scatter/gather list
415849ab826SEric Biggers		with integrity data that will be submitted by the block layer
416849ab826SEric Biggers		core to the associated block driver.
417849ab826SEric Biggers
41807c9093cSEric Biggers
41907c9093cSEric BiggersWhat:		/sys/block/<disk>/queue/max_open_zones
42007c9093cSEric BiggersDate:		July 2020
42107c9093cSEric BiggersContact:	Niklas Cassel <niklas.cassel@wdc.com>
42207c9093cSEric BiggersDescription:
423849ab826SEric Biggers		[RO] For zoned block devices (zoned attribute indicating
42407c9093cSEric Biggers		"host-managed" or "host-aware"), the sum of zones belonging to
425849ab826SEric Biggers		any of the zone states: EXPLICIT OPEN or IMPLICIT OPEN, is
426849ab826SEric Biggers		limited by this value. If this value is 0, there is no limit.
427849ab826SEric Biggers
428849ab826SEric Biggers
429849ab826SEric BiggersWhat:		/sys/block/<disk>/queue/max_sectors_kb
430849ab826SEric BiggersDate:		September 2004
431849ab826SEric BiggersContact:	linux-block@vger.kernel.org
432849ab826SEric BiggersDescription:
433849ab826SEric Biggers		[RW] This is the maximum number of kilobytes that the block
434849ab826SEric Biggers		layer will allow for a filesystem request. Must be smaller than
435849ab826SEric Biggers		or equal to the maximum size allowed by the hardware.
436849ab826SEric Biggers
437849ab826SEric Biggers
438849ab826SEric BiggersWhat:		/sys/block/<disk>/queue/max_segment_size
439849ab826SEric BiggersDate:		March 2010
440849ab826SEric BiggersContact:	linux-block@vger.kernel.org
441849ab826SEric BiggersDescription:
442849ab826SEric Biggers		[RO] Maximum size in bytes of a single element in a DMA
443849ab826SEric Biggers		scatter/gather list.
444849ab826SEric Biggers
445849ab826SEric Biggers
446849ab826SEric BiggersWhat:		/sys/block/<disk>/queue/max_segments
447849ab826SEric BiggersDate:		March 2010
448849ab826SEric BiggersContact:	linux-block@vger.kernel.org
449849ab826SEric BiggersDescription:
450849ab826SEric Biggers		[RO] Maximum number of elements in a DMA scatter/gather list
451849ab826SEric Biggers		that is submitted to the associated block driver.
45207c9093cSEric Biggers
45307c9093cSEric Biggers
45407c9093cSEric BiggersWhat:		/sys/block/<disk>/queue/minimum_io_size
45507c9093cSEric BiggersDate:		April 2009
45607c9093cSEric BiggersContact:	Martin K. Petersen <martin.petersen@oracle.com>
45707c9093cSEric BiggersDescription:
458849ab826SEric Biggers		[RO] Storage devices may report a granularity or preferred
459849ab826SEric Biggers		minimum I/O size which is the smallest request the device can
460849ab826SEric Biggers		perform without incurring a performance penalty.  For disk
461849ab826SEric Biggers		drives this is often the physical block size.  For RAID arrays
462849ab826SEric Biggers		it is often the stripe chunk size.  A properly aligned multiple
463849ab826SEric Biggers		of minimum_io_size is the preferred request size for workloads
464849ab826SEric Biggers		where a high number of I/O operations is desired.
46507c9093cSEric Biggers
46607c9093cSEric Biggers
46707c9093cSEric BiggersWhat:		/sys/block/<disk>/queue/nomerges
46807c9093cSEric BiggersDate:		January 2010
4698b0551a7SEric BiggersContact:	linux-block@vger.kernel.org
47007c9093cSEric BiggersDescription:
471849ab826SEric Biggers		[RW] Standard I/O elevator operations include attempts to merge
472849ab826SEric Biggers		contiguous I/Os. For known random I/O loads these attempts will
473849ab826SEric Biggers		always fail and result in extra cycles being spent in the
474849ab826SEric Biggers		kernel. This allows one to turn off this behavior on one of two
475849ab826SEric Biggers		ways: When set to 1, complex merge checks are disabled, but the
476849ab826SEric Biggers		simple one-shot merges with the previous I/O request are
477849ab826SEric Biggers		enabled. When set to 2, all merge tries are disabled. The
478849ab826SEric Biggers		default value is 0 - which enables all types of merge tries.
479849ab826SEric Biggers
480849ab826SEric Biggers
481849ab826SEric BiggersWhat:		/sys/block/<disk>/queue/nr_requests
482849ab826SEric BiggersDate:		July 2003
483849ab826SEric BiggersContact:	linux-block@vger.kernel.org
484849ab826SEric BiggersDescription:
485849ab826SEric Biggers		[RW] This controls how many requests may be allocated in the
486849ab826SEric Biggers		block layer for read or write requests. Note that the total
487849ab826SEric Biggers		allocated number may be twice this amount, since it applies only
488849ab826SEric Biggers		to reads or writes (not the accumulated sum).
489849ab826SEric Biggers
490849ab826SEric Biggers		To avoid priority inversion through request starvation, a
491849ab826SEric Biggers		request queue maintains a separate request pool per each cgroup
492849ab826SEric Biggers		when CONFIG_BLK_CGROUP is enabled, and this parameter applies to
493849ab826SEric Biggers		each such per-block-cgroup request pool.  IOW, if there are N
494849ab826SEric Biggers		block cgroups, each request queue may have up to N request
495849ab826SEric Biggers		pools, each independently regulated by nr_requests.
49607c9093cSEric Biggers
49707c9093cSEric Biggers
49807c9093cSEric BiggersWhat:		/sys/block/<disk>/queue/nr_zones
49907c9093cSEric BiggersDate:		November 2018
50007c9093cSEric BiggersContact:	Damien Le Moal <damien.lemoal@wdc.com>
50107c9093cSEric BiggersDescription:
502849ab826SEric Biggers		[RO] nr_zones indicates the total number of zones of a zoned
503849ab826SEric Biggers		block device ("host-aware" or "host-managed" zone model). For
504849ab826SEric Biggers		regular block devices, the value is always 0.
50507c9093cSEric Biggers
50607c9093cSEric Biggers
50707c9093cSEric BiggersWhat:		/sys/block/<disk>/queue/optimal_io_size
50807c9093cSEric BiggersDate:		April 2009
50907c9093cSEric BiggersContact:	Martin K. Petersen <martin.petersen@oracle.com>
51007c9093cSEric BiggersDescription:
511849ab826SEric Biggers		[RO] Storage devices may report an optimal I/O size, which is
512849ab826SEric Biggers		the device's preferred unit for sustained I/O.  This is rarely
513849ab826SEric Biggers		reported for disk drives.  For RAID arrays it is usually the
514849ab826SEric Biggers		stripe width or the internal track size.  A properly aligned
515849ab826SEric Biggers		multiple of optimal_io_size is the preferred request size for
516849ab826SEric Biggers		workloads where sustained throughput is desired.  If no optimal
517849ab826SEric Biggers		I/O size is reported this file contains 0.
51807c9093cSEric Biggers
51907c9093cSEric Biggers
52007c9093cSEric BiggersWhat:		/sys/block/<disk>/queue/physical_block_size
52107c9093cSEric BiggersDate:		May 2009
52207c9093cSEric BiggersContact:	Martin K. Petersen <martin.petersen@oracle.com>
52307c9093cSEric BiggersDescription:
524849ab826SEric Biggers		[RO] This is the smallest unit a physical storage device can
525849ab826SEric Biggers		write atomically.  It is usually the same as the logical block
526849ab826SEric Biggers		size but may be bigger.  One example is SATA drives with 4KB
527849ab826SEric Biggers		sectors that expose a 512-byte logical block size to the
528849ab826SEric Biggers		operating system.  For stacked block devices the
529849ab826SEric Biggers		physical_block_size variable contains the maximum
530849ab826SEric Biggers		physical_block_size of the component devices.
531849ab826SEric Biggers
532849ab826SEric Biggers
533849ab826SEric BiggersWhat:		/sys/block/<disk>/queue/read_ahead_kb
534849ab826SEric BiggersDate:		May 2004
535849ab826SEric BiggersContact:	linux-block@vger.kernel.org
536849ab826SEric BiggersDescription:
537849ab826SEric Biggers		[RW] Maximum number of kilobytes to read-ahead for filesystems
538849ab826SEric Biggers		on this block device.
539849ab826SEric Biggers
540849ab826SEric Biggers
541849ab826SEric BiggersWhat:		/sys/block/<disk>/queue/rotational
542849ab826SEric BiggersDate:		January 2009
543849ab826SEric BiggersContact:	linux-block@vger.kernel.org
544849ab826SEric BiggersDescription:
545849ab826SEric Biggers		[RW] This file is used to stat if the device is of rotational
546849ab826SEric Biggers		type or non-rotational type.
547849ab826SEric Biggers
548849ab826SEric Biggers
549849ab826SEric BiggersWhat:		/sys/block/<disk>/queue/rq_affinity
550849ab826SEric BiggersDate:		September 2008
551849ab826SEric BiggersContact:	linux-block@vger.kernel.org
552849ab826SEric BiggersDescription:
553849ab826SEric Biggers		[RW] If this option is '1', the block layer will migrate request
554849ab826SEric Biggers		completions to the cpu "group" that originally submitted the
555849ab826SEric Biggers		request. For some workloads this provides a significant
556849ab826SEric Biggers		reduction in CPU cycles due to caching effects.
557849ab826SEric Biggers
558849ab826SEric Biggers		For storage configurations that need to maximize distribution of
559849ab826SEric Biggers		completion processing setting this option to '2' forces the
560849ab826SEric Biggers		completion to run on the requesting cpu (bypassing the "group"
561849ab826SEric Biggers		aggregation logic).
562849ab826SEric Biggers
563849ab826SEric Biggers
564849ab826SEric BiggersWhat:		/sys/block/<disk>/queue/scheduler
565849ab826SEric BiggersDate:		October 2004
566849ab826SEric BiggersContact:	linux-block@vger.kernel.org
567849ab826SEric BiggersDescription:
568849ab826SEric Biggers		[RW] When read, this file will display the current and available
569849ab826SEric Biggers		IO schedulers for this block device. The currently active IO
570849ab826SEric Biggers		scheduler will be enclosed in [] brackets. Writing an IO
571849ab826SEric Biggers		scheduler name to this file will switch control of this block
572849ab826SEric Biggers		device to that new IO scheduler. Note that writing an IO
573849ab826SEric Biggers		scheduler name to this file will attempt to load that IO
574849ab826SEric Biggers		scheduler module, if it isn't already present in the system.
575849ab826SEric Biggers
576849ab826SEric Biggers
57711630104SEric BiggersWhat:		/sys/block/<disk>/queue/stable_writes
57811630104SEric BiggersDate:		September 2020
57911630104SEric BiggersContact:	linux-block@vger.kernel.org
58011630104SEric BiggersDescription:
58111630104SEric Biggers		[RW] This file will contain '1' if memory must not be modified
58211630104SEric Biggers		while it is being used in a write request to this device.  When
58311630104SEric Biggers		this is the case and the kernel is performing writeback of a
58411630104SEric Biggers		page, the kernel will wait for writeback to complete before
58511630104SEric Biggers		allowing the page to be modified again, rather than allowing
58611630104SEric Biggers		immediate modification as is normally the case.  This
58711630104SEric Biggers		restriction arises when the device accesses the memory multiple
58811630104SEric Biggers		times where the same data must be seen every time -- for
58911630104SEric Biggers		example, once to calculate a checksum and once to actually write
59011630104SEric Biggers		the data.  If no such restriction exists, this file will contain
59111630104SEric Biggers		'0'.  This file is writable for testing purposes.
59211630104SEric Biggers
59311630104SEric Biggers
594849ab826SEric BiggersWhat:		/sys/block/<disk>/queue/throttle_sample_time
595849ab826SEric BiggersDate:		March 2017
596849ab826SEric BiggersContact:	linux-block@vger.kernel.org
597849ab826SEric BiggersDescription:
598849ab826SEric Biggers		[RW] This is the time window that blk-throttle samples data, in
599849ab826SEric Biggers		millisecond.  blk-throttle makes decision based on the
600849ab826SEric Biggers		samplings. Lower time means cgroups have more smooth throughput,
601849ab826SEric Biggers		but higher CPU overhead. This exists only when
602849ab826SEric Biggers		CONFIG_BLK_DEV_THROTTLING_LOW is enabled.
603849ab826SEric Biggers
604849ab826SEric Biggers
6058bc2f7c6SEric BiggersWhat:		/sys/block/<disk>/queue/virt_boundary_mask
6068bc2f7c6SEric BiggersDate:		April 2021
6078bc2f7c6SEric BiggersContact:	linux-block@vger.kernel.org
6088bc2f7c6SEric BiggersDescription:
6098bc2f7c6SEric Biggers		[RO] This file shows the I/O segment memory alignment mask for
6108bc2f7c6SEric Biggers		the block device.  I/O requests to this device will be split
6118bc2f7c6SEric Biggers		between segments wherever either the memory address of the end
6128bc2f7c6SEric Biggers		of the previous segment or the memory address of the beginning
6138bc2f7c6SEric Biggers		of the current segment is not aligned to virt_boundary_mask + 1
6148bc2f7c6SEric Biggers		bytes.
6158bc2f7c6SEric Biggers
6168bc2f7c6SEric Biggers
617849ab826SEric BiggersWhat:		/sys/block/<disk>/queue/wbt_lat_usec
618849ab826SEric BiggersDate:		November 2016
619849ab826SEric BiggersContact:	linux-block@vger.kernel.org
620849ab826SEric BiggersDescription:
621849ab826SEric Biggers		[RW] If the device is registered for writeback throttling, then
622849ab826SEric Biggers		this file shows the target minimum read latency. If this latency
623849ab826SEric Biggers		is exceeded in a given window of time (see wb_window_usec), then
624849ab826SEric Biggers		the writeback throttling will start scaling back writes. Writing
625849ab826SEric Biggers		a value of '0' to this file disables the feature. Writing a
626849ab826SEric Biggers		value of '-1' to this file resets the value to the default
627849ab826SEric Biggers		setting.
628849ab826SEric Biggers
629849ab826SEric Biggers
630849ab826SEric BiggersWhat:		/sys/block/<disk>/queue/write_cache
631849ab826SEric BiggersDate:		April 2016
632849ab826SEric BiggersContact:	linux-block@vger.kernel.org
633849ab826SEric BiggersDescription:
634849ab826SEric Biggers		[RW] When read, this file will display whether the device has
635849ab826SEric Biggers		write back caching enabled or not. It will return "write back"
636849ab826SEric Biggers		for the former case, and "write through" for the latter. Writing
637849ab826SEric Biggers		to this file can change the kernels view of the device, but it
638849ab826SEric Biggers		doesn't alter the device state. This means that it might not be
639849ab826SEric Biggers		safe to toggle the setting from "write back" to "write through",
640849ab826SEric Biggers		since that will also eliminate cache flushes issued by the
641849ab826SEric Biggers		kernel.
64207c9093cSEric Biggers
64307c9093cSEric Biggers
64407c9093cSEric BiggersWhat:		/sys/block/<disk>/queue/write_same_max_bytes
64507c9093cSEric BiggersDate:		January 2012
64607c9093cSEric BiggersContact:	Martin K. Petersen <martin.petersen@oracle.com>
64707c9093cSEric BiggersDescription:
648849ab826SEric Biggers		[RO] Some devices support a write same operation in which a
64907c9093cSEric Biggers		single data block can be written to a range of several
650849ab826SEric Biggers		contiguous blocks on storage. This can be used to wipe areas on
651849ab826SEric Biggers		disk or to initialize drives in a RAID configuration.
652849ab826SEric Biggers		write_same_max_bytes indicates how many bytes can be written in
653849ab826SEric Biggers		a single write same command. If write_same_max_bytes is 0, write
654849ab826SEric Biggers		same is not supported by the device.
65507c9093cSEric Biggers
65607c9093cSEric Biggers
65707c9093cSEric BiggersWhat:		/sys/block/<disk>/queue/write_zeroes_max_bytes
65807c9093cSEric BiggersDate:		November 2016
65907c9093cSEric BiggersContact:	Chaitanya Kulkarni <chaitanya.kulkarni@wdc.com>
66007c9093cSEric BiggersDescription:
661849ab826SEric Biggers		[RO] Devices that support write zeroes operation in which a
662849ab826SEric Biggers		single request can be issued to zero out the range of contiguous
663849ab826SEric Biggers		blocks on storage without having any payload in the request.
664849ab826SEric Biggers		This can be used to optimize writing zeroes to the devices.
665849ab826SEric Biggers		write_zeroes_max_bytes indicates how many bytes can be written
666849ab826SEric Biggers		in a single write zeroes command. If write_zeroes_max_bytes is
667849ab826SEric Biggers		0, write zeroes is not supported by the device.
668849ab826SEric Biggers
669849ab826SEric Biggers
670849ab826SEric BiggersWhat:		/sys/block/<disk>/queue/zone_append_max_bytes
671849ab826SEric BiggersDate:		May 2020
672849ab826SEric BiggersContact:	linux-block@vger.kernel.org
673849ab826SEric BiggersDescription:
674849ab826SEric Biggers		[RO] This is the maximum number of bytes that can be written to
675849ab826SEric Biggers		a sequential zone of a zoned block device using a zone append
676849ab826SEric Biggers		write operation (REQ_OP_ZONE_APPEND). This value is always 0 for
677849ab826SEric Biggers		regular block devices.
678849ab826SEric Biggers
679849ab826SEric Biggers
680849ab826SEric BiggersWhat:		/sys/block/<disk>/queue/zone_write_granularity
681849ab826SEric BiggersDate:		January 2021
682849ab826SEric BiggersContact:	linux-block@vger.kernel.org
683849ab826SEric BiggersDescription:
684849ab826SEric Biggers		[RO] This indicates the alignment constraint, in bytes, for
685849ab826SEric Biggers		write operations in sequential zones of zoned block devices
686849ab826SEric Biggers		(devices with a zoned attributed that reports "host-managed" or
687849ab826SEric Biggers		"host-aware"). This value is always 0 for regular block devices.
68807c9093cSEric Biggers
68907c9093cSEric Biggers
69007c9093cSEric BiggersWhat:		/sys/block/<disk>/queue/zoned
69107c9093cSEric BiggersDate:		September 2016
69207c9093cSEric BiggersContact:	Damien Le Moal <damien.lemoal@wdc.com>
69307c9093cSEric BiggersDescription:
694849ab826SEric Biggers		[RO] zoned indicates if the device is a zoned block device and
695849ab826SEric Biggers		the zone model of the device if it is indeed zoned.  The
696849ab826SEric Biggers		possible values indicated by zoned are "none" for regular block
697849ab826SEric Biggers		devices and "host-aware" or "host-managed" for zoned block
698849ab826SEric Biggers		devices. The characteristics of host-aware and host-managed
699849ab826SEric Biggers		zoned block devices are described in the ZBC (Zoned Block
700849ab826SEric Biggers		Commands) and ZAC (Zoned Device ATA Command Set) standards.
701849ab826SEric Biggers		These standards also define the "drive-managed" zone model.
702849ab826SEric Biggers		However, since drive-managed zoned block devices do not support
703849ab826SEric Biggers		zone commands, they will be treated as regular block devices and
704849ab826SEric Biggers		zoned will report "none".
70507c9093cSEric Biggers
70607c9093cSEric Biggers
707ae7a7a53SEric BiggersWhat:		/sys/block/<disk>/stat
708ae7a7a53SEric BiggersDate:		February 2008
709ae7a7a53SEric BiggersContact:	Jerome Marchand <jmarchan@redhat.com>
710ae7a7a53SEric BiggersDescription:
711ae7a7a53SEric Biggers		The /sys/block/<disk>/stat files displays the I/O
712ae7a7a53SEric Biggers		statistics of disk <disk>. They contain 11 fields:
713ae7a7a53SEric Biggers
714ae7a7a53SEric Biggers		==  ==============================================
715ae7a7a53SEric Biggers		 1  reads completed successfully
716ae7a7a53SEric Biggers		 2  reads merged
717ae7a7a53SEric Biggers		 3  sectors read
718ae7a7a53SEric Biggers		 4  time spent reading (ms)
719ae7a7a53SEric Biggers		 5  writes completed
720ae7a7a53SEric Biggers		 6  writes merged
721ae7a7a53SEric Biggers		 7  sectors written
722ae7a7a53SEric Biggers		 8  time spent writing (ms)
723ae7a7a53SEric Biggers		 9  I/Os currently in progress
724ae7a7a53SEric Biggers		10  time spent doing I/Os (ms)
725ae7a7a53SEric Biggers		11  weighted time spent doing I/Os (ms)
726ae7a7a53SEric Biggers		12  discards completed
727ae7a7a53SEric Biggers		13  discards merged
728ae7a7a53SEric Biggers		14  sectors discarded
729ae7a7a53SEric Biggers		15  time spent discarding (ms)
730ae7a7a53SEric Biggers		16  flush requests completed
731ae7a7a53SEric Biggers		17  time spent flushing (ms)
732ae7a7a53SEric Biggers		==  ==============================================
733ae7a7a53SEric Biggers
734ae7a7a53SEric Biggers		For more details refer Documentation/admin-guide/iostats.rst
735