Documentation/driver-api/early-userspace/buffer-format.rst

   1 =======================
   2 initramfs buffer format
   3 =======================
   4
   5 Al Viro, H. Peter Anvin
   6
   7 Last revision: 2002-01-13
   8
   9 Starting with kernel 2.5.x, the old "initial ramdisk" protocol is
  10 getting {replaced/complemented} with the new "initial ramfs"
  11 (initramfs) protocol.  The initramfs contents is passed using the same
  12 memory buffer protocol used by the initrd protocol, but the contents
  13 is different.  The initramfs buffer contains an archive which is
  14 expanded into a ramfs filesystem; this document details the format of
  15 the initramfs buffer format.
  16
  17 The initramfs buffer format is based around the "newc" or "crc" CPIO
  18 formats, and can be created with the cpio(1) utility.  The cpio
  19 archive can be compressed using gzip(1).  One valid version of an
  20 initramfs buffer is thus a single .cpio.gz file.
  21
  22 The full format of the initramfs buffer is defined by the following
  23 grammar, where::
  24
  25         *       is used to indicate "0 or more occurrences of"
  26         (|)     indicates alternatives
  27         +       indicates concatenation
  28         GZIP()  indicates the gzip(1) of the operand
  29         ALGN(n) means padding with null bytes to an n-byte boundary
  30
  31         initramfs  := ("\0" | cpio_archive | cpio_gzip_archive)*
  32
  33         cpio_gzip_archive := GZIP(cpio_archive)
  34
  35         cpio_archive := cpio_file* + (<nothing> | cpio_trailer)
  36
  37         cpio_file := ALGN(4) + cpio_header + filename + "\0" + ALGN(4) + data
  38
  39         cpio_trailer := ALGN(4) + cpio_header + "TRAILER!!!\0" + ALGN(4)
  40
  41
  42 In human terms, the initramfs buffer contains a collection of
  43 compressed and/or uncompressed cpio archives (in the "newc" or "crc"
  44 formats); arbitrary amounts zero bytes (for padding) can be added
  45 between members.
  46
  47 The cpio "TRAILER!!!" entry (cpio end-of-archive) is optional, but is
  48 not ignored; see "handling of hard links" below.
  49
  50 The structure of the cpio_header is as follows (all fields contain
  51 hexadecimal ASCII numbers fully padded with '0' on the left to the
  52 full width of the field, for example, the integer 4780 is represented
  53 by the ASCII string "000012ac"):
  54
  55 ============= ================== ==============================================
  56 Field name    Field size         Meaning
  57 ============= ================== ==============================================
  58 c_magic       6 bytes            The string "070701" or "070702"
  59 c_ino         8 bytes            File inode number
  60 c_mode        8 bytes            File mode and permissions
  61 c_uid         8 bytes            File uid
  62 c_gid         8 bytes            File gid
  63 c_nlink       8 bytes            Number of links
  64 c_mtime       8 bytes            Modification time
  65 c_filesize    8 bytes            Size of data field
  66 c_maj         8 bytes            Major part of file device number
  67 c_min         8 bytes            Minor part of file device number
  68 c_rmaj        8 bytes            Major part of device node reference
  69 c_rmin        8 bytes            Minor part of device node reference
  70 c_namesize    8 bytes            Length of filename, including final \0
  71 c_chksum      8 bytes            Checksum of data field if c_magic is 070702;
  72                                  otherwise zero
  73 ============= ================== ==============================================
  74
  75 The c_mode field matches the contents of st_mode returned by stat(2)
  76 on Linux, and encodes the file type and file permissions.
  77
  78 The c_filesize should be zero for any file which is not a regular file
  79 or symlink.
  80
  81 The c_chksum field contains a simple 32-bit unsigned sum of all the
  82 bytes in the data field.  cpio(1) refers to this as "crc", which is
  83 clearly incorrect (a cyclic redundancy check is a different and
  84 significantly stronger integrity check), however, this is the
  85 algorithm used.
  86
  87 If the filename is "TRAILER!!!" this is actually an end-of-archive
  88 marker; the c_filesize for an end-of-archive marker must be zero.
  89
  90
  91 Handling of hard links
  92 ======================
  93
  94 When a nondirectory with c_nlink > 1 is seen, the (c_maj,c_min,c_ino)
  95 tuple is looked up in a tuple buffer.  If not found, it is entered in
  96 the tuple buffer and the entry is created as usual; if found, a hard
  97 link rather than a second copy of the file is created.  It is not
  98 necessary (but permitted) to include a second copy of the file
  99 contents; if the file contents is not included, the c_filesize field
 100 should be set to zero to indicate no data section follows.  If data is
 101 present, the previous instance of the file is overwritten; this allows
 102 the data-carrying instance of a file to occur anywhere in the sequence
 103 (GNU cpio is reported to attach the data to the last instance of a
 104 file only.)
 105
 106 c_filesize must not be zero for a symlink.
 107
 108 When a "TRAILER!!!" end-of-archive marker is seen, the tuple buffer is
 109 reset.  This permits archives which are generated independently to be
 110 concatenated.
 111
 112 To combine file data from different sources (without having to
 113 regenerate the (c_maj,c_min,c_ino) fields), therefore, either one of
 114 the following techniques can be used:
 115
 116 a) Separate the different file data sources with a "TRAILER!!!"
 117    end-of-archive marker, or
 118
 119 b) Make sure c_nlink == 1 for all nondirectory entries.