Re: [PATCH 25/25] Documentation: sysfs-block-device: document command duration limits

[Bagas Sanjaya <bagasdotme@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 7721 bytes --]

On Thu, Dec 08, 2022 at 11:59:41AM +0100, Niklas Cassel wrote:
> +What:		/sys/block/*/device/duration_limits/enable
> +Date:		Dec, 2022
> +KernelVersion:	v6.3
> +Contact:	linux-scsi@vger.kernel.org
> +Description:
> +		(RW) For ATA and SCSI devices supporting the command duration
> +		limits feature, write to the file to turn on or off the
> +		feature. By default this feature is turned off. If the device
> +		does not support the command duration limits feature, this
> +		attribute does not exist (the directory
> +		"/sys/block/*/device/duration_limits" does not exist).
> +		Writing "1" to this file enables the use of command duration
> +		limits for read and write commands in the kernel and turns on
> +		the feature on the device. Writing "0" disables the feature.

Sphinx reported inline emphasis warning due to unescaped asterisk above:

Documentation/ABI/testing/sysfs-block-device:101: WARNING: Inline emphasis start-string without end-string.

I have applied the fixup:

---- >8 ----
diff --git a/Documentation/ABI/testing/sysfs-block-device b/Documentation/ABI/testing/sysfs-block-device
index 44841f91c69bfe..2cf806b638fbb3 100644
--- a/Documentation/ABI/testing/sysfs-block-device
+++ b/Documentation/ABI/testing/sysfs-block-device
@@ -107,7 +107,7 @@ Description:
 		feature. By default this feature is turned off. If the device
 		does not support the command duration limits feature, this
 		attribute does not exist (the directory
-		"/sys/block/*/device/duration_limits" does not exist).
+		"/sys/block/\*/device/duration_limits" does not exist).
 		Writing "1" to this file enables the use of command duration
 		limits for read and write commands in the kernel and turns on
 		the feature on the device. Writing "0" disables the feature.

> +
> +
> +What:		/sys/block/*/device/duration_limits/read/[1-7]/*
> +Date:		Dec, 2022
> +KernelVersion:	v6.3
> +Contact:	linux-scsi@vger.kernel.org
> +Description:
> +		(RO) For ATA and SCSI devices supporting the command duration
> +		limits feature, this shows the set of 7 command duration limits
> +		descriptors for read commands currently set on the device. For
> +		each of the 7 descritors, the following read-only attributes
> +		are present:
> +
> +		  - duration_guideline: specifies the preferred length of time
> +		    in microseconds for the completion of a command.
> +
> +		  - duration_guideline_policy: specifies the policy action
> +		    taken if the duration_guideline attribute specifies a
> +		    non-zero command duration guideline that the device is
> +		    unable to achieve for a command.
> +
> +		    Possible values are:
> +
> +		      - 0x0: The device will complete the command at the
> +			     earliest possible time consistent with the
> +			     specified command duration guideline.
> +		      - 0x1: If the specified command duration guideline has
> +			     not been achieved and the command duration
> +			     guideline policy field is not the seventh command
> +			     duration limits descriptor, then the device
> +			     continues processing that command using the
> +			     command duration limits descriptor that has
> +			     the next higher number.
> +		      - 0x2: The device will continue processing the command
> +			     as with no command duration limits descriptor
> +			     being used.
> +		      - 0xD: The device will complete the command and an IO
> +			     failure will be reported to the user with the ETIME
> +			     error code.
> +		      - 0xF: Same as 0xD.
> +
> <snipped>...
> +		    Possible values are:
> +
> +		      - 0x0: The device will complete the command at the
> +			     earliest possible time (i.e, do nothing based on
> +			     the max limit not being met).
> +		      - 0xD: The device will complete the command and an IO
> +			     failure will be reported to the user with the ETIME
> +			     error code.
> +		      - 0xE: Same as 0xD.
> +		      - 0xF: Same as 0xD.
> +
> <snipped>...
> +		    Possible values are:
> +
> +		      - 0x0: The device will complete the command at the
> +			     earliest possible time (i.e, do nothing based on
> +			     the time limit not being met).
> +		      - 0xD: The device will complete the command and an IO
> +			     failure will be reported to the user with the ETIME
> +			     error code.
> +		      - 0xF: Same as 0xD.
> +

The lists items above looks poorly indented in htmldocs (due to use of
proportional fonts). The fix is to align to first character after bullet
list marker, like:

---- >8 ----
diff --git a/Documentation/ABI/testing/sysfs-block-device b/Documentation/ABI/testing/sysfs-block-device
index 2cf806b638fbb3..79f67b975d57ac 100644
--- a/Documentation/ABI/testing/sysfs-block-device
+++ b/Documentation/ABI/testing/sysfs-block-device
@@ -135,21 +135,25 @@ Description:
 		    Possible values are:
 
 		      - 0x0: The device will complete the command at the
-			     earliest possible time consistent with the
-			     specified command duration guideline.
+			earliest possible time consistent with the
+			specified command duration guideline.
+
 		      - 0x1: If the specified command duration guideline has
-			     not been achieved and the command duration
-			     guideline policy field is not the seventh command
-			     duration limits descriptor, then the device
-			     continues processing that command using the
-			     command duration limits descriptor that has
-			     the next higher number.
+			not been achieved and the command duration
+			guideline policy field is not the seventh command
+			duration limits descriptor, then the device
+			continues processing that command using the
+			command duration limits descriptor that has
+			the next higher number.
+
 		      - 0x2: The device will continue processing the command
-			     as with no command duration limits descriptor
-			     being used.
+			as with no command duration limits descriptor
+			being used.
+
 		      - 0xD: The device will complete the command and an IO
-			     failure will be reported to the user with the ETIME
-			     error code.
+			failure will be reported to the user with the ETIME
+			error code.
+
 		      - 0xF: Same as 0xD.
 
 		  - max_active_time: specifies an upper limit in microseconds
@@ -165,12 +169,15 @@ Description:
 		    Possible values are:
 
 		      - 0x0: The device will complete the command at the
-			     earliest possible time (i.e, do nothing based on
-			     the max limit not being met).
+			earliest possible time (i.e, do nothing based on
+			the max limit not being met).
+
 		      - 0xD: The device will complete the command and an IO
-			     failure will be reported to the user with the ETIME
-			     error code.
+			failure will be reported to the user with the ETIME
+			error code.
+
 		      - 0xE: Same as 0xD.
+
 		      - 0xF: Same as 0xD.
 
 		  - max_inactive_time: specifies an upper limit in microseconds
@@ -185,11 +192,13 @@ Description:
 		    Possible values are:
 
 		      - 0x0: The device will complete the command at the
-			     earliest possible time (i.e, do nothing based on
-			     the time limit not being met).
+			earliest possible time (i.e, do nothing based on
+			the time limit not being met).
+
 		      - 0xD: The device will complete the command and an IO
-			     failure will be reported to the user with the ETIME
-			     error code.
+			failure will be reported to the user with the ETIME
+			error code.
+
 		      - 0xF: Same as 0xD.
 
 
Thanks.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]