"Darrick J. Wong" <djwong@xxxxxxxxxx> writes: > On Thu, May 15, 2025 at 08:15:39PM +0530, Ritesh Harjani (IBM) wrote: >> Add an initial documentation around atomic writes support in ext4. >> >> Signed-off-by: Ritesh Harjani (IBM) <ritesh.list@xxxxxxxxx> >> --- >> .../filesystems/ext4/atomic_writes.rst | 220 ++++++++++++++++++ >> Documentation/filesystems/ext4/overview.rst | 1 + >> 2 files changed, 221 insertions(+) >> create mode 100644 Documentation/filesystems/ext4/atomic_writes.rst >> >> diff --git a/Documentation/filesystems/ext4/atomic_writes.rst b/Documentation/filesystems/ext4/atomic_writes.rst >> new file mode 100644 >> index 000000000000..de54eeb6aaae >> --- /dev/null >> +++ b/Documentation/filesystems/ext4/atomic_writes.rst >> @@ -0,0 +1,220 @@ >> +.. SPDX-License-Identifier: GPL-2.0 >> +.. _atomic_writes: >> + >> +Atomic Block Writes >> +------------------------- >> + >> +Introduction >> +~~~~~~~~~~~~ >> + >> +Atomic (untorn) block writes ensure that either the entire write is committed >> +to disk or none of it is. This prevents "torn writes" during power loss or >> +system crashes. The ext4 filesystem supports atomic writes (only with Direct >> +I/O) on regular files with extents, provided the underlying storage device >> +supports hardware atomic writes. This is supported in the following two ways: >> + >> +1. **Single-fsblock Atomic Writes**: >> + EXT4's supports atomic write operations with a single filesystem block since >> + v6.13. In this the atomic write unit minimum and maximum sizes are both set >> + to filesystem blocksize. >> + e.g. doing atomic write of 16KB with 16KB filesystem blocksize on 64KB >> + pagesize system is possible. >> + >> +2. **Multi-fsblock Atomic Writes with Bigalloc**: >> + EXT4 now also supports atomic writes spanning multiple filesystem blocks >> + using a feature known as bigalloc. The atomic write unit's minimum and >> + maximum sizes are determined by the filesystem block size and cluster size, >> + based on the underlying device’s supported atomic write unit limits. >> + >> +Requirements >> +~~~~~~~~~~~~ >> + >> +Basic requirements for atomic writes in ext4: >> + >> + 1. The extents feature must be enabled (default for ext4) >> + 2. The underlying block device must support atomic writes >> + 3. For single-fsblock atomic writes: >> + >> + 1. A filesystem with appropriate block size (up to the page size) >> + 4. For multi-fsblock atomic writes: >> + >> + 1. The bigalloc feature must be enabled >> + 2. The cluster size must be appropriately configured >> + >> +NOTE: EXT4 does not support software or COW based atomic write, which means >> +atomic writes on ext4 are only supported if underlying storage device supports >> +it. >> + >> +Multi-fsblock Implementation Details >> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ >> + >> +The bigalloc feature changes ext4 to allocate in units of multiple filesystem >> +blocks, also known as clusters. With bigalloc each bit within block bitmap >> +represents cluster (power of 2 number of blocks) rather than individual > > Nit: "...represents one cluster" yup, will make that change. > > With that fixed, > Acked-by: "Darrick J. Wong" <djwong@xxxxxxxxxx> > Thanks! -ritesh > --D >
