[PATCH v5 0/3] man2: Document RWF_ATOMIC

[PATCH v5 0/3] man2: Document RWF_ATOMIC

[John Garry]

Document RWF_ATOMIC flag for pwritev2().

RWF_ATOMIC is used for enabling torn-write protection.

We use RWF_ATOMIC as this is legacy name for similar feature proposed in
the past.

Kernel support has now been merged into Linus' tree, to be released in
v6.11

Differences to v4:
- Add RB tags from Darrick (thanks)
- Revise description for readv.2 (Darrick)
- Re-order RWF_ATOMIC in readv.2

Differences to v3:
- Formatting changes (Alex)
 - semantic newlines
 - Add missing .TP in statx
 - Combine description of atomic write unit min and max
 - misc others

Himanshu Madhani (2):
  statx.2: Document STATX_WRITE_ATOMIC
  readv.2: Document RWF_ATOMIC flag

John Garry (1):
  io_submit.2: Document RWF_ATOMIC

 man/man2/io_submit.2 | 19 ++++++++++++++
 man/man2/readv.2     | 61 ++++++++++++++++++++++++++++++++++++++++++++
 man/man2/statx.2     | 27 ++++++++++++++++++++
 3 files changed, 107 insertions(+)

-- 
2.31.1

[PATCH v5 1/3] statx.2: Document STATX_WRITE_ATOMIC

[John Garry]

From: Himanshu Madhani <himanshu.madhani@oracle.com>

Add the text to the statx man page.

Signed-off-by: Himanshu Madhani <himanshu.madhani@oracle.com>
Reviewed-by: "Darrick J. Wong" <djwong@kernel.org>
Signed-off-by: John Garry <john.g.garry@oracle.com>
---
 man/man2/statx.2 | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/man/man2/statx.2 b/man/man2/statx.2
index 3d47319c6..a7cdc0097 100644
--- a/man/man2/statx.2
+++ b/man/man2/statx.2
@@ -70,6 +70,11 @@ struct statx {
     __u32 stx_dio_offset_align;
 \&
     __u64 stx_subvol;      /* Subvolume identifier */
+\&
+    /* Direct I/O atomic write limits */
+    __u32 stx_atomic_write_unit_min;
+    __u32 stx_atomic_write_unit_max;
+    __u32 stx_atomic_write_segments_max;
 };
 .EE
 .in
@@ -259,6 +264,9 @@ STATX_DIOALIGN	Want stx_dio_mem_align and stx_dio_offset_align
 STATX_MNT_ID_UNIQUE	Want unique stx_mnt_id (since Linux 6.8)
 STATX_SUBVOL	Want stx_subvol
 	(since Linux 6.10; support varies by filesystem)
+STATX_WRITE_ATOMIC	Want stx_atomic_write_unit_min, stx_atomic_write_unit_max,
+	and stx_atomic_write_segments_max.
+	(since Linux 6.11; support varies by filesystem)
 .TE
 .in
 .P
@@ -463,6 +471,22 @@ Subvolumes are fancy directories,
 i.e. they form a tree structure that may be walked recursively.
 Support varies by filesystem;
 it is supported by bcachefs and btrfs since Linux 6.10.
+.TP
+.I stx_atomic_write_unit_min
+.TQ
+.I stx_atomic_write_unit_max
+The minimum and maximum sizes (in bytes) supported for direct I/O
+.RB ( O_DIRECT )
+on the file to be written with torn-write protection.
+These values are each guaranteed to be a power-of-2.
+.TP
+.I stx_atomic_write_segments_max
+The maximum number of elements in an array of vectors for a write with
+torn-write protection enabled.
+See
+.BR RWF_ATOMIC
+flag for
+.BR pwritev2 (2).
 .P
 For further information on the above fields, see
 .BR inode (7).
@@ -516,6 +540,9 @@ It cannot be written to, and all reads from it will be verified
 against a cryptographic hash that covers the
 entire file (e.g., via a Merkle tree).
 .TP
+.BR STATX_ATTR_WRITE_ATOMIC " (since Linux 6.11)"
+The file supports torn-write protection.
+.TP
 .BR STATX_ATTR_DAX " (since Linux 5.8)"
 The file is in the DAX (cpu direct access) state.
 DAX state attempts to
-- 
2.31.1

[PATCH v5 2/3] readv.2: Document RWF_ATOMIC flag

[John Garry]

From: Himanshu Madhani <himanshu.madhani@oracle.com>

Add RWF_ATOMIC flag description for pwritev2().

