docs: initramfs: file data alignment via name padding

The existing cpio extraction logic reads (maximum PATH_MAX) name_len
bytes from the archive into the collected name buffer and ensures that
the trailing byte is a null-terminator. This allows the actual file name
to be shorter than name_len, with the name string simply zero-terminated
prior to the last byte.

Initramfs generators, such as dracut-cpio[1], can take advantage of name
zero-padding to align file data segments within the archive to
filesystem block boundaries. Block boundary alignment may allow the
copy_file_range syscall to reflink archive source and destination
extents.

Link: https://github.com/dracutdevs/dracut/commit/300e4b116c624bca1b9e7251708b1ae656fe9157
Signed-off-by: David Disseldorp <ddiss@suse.de>
Reviewed-by: Nicolas Schier <nsc@kernel.org>
Link: https://lore.kernel.org/r/20250819032607.28727-7-ddiss@suse.de
Signed-off-by: Nathan Chancellor <nathan@kernel.org>

diff --git a/Documentation/driver-api/early-userspace/buffer-format.rst b/Documentation/driver-api/early-userspace/buffer-format.rst
index 726bfa2fe70dad4cf3149361f27b7e4579573821..4597a91100b7bd7f40ef37477e6337531fbaa019 100644 (file)
--- a/Documentation/driver-api/early-userspace/buffer-format.rst
+++ b/Documentation/driver-api/early-userspace/buffer-format.rst
@@ -86,6 +86,11 @@ c_mtime is ignored unless CONFIG_INITRAMFS_PRESERVE_MTIME=y is set.
 The c_filesize should be zero for any file which is not a regular file
 or symlink.
 
+c_namesize may account for more than one trailing '\0', as long as the
+value doesn't exceed PATH_MAX.  This can be useful for ensuring that a
+subsequent file data segment is aligned, e.g. to a filesystem block
+boundary.
+
 The c_chksum field contains a simple 32-bit unsigned sum of all the
 bytes in the data field.  cpio(1) refers to this as "crc", which is
 clearly incorrect (a cyclic redundancy check is a different and