linux/Documentation/filesystems/ramfs-rootfs-initramfs.txt
<<
>>
Prefs
   1ramfs, rootfs and initramfs
   2October 17, 2005
   3Rob Landley <rob@landley.net>
   4=============================
   5
   6What is ramfs?
   7--------------
   8
   9Ramfs is a very simple filesystem that exports Linux's disk caching
  10mechanisms (the page cache and dentry cache) as a dynamically resizable
  11RAM-based filesystem.
  12
  13Normally all files are cached in memory by Linux.  Pages of data read from
  14backing store (usually the block device the filesystem is mounted on) are kept
  15around in case it's needed again, but marked as clean (freeable) in case the
  16Virtual Memory system needs the memory for something else.  Similarly, data
  17written to files is marked clean as soon as it has been written to backing
  18store, but kept around for caching purposes until the VM reallocates the
  19memory.  A similar mechanism (the dentry cache) greatly speeds up access to
  20directories.
  21
  22With ramfs, there is no backing store.  Files written into ramfs allocate
  23dentries and page cache as usual, but there's nowhere to write them to.
  24This means the pages are never marked clean, so they can't be freed by the
  25VM when it's looking to recycle memory.
  26
  27The amount of code required to implement ramfs is tiny, because all the
  28work is done by the existing Linux caching infrastructure.  Basically,
  29you're mounting the disk cache as a filesystem.  Because of this, ramfs is not
  30an optional component removable via menuconfig, since there would be negligible
  31space savings.
  32
  33ramfs and ramdisk:
  34------------------
  35
  36The older "ram disk" mechanism created a synthetic block device out of
  37an area of RAM and used it as backing store for a filesystem.  This block
  38device was of fixed size, so the filesystem mounted on it was of fixed
  39size.  Using a ram disk also required unnecessarily copying memory from the
  40fake block device into the page cache (and copying changes back out), as well
  41as creating and destroying dentries.  Plus it needed a filesystem driver
  42(such as ext2) to format and interpret this data.
  43
  44Compared to ramfs, this wastes memory (and memory bus bandwidth), creates
  45unnecessary work for the CPU, and pollutes the CPU caches.  (There are tricks
  46to avoid this copying by playing with the page tables, but they're unpleasantly
  47complicated and turn out to be about as expensive as the copying anyway.)
  48More to the point, all the work ramfs is doing has to happen _anyway_,
  49since all file access goes through the page and dentry caches.  The RAM
  50disk is simply unnecessary; ramfs is internally much simpler.
  51
  52Another reason ramdisks are semi-obsolete is that the introduction of
  53loopback devices offered a more flexible and convenient way to create
  54synthetic block devices, now from files instead of from chunks of memory.
  55See losetup (8) for details.
  56
  57ramfs and tmpfs:
  58----------------
  59
  60One downside of ramfs is you can keep writing data into it until you fill
  61up all memory, and the VM can't free it because the VM thinks that files
  62should get written to backing store (rather than swap space), but ramfs hasn't
  63got any backing store.  Because of this, only root (or a trusted user) should
  64be allowed write access to a ramfs mount.
  65
  66A ramfs derivative called tmpfs was created to add size limits, and the ability
  67to write the data to swap space.  Normal users can be allowed write access to
  68tmpfs mounts.  See Documentation/filesystems/tmpfs.txt for more information.
  69
  70What is rootfs?
  71---------------
  72
  73Rootfs is a special instance of ramfs (or tmpfs, if that's enabled), which is
  74always present in 2.6 systems.  You can't unmount rootfs for approximately the
  75same reason you can't kill the init process; rather than having special code
  76to check for and handle an empty list, it's smaller and simpler for the kernel
  77to just make sure certain lists can't become empty.
  78
  79Most systems just mount another filesystem over rootfs and ignore it.  The
  80amount of space an empty instance of ramfs takes up is tiny.
  81
  82What is initramfs?
  83------------------
  84
  85All 2.6 Linux kernels contain a gzipped "cpio" format archive, which is
  86extracted into rootfs when the kernel boots up.  After extracting, the kernel
  87checks to see if rootfs contains a file "init", and if so it executes it as PID
  881.  If found, this init process is responsible for bringing the system the
  89rest of the way up, including locating and mounting the real root device (if
  90any).  If rootfs does not contain an init program after the embedded cpio
  91archive is extracted into it, the kernel will fall through to the older code
  92to locate and mount a root partition, then exec some variant of /sbin/init
  93out of that.
  94
  95All this differs from the old initrd in several ways:
  96
  97  - The old initrd was always a separate file, while the initramfs archive is
  98    linked into the linux kernel image.  (The directory linux-*/usr is devoted
  99    to generating this archive during the build.)
 100
 101  - The old initrd file was a gzipped filesystem image (in some file format,
 102    such as ext2, that needed a driver built into the kernel), while the new
 103    initramfs archive is a gzipped cpio archive (like tar only simpler,
 104    see cpio(1) and Documentation/early-userspace/buffer-format.txt).  The
 105    kernel's cpio extraction code is not only extremely small, it's also
 106    __init text and data that can be discarded during the boot process.
 107
 108  - The program run by the old initrd (which was called /initrd, not /init) did
 109    some setup and then returned to the kernel, while the init program from
 110    initramfs is not expected to return to the kernel.  (If /init needs to hand
 111    off control it can overmount / with a new root device and exec another init
 112    program.  See the switch_root utility, below.)
 113
 114  - When switching another root device, initrd would pivot_root and then
 115    umount the ramdisk.  But initramfs is rootfs: you can neither pivot_root
 116    rootfs, nor unmount it.  Instead delete everything out of rootfs to
 117    free up the space (find -xdev / -exec rm '{}' ';'), overmount rootfs
 118    with the new root (cd /newmount; mount --move . /; chroot .), attach
 119    stdin/stdout/stderr to the new /dev/console, and exec the new init.
 120
 121    Since this is a remarkably persnickety process (and involves deleting
 122    commands before you can run them), the klibc package introduced a helper
 123    program (utils/run_init.c) to do all this for you.  Most other packages
 124    (such as busybox) have named this command "switch_root".
 125
 126Populating initramfs:
 127---------------------
 128
 129The 2.6 kernel build process always creates a gzipped cpio format initramfs
 130archive and links it into the resulting kernel binary.  By default, this
 131archive is empty (consuming 134 bytes on x86).
 132
 133The config option CONFIG_INITRAMFS_SOURCE (in General Setup in menuconfig,
 134and living in usr/Kconfig) can be used to specify a source for the
 135initramfs archive, which will automatically be incorporated into the
 136resulting binary.  This option can point to an existing gzipped cpio
 137archive, a directory containing files to be archived, or a text file
 138specification such as the following example:
 139
 140  dir /dev 755 0 0
 141  nod /dev/console 644 0 0 c 5 1
 142  nod /dev/loop0 644 0 0 b 7 0
 143  dir /bin 755 1000 1000
 144  slink /bin/sh busybox 777 0 0
 145  file /bin/busybox initramfs/busybox 755 0 0
 146  dir /proc 755 0 0
 147  dir /sys 755 0 0
 148  dir /mnt 755 0 0
 149  file /init initramfs/init.sh 755 0 0
 150
 151Run "usr/gen_init_cpio" (after the kernel build) to get a usage message
 152documenting the above file format.
 153
 154One advantage of the configuration file is that root access is not required to
 155set permissions or create device nodes in the new archive.  (Note that those
 156two example "file" entries expect to find files named "init.sh" and "busybox" in
 157a directory called "initramfs", under the linux-2.6.* directory.  See
 158Documentation/early-userspace/README for more details.)
 159
 160The kernel does not depend on external cpio tools.  If you specify a
 161directory instead of a configuration file, the kernel's build infrastructure
 162creates a configuration file from that directory (usr/Makefile calls
 163scripts/gen_initramfs_list.sh), and proceeds to package up that directory
 164using the config file (by feeding it to usr/gen_init_cpio, which is created
 165from usr/gen_init_cpio.c).  The kernel's build-time cpio creation code is
 166entirely self-contained, and the kernel's boot-time extractor is also
 167(obviously) self-contained.
 168
 169The one thing you might need external cpio utilities installed for is creating
 170or extracting your own preprepared cpio files to feed to the kernel build
 171(instead of a config file or directory).
 172
 173The following command line can extract a cpio image (either by the above script
 174or by the kernel build) back into its component files:
 175
 176  cpio -i -d -H newc -F initramfs_data.cpio --no-absolute-filenames
 177
 178The following shell script can create a prebuilt cpio archive you can
 179use in place of the above config file:
 180
 181  #!/bin/sh
 182
 183  # Copyright 2006 Rob Landley <rob@landley.net> and TimeSys Corporation.
 184  # Licensed under GPL version 2
 185
 186  if [ $# -ne 2 ]
 187  then
 188    echo "usage: mkinitramfs directory imagename.cpio.gz"
 189    exit 1
 190  fi
 191
 192  if [ -d "$1" ]
 193  then
 194    echo "creating $2 from $1"
 195    (cd "$1"; find . | cpio -o -H newc | gzip) > "$2"
 196  else
 197    echo "First argument must be a directory"
 198    exit 1
 199  fi
 200
 201Note: The cpio man page contains some bad advice that will break your initramfs
 202archive if you follow it.  It says "A typical way to generate the list
 203of filenames is with the find command; you should give find the -depth option
 204to minimize problems with permissions on directories that are unwritable or not
 205searchable."  Don't do this when creating initramfs.cpio.gz images, it won't
 206work.  The Linux kernel cpio extractor won't create files in a directory that
 207doesn't exist, so the directory entries must go before the files that go in
 208those directories.  The above script gets them in the right order.
 209
 210External initramfs images:
 211--------------------------
 212
 213If the kernel has initrd support enabled, an external cpio.gz archive can also
 214be passed into a 2.6 kernel in place of an initrd.  In this case, the kernel
 215will autodetect the type (initramfs, not initrd) and extract the external cpio
 216archive into rootfs before trying to run /init.
 217
 218This has the memory efficiency advantages of initramfs (no ramdisk block
 219device) but the separate packaging of initrd (which is nice if you have
 220non-GPL code you'd like to run from initramfs, without conflating it with
 221the GPL licensed Linux kernel binary).
 222
 223It can also be used to supplement the kernel's built-in initramfs image.  The
 224files in the external archive will overwrite any conflicting files in
 225the built-in initramfs archive.  Some distributors also prefer to customize
 226a single kernel image with task-specific initramfs images, without recompiling.
 227
 228Contents of initramfs:
 229----------------------
 230
 231An initramfs archive is a complete self-contained root filesystem for Linux.
 232If you don't already understand what shared libraries, devices, and paths
 233you need to get a minimal root filesystem up and running, here are some
 234references:
 235http://www.tldp.org/HOWTO/Bootdisk-HOWTO/
 236http://www.tldp.org/HOWTO/From-PowerUp-To-Bash-Prompt-HOWTO.html
 237http://www.linuxfromscratch.org/lfs/view/stable/
 238
 239The "klibc" package (http://www.kernel.org/pub/linux/libs/klibc) is
 240designed to be a tiny C library to statically link early userspace
 241code against, along with some related utilities.  It is BSD licensed.
 242
 243I use uClibc (http://www.uclibc.org) and busybox (http://www.busybox.net)
 244myself.  These are LGPL and GPL, respectively.  (A self-contained initramfs
 245package is planned for the busybox 1.3 release.)
 246
 247In theory you could use glibc, but that's not well suited for small embedded
 248uses like this.  (A "hello world" program statically linked against glibc is
 249over 400k.  With uClibc it's 7k.  Also note that glibc dlopens libnss to do
 250name lookups, even when otherwise statically linked.)
 251
 252A good first step is to get initramfs to run a statically linked "hello world"
 253program as init, and test it under an emulator like qemu (www.qemu.org) or
 254User Mode Linux, like so:
 255
 256  cat > hello.c << EOF
 257  #include <stdio.h>
 258  #include <unistd.h>
 259
 260  int main(int argc, char *argv[])
 261  {
 262    printf("Hello world!\n");
 263    sleep(999999999);
 264  }
 265  EOF
 266  gcc -static hello.c -o init
 267  echo init | cpio -o -H newc | gzip > test.cpio.gz
 268  # Testing external initramfs using the initrd loading mechanism.
 269  qemu -kernel /boot/vmlinuz -initrd test.cpio.gz /dev/zero
 270
 271When debugging a normal root filesystem, it's nice to be able to boot with
 272"init=/bin/sh".  The initramfs equivalent is "rdinit=/bin/sh", and it's
 273just as useful.
 274
 275Why cpio rather than tar?
 276-------------------------
 277
 278This decision was made back in December, 2001.  The discussion started here:
 279
 280  http://www.uwsg.iu.edu/hypermail/linux/kernel/0112.2/1538.html
 281
 282And spawned a second thread (specifically on tar vs cpio), starting here:
 283
 284  http://www.uwsg.iu.edu/hypermail/linux/kernel/0112.2/1587.html
 285
 286The quick and dirty summary version (which is no substitute for reading
 287the above threads) is:
 288
 2891) cpio is a standard.  It's decades old (from the AT&T days), and already
 290   widely used on Linux (inside RPM, Red Hat's device driver disks).  Here's
 291   a Linux Journal article about it from 1996:
 292
 293      http://www.linuxjournal.com/article/1213
 294
 295   It's not as popular as tar because the traditional cpio command line tools
 296   require _truly_hideous_ command line arguments.  But that says nothing
 297   either way about the archive format, and there are alternative tools,
 298   such as:
 299
 300     http://freecode.com/projects/afio
 301
 3022) The cpio archive format chosen by the kernel is simpler and cleaner (and
 303   thus easier to create and parse) than any of the (literally dozens of)
 304   various tar archive formats.  The complete initramfs archive format is
 305   explained in buffer-format.txt, created in usr/gen_init_cpio.c, and
 306   extracted in init/initramfs.c.  All three together come to less than 26k
 307   total of human-readable text.
 308
 3093) The GNU project standardizing on tar is approximately as relevant as
 310   Windows standardizing on zip.  Linux is not part of either, and is free
 311   to make its own technical decisions.
 312
 3134) Since this is a kernel internal format, it could easily have been
 314   something brand new.  The kernel provides its own tools to create and
 315   extract this format anyway.  Using an existing standard was preferable,
 316   but not essential.
 317
 3185) Al Viro made the decision (quote: "tar is ugly as hell and not going to be
 319   supported on the kernel side"):
 320
 321      http://www.uwsg.iu.edu/hypermail/linux/kernel/0112.2/1540.html
 322
 323   explained his reasoning:
 324
 325      http://www.uwsg.iu.edu/hypermail/linux/kernel/0112.2/1550.html
 326      http://www.uwsg.iu.edu/hypermail/linux/kernel/0112.2/1638.html
 327
 328   and, most importantly, designed and implemented the initramfs code.
 329
 330Future directions:
 331------------------
 332
 333Today (2.6.16), initramfs is always compiled in, but not always used.  The
 334kernel falls back to legacy boot code that is reached only if initramfs does
 335not contain an /init program.  The fallback is legacy code, there to ensure a
 336smooth transition and allowing early boot functionality to gradually move to
 337"early userspace" (I.E. initramfs).
 338
 339The move to early userspace is necessary because finding and mounting the real
 340root device is complex.  Root partitions can span multiple devices (raid or
 341separate journal).  They can be out on the network (requiring dhcp, setting a
 342specific MAC address, logging into a server, etc).  They can live on removable
 343media, with dynamically allocated major/minor numbers and persistent naming
 344issues requiring a full udev implementation to sort out.  They can be
 345compressed, encrypted, copy-on-write, loopback mounted, strangely partitioned,
 346and so on.
 347
 348This kind of complexity (which inevitably includes policy) is rightly handled
 349in userspace.  Both klibc and busybox/uClibc are working on simple initramfs
 350packages to drop into a kernel build.
 351
 352The klibc package has now been accepted into Andrew Morton's 2.6.17-mm tree.
 353The kernel's current early boot code (partition detection, etc) will probably
 354be migrated into a default initramfs, automatically created and used by the
 355kernel build.
 356
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.