usr (initramfs generator)

Purpose

usr/ builds the initial root file system that gets embedded into the kernel image (or built as a separate initramfs). At boot time the cpio archive built here is unpacked by init/initramfs.c and becomes /.

This is the rootfs that init/main.c's kernel_init finds when it tries to exec PID 1.

Directory layout

usr/
├── Kconfig
├── Makefile
├── default_cpio_list
├── gen_init_cpio.c        # Tool that builds a cpio archive from a description file
├── gen_initramfs.sh       # Driver script: read a list, produce a cpio archive
└── include/

How it works

The build flow:

1. Kbuild reads CONFIG_INITRAMFS_SOURCE from .config. This points at either a directory or a description file (the cpio "list" format).
2. usr/gen_initramfs.sh invokes usr/gen_init_cpio to produce a cpio archive.
3. Optional compression is applied (gzip, xz, lzo, lz4, zstd).
4. The archive is wrapped in object code (initramfs_data.S) and linked into vmlinux.
5. At boot, init/initramfs.c (specifically populate_rootfs) decodes it back into the rootfs.

A minimal description file looks like:

dir /dev 755 0 0
nod /dev/console 644 0 0 c 5 1
file /init init.sh 755 0 0

Built-in vs external initramfs

• Built-in: archive embedded into the kernel. Single self-contained kernel image. Good for embedded systems and rescue kernels.
• External: bootloader passes a separate initrd= to the kernel. Good for distros that don't want to rebuild the kernel for every initramfs change.

If both exist, the embedded one is unpacked first; the external one is unpacked over it.

Integration points

• init/: init/initramfs.c is the unpacker.
• scripts/: Kbuild wires the cpio generation into the kernel image.
• lib/: decompression libraries (zlib, lz4, zstd) are needed at unpack time.

Entry points for modification

• The cpio format itself rarely changes. Modifications are usually about build-system integration.
• For booting, consider using dracut or mkinitcpio etc. to produce a real initramfs and pointing CONFIG_INITRAMFS_SOURCE= at the resulting cpio.

Related pages

• Init — the boot-time consumer.
• Scripts — the build glue.