From patchwork Wed Dec 8 00:56:33 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eric Biggers X-Patchwork-Id: 12663107 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 4CE10C433FE for ; Wed, 8 Dec 2021 00:57:46 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S239031AbhLHBBE (ORCPT ); Tue, 7 Dec 2021 20:01:04 -0500 Received: from sin.source.kernel.org ([145.40.73.55]:38684 "EHLO sin.source.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S238916AbhLHBBC (ORCPT ); Tue, 7 Dec 2021 20:01:02 -0500 Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by sin.source.kernel.org (Postfix) with ESMTPS id 63158CE1F58; Wed, 8 Dec 2021 00:57:29 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 5E2B4C341C5; Wed, 8 Dec 2021 00:57:27 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1638925047; bh=eyFDhLZXXF0TjsoOyaqwW+4RWrrRXJe67NtK8tlN9nU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=DVjbNvLQuFmbAP9T/11p/89kLj7Oi0EXGjmXyQXHEr3brp8pnfWh0bAaV13fzpr7O VyworE4Dy6N7sXvrhdMO+sAlWeMlLI0Ky/0m1mRd5vC2KvjaKGdHkuy4bovpeloEi8 oxGro/wbwN/+O+6hLr/C6OOT3EUoxHZGV6RxSfLYCdpSsuAXXJRo4oYSlb5gfrDqpK T0xtb/FTw3+psumUKUzYEXC9yUoRDcsPvWQgufFSY9eF5X4O8i5krVoR57i8FcJCdx 0w6CwDjTZfqpxmcKkQEFaHwrPyzR1AJjYs97VdrpCF04Z6h9uieizfVR2d3j+lvIu4 1Jkn9NvtZG9Hw== From: Eric Biggers To: linux-block@vger.kernel.org, Jens Axboe Cc: linux-doc@vger.kernel.org, Greg Kroah-Hartman , linux-kernel@vger.kernel.org Subject: [PATCH v2 1/8] docs: sysfs-block: move to stable directory Date: Tue, 7 Dec 2021 16:56:33 -0800 Message-Id: <20211208005640.102814-2-ebiggers@kernel.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20211208005640.102814-1-ebiggers@kernel.org> References: <20211208005640.102814-1-ebiggers@kernel.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-block@vger.kernel.org From: Eric Biggers The block layer sysfs ABI is widely used by userspace software and is considered stable. Signed-off-by: Eric Biggers --- Documentation/ABI/{testing => stable}/sysfs-block | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename Documentation/ABI/{testing => stable}/sysfs-block (100%) diff --git a/Documentation/ABI/testing/sysfs-block b/Documentation/ABI/stable/sysfs-block similarity index 100% rename from Documentation/ABI/testing/sysfs-block rename to Documentation/ABI/stable/sysfs-block From patchwork Wed Dec 8 00:56:34 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eric Biggers X-Patchwork-Id: 12663097 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 7AE1BC433EF for ; Wed, 8 Dec 2021 00:57:33 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S238969AbhLHBBD (ORCPT ); Tue, 7 Dec 2021 20:01:03 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:53514 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234815AbhLHBBC (ORCPT ); Tue, 7 Dec 2021 20:01:02 -0500 Received: from ams.source.kernel.org (ams.source.kernel.org [IPv6:2604:1380:4601:e00::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id E8B2FC061574; Tue, 7 Dec 2021 16:57:30 -0800 (PST) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ams.source.kernel.org (Postfix) with ESMTPS id 3665DB81EBA; Wed, 8 Dec 2021 00:57:29 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id B71C4C341C8; Wed, 8 Dec 2021 00:57:27 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1638925048; bh=bsUF8sNld1djpkWYx32MoAbOgl0M22v5vjggw0Jh348=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=nkOeQBKYaQ9hGjlirdgBQMX10TGDruNl4+V+yKoYBiHqzUkJAtk00fyYZNccwFUJO PchsoPI9rZ2aHS9Uny05SwWyc+ZBaWpn9iS7QRxA45dpwzlG3lmBFfqSO5XggKeNt0 rhBOdxzz72PVLw9rOPMgOLLfVDqcnv5lhd7ju0M+i+0j94QJN8ta5MrncJ/rkRq8rG NdUhlFUXKLa8g2vt3ELuVXulI+tR/+cJ+hAkL0nQm0WQr+XwrADq+usk7tmMDrFTBq 6sAoQ9lk3FQxyYVZpnPMPh7Vm1sysBWjaYH2W7eWFrKOw4vHuIQrugjHmxCyNaznwB aGWqP1f9hdwSw== From: Eric Biggers To: linux-block@vger.kernel.org, Jens Axboe Cc: linux-doc@vger.kernel.org, Greg Kroah-Hartman , linux-kernel@vger.kernel.org, Hannes Reinecke Subject: [PATCH v2 2/8] docs: sysfs-block: sort alphabetically Date: Tue, 7 Dec 2021 16:56:34 -0800 Message-Id: <20211208005640.102814-3-ebiggers@kernel.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20211208005640.102814-1-ebiggers@kernel.org> References: <20211208005640.102814-1-ebiggers@kernel.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-block@vger.kernel.org From: Eric Biggers Sort the documentation for the files alphabetically by file path so that there is a logical order and it's clear where to add new files. With two small exceptions, this patch doesn't change the documentation itself and just reorders it: - In /sys/block///stat, I replaced with to be consistent with the other files. - The description for /sys/block///stat referred to another file "above", which I reworded. Reviewed-by: Greg Kroah-Hartman Reviewed-by: Hannes Reinecke Signed-off-by: Eric Biggers --- Documentation/ABI/stable/sysfs-block | 385 ++++++++++++++------------- 1 file changed, 203 insertions(+), 182 deletions(-) diff --git a/Documentation/ABI/stable/sysfs-block b/Documentation/ABI/stable/sysfs-block index b16b0c45a272e..9febd53a5ebe8 100644 --- a/Documentation/ABI/stable/sysfs-block +++ b/Documentation/ABI/stable/sysfs-block @@ -1,31 +1,37 @@ -What: /sys/block//stat -Date: February 2008 -Contact: Jerome Marchand +What: /sys/block//alignment_offset +Date: April 2009 +Contact: Martin K. Petersen Description: - The /sys/block//stat files displays the I/O - statistics of disk . They contain 11 fields: + Storage devices may report a physical block size that is + bigger than the logical block size (for instance a drive + with 4KB physical sectors exposing 512-byte logical + blocks to the operating system). This parameter + indicates how many bytes the beginning of the device is + offset from the disk's natural alignment. - == ============================================== - 1 reads completed successfully - 2 reads merged - 3 sectors read - 4 time spent reading (ms) - 5 writes completed - 6 writes merged - 7 sectors written - 8 time spent writing (ms) - 9 I/Os currently in progress - 10 time spent doing I/Os (ms) - 11 weighted time spent doing I/Os (ms) - 12 discards completed - 13 discards merged - 14 sectors discarded - 15 time spent discarding (ms) - 16 flush requests completed - 17 time spent flushing (ms) - == ============================================== - For more details refer Documentation/admin-guide/iostats.rst +What: /sys/block//discard_alignment +Date: May 2011 +Contact: Martin K. Petersen +Description: + Devices that support discard functionality may + internally allocate space in units that are bigger than + the exported logical block size. The discard_alignment + parameter indicates how many bytes the beginning of the + device is offset from the internal allocation unit's + natural alignment. + + +What: /sys/block//diskseq +Date: February 2021 +Contact: Matteo Croce +Description: + The /sys/block//diskseq files reports the disk + sequence number, which is a monotonically increasing + number assigned to every drive. + Some devices, like the loop device, refresh such number + every time the backing file is changed. + The value type is 64 bit unsigned. What: /sys/block//inflight @@ -44,26 +50,12 @@ Description: and for SCSI device also its queue_depth. -What: /sys/block//diskseq -Date: February 2021 -Contact: Matteo Croce -Description: - The /sys/block//diskseq files reports the disk - sequence number, which is a monotonically increasing - number assigned to every drive. - Some devices, like the loop device, refresh such number - every time the backing file is changed. - The value type is 64 bit unsigned. - - -What: /sys/block///stat -Date: February 2008 -Contact: Jerome Marchand +What: /sys/block//integrity/device_is_integrity_capable +Date: July 2014 +Contact: Martin K. Petersen Description: - The /sys/block///stat files display the - I/O statistics of partition . The format is the - same as the above-written /sys/block//stat - format. + Indicates whether a storage device is capable of storing + integrity metadata. Set if the device is T10 PI-capable. What: /sys/block//integrity/format @@ -74,6 +66,15 @@ Description: E.g. T10-DIF-TYPE1-CRC. +What: /sys/block//integrity/protection_interval_bytes +Date: July 2015 +Contact: Martin K. Petersen +Description: + Describes the number of data bytes which are protected + by one integrity tuple. Typically the device's logical + block size. + + What: /sys/block//integrity/read_verify Date: June 2008 Contact: Martin K. Petersen @@ -91,21 +92,6 @@ Description: 512 bytes of data. -What: /sys/block//integrity/device_is_integrity_capable -Date: July 2014 -Contact: Martin K. Petersen -Description: - Indicates whether a storage device is capable of storing - integrity metadata. Set if the device is T10 PI-capable. - -What: /sys/block//integrity/protection_interval_bytes -Date: July 2015 -Contact: Martin K. Petersen -Description: - Describes the number of data bytes which are protected - by one integrity tuple. Typically the device's logical - block size. - What: /sys/block//integrity/write_generate Date: June 2008 Contact: Martin K. Petersen @@ -114,16 +100,6 @@ Description: generate checksums for write requests bound for devices that support receiving integrity metadata. -What: /sys/block//alignment_offset -Date: April 2009 -Contact: Martin K. Petersen -Description: - Storage devices may report a physical block size that is - bigger than the logical block size (for instance a drive - with 4KB physical sectors exposing 512-byte logical - blocks to the operating system). This parameter - indicates how many bytes the beginning of the device is - offset from the disk's natural alignment. What: /sys/block///alignment_offset Date: April 2009 @@ -136,76 +112,6 @@ Description: indicates how many bytes the beginning of the partition is offset from the disk's natural alignment. -What: /sys/block//queue/logical_block_size -Date: May 2009 -Contact: Martin K. Petersen -Description: - This is the smallest unit the storage device can - address. It is typically 512 bytes. - -What: /sys/block//queue/physical_block_size -Date: May 2009 -Contact: Martin K. Petersen -Description: - This is the smallest unit a physical storage device can - write atomically. It is usually the same as the logical - block size but may be bigger. One example is SATA - drives with 4KB sectors that expose a 512-byte logical - block size to the operating system. For stacked block - devices the physical_block_size variable contains the - maximum physical_block_size of the component devices. - -What: /sys/block//queue/minimum_io_size -Date: April 2009 -Contact: Martin K. Petersen -Description: - Storage devices may report a granularity or preferred - minimum I/O size which is the smallest request the - device can perform without incurring a performance - penalty. For disk drives this is often the physical - block size. For RAID arrays it is often the stripe - chunk size. A properly aligned multiple of - minimum_io_size is the preferred request size for - workloads where a high number of I/O operations is - desired. - -What: /sys/block//queue/optimal_io_size -Date: April 2009 -Contact: Martin K. Petersen -Description: - Storage devices may report an optimal I/O size, which is - the device's preferred unit for sustained I/O. This is - rarely reported for disk drives. For RAID arrays it is - usually the stripe width or the internal track size. A - properly aligned multiple of optimal_io_size is the - preferred request size for workloads where sustained - throughput is desired. If no optimal I/O size is - reported this file contains 0. - -What: /sys/block//queue/nomerges -Date: January 2010 -Contact: -Description: - Standard I/O elevator operations include attempts to - merge contiguous I/Os. For known random I/O loads these - attempts will always fail and result in extra cycles - being spent in the kernel. This allows one to turn off - this behavior on one of two ways: When set to 1, complex - merge checks are disabled, but the simple one-shot merges - with the previous I/O request are enabled. When set to 2, - all merge tries are disabled. The default value is 0 - - which enables all types of merge tries. - -What: /sys/block//discard_alignment -Date: May 2011 -Contact: Martin K. Petersen -Description: - Devices that support discard functionality may - internally allocate space in units that are bigger than - the exported logical block size. The discard_alignment - parameter indicates how many bytes the beginning of the - device is offset from the internal allocation unit's - natural alignment. What: /sys/block///discard_alignment Date: May 2011 @@ -218,6 +124,30 @@ Description: partition is offset from the internal allocation unit's natural alignment. + +What: /sys/block///stat +Date: February 2008 +Contact: Jerome Marchand +Description: + The /sys/block///stat files display the + I/O statistics of partition . The format is the + same as the format of /sys/block//stat. + + +What: /sys/block//queue/chunk_sectors +Date: September 2016 +Contact: Hannes Reinecke +Description: + chunk_sectors has different meaning depending on the type + of the disk. For a RAID device (dm-raid), chunk_sectors + indicates the size in 512B sectors of the RAID volume + stripe segment. For a zoned block device, either + host-aware or host-managed, chunk_sectors indicates the + size in 512B sectors of the zones of the device, with + the eventual exception of the last zone of the device + which may be smaller. + + What: /sys/block//queue/discard_granularity Date: May 2011 Contact: Martin K. Petersen @@ -231,6 +161,7 @@ Description: physical block size. A discard_granularity of 0 means that the device does not support discard functionality. + What: /sys/block//queue/discard_max_bytes Date: May 2011 Contact: Martin K. Petersen @@ -247,6 +178,7 @@ Description: value of 0 means that the device does not support discard functionality. + What: /sys/block//queue/discard_zeroes_data Date: May 2011 Contact: Martin K. Petersen @@ -254,6 +186,111 @@ Description: Will always return 0. Don't rely on any specific behavior for discards, and don't read this file. + +What: /sys/block//queue/io_timeout +Date: November 2018 +Contact: Weiping Zhang +Description: + io_timeout is the request timeout in milliseconds. If a request + does not complete in this time then the block driver timeout + handler is invoked. That timeout handler can decide to retry + the request, to fail it or to start a device recovery strategy. + + +What: /sys/block//queue/logical_block_size +Date: May 2009 +Contact: Martin K. Petersen +Description: + This is the smallest unit the storage device can + address. It is typically 512 bytes. + + +What: /sys/block//queue/max_active_zones +Date: July 2020 +Contact: Niklas Cassel +Description: + For zoned block devices (zoned attribute indicating + "host-managed" or "host-aware"), the sum of zones belonging to + any of the zone states: EXPLICIT OPEN, IMPLICIT OPEN or CLOSED, + is limited by this value. If this value is 0, there is no limit. + + +What: /sys/block//queue/max_open_zones +Date: July 2020 +Contact: Niklas Cassel +Description: + For zoned block devices (zoned attribute indicating + "host-managed" or "host-aware"), the sum of zones belonging to + any of the zone states: EXPLICIT OPEN or IMPLICIT OPEN, + is limited by this value. If this value is 0, there is no limit. + + +What: /sys/block//queue/minimum_io_size +Date: April 2009 +Contact: Martin K. Petersen +Description: + Storage devices may report a granularity or preferred + minimum I/O size which is the smallest request the + device can perform without incurring a performance + penalty. For disk drives this is often the physical + block size. For RAID arrays it is often the stripe + chunk size. A properly aligned multiple of + minimum_io_size is the preferred request size for + workloads where a high number of I/O operations is + desired. + + +What: /sys/block//queue/nomerges +Date: January 2010 +Contact: +Description: + Standard I/O elevator operations include attempts to + merge contiguous I/Os. For known random I/O loads these + attempts will always fail and result in extra cycles + being spent in the kernel. This allows one to turn off + this behavior on one of two ways: When set to 1, complex + merge checks are disabled, but the simple one-shot merges + with the previous I/O request are enabled. When set to 2, + all merge tries are disabled. The default value is 0 - + which enables all types of merge tries. + + +What: /sys/block//queue/nr_zones +Date: November 2018 +Contact: Damien Le Moal +Description: + nr_zones indicates the total number of zones of a zoned block + device ("host-aware" or "host-managed" zone model). For regular + block devices, the value is always 0. + + +What: /sys/block//queue/optimal_io_size +Date: April 2009 +Contact: Martin K. Petersen +Description: + Storage devices may report an optimal I/O size, which is + the device's preferred unit for sustained I/O. This is + rarely reported for disk drives. For RAID arrays it is + usually the stripe width or the internal track size. A + properly aligned multiple of optimal_io_size is the + preferred request size for workloads where sustained + throughput is desired. If no optimal I/O size is + reported this file contains 0. + + +What: /sys/block//queue/physical_block_size +Date: May 2009 +Contact: Martin K. Petersen +Description: + This is the smallest unit a physical storage device can + write atomically. It is usually the same as the logical + block size but may be bigger. One example is SATA + drives with 4KB sectors that expose a 512-byte logical + block size to the operating system. For stacked block + devices the physical_block_size variable contains the + maximum physical_block_size of the component devices. + + What: /sys/block//queue/write_same_max_bytes Date: January 2012 Contact: Martin K. Petersen @@ -267,6 +304,7 @@ Description: write_same_max_bytes is 0, write same is not supported by the device. + What: /sys/block//queue/write_zeroes_max_bytes Date: November 2016 Contact: Chaitanya Kulkarni @@ -280,6 +318,7 @@ Description: write_zeroes_max_bytes is 0, write zeroes is not supported by the device. + What: /sys/block//queue/zoned Date: September 2016 Contact: Damien Le Moal @@ -297,50 +336,32 @@ Description: zone commands, they will be treated as regular block devices and zoned will report "none". -What: /sys/block//queue/nr_zones -Date: November 2018 -Contact: Damien Le Moal -Description: - nr_zones indicates the total number of zones of a zoned block - device ("host-aware" or "host-managed" zone model). For regular - block devices, the value is always 0. -What: /sys/block//queue/max_active_zones -Date: July 2020 -Contact: Niklas Cassel -Description: - For zoned block devices (zoned attribute indicating - "host-managed" or "host-aware"), the sum of zones belonging to - any of the zone states: EXPLICIT OPEN, IMPLICIT OPEN or CLOSED, - is limited by this value. If this value is 0, there is no limit. - -What: /sys/block//queue/max_open_zones -Date: July 2020 -Contact: Niklas Cassel +What: /sys/block//stat +Date: February 2008 +Contact: Jerome Marchand Description: - For zoned block devices (zoned attribute indicating - "host-managed" or "host-aware"), the sum of zones belonging to - any of the zone states: EXPLICIT OPEN or IMPLICIT OPEN, - is limited by this value. If this value is 0, there is no limit. + The /sys/block//stat files displays the I/O + statistics of disk . They contain 11 fields: -What: /sys/block//queue/chunk_sectors -Date: September 2016 -Contact: Hannes Reinecke -Description: - chunk_sectors has different meaning depending on the type - of the disk. For a RAID device (dm-raid), chunk_sectors - indicates the size in 512B sectors of the RAID volume - stripe segment. For a zoned block device, either - host-aware or host-managed, chunk_sectors indicates the - size in 512B sectors of the zones of the device, with - the eventual exception of the last zone of the device - which may be smaller. + == ============================================== + 1 reads completed successfully + 2 reads merged + 3 sectors read + 4 time spent reading (ms) + 5 writes completed + 6 writes merged + 7 sectors written + 8 time spent writing (ms) + 9 I/Os currently in progress + 10 time spent doing I/Os (ms) + 11 weighted time spent doing I/Os (ms) + 12 discards completed + 13 discards merged + 14 sectors discarded + 15 time spent discarding (ms) + 16 flush requests completed + 17 time spent flushing (ms) + == ============================================== -What: /sys/block//queue/io_timeout -Date: November 2018 -Contact: Weiping Zhang -Description: - io_timeout is the request timeout in milliseconds. If a request - does not complete in this time then the block driver timeout - handler is invoked. That timeout handler can decide to retry - the request, to fail it or to start a device recovery strategy. + For more details refer Documentation/admin-guide/iostats.rst From patchwork Wed Dec 8 00:56:35 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eric Biggers X-Patchwork-Id: 12663103 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 7B327C433F5 for ; Wed, 8 Dec 2021 00:57:39 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S239072AbhLHBBF (ORCPT ); Tue, 7 Dec 2021 20:01:05 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:53520 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S238972AbhLHBBD (ORCPT ); Tue, 7 Dec 2021 20:01:03 -0500 Received: from sin.source.kernel.org (sin.source.kernel.org [IPv6:2604:1380:40e1:4800::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id F0076C061574; Tue, 7 Dec 2021 16:57:31 -0800 (PST) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by sin.source.kernel.org (Postfix) with ESMTPS id 2BA3CCE1F59; Wed, 8 Dec 2021 00:57:30 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 2869DC341CB; Wed, 8 Dec 2021 00:57:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1638925048; bh=GFrSBsqaPnbevknnfrehYOVxZM1KY9cMbSCnL8jEkEI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=JGznqfYoZbVvxb189PSrecMxHHbNSxPojUOWsRGvDsdShQ+PxTplxa5XLGPqy3a/q JapPa2LeuGgNVVPIUVmdHTZmr1M6C9EvKFVYRloKaxqGEoQcvlwhs+6UkT5fJakgiw bvxAchZZt8gCpQAoIZPgQJuc9cJNZ15S+YUOwyFRtnjLTSoapue+G/N6PmEUPBNFyw TgYwG6BmUdMbSLkp+u3vTIL9UEf4CEzvEmODxsjaMfcS1RR3QKDcoKW6oQkm7udnW4 PKoSXw2Vlso5mKknViwpyiPBb35L142jkc/3ah1uCY4oRvyir/RIVidKCMF/c3JvDS 1QtjBjQcZm/0Q== From: Eric Biggers To: linux-block@vger.kernel.org, Jens Axboe Cc: linux-doc@vger.kernel.org, Greg Kroah-Hartman , linux-kernel@vger.kernel.org, Hannes Reinecke Subject: [PATCH v2 3/8] docs: sysfs-block: add contact for nomerges Date: Tue, 7 Dec 2021 16:56:35 -0800 Message-Id: <20211208005640.102814-4-ebiggers@kernel.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20211208005640.102814-1-ebiggers@kernel.org> References: <20211208005640.102814-1-ebiggers@kernel.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-block@vger.kernel.org From: Eric Biggers The nomerges file was missing a "Contact" entry. Use linux-block. Reviewed-by: Greg Kroah-Hartman Reviewed-by: Hannes Reinecke Signed-off-by: Eric Biggers --- Documentation/ABI/stable/sysfs-block | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/ABI/stable/sysfs-block b/Documentation/ABI/stable/sysfs-block index 9febd53a5ebe8..c70fce6b76c17 100644 --- a/Documentation/ABI/stable/sysfs-block +++ b/Documentation/ABI/stable/sysfs-block @@ -242,7 +242,7 @@ Description: What: /sys/block//queue/nomerges Date: January 2010 -Contact: +Contact: linux-block@vger.kernel.org Description: Standard I/O elevator operations include attempts to merge contiguous I/Os. For known random I/O loads these From patchwork Wed Dec 8 00:56:36 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eric Biggers X-Patchwork-Id: 12663111 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 01087C433F5 for ; Wed, 8 Dec 2021 00:57:50 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S239280AbhLHBBU (ORCPT ); Tue, 7 Dec 2021 20:01:20 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:53524 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S239014AbhLHBBD (ORCPT ); Tue, 7 Dec 2021 20:01:03 -0500 Received: from sin.source.kernel.org (sin.source.kernel.org [IPv6:2604:1380:40e1:4800::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 7273AC061746; Tue, 7 Dec 2021 16:57:32 -0800 (PST) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by sin.source.kernel.org (Postfix) with ESMTPS id 84829CE1F5B; Wed, 8 Dec 2021 00:57:30 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 7FAD4C341CA; Wed, 8 Dec 2021 00:57:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1638925048; bh=8+APaLFjTajCgb6OWAqt3RT21EQ6OfqSDcoEgjOcS14=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=nCaLlafaHUSVO9mv+gMEKd49AmoQLENHfpiyWdWwKdENkO/Yi6+rVTxg6zO8X60Qo jU3uO0Pw75IEMVpL9vz17qzD/cRC/NUFYnepF8KjC7pKD0so4gEh5I0ppZNGyrjekj Mv26nb3em1+lMAIGTwOgo40t2ajiaYWpib58vlwUUDWYYY/XaDsvsPjR+FSAwwGd6g oLQUUp0nPNhHBTMbwg2H0jl5e29v3o5Hfg7D1UOkGkivYIRVBa28OZTw/iyS+au7hc N3c/IUFQ7CDu1dfiMFyrUGdnw6xWwGg48CqPGppOptzKP29B12sNufWDGX7TaGiJqT AtyFYzAtCjnCQ== From: Eric Biggers To: linux-block@vger.kernel.org, Jens Axboe Cc: linux-doc@vger.kernel.org, Greg Kroah-Hartman , linux-kernel@vger.kernel.org, Hannes Reinecke Subject: [PATCH v2 4/8] docs: sysfs-block: fill in missing documentation from queue-sysfs.rst Date: Tue, 7 Dec 2021 16:56:36 -0800 Message-Id: <20211208005640.102814-5-ebiggers@kernel.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20211208005640.102814-1-ebiggers@kernel.org> References: <20211208005640.102814-1-ebiggers@kernel.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-block@vger.kernel.org From: Eric Biggers sysfs documentation is supposed to go in Documentation/ABI/. However, /sys/block//queue/* are documented in Documentation/block/queue-sysfs.rst, and sometimes redundantly in Documentation/ABI/stable/sysfs-block too. Let's consolidate this documentation into Documentation/ABI/. Therefore, copy the relevant docs from queue-sysfs.rst into sysfs-block. This primarily means adding the 25 missing files that were documented in queue-sysfs.rst only, as well as mentioning the RO/RW status of files. Documentation/ABI/ requires "Date" and "Contact" fields. For the Date fields, I used the date of the commit which added support for each file. For the "Contact" fields, I used linux-block. Reviewed-by: Greg Kroah-Hartman Reviewed-by: Hannes Reinecke Signed-off-by: Eric Biggers --- Documentation/ABI/stable/sysfs-block | 482 +++++++++++++++++++++------ 1 file changed, 381 insertions(+), 101 deletions(-) diff --git a/Documentation/ABI/stable/sysfs-block b/Documentation/ABI/stable/sysfs-block index c70fce6b76c17..de3b86a3dfa55 100644 --- a/Documentation/ABI/stable/sysfs-block +++ b/Documentation/ABI/stable/sysfs-block @@ -46,7 +46,7 @@ Description: The value type is unsigned int. Cf. Documentation/block/stat.rst which contains a single value for requests in flight. - This is related to nr_requests in Documentation/block/queue-sysfs.rst + This is related to /sys/block//queue/nr_requests and for SCSI device also its queue_depth. @@ -134,207 +134,487 @@ Description: same as the format of /sys/block//stat. +What: /sys/block//queue/add_random +Date: June 2010 +Contact: linux-block@vger.kernel.org +Description: + [RW] This file allows to turn off the disk entropy contribution. + Default value of this file is '1'(on). + + What: /sys/block//queue/chunk_sectors Date: September 2016 Contact: Hannes Reinecke Description: - chunk_sectors has different meaning depending on the type + [RO] chunk_sectors has different meaning depending on the type of the disk. For a RAID device (dm-raid), chunk_sectors - indicates the size in 512B sectors of the RAID volume - stripe segment. For a zoned block device, either - host-aware or host-managed, chunk_sectors indicates the - size in 512B sectors of the zones of the device, with - the eventual exception of the last zone of the device - which may be smaller. + indicates the size in 512B sectors of the RAID volume stripe + segment. For a zoned block device, either host-aware or + host-managed, chunk_sectors indicates the size in 512B sectors + of the zones of the device, with the eventual exception of the + last zone of the device which may be smaller. + + +What: /sys/block//queue/dax +Date: June 2016 +Contact: linux-block@vger.kernel.org +Description: + [RO] This file indicates whether the device supports Direct + Access (DAX), used by CPU-addressable storage to bypass the + pagecache. It shows '1' if true, '0' if not. What: /sys/block//queue/discard_granularity Date: May 2011 Contact: Martin K. Petersen Description: - Devices that support discard functionality may - internally allocate space using units that are bigger - than the logical block size. The discard_granularity - parameter indicates the size of the internal allocation - unit in bytes if reported by the device. Otherwise the - discard_granularity will be set to match the device's - physical block size. A discard_granularity of 0 means - that the device does not support discard functionality. + [RO] Devices that support discard functionality may internally + allocate space using units that are bigger than the logical + block size. The discard_granularity parameter indicates the size + of the internal allocation unit in bytes if reported by the + device. Otherwise the discard_granularity will be set to match + the device's physical block size. A discard_granularity of 0 + means that the device does not support discard functionality. What: /sys/block//queue/discard_max_bytes Date: May 2011 Contact: Martin K. Petersen Description: - Devices that support discard functionality may have - internal limits on the number of bytes that can be - trimmed or unmapped in a single operation. Some storage - protocols also have inherent limits on the number of - blocks that can be described in a single command. The - discard_max_bytes parameter is set by the device driver - to the maximum number of bytes that can be discarded in - a single operation. Discard requests issued to the - device must not exceed this limit. A discard_max_bytes - value of 0 means that the device does not support - discard functionality. + [RW] While discard_max_hw_bytes is the hardware limit for the + device, this setting is the software limit. Some devices exhibit + large latencies when large discards are issued, setting this + value lower will make Linux issue smaller discards and + potentially help reduce latencies induced by large discard + operations. + + +What: /sys/block//queue/discard_max_hw_bytes +Date: July 2015 +Contact: linux-block@vger.kernel.org +Description: + [RO] Devices that support discard functionality may have + internal limits on the number of bytes that can be trimmed or + unmapped in a single operation. The `discard_max_hw_bytes` + parameter is set by the device driver to the maximum number of + bytes that can be discarded in a single operation. Discard + requests issued to the device must not exceed this limit. A + `discard_max_hw_bytes` value of 0 means that the device does not + support discard functionality. What: /sys/block//queue/discard_zeroes_data Date: May 2011 Contact: Martin K. Petersen Description: - Will always return 0. Don't rely on any specific behavior + [RO] Will always return 0. Don't rely on any specific behavior for discards, and don't read this file. +What: /sys/block//queue/fua +Date: May 2018 +Contact: linux-block@vger.kernel.org +Description: + [RO] Whether or not the block driver supports the FUA flag for + write requests. FUA stands for Force Unit Access. If the FUA + flag is set that means that write requests must bypass the + volatile cache of the storage device. + + +What: /sys/block//queue/hw_sector_size +Date: January 2008 +Contact: linux-block@vger.kernel.org +Description: + [RO] This is the hardware sector size of the device, in bytes. + + +What: /sys/block//queue/independent_access_ranges/ +Date: October 2021 +Contact: linux-block@vger.kernel.org +Description: + [RO] The presence of this sub-directory of the + /sys/block/xxx/queue/ directory indicates that the device is + capable of executing requests targeting different sector ranges + in parallel. For instance, single LUN multi-actuator hard-disks + will have an independent_access_ranges directory if the device + correctly advertizes the sector ranges of its actuators. + + The independent_access_ranges directory contains one directory + per access range, with each range described using the sector + (RO) attribute file to indicate the first sector of the range + and the nr_sectors (RO) attribute file to indicate the total + number of sectors in the range starting from the first sector of + the range. For example, a dual-actuator hard-disk will have the + following independent_access_ranges entries.:: + + $ tree /sys/block//queue/independent_access_ranges/ + /sys/block//queue/independent_access_ranges/ + |-- 0 + | |-- nr_sectors + | `-- sector + `-- 1 + |-- nr_sectors + `-- sector + + The sector and nr_sectors attributes use 512B sector unit, + regardless of the actual block size of the device. Independent + access ranges do not overlap and include all sectors within the + device capacity. The access ranges are numbered in increasing + order of the range start sector, that is, the sector attribute + of range 0 always has the value 0. + + +What: /sys/block//queue/io_poll +Date: November 2015 +Contact: linux-block@vger.kernel.org +Description: + [RW] When read, this file shows whether polling is enabled (1) + or disabled (0). Writing '0' to this file will disable polling + for this device. Writing any non-zero value will enable this + feature. + + +What: /sys/block//queue/io_poll_delay +Date: November 2016 +Contact: linux-block@vger.kernel.org +Description: + [RW] If polling is enabled, this controls what kind of polling + will be performed. It defaults to -1, which is classic polling. + In this mode, the CPU will repeatedly ask for completions + without giving up any time. If set to 0, a hybrid polling mode + is used, where the kernel will attempt to make an educated guess + at when the IO will complete. Based on this guess, the kernel + will put the process issuing IO to sleep for an amount of time, + before entering a classic poll loop. This mode might be a little + slower than pure classic polling, but it will be more efficient. + If set to a value larger than 0, the kernel will put the process + issuing IO to sleep for this amount of microseconds before + entering classic polling. + + What: /sys/block//queue/io_timeout Date: November 2018 Contact: Weiping Zhang Description: - io_timeout is the request timeout in milliseconds. If a request - does not complete in this time then the block driver timeout - handler is invoked. That timeout handler can decide to retry - the request, to fail it or to start a device recovery strategy. + [RW] io_timeout is the request timeout in milliseconds. If a + request does not complete in this time then the block driver + timeout handler is invoked. That timeout handler can decide to + retry the request, to fail it or to start a device recovery + strategy. + + +What: /sys/block//queue/iostats +Date: January 2009 +Contact: linux-block@vger.kernel.org +Description: + [RW] This file is used to control (on/off) the iostats + accounting of the disk. What: /sys/block//queue/logical_block_size Date: May 2009 Contact: Martin K. Petersen Description: - This is the smallest unit the storage device can - address. It is typically 512 bytes. + [RO] This is the smallest unit the storage device can address. + It is typically 512 bytes. What: /sys/block//queue/max_active_zones Date: July 2020 Contact: Niklas Cassel Description: - For zoned block devices (zoned attribute indicating + [RO] For zoned block devices (zoned attribute indicating "host-managed" or "host-aware"), the sum of zones belonging to any of the zone states: EXPLICIT OPEN, IMPLICIT OPEN or CLOSED, is limited by this value. If this value is 0, there is no limit. + If the host attempts to exceed this limit, the driver should + report this error with BLK_STS_ZONE_ACTIVE_RESOURCE, which user + space may see as the EOVERFLOW errno. + + +What: /sys/block//queue/max_discard_segments +Date: February 2017 +Contact: linux-block@vger.kernel.org +Description: + [RO] The maximum number of DMA scatter/gather entries in a + discard request. + + +What: /sys/block//queue/max_hw_sectors_kb +Date: September 2004 +Contact: linux-block@vger.kernel.org +Description: + [RO] This is the maximum number of kilobytes supported in a + single data transfer. + + +What: /sys/block//queue/max_integrity_segments +Date: September 2010 +Contact: linux-block@vger.kernel.org +Description: + [RO] Maximum number of elements in a DMA scatter/gather list + with integrity data that will be submitted by the block layer + core to the associated block driver. + What: /sys/block//queue/max_open_zones Date: July 2020 Contact: Niklas Cassel Description: - For zoned block devices (zoned attribute indicating + [RO] For zoned block devices (zoned attribute indicating "host-managed" or "host-aware"), the sum of zones belonging to - any of the zone states: EXPLICIT OPEN or IMPLICIT OPEN, - is limited by this value. If this value is 0, there is no limit. + any of the zone states: EXPLICIT OPEN or IMPLICIT OPEN, is + limited by this value. If this value is 0, there is no limit. + + +What: /sys/block//queue/max_sectors_kb +Date: September 2004 +Contact: linux-block@vger.kernel.org +Description: + [RW] This is the maximum number of kilobytes that the block + layer will allow for a filesystem request. Must be smaller than + or equal to the maximum size allowed by the hardware. + + +What: /sys/block//queue/max_segment_size +Date: March 2010 +Contact: linux-block@vger.kernel.org +Description: + [RO] Maximum size in bytes of a single element in a DMA + scatter/gather list. + + +What: /sys/block//queue/max_segments +Date: March 2010 +Contact: linux-block@vger.kernel.org +Description: + [RO] Maximum number of elements in a DMA scatter/gather list + that is submitted to the associated block driver. What: /sys/block//queue/minimum_io_size Date: April 2009 Contact: Martin K. Petersen Description: - Storage devices may report a granularity or preferred - minimum I/O size which is the smallest request the - device can perform without incurring a performance - penalty. For disk drives this is often the physical - block size. For RAID arrays it is often the stripe - chunk size. A properly aligned multiple of - minimum_io_size is the preferred request size for - workloads where a high number of I/O operations is - desired. + [RO] Storage devices may report a granularity or preferred + minimum I/O size which is the smallest request the device can + perform without incurring a performance penalty. For disk + drives this is often the physical block size. For RAID arrays + it is often the stripe chunk size. A properly aligned multiple + of minimum_io_size is the preferred request size for workloads + where a high number of I/O operations is desired. What: /sys/block//queue/nomerges Date: January 2010 Contact: linux-block@vger.kernel.org Description: - Standard I/O elevator operations include attempts to - merge contiguous I/Os. For known random I/O loads these - attempts will always fail and result in extra cycles - being spent in the kernel. This allows one to turn off - this behavior on one of two ways: When set to 1, complex - merge checks are disabled, but the simple one-shot merges - with the previous I/O request are enabled. When set to 2, - all merge tries are disabled. The default value is 0 - - which enables all types of merge tries. + [RW] Standard I/O elevator operations include attempts to merge + contiguous I/Os. For known random I/O loads these attempts will + always fail and result in extra cycles being spent in the + kernel. This allows one to turn off this behavior on one of two + ways: When set to 1, complex merge checks are disabled, but the + simple one-shot merges with the previous I/O request are + enabled. When set to 2, all merge tries are disabled. The + default value is 0 - which enables all types of merge tries. + + +What: /sys/block//queue/nr_requests +Date: July 2003 +Contact: linux-block@vger.kernel.org +Description: + [RW] This controls how many requests may be allocated in the + block layer for read or write requests. Note that the total + allocated number may be twice this amount, since it applies only + to reads or writes (not the accumulated sum). + + To avoid priority inversion through request starvation, a + request queue maintains a separate request pool per each cgroup + when CONFIG_BLK_CGROUP is enabled, and this parameter applies to + each such per-block-cgroup request pool. IOW, if there are N + block cgroups, each request queue may have up to N request + pools, each independently regulated by nr_requests. What: /sys/block//queue/nr_zones Date: November 2018 Contact: Damien Le Moal Description: - nr_zones indicates the total number of zones of a zoned block - device ("host-aware" or "host-managed" zone model). For regular - block devices, the value is always 0. + [RO] nr_zones indicates the total number of zones of a zoned + block device ("host-aware" or "host-managed" zone model). For + regular block devices, the value is always 0. What: /sys/block//queue/optimal_io_size Date: April 2009 Contact: Martin K. Petersen Description: - Storage devices may report an optimal I/O size, which is - the device's preferred unit for sustained I/O. This is - rarely reported for disk drives. For RAID arrays it is - usually the stripe width or the internal track size. A - properly aligned multiple of optimal_io_size is the - preferred request size for workloads where sustained - throughput is desired. If no optimal I/O size is - reported this file contains 0. + [RO] Storage devices may report an optimal I/O size, which is + the device's preferred unit for sustained I/O. This is rarely + reported for disk drives. For RAID arrays it is usually the + stripe width or the internal track size. A properly aligned + multiple of optimal_io_size is the preferred request size for + workloads where sustained throughput is desired. If no optimal + I/O size is reported this file contains 0. What: /sys/block//queue/physical_block_size Date: May 2009 Contact: Martin K. Petersen Description: - This is the smallest unit a physical storage device can - write atomically. It is usually the same as the logical - block size but may be bigger. One example is SATA - drives with 4KB sectors that expose a 512-byte logical - block size to the operating system. For stacked block - devices the physical_block_size variable contains the - maximum physical_block_size of the component devices. + [RO] This is the smallest unit a physical storage device can + write atomically. It is usually the same as the logical block + size but may be bigger. One example is SATA drives with 4KB + sectors that expose a 512-byte logical block size to the + operating system. For stacked block devices the + physical_block_size variable contains the maximum + physical_block_size of the component devices. + + +What: /sys/block//queue/read_ahead_kb +Date: May 2004 +Contact: linux-block@vger.kernel.org +Description: + [RW] Maximum number of kilobytes to read-ahead for filesystems + on this block device. + + +What: /sys/block//queue/rotational +Date: January 2009 +Contact: linux-block@vger.kernel.org +Description: + [RW] This file is used to stat if the device is of rotational + type or non-rotational type. + + +What: /sys/block//queue/rq_affinity +Date: September 2008 +Contact: linux-block@vger.kernel.org +Description: + [RW] If this option is '1', the block layer will migrate request + completions to the cpu "group" that originally submitted the + request. For some workloads this provides a significant + reduction in CPU cycles due to caching effects. + + For storage configurations that need to maximize distribution of + completion processing setting this option to '2' forces the + completion to run on the requesting cpu (bypassing the "group" + aggregation logic). + + +What: /sys/block//queue/scheduler +Date: October 2004 +Contact: linux-block@vger.kernel.org +Description: + [RW] When read, this file will display the current and available + IO schedulers for this block device. The currently active IO + scheduler will be enclosed in [] brackets. Writing an IO + scheduler name to this file will switch control of this block + device to that new IO scheduler. Note that writing an IO + scheduler name to this file will attempt to load that IO + scheduler module, if it isn't already present in the system. + + +What: /sys/block//queue/throttle_sample_time +Date: March 2017 +Contact: linux-block@vger.kernel.org +Description: + [RW] This is the time window that blk-throttle samples data, in + millisecond. blk-throttle makes decision based on the + samplings. Lower time means cgroups have more smooth throughput, + but higher CPU overhead. This exists only when + CONFIG_BLK_DEV_THROTTLING_LOW is enabled. + + +What: /sys/block//queue/wbt_lat_usec +Date: November 2016 +Contact: linux-block@vger.kernel.org +Description: + [RW] If the device is registered for writeback throttling, then + this file shows the target minimum read latency. If this latency + is exceeded in a given window of time (see wb_window_usec), then + the writeback throttling will start scaling back writes. Writing + a value of '0' to this file disables the feature. Writing a + value of '-1' to this file resets the value to the default + setting. + + +What: /sys/block//queue/write_cache +Date: April 2016 +Contact: linux-block@vger.kernel.org +Description: + [RW] When read, this file will display whether the device has + write back caching enabled or not. It will return "write back" + for the former case, and "write through" for the latter. Writing + to this file can change the kernels view of the device, but it + doesn't alter the device state. This means that it might not be + safe to toggle the setting from "write back" to "write through", + since that will also eliminate cache flushes issued by the + kernel. What: /sys/block//queue/write_same_max_bytes Date: January 2012 Contact: Martin K. Petersen Description: - Some devices support a write same operation in which a + [RO] Some devices support a write same operation in which a single data block can be written to a range of several - contiguous blocks on storage. This can be used to wipe - areas on disk or to initialize drives in a RAID - configuration. write_same_max_bytes indicates how many - bytes can be written in a single write same command. If - write_same_max_bytes is 0, write same is not supported - by the device. + contiguous blocks on storage. This can be used to wipe areas on + disk or to initialize drives in a RAID configuration. + write_same_max_bytes indicates how many bytes can be written in + a single write same command. If write_same_max_bytes is 0, write + same is not supported by the device. What: /sys/block//queue/write_zeroes_max_bytes Date: November 2016 Contact: Chaitanya Kulkarni Description: - Devices that support write zeroes operation in which a - single request can be issued to zero out the range of - contiguous blocks on storage without having any payload - in the request. This can be used to optimize writing zeroes - to the devices. write_zeroes_max_bytes indicates how many - bytes can be written in a single write zeroes command. If - write_zeroes_max_bytes is 0, write zeroes is not supported - by the device. + [RO] Devices that support write zeroes operation in which a + single request can be issued to zero out the range of contiguous + blocks on storage without having any payload in the request. + This can be used to optimize writing zeroes to the devices. + write_zeroes_max_bytes indicates how many bytes can be written + in a single write zeroes command. If write_zeroes_max_bytes is + 0, write zeroes is not supported by the device. + + +What: /sys/block//queue/zone_append_max_bytes +Date: May 2020 +Contact: linux-block@vger.kernel.org +Description: + [RO] This is the maximum number of bytes that can be written to + a sequential zone of a zoned block device using a zone append + write operation (REQ_OP_ZONE_APPEND). This value is always 0 for + regular block devices. + + +What: /sys/block//queue/zone_write_granularity +Date: January 2021 +Contact: linux-block@vger.kernel.org +Description: + [RO] This indicates the alignment constraint, in bytes, for + write operations in sequential zones of zoned block devices + (devices with a zoned attributed that reports "host-managed" or + "host-aware"). This value is always 0 for regular block devices. What: /sys/block//queue/zoned Date: September 2016 Contact: Damien Le Moal Description: - zoned indicates if the device is a zoned block device - and the zone model of the device if it is indeed zoned. - The possible values indicated by zoned are "none" for - regular block devices and "host-aware" or "host-managed" - for zoned block devices. The characteristics of - host-aware and host-managed zoned block devices are - described in the ZBC (Zoned Block Commands) and ZAC - (Zoned Device ATA Command Set) standards. These standards - also define the "drive-managed" zone model. However, - since drive-managed zoned block devices do not support - zone commands, they will be treated as regular block - devices and zoned will report "none". + [RO] zoned indicates if the device is a zoned block device and + the zone model of the device if it is indeed zoned. The + possible values indicated by zoned are "none" for regular block + devices and "host-aware" or "host-managed" for zoned block + devices. The characteristics of host-aware and host-managed + zoned block devices are described in the ZBC (Zoned Block + Commands) and ZAC (Zoned Device ATA Command Set) standards. + These standards also define the "drive-managed" zone model. + However, since drive-managed zoned block devices do not support + zone commands, they will be treated as regular block devices and + zoned will report "none". What: /sys/block//stat From patchwork Wed Dec 8 00:56:37 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eric Biggers X-Patchwork-Id: 12663105 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 92F05C433F5 for ; Wed, 8 Dec 2021 00:57:45 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S239052AbhLHBBE (ORCPT ); Tue, 7 Dec 2021 20:01:04 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:53516 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S238948AbhLHBBC (ORCPT ); Tue, 7 Dec 2021 20:01:02 -0500 Received: from ams.source.kernel.org (ams.source.kernel.org [IPv6:2604:1380:4601:e00::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 8456BC061746; Tue, 7 Dec 2021 16:57:31 -0800 (PST) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ams.source.kernel.org (Postfix) with ESMTPS id 493F7B81F07; Wed, 8 Dec 2021 00:57:30 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id DD7ABC341CD; Wed, 8 Dec 2021 00:57:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1638925049; bh=T6c3r/MsuZMeHAt1ZBPcbgrbe8ykTaS8eY/bKSrSpMg=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=gIs2sq0lWuK5pCQKn5Njqx8TrbUHG1cMFB/wiG9EzNWqdsSh2M+8Fk9tL3YtSxAv2 hSMix7rpoFACCMepj5F6spKRC/4UaJCads7LR3VWJtTQqqjTRgsoe9ud5+EAX5ojPV pPkyAsqAZrAheS3Rjlw/fo2qr5mTaBDXI+e0cpINtd8Y2emOuxYpODCBthqLT5IB7p 4UdqnueBe0Rr76tptAcpbrMxuKYk82iQyMR5Q9QnBwFVFWp4hvvYoAptq4Pb1ElHNZ 9OVfQbLxE8pG4w9y14lOeLeyaHGDbzkwtCAOc5dfeVxVDY79j2z6u1pc3zhe19gOew Meptg+q8po89g== From: Eric Biggers To: linux-block@vger.kernel.org, Jens Axboe Cc: linux-doc@vger.kernel.org, Greg Kroah-Hartman , linux-kernel@vger.kernel.org, Hannes Reinecke Subject: [PATCH v2 5/8] docs: sysfs-block: document stable_writes Date: Tue, 7 Dec 2021 16:56:37 -0800 Message-Id: <20211208005640.102814-6-ebiggers@kernel.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20211208005640.102814-1-ebiggers@kernel.org> References: <20211208005640.102814-1-ebiggers@kernel.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-block@vger.kernel.org From: Eric Biggers /sys/block//queue/stable_writes is completely undocumented. Document it. Reviewed-by: Greg Kroah-Hartman Reviewed-by: Hannes Reinecke Signed-off-by: Eric Biggers --- Documentation/ABI/stable/sysfs-block | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/Documentation/ABI/stable/sysfs-block b/Documentation/ABI/stable/sysfs-block index de3b86a3dfa55..30ce8dc587bb2 100644 --- a/Documentation/ABI/stable/sysfs-block +++ b/Documentation/ABI/stable/sysfs-block @@ -516,6 +516,16 @@ Description: scheduler module, if it isn't already present in the system. +What: /sys/block//queue/stable_writes +Date: September 2020 +Contact: linux-block@vger.kernel.org +Description: + [RW] If the device requires that memory must not be modified + while it is being written out to disk, this file will contain + '1'. Otherwise it will contain '0'. This file is writable for + testing purposes. + + What: /sys/block//queue/throttle_sample_time Date: March 2017 Contact: linux-block@vger.kernel.org From patchwork Wed Dec 8 00:56:38 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eric Biggers X-Patchwork-Id: 12663099 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 9EDC8C4332F for ; Wed, 8 Dec 2021 00:57:35 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S239090AbhLHBBF (ORCPT ); Tue, 7 Dec 2021 20:01:05 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:53522 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S238974AbhLHBBD (ORCPT ); Tue, 7 Dec 2021 20:01:03 -0500 Received: from ams.source.kernel.org (ams.source.kernel.org [IPv6:2604:1380:4601:e00::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 0DAB0C061748; Tue, 7 Dec 2021 16:57:32 -0800 (PST) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ams.source.kernel.org (Postfix) with ESMTPS id BA27CB81F26; Wed, 8 Dec 2021 00:57:30 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 3FB12C341CE; Wed, 8 Dec 2021 00:57:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1638925049; bh=qsC4hUoks9qZEzFdXzOQJQtkxZyTe1zi+Uf/zpPh68A=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=PNmzTXp0JbeTsVYbdF1Wb/iitqdhuk2phev3PLTHe3nOMu/wC5BxWkKTklcl89CsJ NPkiqNXnsCwFdBot4a7kUPrYuL+qB9AHYR+Aas9wdV+irgsbhMiNtpCDz3shiYYl62 VESXCJjKhBKEzml3x81ePV2t7+/EiMNQq3z/xn14lZkv9KvMO8ePN/I5z/h5nn4+px CIZkCjbqmZVBItLOUZhtJIgYOgCDes3NC1HPGBNQykT0g9Oft7VnH8iPpB1s6EfudZ 5OIy+S4yPvRXvHNzxYggrhgDRGnS8MIINBfvGn1DgZgD+4HdD20GbQ6yzsx/WQy6Po I0OHPxb6KiVgg== From: Eric Biggers To: linux-block@vger.kernel.org, Jens Axboe Cc: linux-doc@vger.kernel.org, Greg Kroah-Hartman , linux-kernel@vger.kernel.org, Hannes Reinecke Subject: [PATCH v2 6/8] docs: sysfs-block: document virt_boundary_mask Date: Tue, 7 Dec 2021 16:56:38 -0800 Message-Id: <20211208005640.102814-7-ebiggers@kernel.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20211208005640.102814-1-ebiggers@kernel.org> References: <20211208005640.102814-1-ebiggers@kernel.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-block@vger.kernel.org From: Eric Biggers /sys/block//queue/virt_boundary_mask is completely undocumented. Document it. Reviewed-by: Greg Kroah-Hartman Reviewed-by: Hannes Reinecke Signed-off-by: Eric Biggers --- Documentation/ABI/stable/sysfs-block | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/Documentation/ABI/stable/sysfs-block b/Documentation/ABI/stable/sysfs-block index 30ce8dc587bb2..e988742a54a4c 100644 --- a/Documentation/ABI/stable/sysfs-block +++ b/Documentation/ABI/stable/sysfs-block @@ -537,6 +537,17 @@ Description: CONFIG_BLK_DEV_THROTTLING_LOW is enabled. +What: /sys/block//queue/virt_boundary_mask +Date: April 2021 +Contact: linux-block@vger.kernel.org +Description: + [RO] This file shows the I/O segment alignment mask for the + block device. I/O requests to this device will be split between + segments wherever either the end of the previous segment or the + beginning of the current segment is not aligned to + virt_boundary_mask + 1 bytes. + + What: /sys/block//queue/wbt_lat_usec Date: November 2016 Contact: linux-block@vger.kernel.org From patchwork Wed Dec 8 00:56:39 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eric Biggers X-Patchwork-Id: 12663101 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 0E593C433FE for ; Wed, 8 Dec 2021 00:57:37 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S238916AbhLHBBG (ORCPT ); Tue, 7 Dec 2021 20:01:06 -0500 Received: from sin.source.kernel.org ([145.40.73.55]:38714 "EHLO sin.source.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S238989AbhLHBBE (ORCPT ); Tue, 7 Dec 2021 20:01:04 -0500 Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by sin.source.kernel.org (Postfix) with ESMTPS id 967ECCE1F5C; Wed, 8 Dec 2021 00:57:31 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 968AAC341C3; Wed, 8 Dec 2021 00:57:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1638925049; bh=FciDfsbkk4aURLiV7DQGVTYDo+ZWM683IPpoEAq36rM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=HHHv8rLxnnCD88O4Mn3Np91meqpdC0WZMeFfOTWc5W33NzVJUiVR+JdnGoKMmSz6h w1ucDIA/POKsC+/rxutfqgQJUqcLL8c55fWAxCNrjzIQO68jGP0AOcCwh4b7R6s24n zmTLj8fbl58Wbqaa3LoU0oXXhs91+YyqDwPL/+NyTRwmQ/E2b+sD+2jhRIbt00/vSk mSTGd/DSYWNN0hZXysd9/qDuoulZVM+3yI9cdBTu9E2nWnYd64mJmHz4s8noaZZ9lc GXjpbd1MWHxq6QStj9FN1PNmjnZNAD3+26ZW6djAqQr7gv7kobJugvzSHIPCderKxz wZe37aa3c8GIg== From: Eric Biggers To: linux-block@vger.kernel.org, Jens Axboe Cc: linux-doc@vger.kernel.org, Greg Kroah-Hartman , linux-kernel@vger.kernel.org, Hannes Reinecke Subject: [PATCH v2 7/8] docs: block: remove queue-sysfs.rst Date: Tue, 7 Dec 2021 16:56:39 -0800 Message-Id: <20211208005640.102814-8-ebiggers@kernel.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20211208005640.102814-1-ebiggers@kernel.org> References: <20211208005640.102814-1-ebiggers@kernel.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-block@vger.kernel.org From: Eric Biggers This has been replaced by Documentation/ABI/stable/sysfs-block, which is the correct place for sysfs documentation. Reviewed-by: Greg Kroah-Hartman Reviewed-by: Hannes Reinecke Signed-off-by: Eric Biggers --- Documentation/block/index.rst | 1 - Documentation/block/queue-sysfs.rst | 321 ---------------------------- 2 files changed, 322 deletions(-) delete mode 100644 Documentation/block/queue-sysfs.rst diff --git a/Documentation/block/index.rst b/Documentation/block/index.rst index 86dcf7159f990..3a41495dd77b5 100644 --- a/Documentation/block/index.rst +++ b/Documentation/block/index.rst @@ -20,7 +20,6 @@ Block kyber-iosched null_blk pr - queue-sysfs request stat switching-sched diff --git a/Documentation/block/queue-sysfs.rst b/Documentation/block/queue-sysfs.rst deleted file mode 100644 index 3f569d5324857..0000000000000 --- a/Documentation/block/queue-sysfs.rst +++ /dev/null @@ -1,321 +0,0 @@ -================= -Queue sysfs files -================= - -This text file will detail the queue files that are located in the sysfs tree -for each block device. Note that stacked devices typically do not export -any settings, since their queue merely functions as a remapping target. -These files are the ones found in the /sys/block/xxx/queue/ directory. - -Files denoted with a RO postfix are readonly and the RW postfix means -read-write. - -add_random (RW) ---------------- -This file allows to turn off the disk entropy contribution. Default -value of this file is '1'(on). - -chunk_sectors (RO) ------------------- -This has different meaning depending on the type of the block device. -For a RAID device (dm-raid), chunk_sectors indicates the size in 512B sectors -of the RAID volume stripe segment. For a zoned block device, either host-aware -or host-managed, chunk_sectors indicates the size in 512B sectors of the zones -of the device, with the eventual exception of the last zone of the device which -may be smaller. - -dax (RO) --------- -This file indicates whether the device supports Direct Access (DAX), -used by CPU-addressable storage to bypass the pagecache. It shows '1' -if true, '0' if not. - -discard_granularity (RO) ------------------------- -This shows the size of internal allocation of the device in bytes, if -reported by the device. A value of '0' means device does not support -the discard functionality. - -discard_max_hw_bytes (RO) -------------------------- -Devices that support discard functionality may have internal limits on -the number of bytes that can be trimmed or unmapped in a single operation. -The `discard_max_hw_bytes` parameter is set by the device driver to the -maximum number of bytes that can be discarded in a single operation. -Discard requests issued to the device must not exceed this limit. -A `discard_max_hw_bytes` value of 0 means that the device does not support -discard functionality. - -discard_max_bytes (RW) ----------------------- -While discard_max_hw_bytes is the hardware limit for the device, this -setting is the software limit. Some devices exhibit large latencies when -large discards are issued, setting this value lower will make Linux issue -smaller discards and potentially help reduce latencies induced by large -discard operations. - -discard_zeroes_data (RO) ------------------------- -Obsolete. Always zero. - -fua (RO) --------- -Whether or not the block driver supports the FUA flag for write requests. -FUA stands for Force Unit Access. If the FUA flag is set that means that -write requests must bypass the volatile cache of the storage device. - -hw_sector_size (RO) -------------------- -This is the hardware sector size of the device, in bytes. - -io_poll (RW) ------------- -When read, this file shows whether polling is enabled (1) or disabled -(0). Writing '0' to this file will disable polling for this device. -Writing any non-zero value will enable this feature. - -io_poll_delay (RW) ------------------- -If polling is enabled, this controls what kind of polling will be -performed. It defaults to -1, which is classic polling. In this mode, -the CPU will repeatedly ask for completions without giving up any time. -If set to 0, a hybrid polling mode is used, where the kernel will attempt -to make an educated guess at when the IO will complete. Based on this -guess, the kernel will put the process issuing IO to sleep for an amount -of time, before entering a classic poll loop. This mode might be a -little slower than pure classic polling, but it will be more efficient. -If set to a value larger than 0, the kernel will put the process issuing -IO to sleep for this amount of microseconds before entering classic -polling. - -io_timeout (RW) ---------------- -io_timeout is the request timeout in milliseconds. If a request does not -complete in this time then the block driver timeout handler is invoked. -That timeout handler can decide to retry the request, to fail it or to start -a device recovery strategy. - -iostats (RW) -------------- -This file is used to control (on/off) the iostats accounting of the -disk. - -logical_block_size (RO) ------------------------ -This is the logical block size of the device, in bytes. - -max_discard_segments (RO) -------------------------- -The maximum number of DMA scatter/gather entries in a discard request. - -max_hw_sectors_kb (RO) ----------------------- -This is the maximum number of kilobytes supported in a single data transfer. - -max_integrity_segments (RO) ---------------------------- -Maximum number of elements in a DMA scatter/gather list with integrity -data that will be submitted by the block layer core to the associated -block driver. - -max_active_zones (RO) ---------------------- -For zoned block devices (zoned attribute indicating "host-managed" or -"host-aware"), the sum of zones belonging to any of the zone states: -EXPLICIT OPEN, IMPLICIT OPEN or CLOSED, is limited by this value. -If this value is 0, there is no limit. - -If the host attempts to exceed this limit, the driver should report this error -with BLK_STS_ZONE_ACTIVE_RESOURCE, which user space may see as the EOVERFLOW -errno. - -max_open_zones (RO) -------------------- -For zoned block devices (zoned attribute indicating "host-managed" or -"host-aware"), the sum of zones belonging to any of the zone states: -EXPLICIT OPEN or IMPLICIT OPEN, is limited by this value. -If this value is 0, there is no limit. - -If the host attempts to exceed this limit, the driver should report this error -with BLK_STS_ZONE_OPEN_RESOURCE, which user space may see as the ETOOMANYREFS -errno. - -max_sectors_kb (RW) -------------------- -This is the maximum number of kilobytes that the block layer will allow -for a filesystem request. Must be smaller than or equal to the maximum -size allowed by the hardware. - -max_segments (RO) ------------------ -Maximum number of elements in a DMA scatter/gather list that is submitted -to the associated block driver. - -max_segment_size (RO) ---------------------- -Maximum size in bytes of a single element in a DMA scatter/gather list. - -minimum_io_size (RO) --------------------- -This is the smallest preferred IO size reported by the device. - -nomerges (RW) -------------- -This enables the user to disable the lookup logic involved with IO -merging requests in the block layer. By default (0) all merges are -enabled. When set to 1 only simple one-hit merges will be tried. When -set to 2 no merge algorithms will be tried (including one-hit or more -complex tree/hash lookups). - -nr_requests (RW) ----------------- -This controls how many requests may be allocated in the block layer for -read or write requests. Note that the total allocated number may be twice -this amount, since it applies only to reads or writes (not the accumulated -sum). - -To avoid priority inversion through request starvation, a request -queue maintains a separate request pool per each cgroup when -CONFIG_BLK_CGROUP is enabled, and this parameter applies to each such -per-block-cgroup request pool. IOW, if there are N block cgroups, -each request queue may have up to N request pools, each independently -regulated by nr_requests. - -nr_zones (RO) -------------- -For zoned block devices (zoned attribute indicating "host-managed" or -"host-aware"), this indicates the total number of zones of the device. -This is always 0 for regular block devices. - -optimal_io_size (RO) --------------------- -This is the optimal IO size reported by the device. - -physical_block_size (RO) ------------------------- -This is the physical block size of device, in bytes. - -read_ahead_kb (RW) ------------------- -Maximum number of kilobytes to read-ahead for filesystems on this block -device. - -rotational (RW) ---------------- -This file is used to stat if the device is of rotational type or -non-rotational type. - -rq_affinity (RW) ----------------- -If this option is '1', the block layer will migrate request completions to the -cpu "group" that originally submitted the request. For some workloads this -provides a significant reduction in CPU cycles due to caching effects. - -For storage configurations that need to maximize distribution of completion -processing setting this option to '2' forces the completion to run on the -requesting cpu (bypassing the "group" aggregation logic). - -scheduler (RW) --------------- -When read, this file will display the current and available IO schedulers -for this block device. The currently active IO scheduler will be enclosed -in [] brackets. Writing an IO scheduler name to this file will switch -control of this block device to that new IO scheduler. Note that writing -an IO scheduler name to this file will attempt to load that IO scheduler -module, if it isn't already present in the system. - -write_cache (RW) ----------------- -When read, this file will display whether the device has write back -caching enabled or not. It will return "write back" for the former -case, and "write through" for the latter. Writing to this file can -change the kernels view of the device, but it doesn't alter the -device state. This means that it might not be safe to toggle the -setting from "write back" to "write through", since that will also -eliminate cache flushes issued by the kernel. - -write_same_max_bytes (RO) -------------------------- -This is the number of bytes the device can write in a single write-same -command. A value of '0' means write-same is not supported by this -device. - -wbt_lat_usec (RW) ------------------ -If the device is registered for writeback throttling, then this file shows -the target minimum read latency. If this latency is exceeded in a given -window of time (see wb_window_usec), then the writeback throttling will start -scaling back writes. Writing a value of '0' to this file disables the -feature. Writing a value of '-1' to this file resets the value to the -default setting. - -throttle_sample_time (RW) -------------------------- -This is the time window that blk-throttle samples data, in millisecond. -blk-throttle makes decision based on the samplings. Lower time means cgroups -have more smooth throughput, but higher CPU overhead. This exists only when -CONFIG_BLK_DEV_THROTTLING_LOW is enabled. - -write_zeroes_max_bytes (RO) ---------------------------- -For block drivers that support REQ_OP_WRITE_ZEROES, the maximum number of -bytes that can be zeroed at once. The value 0 means that REQ_OP_WRITE_ZEROES -is not supported. - -zone_append_max_bytes (RO) --------------------------- -This is the maximum number of bytes that can be written to a sequential -zone of a zoned block device using a zone append write operation -(REQ_OP_ZONE_APPEND). This value is always 0 for regular block devices. - -zoned (RO) ----------- -This indicates if the device is a zoned block device and the zone model of the -device if it is indeed zoned. The possible values indicated by zoned are -"none" for regular block devices and "host-aware" or "host-managed" for zoned -block devices. The characteristics of host-aware and host-managed zoned block -devices are described in the ZBC (Zoned Block Commands) and ZAC -(Zoned Device ATA Command Set) standards. These standards also define the -"drive-managed" zone model. However, since drive-managed zoned block devices -do not support zone commands, they will be treated as regular block devices -and zoned will report "none". - -zone_write_granularity (RO) ---------------------------- -This indicates the alignment constraint, in bytes, for write operations in -sequential zones of zoned block devices (devices with a zoned attributed -that reports "host-managed" or "host-aware"). This value is always 0 for -regular block devices. - -independent_access_ranges (RO) ------------------------------- - -The presence of this sub-directory of the /sys/block/xxx/queue/ directory -indicates that the device is capable of executing requests targeting -different sector ranges in parallel. For instance, single LUN multi-actuator -hard-disks will have an independent_access_ranges directory if the device -correctly advertizes the sector ranges of its actuators. - -The independent_access_ranges directory contains one directory per access -range, with each range described using the sector (RO) attribute file to -indicate the first sector of the range and the nr_sectors (RO) attribute file -to indicate the total number of sectors in the range starting from the first -sector of the range. For example, a dual-actuator hard-disk will have the -following independent_access_ranges entries.:: - - $ tree /sys/block//queue/independent_access_ranges/ - /sys/block//queue/independent_access_ranges/ - |-- 0 - | |-- nr_sectors - | `-- sector - `-- 1 - |-- nr_sectors - `-- sector - -The sector and nr_sectors attributes use 512B sector unit, regardless of -the actual block size of the device. Independent access ranges do not -overlap and include all sectors within the device capacity. The access -ranges are numbered in increasing order of the range start sector, -that is, the sector attribute of range 0 always has the value 0. - -Jens Axboe , February 2009 From patchwork Wed Dec 8 00:56:40 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eric Biggers X-Patchwork-Id: 12663109 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id A96C4C433F5 for ; Wed, 8 Dec 2021 00:57:47 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S239047AbhLHBBP (ORCPT ); Tue, 7 Dec 2021 20:01:15 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:53536 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S239086AbhLHBBE (ORCPT ); Tue, 7 Dec 2021 20:01:04 -0500 Received: from sin.source.kernel.org (sin.source.kernel.org [IPv6:2604:1380:40e1:4800::1]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id A0031C061746; Tue, 7 Dec 2021 16:57:33 -0800 (PST) Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by sin.source.kernel.org (Postfix) with ESMTPS id ED8DCCE1F42; Wed, 8 Dec 2021 00:57:31 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id EE118C341C5; Wed, 8 Dec 2021 00:57:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1638925050; bh=doXw0FYXEv55XwbYN1486+6hyhzPsD7PUsHDWpGZ1no=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ESTxpbjv8+14Eiq3kOAgxzpInZ3e1a0+97xQRcb3YLLeUwa+XCczhp0Wq+ytPr0fm E4TOErkwSQOjByTuyBSuJkOQkozjHMpgR5UkG0I16hjyL8p1eSW/7yhzrTa0GQ48BO cx4hX1/OVH1xHmg0RBneFVrltGyVegc95ODPD3pyjVIKNYvrXTlq3eBT8Xy18mmZ/h p25mtqd3Gq9CaHTC7jjZepRzo2pGv8tLGXvnByXDLIKiZciGegUq7sRCGd2CfD9aca KJDLSBdZj6N+NwtmHDakm3X+I3VTHWFSfPHKbHNvz7XHbDXf7TTkFpzgmVfLj1CXD8 HGNg9GYhvuy+g== From: Eric Biggers To: linux-block@vger.kernel.org, Jens Axboe Cc: linux-doc@vger.kernel.org, Greg Kroah-Hartman , linux-kernel@vger.kernel.org, Hannes Reinecke Subject: [PATCH v2 8/8] MAINTAINERS: add entries for block layer documentation Date: Tue, 7 Dec 2021 16:56:40 -0800 Message-Id: <20211208005640.102814-9-ebiggers@kernel.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20211208005640.102814-1-ebiggers@kernel.org> References: <20211208005640.102814-1-ebiggers@kernel.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-block@vger.kernel.org From: Eric Biggers Include Documentation/block/ and Documentation/ABI/stable/sysfs-block in the "BLOCK LAYER" maintainers file entry. Reviewed-by: Greg Kroah-Hartman Reviewed-by: Hannes Reinecke Signed-off-by: Eric Biggers --- MAINTAINERS | 2 ++ 1 file changed, 2 insertions(+) diff --git a/MAINTAINERS b/MAINTAINERS index 360e9aa0205d6..19db69dda15af 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -3380,6 +3380,8 @@ M: Jens Axboe L: linux-block@vger.kernel.org S: Maintained T: git git://git.kernel.org/pub/scm/linux/kernel/git/axboe/linux-block.git +F: Documentation/ABI/stable/sysfs-block +F: Documentation/block/ F: block/ F: drivers/block/ F: include/linux/blk*