aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/filesystems/romfs.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/filesystems/romfs.txt')
-rw-r--r--Documentation/filesystems/romfs.txt187
1 files changed, 187 insertions, 0 deletions
diff --git a/Documentation/filesystems/romfs.txt b/Documentation/filesystems/romfs.txt
new file mode 100644
index 000000000000..2d2a7b2a16b9
--- /dev/null
+++ b/Documentation/filesystems/romfs.txt
@@ -0,0 +1,187 @@
1ROMFS - ROM FILE SYSTEM
2
3This is a quite dumb, read only filesystem, mainly for initial RAM
4disks of installation disks. It has grown up by the need of having
5modules linked at boot time. Using this filesystem, you get a very
6similar feature, and even the possibility of a small kernel, with a
7file system which doesn't take up useful memory from the router
8functions in the basement of your office.
9
10For comparison, both the older minix and xiafs (the latter is now
11defunct) filesystems, compiled as module need more than 20000 bytes,
12while romfs is less than a page, about 4000 bytes (assuming i586
13code). Under the same conditions, the msdos filesystem would need
14about 30K (and does not support device nodes or symlinks), while the
15nfs module with nfsroot is about 57K. Furthermore, as a bit unfair
16comparison, an actual rescue disk used up 3202 blocks with ext2, while
17with romfs, it needed 3079 blocks.
18
19To create such a file system, you'll need a user program named
20genromfs. It is available via anonymous ftp on sunsite.unc.edu and
21its mirrors, in the /pub/Linux/system/recovery/ directory.
22
23As the name suggests, romfs could be also used (space-efficiently) on
24various read-only media, like (E)EPROM disks if someone will have the
25motivation.. :)
26
27However, the main purpose of romfs is to have a very small kernel,
28which has only this filesystem linked in, and then can load any module
29later, with the current module utilities. It can also be used to run
30some program to decide if you need SCSI devices, and even IDE or
31floppy drives can be loaded later if you use the "initrd"--initial
32RAM disk--feature of the kernel. This would not be really news
33flash, but with romfs, you can even spare off your ext2 or minix or
34maybe even affs filesystem until you really know that you need it.
35
36For example, a distribution boot disk can contain only the cd disk
37drivers (and possibly the SCSI drivers), and the ISO 9660 filesystem
38module. The kernel can be small enough, since it doesn't have other
39filesystems, like the quite large ext2fs module, which can then be
40loaded off the CD at a later stage of the installation. Another use
41would be for a recovery disk, when you are reinstalling a workstation
42from the network, and you will have all the tools/modules available
43from a nearby server, so you don't want to carry two disks for this
44purpose, just because it won't fit into ext2.
45
46romfs operates on block devices as you can expect, and the underlying
47structure is very simple. Every accessible structure begins on 16
48byte boundaries for fast access. The minimum space a file will take
49is 32 bytes (this is an empty file, with a less than 16 character
50name). The maximum overhead for any non-empty file is the header, and
51the 16 byte padding for the name and the contents, also 16+14+15 = 45
52bytes. This is quite rare however, since most file names are longer
53than 3 bytes, and shorter than 15 bytes.
54
55The layout of the filesystem is the following:
56
57offset content
58
59 +---+---+---+---+
60 0 | - | r | o | m | \
61 +---+---+---+---+ The ASCII representation of those bytes
62 4 | 1 | f | s | - | / (i.e. "-rom1fs-")
63 +---+---+---+---+
64 8 | full size | The number of accessible bytes in this fs.
65 +---+---+---+---+
66 12 | checksum | The checksum of the FIRST 512 BYTES.
67 +---+---+---+---+
68 16 | volume name | The zero terminated name of the volume,
69 : : padded to 16 byte boundary.
70 +---+---+---+---+
71 xx | file |
72 : headers :
73
74Every multi byte value (32 bit words, I'll use the longwords term from
75now on) must be in big endian order.
76
77The first eight bytes identify the filesystem, even for the casual
78inspector. After that, in the 3rd longword, it contains the number of
79bytes accessible from the start of this filesystem. The 4th longword
80is the checksum of the first 512 bytes (or the number of bytes
81accessible, whichever is smaller). The applied algorithm is the same
82as in the AFFS filesystem, namely a simple sum of the longwords
83(assuming bigendian quantities again). For details, please consult
84the source. This algorithm was chosen because although it's not quite
85reliable, it does not require any tables, and it is very simple.
86
87The following bytes are now part of the file system; each file header
88must begin on a 16 byte boundary.
89
90offset content
91
92 +---+---+---+---+
93 0 | next filehdr|X| The offset of the next file header
94 +---+---+---+---+ (zero if no more files)
95 4 | spec.info | Info for directories/hard links/devices
96 +---+---+---+---+
97 8 | size | The size of this file in bytes
98 +---+---+---+---+
99 12 | checksum | Covering the meta data, including the file
100 +---+---+---+---+ name, and padding
101 16 | file name | The zero terminated name of the file,
102 : : padded to 16 byte boundary
103 +---+---+---+---+
104 xx | file data |
105 : :
106
107Since the file headers begin always at a 16 byte boundary, the lowest
1084 bits would be always zero in the next filehdr pointer. These four
109bits are used for the mode information. Bits 0..2 specify the type of
110the file; while bit 4 shows if the file is executable or not. The
111permissions are assumed to be world readable, if this bit is not set,
112and world executable if it is; except the character and block devices,
113they are never accessible for other than owner. The owner of every
114file is user and group 0, this should never be a problem for the
115intended use. The mapping of the 8 possible values to file types is
116the following:
117
118 mapping spec.info means
119 0 hard link link destination [file header]
120 1 directory first file's header
121 2 regular file unused, must be zero [MBZ]
122 3 symbolic link unused, MBZ (file data is the link content)
123 4 block device 16/16 bits major/minor number
124 5 char device - " -
125 6 socket unused, MBZ
126 7 fifo unused, MBZ
127
128Note that hard links are specifically marked in this filesystem, but
129they will behave as you can expect (i.e. share the inode number).
130Note also that it is your responsibility to not create hard link
131loops, and creating all the . and .. links for directories. This is
132normally done correctly by the genromfs program. Please refrain from
133using the executable bits for special purposes on the socket and fifo
134special files, they may have other uses in the future. Additionally,
135please remember that only regular files, and symlinks are supposed to
136have a nonzero size field; they contain the number of bytes available
137directly after the (padded) file name.
138
139Another thing to note is that romfs works on file headers and data
140aligned to 16 byte boundaries, but most hardware devices and the block
141device drivers are unable to cope with smaller than block-sized data.
142To overcome this limitation, the whole size of the file system must be
143padded to an 1024 byte boundary.
144
145If you have any problems or suggestions concerning this file system,
146please contact me. However, think twice before wanting me to add
147features and code, because the primary and most important advantage of
148this file system is the small code. On the other hand, don't be
149alarmed, I'm not getting that much romfs related mail. Now I can
150understand why Avery wrote poems in the ARCnet docs to get some more
151feedback. :)
152
153romfs has also a mailing list, and to date, it hasn't received any
154traffic, so you are welcome to join it to discuss your ideas. :)
155
156It's run by ezmlm, so you can subscribe to it by sending a message
157to romfs-subscribe@shadow.banki.hu, the content is irrelevant.
158
159Pending issues:
160
161- Permissions and owner information are pretty essential features of a
162Un*x like system, but romfs does not provide the full possibilities.
163I have never found this limiting, but others might.
164
165- The file system is read only, so it can be very small, but in case
166one would want to write _anything_ to a file system, he still needs
167a writable file system, thus negating the size advantages. Possible
168solutions: implement write access as a compile-time option, or a new,
169similarly small writable filesystem for RAM disks.
170
171- Since the files are only required to have alignment on a 16 byte
172boundary, it is currently possibly suboptimal to read or execute files
173from the filesystem. It might be resolved by reordering file data to
174have most of it (i.e. except the start and the end) laying at "natural"
175boundaries, thus it would be possible to directly map a big portion of
176the file contents to the mm subsystem.
177
178- Compression might be an useful feature, but memory is quite a
179limiting factor in my eyes.
180
181- Where it is used?
182
183- Does it work on other architectures than intel and motorola?
184
185
186Have fun,
187Janos Farkas <chexum@shadow.banki.hu>