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