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