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