From patchwork Thu Dec 9 00:38:26 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eric Biggers X-Patchwork-Id: 12665583 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 79AC8C433EF for ; Thu, 9 Dec 2021 00:40:04 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S235376AbhLIAne (ORCPT ); Wed, 8 Dec 2021 19:43:34 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:41338 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232361AbhLIAne (ORCPT ); Wed, 8 Dec 2021 19:43:34 -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 6DE92C061746; Wed, 8 Dec 2021 16:40:01 -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 15974B82331; Thu, 9 Dec 2021 00:40:00 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 800D4C341C6; Thu, 9 Dec 2021 00:39:58 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1639010398; bh=Rru9VNpKwobGSsbMxjlqdcJD47gIcRS3a6kDRYb0Q30=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=eTo8jAuPeOQ8DXQE6IsrDRmK7CwS1MHMwac+PggASMHREGUYdWv0GaU63McBPUnYr wNbkgy6Pv3GQFus+XHv+uRdeYLaI6Oy4RFkokWk+SEZfaelk+UCIMJEYAgiccSOEsl 2LW78zJ8H0LpWrGcPGmDoEcYH3MCnOS1CcO+K8/ad4/QuzIJCROph8safHc/ooFjl0 ik9DMKhoEGpuZavzq0q98Jp6HyiwDsgNcirQNrmSWxGPjLOEtcz6ikL+W7abTXjrue DyqQv/4J6DYchnbY03Bzeb7mgOllKE/zUz6Je3SDZMPTm58mXz9TUzncyUtv4YwUls /hF//Hp/elYGw== 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, "Martin K. Petersen" , Bart Van Assche Subject: [PATCH v3 1/8] docs: sysfs-block: move to stable directory Date: Wed, 8 Dec 2021 16:38:26 -0800 Message-Id: <20211209003833.6396-2-ebiggers@kernel.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20211209003833.6396-1-ebiggers@kernel.org> References: <20211209003833.6396-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. Reviewed-by: Martin K. Petersen Reviewed-by: Bart Van Assche 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 Thu Dec 9 00:38:27 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eric Biggers X-Patchwork-Id: 12665599 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 91910C433EF for ; Thu, 9 Dec 2021 00:40:16 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S241561AbhLIAnp (ORCPT ); Wed, 8 Dec 2021 19:43:45 -0500 Received: from sin.source.kernel.org ([145.40.73.55]:49318 "EHLO sin.source.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S241329AbhLIAnf (ORCPT ); Wed, 8 Dec 2021 19:43:35 -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 1940FCE241C; Thu, 9 Dec 2021 00:40:01 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id E7185C341CA; Thu, 9 Dec 2021 00:39:58 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1639010399; bh=LcRULFDl6YUhiE/QDw/ugAUBdimroPYiC5+uQNSitts=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=XIogTA/wQRzTRijhhnLcju/5gJOlFT8ipwOwTyldhJA9xDeSRFS+BusNacD1Tkxhg B3gtXZKjZPK+Kg8k4GZZJgVgrt0NrqcQ9zbXFz7SrX0gkkJVSD9D3uAmY8pKmB0Zwr QpQb+K/bKueycfWGzg2yygUE5rUTi7ONRST8WET1zgq2RuHP5ZicNkFU2B73yCeDMY ussuXRxhwUp08DOCAXmonlj1KQLGoQy+FEmngclo+aK782D1pFo6sdtza2HckngBds co51LAvP4XJtzK2SsqF+7FzkobGJ7K44klIFl2b5Hs4BimswM76XoIXNUTJM1iUjA3 maGXqxe6u75sA== 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 , "Martin K. Petersen" , Bart Van Assche Subject: [PATCH v3 2/8] docs: sysfs-block: sort alphabetically Date: Wed, 8 Dec 2021 16:38:27 -0800 Message-Id: <20211209003833.6396-3-ebiggers@kernel.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20211209003833.6396-1-ebiggers@kernel.org> References: <20211209003833.6396-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 Reviewed-by: Martin K. Petersen Reviewed-by: Bart Van Assche 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 Thu Dec 9 00:38:28 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eric Biggers X-Patchwork-Id: 12665597 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 4C1A2C43217 for ; Thu, 9 Dec 2021 00:40:17 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S241596AbhLIAnr (ORCPT ); Wed, 8 Dec 2021 19:43:47 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:41340 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S241365AbhLIAne (ORCPT ); Wed, 8 Dec 2021 19:43:34 -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 4720CC061746; Wed, 8 Dec 2021 16:40:02 -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 03283B82284; Thu, 9 Dec 2021 00:40:01 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 641C9C341C7; Thu, 9 Dec 2021 00:39:59 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1639010399; bh=JSsIsPMDLa6QoQk3ochxR7oNxZfnhw6OWqS5mt7MjrY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=jDWMVgPqDEyn2MUW0Awss8wH2IEx8ENZJdHBysL4AqbHNx3KzB0OslhiVEvTT0KSd 8C70ajc9AbJgzGONqb02BQFwDx3KvxodPX7i8h7AEgCke3Zg7oHpTFbDQX2YxyJAHr n8K3yqCnGrRvR31c3dxyxNneTQzxZxJbOC/uNVu0seqaE+xb+S9vBEISy7U9EfWyFb gPZmIAccDI2XUeTWl0vSC/CBCrMxucgswBThJjVLEorrhw69UrujvYgCfgEXbdjcSx TPxNvk1VXaBMyFWdzH7bb/v14ctEUe6W0rPRtTtnkqSNxbkNxRcDnB0ge2/HeFtExN 0T4me1orcc1XQ== 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 , "Martin K. Petersen" , Bart Van Assche Subject: [PATCH v3 3/8] docs: sysfs-block: add contact for nomerges Date: Wed, 8 Dec 2021 16:38:28 -0800 Message-Id: <20211209003833.6396-4-ebiggers@kernel.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20211209003833.6396-1-ebiggers@kernel.org> References: <20211209003833.6396-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 Reviewed-by: Martin K. Petersen Reviewed-by: Bart Van Assche 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 Thu Dec 9 00:38:29 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eric Biggers X-Patchwork-Id: 12665595 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 EF320C433FE for ; Thu, 9 Dec 2021 00:40:14 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S241550AbhLIAnn (ORCPT ); Wed, 8 Dec 2021 19:43:43 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:41342 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S241494AbhLIAnf (ORCPT ); Wed, 8 Dec 2021 19:43:35 -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 BDD44C0617A1; Wed, 8 Dec 2021 16:40:02 -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 5F8EDB82334; Thu, 9 Dec 2021 00:40:01 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id C72FDC341CB; Thu, 9 Dec 2021 00:39:59 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1639010400; bh=FzJDpSjCF70OMfX+X30ItVNz7J1ZnfR40jc1JeYZz2Y=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=u4H8fukMytnGaiacxkbLVIwCPay/ZvfekTBwJYtxTu4OAIsQxrjhhhSlioqy3S6ZS o0TG7WuJmHzYpEO2kGsvuLsfpvbH97L+FUvKcqmWho59+TmfO2Hud8hqSJq5IRJEp4 vuz+1QW5lamrf8lPMoFvz5D0FfJfo1JW6njChQzQtPbg+f8Phfm/Urvk1YR5YOWagT rg9n0V+fUvSj2aQJcxSV28ZC9L1OD4gT000BojZgO6gUTlGDnZbFg3GUrY6zw9FOmg L3Dbk6hRQKM2nKcS1hpuBc/K278d+C6GiTR2RI7xRJmgv4UPS1gOoMmXKBEyu157gX ZrhmLwGXU5tlg== 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 , "Martin K. Petersen" , Bart Van Assche Subject: [PATCH v3 4/8] docs: sysfs-block: fill in missing documentation from queue-sysfs.rst Date: Wed, 8 Dec 2021 16:38:29 -0800 Message-Id: <20211209003833.6396-5-ebiggers@kernel.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20211209003833.6396-1-ebiggers@kernel.org> References: <20211209003833.6396-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 Reviewed-by: Martin K. Petersen Reviewed-by: Bart Van Assche 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 Thu Dec 9 00:38:30 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eric Biggers X-Patchwork-Id: 12665589 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 1189AC433F5 for ; Thu, 9 Dec 2021 00:40:12 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S241519AbhLIAnj (ORCPT ); Wed, 8 Dec 2021 19:43:39 -0500 Received: from sin.source.kernel.org ([145.40.73.55]:49330 "EHLO sin.source.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232361AbhLIAng (ORCPT ); Wed, 8 Dec 2021 19:43:36 -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 38252CE241A; Thu, 9 Dec 2021 00:40:02 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 3BD68C341CD; Thu, 9 Dec 2021 00:40:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1639010400; bh=lN6irFSPdhVHSZbXhcFEryQ2TyUCysymqpfoNti6hp0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=RVyL+3ACtIVF1qBcKVueuHMLbaRMi+taZDSnzOO/y0mW/w8y/87ndad7KL0U0/ETi 8amArDqT8t3X5VaYaJTEvFfzCQiE9lhc0DUtlKbghCCfySmGvJPv7gYUD1NsuManNZ D0obQDABtwv5GAkx0H9/X0JxAiOmzABIchqwI4q2YN7XN8tKMIEuZqvyODeaCFyHHD Ruy02vxoKEvsyaiyAD0UeWWGJQYVLYr5aYAgDWToXw3U8/NNH3eXyJ4mHJxQhfx1dY l9+N84C1kBp4FjZEkQTSr3WAD5YQfQTKC1/OHb00S9rhjj0u479bNuhinV+qOB6F5j hELnrmK+A2H0Q== 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, Bart Van Assche Subject: [PATCH v3 5/8] docs: sysfs-block: document stable_writes Date: Wed, 8 Dec 2021 16:38:30 -0800 Message-Id: <20211209003833.6396-6-ebiggers@kernel.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20211209003833.6396-1-ebiggers@kernel.org> References: <20211209003833.6396-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: Bart Van Assche Signed-off-by: Eric Biggers --- Documentation/ABI/stable/sysfs-block | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/Documentation/ABI/stable/sysfs-block b/Documentation/ABI/stable/sysfs-block index de3b86a3dfa55..288626e8cb532 100644 --- a/Documentation/ABI/stable/sysfs-block +++ b/Documentation/ABI/stable/sysfs-block @@ -516,6 +516,23 @@ 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] This file will contain '1' if memory must not be modified + while it is being used in a write request to this device. When + this is the case and the kernel is performing writeback of a + page, the kernel will wait for writeback to complete before + allowing the page to be modified again, rather than allowing + immediate modification as is normally the case. This + restriction arises when the device accesses the memory multiple + times where the same data must be seen every time -- for + example, once to calculate a checksum and once to actually write + the data. If no such restriction exists, this file 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 Thu Dec 9 00:38:31 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eric Biggers X-Patchwork-Id: 12665593 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 EAC50C433EF for ; Thu, 9 Dec 2021 00:40:13 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S241534AbhLIAnl (ORCPT ); Wed, 8 Dec 2021 19:43:41 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:41344 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S241498AbhLIAnf (ORCPT ); Wed, 8 Dec 2021 19:43:35 -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 34F79C061746; Wed, 8 Dec 2021 16:40:03 -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 EB95BB82333; Thu, 9 Dec 2021 00:40:01 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 92052C00446; Thu, 9 Dec 2021 00:40:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1639010400; bh=b3K9Nj6GMD0TSZap+1QDuzGQ5JETQw0RNVbhy2D9m/c=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=qvthDnOufOhVNsnsM1t0Jj/bU6ufK6qWJ2ycAgEsXnJd8awMRpRLjN26Z/xbGhMoe QZBbVeDnuwvLrYdT2CgekZ6kcKvBYlkFb0h2EVMyF5TZIT85LbPiA4q9N1FvDWWuSX YkKUrkJzIawhvOxmMQl+gkXVW0ICRXgCyV1aNUS+kSGBdAWXAkgl/uKPwLNLQZXTdS EJ4mTf+9yKrmAjmv3obvap0+Qz6Gopr0YnVKcIbYmMBVQIjNUPoCn/Nmsm37LJkqVT nucZS5HhaKZcmM7QXhyv+BTE5VA9yRf61geUYDhTbf8Hp5NT9xJk+oT36uYmFhDsE8 4puhMg4vXZ98Q== 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, Bart Van Assche Subject: [PATCH v3 6/8] docs: sysfs-block: document virt_boundary_mask Date: Wed, 8 Dec 2021 16:38:31 -0800 Message-Id: <20211209003833.6396-7-ebiggers@kernel.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20211209003833.6396-1-ebiggers@kernel.org> References: <20211209003833.6396-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: Bart Van Assche Signed-off-by: Eric Biggers --- Documentation/ABI/stable/sysfs-block | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/Documentation/ABI/stable/sysfs-block b/Documentation/ABI/stable/sysfs-block index 288626e8cb532..8dd3e84a8aade 100644 --- a/Documentation/ABI/stable/sysfs-block +++ b/Documentation/ABI/stable/sysfs-block @@ -544,6 +544,18 @@ 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 memory alignment mask for + the block device. I/O requests to this device will be split + between segments wherever either the memory address of the end + of the previous segment or the memory address of 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 Thu Dec 9 00:38:32 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eric Biggers X-Patchwork-Id: 12665587 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 BD46DC433FE for ; Thu, 9 Dec 2021 00:40:08 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S241504AbhLIAnh (ORCPT ); Wed, 8 Dec 2021 19:43:37 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:41354 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S241509AbhLIAng (ORCPT ); Wed, 8 Dec 2021 19:43:36 -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 E19E8C061746; Wed, 8 Dec 2021 16:40:03 -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 7B579B82331; Thu, 9 Dec 2021 00:40:02 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id E76E7C341CC; Thu, 9 Dec 2021 00:40:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1639010401; bh=6msyd9E2tZuoOJVZm8tJQBmYqQNK9fnfm8lZ8l8dg88=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=nr9478D7s8aAMSLjYMQQSh4ZGvPSIFPqDMJm8doG2QNRIrm815sQ8NIfOK/ChRXGO ihLDBz0UNT6yHv2TFHTDOf7Y5u2NfQFZZKFKAq8IFYFsFfv0BxQxndZ0+JbyAGTEsr AorzeNiLgE7sYu+j71es859k30pe9vNXhxcfFcUJtOYvtPmx5E8ZVvEoHD+iqdjR8L 2TckA30KMrJT6Zso6M/XC+xZZu9uOvbhlBz5SgGi2FrFJPnMLIv8RR/FHYOyhXB6la JvmOBZ3NLiqtx7u5QMGh4vX4xtyvtZD9jsrSRZAuWdezbrS4Qc5AYmlMFgMicZcyA6 UDn+cr8w7C+cg== 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 , "Martin K. Petersen" , Bart Van Assche Subject: [PATCH v3 7/8] docs: block: remove queue-sysfs.rst Date: Wed, 8 Dec 2021 16:38:32 -0800 Message-Id: <20211209003833.6396-8-ebiggers@kernel.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20211209003833.6396-1-ebiggers@kernel.org> References: <20211209003833.6396-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 Reviewed-by: Martin K. Petersen Reviewed-by: Bart Van Assche 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 Thu Dec 9 00:38: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: 12665591 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 4368AC433FE for ; Thu, 9 Dec 2021 00:40:12 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S241522AbhLIAnk (ORCPT ); Wed, 8 Dec 2021 19:43:40 -0500 Received: from ams.source.kernel.org ([145.40.68.75]:53640 "EHLO ams.source.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S241500AbhLIAnh (ORCPT ); Wed, 8 Dec 2021 19:43:37 -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 ams.source.kernel.org (Postfix) with ESMTPS id D74F6B82284; Thu, 9 Dec 2021 00:40:02 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 56C23C341C6; Thu, 9 Dec 2021 00:40:01 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1639010401; bh=UZR5o//IotWL4AvI7WNqFdHHhYJPi8ZNZjYRMgcahzs=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Ku8xohOzI9YJ4GJ1V9Mtu8ypiJDL6bVV30SBzNt60yAOicLutbwVcY29koDLSSspY p7+ddx71zagO0l63Nx/mF35AaR4NQ8r3wWel3xl70Ngc5kRw1/LRQoZjAGtECwzq2P GB2g5Plz8zBynkHzC2lcBKHgIX6F3miijbm3N13shuRKEevV4xN9bHIkad7jCJ09i6 2+4PEZkj6Io9C0PfRx8LgsQm28wwPD+3U9I8Yc93xBJUrAqjOgs9ZoYVimcQm37hBS NNC8P/tHjGR1HHiLHwyXf5vSOAYcPxF9IfCwR08OxmeT9YnC8cDaaIEPnVxwNvrrZO tro1NdPzLG5Ug== 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 , "Martin K. Petersen" , Bart Van Assche Subject: [PATCH v3 8/8] MAINTAINERS: add entries for block layer documentation Date: Wed, 8 Dec 2021 16:38:33 -0800 Message-Id: <20211209003833.6396-9-ebiggers@kernel.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20211209003833.6396-1-ebiggers@kernel.org> References: <20211209003833.6396-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 Reviewed-by: Martin K. Petersen Reviewed-by: Bart Van Assche 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*