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