[v2,5/8] docs: sysfs-block: document stable_writes

Commit Message

Eric Biggers Dec. 8, 2021, 12:56 a.m. UTC

From: Eric Biggers <[e-mail]>

/sys/block/<disk>/queue/stable_writes is completely undocumented.
Document it.

Reviewed-by: Greg Kroah-Hartman <[e-mail]>
Reviewed-by: Hannes Reinecke <[e-mail]>
Signed-off-by: Eric Biggers <[e-mail]>
---
 Documentation/ABI/stable/sysfs-block | 10 ++++++++++
 1 file changed, 10 insertions(+)

Comments

Bart Van Assche Dec. 8, 2021, 6:01 p.m. UTC | #1

On 12/7/21 4:56 PM, Eric Biggers wrote:
> +What:		/sys/block/<disk>/queue/stable_writes
> +Date:		September 2020
> +Contact:	[e-mail]
> +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.

Hmm ... doesn't this attribute apply to the process of transferring data from
host memory to the device instead of to writing to the disk? Whether data goes
to the storage device cache or to the storage medium itself depends on attributes
like FUA.

Thanks,

Bart.

Eric Biggers Dec. 8, 2021, 10:34 p.m. UTC | #2

On Wed, Dec 08, 2021 at 10:01:10AM -0800, Bart Van Assche wrote:
> On 12/7/21 4:56 PM, Eric Biggers wrote:
> > +What:		/sys/block/<disk>/queue/stable_writes
> > +Date:		September 2020
> > +Contact:	[e-mail]
> > +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.
> 
> Hmm ... doesn't this attribute apply to the process of transferring data from
> host memory to the device instead of to writing to the disk? Whether data goes
> to the storage device cache or to the storage medium itself depends on attributes
> like FUA.
> 

Yes, I meant "written out to disk" in the general sense of writeback, not in the
sense of when the data reaches its final destination.  I'm not sure what the
best way to explain it is.  I think it's more than just "the process of
transferring data from host memory to the device", as that is just part of a
write request, whereas stable_writes applies to whole requests.  How about:

		[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.

- Eric

Bart Van Assche Dec. 8, 2021, 10:59 p.m. UTC | #3

On 12/8/21 2:34 PM, Eric Biggers wrote:
> Yes, I meant "written out to disk" in the general sense of writeback, not in the
> sense of when the data reaches its final destination.  I'm not sure what the
> best way to explain it is.  I think it's more than just "the process of
> transferring data from host memory to the device", as that is just part of a
> write request, whereas stable_writes applies to whole requests.  How about:
> 
> 		[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.

The above sounds good to me.

Thanks,

Bart.

Patch

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/<disk>/queue/stable_writes
+Date:		September 2020
+Contact:	[e-mail]
+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/<disk>/queue/throttle_sample_time
 Date:		March 2017
 Contact:	[e-mail]