[PATCH v2] docs: initramfs: update compression and mtime descriptions

[PATCH v2] docs: initramfs: update compression and mtime descriptions

[David Disseldorp]

Update the document to reflect that initramfs didn't replace initrd
following kernel 2.5.x.
The initramfs buffer format now supports many compression types in
addition to gzip, so include them in the grammar section.
c_mtime use is dependent on CONFIG_INITRAMFS_PRESERVE_MTIME.

Signed-off-by: David Disseldorp <ddiss@suse.de>
---
Changes since v1 following feedback from Randy Dunlap:
- contents -> content
- format of the initramfs buffer format -> the initramfs buffer format

 .../early-userspace/buffer-format.rst         | 34 ++++++++++++-------
 1 file changed, 21 insertions(+), 13 deletions(-)

diff --git a/Documentation/driver-api/early-userspace/buffer-format.rst b/Documentation/driver-api/early-userspace/buffer-format.rst
index 7f74e301fdf35..726bfa2fe70da 100644
--- a/Documentation/driver-api/early-userspace/buffer-format.rst
+++ b/Documentation/driver-api/early-userspace/buffer-format.rst
@@ -4,20 +4,18 @@ initramfs buffer format
 
 Al Viro, H. Peter Anvin
 
-Last revision: 2002-01-13
-
-Starting with kernel 2.5.x, the old "initial ramdisk" protocol is
-getting {replaced/complemented} with the new "initial ramfs"
-(initramfs) protocol.  The initramfs contents is passed using the same
-memory buffer protocol used by the initrd protocol, but the contents
+With kernel 2.5.x, the old "initial ramdisk" protocol was complemented
+with an "initial ramfs" protocol.  The initramfs content is passed
+using the same memory buffer protocol used by initrd, but the content
 is different.  The initramfs buffer contains an archive which is
-expanded into a ramfs filesystem; this document details the format of
-the initramfs buffer format.
+expanded into a ramfs filesystem; this document details the initramfs
+buffer format.
 
 The initramfs buffer format is based around the "newc" or "crc" CPIO
 formats, and can be created with the cpio(1) utility.  The cpio
-archive can be compressed using gzip(1).  One valid version of an
-initramfs buffer is thus a single .cpio.gz file.
+archive can be compressed using gzip(1), or any other algorithm provided
+via CONFIG_DECOMPRESS_*.  One valid version of an initramfs buffer is
+thus a single .cpio.gz file.
 
 The full format of the initramfs buffer is defined by the following
 grammar, where::
@@ -25,12 +23,20 @@ grammar, where::
 	*	is used to indicate "0 or more occurrences of"
 	(|)	indicates alternatives
 	+	indicates concatenation
-	GZIP()	indicates the gzip(1) of the operand
+	GZIP()	indicates gzip compression of the operand
+	BZIP2()	indicates bzip2 compression of the operand
+	LZMA()	indicates lzma compression of the operand
+	XZ()	indicates xz compression of the operand
+	LZO()	indicates lzo compression of the operand
+	LZ4()	indicates lz4 compression of the operand
+	ZSTD()	indicates zstd compression of the operand
 	ALGN(n)	means padding with null bytes to an n-byte boundary
 
-	initramfs  := ("\0" | cpio_archive | cpio_gzip_archive)*
+	initramfs := ("\0" | cpio_archive | cpio_compressed_archive)*
 
-	cpio_gzip_archive := GZIP(cpio_archive)
+	cpio_compressed_archive := (GZIP(cpio_archive) | BZIP2(cpio_archive)
+		| LZMA(cpio_archive) | XZ(cpio_archive) | LZO(cpio_archive)
+		| LZ4(cpio_archive) | ZSTD(cpio_archive))
 
 	cpio_archive := cpio_file* + (<nothing> | cpio_trailer)
 
@@ -75,6 +81,8 @@ c_chksum      8 bytes		 Checksum of data field if c_magic is 070702;
 The c_mode field matches the contents of st_mode returned by stat(2)
 on Linux, and encodes the file type and file permissions.
 
+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.
 
-- 
2.43.0

Re: [PATCH v2] docs: initramfs: update compression and mtime descriptions

[Randy Dunlap]

On 4/1/25 8:39 PM, David Disseldorp wrote:
> Update the document to reflect that initramfs didn't replace initrd
> following kernel 2.5.x.
> The initramfs buffer format now supports many compression types in
> addition to gzip, so include them in the grammar section.
> c_mtime use is dependent on CONFIG_INITRAMFS_PRESERVE_MTIME.
> 
> Signed-off-by: David Disseldorp <ddiss@suse.de>

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.