Signed-off-by: Himanshu Madhani <himanshu.madhani@oracle.com>
[jpg: complete rewrite]
Signed-off-by: John Garry <john.g.garry@oracle.com>
---
 man/man2/readv.2 | 61 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/man/man2/readv.2 b/man/man2/readv.2
index eecde06dc..7737eb65c 100644
--- a/man/man2/readv.2
+++ b/man/man2/readv.2
@@ -237,6 +237,50 @@ the data is always appended to the end of the file.
 However, if the
 .I offset
 argument is \-1, the current file offset is updated.
+.TP
+.BR RWF_ATOMIC " (since Linux 6.11)"
+Requires that writes to regular files in block-based filesystems be issued with
+torn-write protection.
+Torn-write protection means that for a power or any other hardware failure,
+all or none of the data from the write will be stored,
+but never a mix of old and new data.
+This flag is meaningful only for
+.BR pwritev2 (),
+and its effect applies only to the data range written by the system call.
+The total write length must be power-of-2 and must be sized in the range
+.RI [ stx_atomic_write_unit_min ,
+.IR stx_atomic_write_unit_max ].
+The write must be at a naturally-aligned offset within the file with respect to
+the total write length.
+For example,
+a write of length 32KiB at a file offset of 32KiB is permitted,
+however a write of length 32KiB at a file offset of 48KiB is not permitted.
+The upper limit of
+.I iovcnt
+for
+.BR pwritev2 ()
+is given by the value in
+.I stx_atomic_write_segments_max.
+Torn-write protection only works with
+.B O_DIRECT
+flag,
+i.e. buffered writes are not supported.
+To guarantee consistency from the write between a file's in-core state with the
+storage device,
+.B O_SYNC
+or
+.B O_DSYNC
+must be specified for
+.BR open (2).
+The same synchronized I/O guarantees as described in
+.BR open (2)
+are provided when these flags or their equivalent flags and system calls are
+used (e.g.
+if
+.BR RWF_SYNC
+is specified for
+.BR pwritev2 ()
+).
 .SH RETURN VALUE
 On success,
 .BR readv (),
@@ -280,9 +324,26 @@ values overflows an
 value.
 .TP
 .B EINVAL
+If
+.BR RWF_ATOMIC
+is specified,
+the combination of the sum of the
+.I iov_len
+values and the
+.I offset
+value does not comply with the length and offset torn-write protection rules.
+.TP
+.B EINVAL
 The vector count,
 .IR iovcnt ,
 is less than zero or greater than the permitted maximum.
+If
+.BR RWF_ATOMIC
+is specified,
+this maximum is given by the
+.I stx_atomic_write_segments_max
+value from
+.I statx.
 .TP
 .B EOPNOTSUPP
 An unknown flag is specified in \fIflags\fP.
-- 
2.31.1

[PATCH v5 3/3] io_submit.2: Document RWF_ATOMIC

[John Garry]

Document RWF_ATOMIC for asynchronous I/O.

Reviewed-by: "Darrick J. Wong" <djwong@kernel.org>
Signed-off-by: John Garry <john.g.garry@oracle.com>
---
 man/man2/io_submit.2 | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/man/man2/io_submit.2 b/man/man2/io_submit.2
index c53ae9aaf..12b4a72d7 100644
--- a/man/man2/io_submit.2
+++ b/man/man2/io_submit.2
@@ -140,6 +140,25 @@ as well the description of
 .B O_SYNC
 in
 .BR open (2).
+.TP
+.BR RWF_ATOMIC " (since Linux 6.11)"
+Write a block of data such that a write will never be torn from power fail or
+similar.
+See the description of
+.B RWF_ATOMIC
+in
+.BR pwritev2 (2).
+For usage with
+.BR IOCB_CMD_PWRITEV,
+the upper vector limit is in
+.I stx_atomic_write_segments_max.
+See
+.B STATX_WRITE_ATOMIC
+and
+.I stx_atomic_write_segments_max
+description
+in
+.BR statx (2).
 .RE
 .TP
 .I aio_lio_opcode
-- 
2.31.1

Re: [PATCH v5 2/3] readv.2: Document RWF_ATOMIC flag

[Darrick J. Wong]

On Mon, Jul 22, 2024 at 09:57:22AM +0000, John Garry wrote:
> From: Himanshu Madhani <himanshu.madhani@oracle.com>
> 
> Add RWF_ATOMIC flag description for pwritev2().
> 
> Signed-off-by: Himanshu Madhani <himanshu.madhani@oracle.com>
> [jpg: complete rewrite]
> Signed-off-by: John Garry <john.g.garry@oracle.com>

Sounds good to me now!  Thanks for taking care of the documentation!
Reviewed-by: Darrick J. Wong <djwong@kernel.org>

