Orange Pi5 kernel

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