Re: [PATCH v5 7/7] ext4: Add atomic block write documentation

[John Garry <john.g.garry@oracle.com>]

On 15/05/2025 20:50, Ritesh Harjani (IBM) wrote:

thanks for adding this info

> Application Interface

Should we put this into a common file, as it is just not relevant to ext4?

Or move this file to a common location, and have separate sections for 
ext4 and xfs? This would save having scattered files for instructions.

> +~~~~~~~~~~~~~~~~~~~~~
> +
> +Applications can use the ``pwritev2()`` system call with the ``RWF_ATOMIC`` flag
> +to perform atomic writes:
> +
> +.. code-block:: c
> +
> +    pwritev2(fd, iov, iovcnt, offset, RWF_ATOMIC);
> +
> +The write must be aligned to the filesystem's block size and not exceed the
> +filesystem's maximum atomic write unit size.
> +See ``generic_atomic_write_valid()`` for more details.
> +
> +``statx()`` system call with ``STATX_WRITE_ATOMIC`` flag can provides following
> +details:
> +
> + * ``stx_atomic_write_unit_min``: Minimum size of an atomic write request.
> + * ``stx_atomic_write_unit_max``: Maximum size of an atomic write request.
> + * ``stx_atomic_write_segments_max``: Upper limit for segments. The number of
> +   separate memory buffers that can be gathered into a write operation

there will also be stx_atomic_write_unit_max_opt, as queued for 6.16

For HW-only support, I think that it is ok to just return same as 
stx_atomic_write_unit_max when we can atomic write > 1 filesystem block

> +   (e.g., the iovcnt parameter for IOV_ITER).


> Currently, this is always set to one.

JFYI, for xfs supporting filesystem-based atomic writes only, i.e. no HW 
support, we could set this to a higher value

> +
> +The STATX_ATTR_WRITE_ATOMIC flag in ``statx->attributes`` is set if atomic
> +writes are supported.
> +
> +.. _atomic_write_bdev_support:
> +
> +Hardware Support
> +----------------
> +
> +The underlying storage device must support atomic write operations.
> +Modern NVMe and SCSI devices often provide this capability.
> +The Linux kernel exposes this information through sysfs:
> +
> +* ``/sys/block/<device>/queue/atomic_write_unit_min`` - Minimum atomic write size
> +* ``/sys/block/<device>/queue/atomic_write_unit_max`` - Maximum atomic write size

there is also the max bytes and boundary files. I am not sure if it was 
intentional to omit them.

> +
> +Nonzero values for these attributes indicate that the device supports
> +atomic writes.
> +
> +See Also

thanks,
John