About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / early-userspace / buffer-format.txt




Custom Search

Based on kernel version 3.16. Page generated on 2014-08-06 21:39 EST.

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.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.