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