buffer-format.txt 4.5 KB

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