Documentation/driver-api/early-userspace/buffer-format.rst

Source file repositories/reference/linux-study-clean/Documentation/driver-api/early-userspace/buffer-format.rst

File Facts

System
Linux kernel
Corpus path
Documentation/driver-api/early-userspace/buffer-format.rst
Extension
.rst
Size
5543 bytes
Lines
133
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

=======================
initramfs buffer format
=======================

Al Viro, H. Peter Anvin

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 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), 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::

	*	is used to indicate "0 or more occurrences of"
	(|)	indicates alternatives
	+	indicates concatenation
	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_compressed_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)

	cpio_file := ALGN(4) + cpio_header + filename + "\0" + ALGN(4) + data

	cpio_trailer := ALGN(4) + cpio_header + "TRAILER!!!\0" + ALGN(4)


In human terms, the initramfs buffer contains a collection of
compressed and/or uncompressed cpio archives (in the "newc" or "crc"
formats); arbitrary amounts zero bytes (for padding) can be added
between members.

The cpio "TRAILER!!!" entry (cpio end-of-archive) is optional, but is
not ignored; see "handling of hard links" below.

The structure of the cpio_header is as follows (all fields contain
hexadecimal ASCII numbers fully padded with '0' on the left to the
full width of the field, for example, the integer 4780 is represented
by the ASCII string "000012ac"):

============= ================== ==============================================
Field name    Field size	 Meaning
============= ================== ==============================================
c_magic	      6 bytes		 The string "070701" or "070702"
c_ino	      8 bytes		 File inode number
c_mode	      8 bytes		 File mode and permissions
c_uid	      8 bytes		 File uid
c_gid	      8 bytes		 File gid
c_nlink	      8 bytes		 Number of links
c_mtime	      8 bytes		 Modification time

Annotation

Implementation Notes