0001 =======================
0002 initramfs buffer format
0003 =======================
0004
0005 Al Viro, H. Peter Anvin
0006
0007 Last revision: 2002-01-13
0008
0009 Starting with kernel 2.5.x, the old "initial ramdisk" protocol is
0010 getting {replaced/complemented} with the new "initial ramfs"
0011 (initramfs) protocol. The initramfs contents is passed using the same
0012 memory buffer protocol used by the initrd protocol, but the contents
0013 is different. The initramfs buffer contains an archive which is
0014 expanded into a ramfs filesystem; this document details the format of
0015 the initramfs buffer format.
0016
0017 The initramfs buffer format is based around the "newc" or "crc" CPIO
0018 formats, and can be created with the cpio(1) utility. The cpio
0019 archive can be compressed using gzip(1). One valid version of an
0020 initramfs buffer is thus a single .cpio.gz file.
0021
0022 The full format of the initramfs buffer is defined by the following
0023 grammar, where::
0024
0025 * is used to indicate "0 or more occurrences of"
0026 (|) indicates alternatives
0027 + indicates concatenation
0028 GZIP() indicates the gzip(1) of the operand
0029 ALGN(n) means padding with null bytes to an n-byte boundary
0030
0031 initramfs := ("\0" | cpio_archive | cpio_gzip_archive)*
0032
0033 cpio_gzip_archive := GZIP(cpio_archive)
0034
0035 cpio_archive := cpio_file* + (<nothing> | cpio_trailer)
0036
0037 cpio_file := ALGN(4) + cpio_header + filename + "\0" + ALGN(4) + data
0038
0039 cpio_trailer := ALGN(4) + cpio_header + "TRAILER!!!\0" + ALGN(4)
0040
0041
0042 In human terms, the initramfs buffer contains a collection of
0043 compressed and/or uncompressed cpio archives (in the "newc" or "crc"
0044 formats); arbitrary amounts zero bytes (for padding) can be added
0045 between members.
0046
0047 The cpio "TRAILER!!!" entry (cpio end-of-archive) is optional, but is
0048 not ignored; see "handling of hard links" below.
0049
0050 The structure of the cpio_header is as follows (all fields contain
0051 hexadecimal ASCII numbers fully padded with '0' on the left to the
0052 full width of the field, for example, the integer 4780 is represented
0053 by the ASCII string "000012ac"):
0054
0055 ============= ================== ==============================================
0056 Field name Field size Meaning
0057 ============= ================== ==============================================
0058 c_magic 6 bytes The string "070701" or "070702"
0059 c_ino 8 bytes File inode number
0060 c_mode 8 bytes File mode and permissions
0061 c_uid 8 bytes File uid
0062 c_gid 8 bytes File gid
0063 c_nlink 8 bytes Number of links
0064 c_mtime 8 bytes Modification time
0065 c_filesize 8 bytes Size of data field
0066 c_maj 8 bytes Major part of file device number
0067 c_min 8 bytes Minor part of file device number
0068 c_rmaj 8 bytes Major part of device node reference
0069 c_rmin 8 bytes Minor part of device node reference
0070 c_namesize 8 bytes Length of filename, including final \0
0071 c_chksum 8 bytes Checksum of data field if c_magic is 070702;
0072 otherwise zero
0073 ============= ================== ==============================================
0074
0075 The c_mode field matches the contents of st_mode returned by stat(2)
0076 on Linux, and encodes the file type and file permissions.
0077
0078 The c_filesize should be zero for any file which is not a regular file
0079 or symlink.
0080
0081 The c_chksum field contains a simple 32-bit unsigned sum of all the
0082 bytes in the data field. cpio(1) refers to this as "crc", which is
0083 clearly incorrect (a cyclic redundancy check is a different and
0084 significantly stronger integrity check), however, this is the
0085 algorithm used.
0086
0087 If the filename is "TRAILER!!!" this is actually an end-of-archive
0088 marker; the c_filesize for an end-of-archive marker must be zero.
0089
0090
0091 Handling of hard links
0092 ======================
0093
0094 When a nondirectory with c_nlink > 1 is seen, the (c_maj,c_min,c_ino)
0095 tuple is looked up in a tuple buffer. If not found, it is entered in
0096 the tuple buffer and the entry is created as usual; if found, a hard
0097 link rather than a second copy of the file is created. It is not
0098 necessary (but permitted) to include a second copy of the file
0099 contents; if the file contents is not included, the c_filesize field
0100 should be set to zero to indicate no data section follows. If data is
0101 present, the previous instance of the file is overwritten; this allows
0102 the data-carrying instance of a file to occur anywhere in the sequence
0103 (GNU cpio is reported to attach the data to the last instance of a
0104 file only.)
0105
0106 c_filesize must not be zero for a symlink.
0107
0108 When a "TRAILER!!!" end-of-archive marker is seen, the tuple buffer is
0109 reset. This permits archives which are generated independently to be
0110 concatenated.
0111
0112 To combine file data from different sources (without having to
0113 regenerate the (c_maj,c_min,c_ino) fields), therefore, either one of
0114 the following techniques can be used:
0115
0116 a) Separate the different file data sources with a "TRAILER!!!"
0117 end-of-archive marker, or
0118
0119 b) Make sure c_nlink == 1 for all nondirectory entries.