--D

> ---
>  man/man2/readv.2 | 61 ++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 61 insertions(+)
> 
> diff --git a/man/man2/readv.2 b/man/man2/readv.2
> index eecde06dc..7737eb65c 100644
> --- a/man/man2/readv.2
> +++ b/man/man2/readv.2
> @@ -237,6 +237,50 @@ the data is always appended to the end of the file.
>  However, if the
>  .I offset
>  argument is \-1, the current file offset is updated.
> +.TP
> +.BR RWF_ATOMIC " (since Linux 6.11)"
> +Requires that writes to regular files in block-based filesystems be issued with
> +torn-write protection.
> +Torn-write protection means that for a power or any other hardware failure,
> +all or none of the data from the write will be stored,
> +but never a mix of old and new data.
> +This flag is meaningful only for
> +.BR pwritev2 (),
> +and its effect applies only to the data range written by the system call.
> +The total write length must be power-of-2 and must be sized in the range
> +.RI [ stx_atomic_write_unit_min ,
> +.IR stx_atomic_write_unit_max ].
> +The write must be at a naturally-aligned offset within the file with respect to
> +the total write length.
> +For example,
> +a write of length 32KiB at a file offset of 32KiB is permitted,
> +however a write of length 32KiB at a file offset of 48KiB is not permitted.
> +The upper limit of
> +.I iovcnt
> +for
> +.BR pwritev2 ()
> +is given by the value in
> +.I stx_atomic_write_segments_max.
> +Torn-write protection only works with
> +.B O_DIRECT
> +flag,
> +i.e. buffered writes are not supported.
> +To guarantee consistency from the write between a file's in-core state with the
> +storage device,
> +.B O_SYNC
> +or
> +.B O_DSYNC
> +must be specified for
> +.BR open (2).
> +The same synchronized I/O guarantees as described in
> +.BR open (2)
> +are provided when these flags or their equivalent flags and system calls are
> +used (e.g.
> +if
> +.BR RWF_SYNC
> +is specified for
> +.BR pwritev2 ()
> +).
>  .SH RETURN VALUE
>  On success,
>  .BR readv (),
> @@ -280,9 +324,26 @@ values overflows an
>  value.
>  .TP
>  .B EINVAL
> +If
> +.BR RWF_ATOMIC
> +is specified,
> +the combination of the sum of the
> +.I iov_len
> +values and the
> +.I offset
> +value does not comply with the length and offset torn-write protection rules.
> +.TP
> +.B EINVAL
>  The vector count,
>  .IR iovcnt ,
>  is less than zero or greater than the permitted maximum.
> +If
> +.BR RWF_ATOMIC
> +is specified,
> +this maximum is given by the
> +.I stx_atomic_write_segments_max
> +value from
> +.I statx.
>  .TP
>  .B EOPNOTSUPP
>  An unknown flag is specified in \fIflags\fP.
> -- 
> 2.31.1
> 
> 

Re: [PATCH v5 0/3] man2: Document RWF_ATOMIC

[Alejandro Colomar]

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

Hi John, Darrick,

On Mon, Jul 22, 2024 at 09:57:20AM GMT, John Garry wrote:
> Document RWF_ATOMIC flag for pwritev2().
> 
> RWF_ATOMIC is used for enabling torn-write protection.
> 
> We use RWF_ATOMIC as this is legacy name for similar feature proposed in
> the past.
> 
> Kernel support has now been merged into Linus' tree, to be released in
> v6.11
> 
> Differences to v4:
> - Add RB tags from Darrick (thanks)
> - Revise description for readv.2 (Darrick)
> - Re-order RWF_ATOMIC in readv.2
> 
> Differences to v3:
> - Formatting changes (Alex)
>  - semantic newlines
>  - Add missing .TP in statx
>  - Combine description of atomic write unit min and max
>  - misc others
> 
> Himanshu Madhani (2):
>   statx.2: Document STATX_WRITE_ATOMIC
>   readv.2: Document RWF_ATOMIC flag
> 
> John Garry (1):
>   io_submit.2: Document RWF_ATOMIC

I've applied the 3 patches, with Darrick's RB extra tag, and some
formatting fixes from myself.  Thanks for the patches!

Have a lovely day!
Alex

> 
>  man/man2/io_submit.2 | 19 ++++++++++++++
>  man/man2/readv.2     | 61 ++++++++++++++++++++++++++++++++++++++++++++
>  man/man2/statx.2     | 27 ++++++++++++++++++++
>  3 files changed, 107 insertions(+)
> 
> -- 
> 2.31.1
> 

-- 
<https://www.alejandro-colomar.es/>

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