Commit | Line | Data |
---|---|---|
1da177e4 LT |
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. |