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