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