summaryrefslogtreecommitdiffstats
path: root/Documentation/early-userspace/README
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/early-userspace/README')
-rw-r--r--Documentation/early-userspace/README152
1 files changed, 0 insertions, 152 deletions
diff --git a/Documentation/early-userspace/README b/Documentation/early-userspace/README
deleted file mode 100644
index e35d830..0000000
--- a/Documentation/early-userspace/README
+++ /dev/null
@@ -1,152 +0,0 @@
-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 --help' 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
-entire CONFIG_INITRAMFS_SOURCE is passed to
-scripts/gen_initramfs_list.sh. This means that CONFIG_INITRAMFS_SOURCE
-can really be interpreted as any legal argument to
-gen_initramfs_list.sh. If a directory is specified as an argument then
-the contents are scanned, uid/gid translation is performed, and
-usr/gen_init_cpio file directives are output. If a directory is
-specified as an arugemnt to scripts/gen_initramfs_list.sh then the
-contents of the file are simply copied to the output. All of the output
-directives from directory scanning and file contents copying are
-processed by usr/gen_init_cpio.
-
-See also 'scripts/gen_initramfs_list.sh -h'.
-
-Where's this all leading?
-=========================
-
-The klibc distribution contains some of the necessary software to make
-early userspace useful. The klibc distribution is currently
-maintained separately from the kernel, but this may change early in
-the 2.7 era (it missed the boat for 2.5).
-
-You can obtain somewhat infrequent snapshots of klibc from
-ftp://ftp.kernel.org/pub/linux/libs/klibc/
-
-For active users, you are better off using the klibc git
-repository, at http://git.kernel.org/?p=libs/klibc/klibc.git
-
-The standalone klibc distribution currently provides three components,
-in addition to the klibc library:
-
-- ipconfig, a program that configures network interfaces. It can
- configure them statically, or use DHCP to obtain information
- dynamically (aka "IP autoconfiguration").
-- nfsmount, a program that can mount an NFS filesystem.
-- kinit, the "glue" that uses ipconfig and nfsmount to replace the old
- support for IP autoconfig, mount a filesystem over NFS, and continue
- system boot using that filesystem as root.
-
-kinit is built as a single statically linked binary to save space.
-
-Eventually, several more chunks of kernel functionality will hopefully
-move to early userspace:
-
-- Almost all of init/do_mounts* (the beginning of this is already in
- place)
-- ACPI table parsing
-- Insert unwieldy subsystem that doesn't really need to be in kernel
- space here
-
-If kinit doesn't meet your current needs and you've got bytes to burn,
-the klibc distribution includes a small Bourne-compatible shell (ash)
-and a number of other utilities, so you can replace kinit and build
-custom initramfs images that meet your needs exactly.
-
-For questions and help, you can sign up for the early userspace
-mailing list at http://www.zytor.com/mailman/listinfo/klibc
-
-How does it work?
-=================
-
-The kernel has currently 3 ways to mount the root filesystem:
-
-a) all required device and filesystem drivers compiled into the kernel, no
- initrd. init/main.c:init() will call prepare_namespace() to mount the
- final root filesystem, based on the root= option and optional init= to run
- some other init binary than listed at the end of init/main.c:init().
-
-b) some device and filesystem drivers built as modules and stored in an
- initrd. The initrd must contain a binary '/linuxrc' which is supposed to
- load these driver modules. It is also possible to mount the final root
- filesystem via linuxrc and use the pivot_root syscall. The initrd is
- mounted and executed via prepare_namespace().
-
-c) using initramfs. The call to prepare_namespace() must be skipped.
- This means that a binary must do all the work. Said binary can be stored
- into initramfs either via modifying usr/gen_init_cpio.c or via the new
- initrd format, an cpio archive. It must be called "/init". This binary
- is responsible to do all the things prepare_namespace() would do.
-
- To maintain backwards compatibility, the /init binary will only run if it
- comes via an initramfs cpio archive. If this is not the case,
- init/main.c:init() will run prepare_namespace() to mount the final root
- and exec one of the predefined init binaries.
-
-Bryan O'Sullivan <bos@serpentine.com>