Linux-2.6.12-rc2
Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip!
This commit is contained in:
Linus Torvalds
152
Documentation/early-userspace/README
Normal file
152
Documentation/early-userspace/README
Normal file
@@ -0,0 +1,152 @@
|
||||
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 -c")
|
||||
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.
|
||||
Youre 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 it's 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 BitKeeper
|
||||
repositories, at http://klibc.bkbits.net/
|
||||
|
||||
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 remain 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>
|
||||
112
Documentation/early-userspace/buffer-format.txt
Normal file
112
Documentation/early-userspace/buffer-format.txt
Normal file
@@ -0,0 +1,112 @@
|
||||
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.
|
||||
Reference in New Issue
Block a user