Documentation/driver-api/early-userspace/early_userspace_support.rst

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

File Facts

System
Linux kernel
Corpus path
Documentation/driver-api/early-userspace/early_userspace_support.rst
Extension
.rst
Size
6840 bytes
Lines
155
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

=======================
Early userspace support
=======================

Last update: 2004-12-20 tlh


"Early userspace" is a set of libraries and programs that provide
various pieces of functionality that are important enough to be
available while a Linux kernel is coming up, but that don't need to be
run inside the kernel itself.

It consists of several major infrastructure components:

- gen_init_cpio, a program that builds a cpio-format archive
  containing a root filesystem image.  This archive is compressed, and
  the compressed image is linked into the kernel image.
- initramfs, a chunk of code that unpacks the compressed cpio image
  midway through the kernel boot process.
- klibc, a userspace C library, currently packaged separately, that is
  optimized for correctness and small size.

The cpio file format used by initramfs is the "newc" (aka "cpio -H newc")
format, and is documented in the file "buffer-format.txt".  There are
two ways to add an early userspace image: specify an existing cpio
archive to be used as the image or have the kernel build process build
the image from specifications.

CPIO ARCHIVE method
-------------------

You can create a cpio archive that contains the early userspace image.
Your cpio archive should be specified in CONFIG_INITRAMFS_SOURCE and it
will be used directly.  Only a single cpio file may be specified in
CONFIG_INITRAMFS_SOURCE and directory and file names are not allowed in
combination with a cpio archive.

IMAGE BUILDING method
---------------------

The kernel build process can also build an early userspace image from
source parts rather than supplying a cpio archive.  This method provides
a way to create images with root-owned files even though the image was
built by an unprivileged user.

The image is specified as one or more sources in
CONFIG_INITRAMFS_SOURCE.  Sources can be either directories or files -
cpio archives are *not* allowed when building from sources.

A source directory will have it and all of its contents packaged.  The
specified directory name will be mapped to '/'.  When packaging a
directory, limited user and group ID translation can be performed.
INITRAMFS_ROOT_UID can be set to a user ID that needs to be mapped to
user root (0).  INITRAMFS_ROOT_GID can be set to a group ID that needs
to be mapped to group root (0).

A source file must be directives in the format required by the
usr/gen_init_cpio utility (run 'usr/gen_init_cpio -h' to get the
file format).  The directives in the file will be passed directly to
usr/gen_init_cpio.

When a combination of directories and files are specified then the
initramfs image will be an aggregate of all of them.  In this way a user
can create a 'root-image' directory and install all files into it.
Because device-special files cannot be created by a unprivileged user,
special files can be listed in a 'root-files' file.  Both 'root-image'
and 'root-files' can be listed in CONFIG_INITRAMFS_SOURCE and a complete
early userspace image can be built by an unprivileged user.

As a technical note, when directories and files are specified, the

Annotation

Implementation Notes