diff options
Diffstat (limited to 'Documentation/early-userspace')
| -rw-r--r-- | Documentation/early-userspace/README | 151 | ||||
| -rw-r--r-- | Documentation/early-userspace/buffer-format.txt | 112 |
2 files changed, 0 insertions, 263 deletions
diff --git a/Documentation/early-userspace/README b/Documentation/early-userspace/README deleted file mode 100644 index 955d667dc87e..000000000000 --- a/Documentation/early-userspace/README +++ /dev/null @@ -1,151 +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 -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 -entire CONFIG_INITRAMFS_SOURCE is passed to -usr/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 argument to usr/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 'usr/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. - -You can obtain somewhat infrequent snapshots of klibc from -https://www.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> diff --git a/Documentation/early-userspace/buffer-format.txt b/Documentation/early-userspace/buffer-format.txt deleted file mode 100644 index e1fd7f9dad16..000000000000 --- a/Documentation/early-userspace/buffer-format.txt +++ /dev/null @@ -1,112 +0,0 @@ - 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 -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. - -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. - -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 the gzip(1) of the operand - ALGN(n) means padding with null bytes to an n-byte boundary - - initramfs := ("\0" | cpio_archive | cpio_gzip_archive)* - - cpio_gzip_archive := GZIP(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 -c_filesize 8 bytes Size of data field -c_maj 8 bytes Major part of file device number -c_min 8 bytes Minor part of file device number -c_rmaj 8 bytes Major part of device node reference -c_rmin 8 bytes Minor part of device node reference -c_namesize 8 bytes Length of filename, including final \0 -c_chksum 8 bytes Checksum of data field if c_magic is 070702; - otherwise zero - -The c_mode field matches the contents of st_mode returned by stat(2) -on Linux, and encodes the file type and file permissions. - -The c_filesize should be zero for any file which is not a regular file -or symlink. - -The c_chksum field contains a simple 32-bit unsigned sum of all the -bytes in the data field. cpio(1) refers to this as "crc", which is -clearly incorrect (a cyclic redundancy check is a different and -significantly stronger integrity check), however, this is the -algorithm used. - -If the filename is "TRAILER!!!" this is actually an end-of-archive -marker; the c_filesize for an end-of-archive marker must be zero. - - -*** Handling of hard links - -When a nondirectory with c_nlink > 1 is seen, the (c_maj,c_min,c_ino) -tuple is looked up in a tuple buffer. If not found, it is entered in -the tuple buffer and the entry is created as usual; if found, a hard -link rather than a second copy of the file is created. It is not -necessary (but permitted) to include a second copy of the file -contents; if the file contents is not included, the c_filesize field -should be set to zero to indicate no data section follows. If data is -present, the previous instance of the file is overwritten; this allows -the data-carrying instance of a file to occur anywhere in the sequence -(GNU cpio is reported to attach the data to the last instance of a -file only.) - -c_filesize must not be zero for a symlink. - -When a "TRAILER!!!" end-of-archive marker is seen, the tuple buffer is -reset. This permits archives which are generated independently to be -concatenated. - -To combine file data from different sources (without having to -regenerate the (c_maj,c_min,c_ino) fields), therefore, either one of -the following techniques can be used: - -a) Separate the different file data sources with a "TRAILER!!!" - end-of-archive marker, or - -b) Make sure c_nlink == 1 for all nondirectory entries. |