> ---
> Changes since v1 following feedback from Randy Dunlap:
> - contents -> content
> - format of the initramfs buffer format -> the initramfs buffer format
> 
>  .../early-userspace/buffer-format.rst         | 34 ++++++++++++-------
>  1 file changed, 21 insertions(+), 13 deletions(-)
> 
> diff --git a/Documentation/driver-api/early-userspace/buffer-format.rst b/Documentation/driver-api/early-userspace/buffer-format.rst
> index 7f74e301fdf35..726bfa2fe70da 100644
> --- a/Documentation/driver-api/early-userspace/buffer-format.rst
> +++ b/Documentation/driver-api/early-userspace/buffer-format.rst
> @@ -4,20 +4,18 @@ initramfs buffer format
>  
>  Al Viro, H. Peter Anvin
>  
> -Last revision: 2002-01-13
> -
> -Starting with kernel 2.5.x, the old "initial ramdisk" protocol is
> -getting {replaced/complemented} with the new "initial ramfs"
> -(initramfs) protocol.  The initramfs contents is passed using the same
> -memory buffer protocol used by the initrd protocol, but the contents
> +With kernel 2.5.x, the old "initial ramdisk" protocol was complemented
> +with an "initial ramfs" protocol.  The initramfs content is passed
> +using the same memory buffer protocol used by initrd, but the content
>  is different.  The initramfs buffer contains an archive which is
> -expanded into a ramfs filesystem; this document details the format of
> -the initramfs buffer format.
> +expanded into a ramfs filesystem; this document details the initramfs
> +buffer format.
>  
>  The initramfs buffer format is based around the "newc" or "crc" CPIO
>  formats, and can be created with the cpio(1) utility.  The cpio
> -archive can be compressed using gzip(1).  One valid version of an
> -initramfs buffer is thus a single .cpio.gz file.
> +archive can be compressed using gzip(1), or any other algorithm provided
> +via CONFIG_DECOMPRESS_*.  One valid version of an initramfs buffer is
> +thus a single .cpio.gz file.
>  
>  The full format of the initramfs buffer is defined by the following
>  grammar, where::
> @@ -25,12 +23,20 @@ grammar, where::
>  	*	is used to indicate "0 or more occurrences of"
>  	(|)	indicates alternatives
>  	+	indicates concatenation
> -	GZIP()	indicates the gzip(1) of the operand
> +	GZIP()	indicates gzip compression of the operand
> +	BZIP2()	indicates bzip2 compression of the operand
> +	LZMA()	indicates lzma compression of the operand
> +	XZ()	indicates xz compression of the operand
> +	LZO()	indicates lzo compression of the operand
> +	LZ4()	indicates lz4 compression of the operand
> +	ZSTD()	indicates zstd compression of the operand
>  	ALGN(n)	means padding with null bytes to an n-byte boundary
>  
> -	initramfs  := ("\0" | cpio_archive | cpio_gzip_archive)*
> +	initramfs := ("\0" | cpio_archive | cpio_compressed_archive)*
>  
> -	cpio_gzip_archive := GZIP(cpio_archive)
> +	cpio_compressed_archive := (GZIP(cpio_archive) | BZIP2(cpio_archive)
> +		| LZMA(cpio_archive) | XZ(cpio_archive) | LZO(cpio_archive)
> +		| LZ4(cpio_archive) | ZSTD(cpio_archive))
>  
>  	cpio_archive := cpio_file* + (<nothing> | cpio_trailer)
>  
> @@ -75,6 +81,8 @@ c_chksum      8 bytes		 Checksum of data field if c_magic is 070702;
>  The c_mode field matches the contents of st_mode returned by stat(2)
>  on Linux, and encodes the file type and file permissions.
>  
> +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.
>  

-- 
~Randy

Re: [PATCH v2] docs: initramfs: update compression and mtime descriptions

[Christian Brauner]

On Wed, 02 Apr 2025 14:39:50 +1100, David Disseldorp wrote:
> Update the document to reflect that initramfs didn't replace initrd
> following kernel 2.5.x.
> The initramfs buffer format now supports many compression types in
> addition to gzip, so include them in the grammar section.
> c_mtime use is dependent on CONFIG_INITRAMFS_PRESERVE_MTIME.
> 
> 
> [...]

Applied to the vfs-6.16.misc branch of the vfs/vfs.git tree.
Patches in the vfs-6.16.misc branch should appear in linux-next soon.

Please report any outstanding bugs that were missed during review in a
new review to the original patch series allowing us to drop it.

It's encouraged to provide Acked-bys and Reviewed-bys even though the
patch has now been applied. If possible patch trailers will be updated.

Note that commit hashes shown below are subject to change due to rebase,
trailer updates or similar. If in doubt, please check the listed branch.

tree:   https://git.kernel.org/pub/scm/linux/kernel/git/vfs/vfs.git
branch: vfs-6.16.misc

[1/1] docs: initramfs: update compression and mtime descriptions
      https://git.kernel.org/vfs/vfs/c/25b64e0cf660