0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ===========================================
0004 Cramfs - cram a filesystem onto a small ROM
0005 ===========================================
0006
0007 cramfs is designed to be simple and small, and to compress things well.
0008
0009 It uses the zlib routines to compress a file one page at a time, and
0010 allows random page access. The meta-data is not compressed, but is
0011 expressed in a very terse representation to make it use much less
0012 diskspace than traditional filesystems.
0013
0014 You can't write to a cramfs filesystem (making it compressible and
0015 compact also makes it _very_ hard to update on-the-fly), so you have to
0016 create the disk image with the "mkcramfs" utility.
0017
0018
0019 Usage Notes
0020 -----------
0021
0022 File sizes are limited to less than 16MB.
0023
0024 Maximum filesystem size is a little over 256MB. (The last file on the
0025 filesystem is allowed to extend past 256MB.)
0026
0027 Only the low 8 bits of gid are stored. The current version of
0028 mkcramfs simply truncates to 8 bits, which is a potential security
0029 issue.
0030
0031 Hard links are supported, but hard linked files
0032 will still have a link count of 1 in the cramfs image.
0033
0034 Cramfs directories have no ``.`` or ``..`` entries. Directories (like
0035 every other file on cramfs) always have a link count of 1. (There's
0036 no need to use -noleaf in ``find``, btw.)
0037
0038 No timestamps are stored in a cramfs, so these default to the epoch
0039 (1970 GMT). Recently-accessed files may have updated timestamps, but
0040 the update lasts only as long as the inode is cached in memory, after
0041 which the timestamp reverts to 1970, i.e. moves backwards in time.
0042
0043 Currently, cramfs must be written and read with architectures of the
0044 same endianness, and can be read only by kernels with PAGE_SIZE
0045 == 4096. At least the latter of these is a bug, but it hasn't been
0046 decided what the best fix is. For the moment if you have larger pages
0047 you can just change the #define in mkcramfs.c, so long as you don't
0048 mind the filesystem becoming unreadable to future kernels.
0049
0050
0051 Memory Mapped cramfs image
0052 --------------------------
0053
0054 The CRAMFS_MTD Kconfig option adds support for loading data directly from
0055 a physical linear memory range (usually non volatile memory like Flash)
0056 instead of going through the block device layer. This saves some memory
0057 since no intermediate buffering is necessary to hold the data before
0058 decompressing.
0059
0060 And when data blocks are kept uncompressed and properly aligned, they will
0061 automatically be mapped directly into user space whenever possible providing
0062 eXecute-In-Place (XIP) from ROM of read-only segments. Data segments mapped
0063 read-write (hence they have to be copied to RAM) may still be compressed in
0064 the cramfs image in the same file along with non compressed read-only
0065 segments. Both MMU and no-MMU systems are supported. This is particularly
0066 handy for tiny embedded systems with very tight memory constraints.
0067
0068 The location of the cramfs image in memory is system dependent. You must
0069 know the proper physical address where the cramfs image is located and
0070 configure an MTD device for it. Also, that MTD device must be supported
0071 by a map driver that implements the "point" method. Examples of such
0072 MTD drivers are cfi_cmdset_0001 (Intel/Sharp CFI flash) or physmap
0073 (Flash device in physical memory map). MTD partitions based on such devices
0074 are fine too. Then that device should be specified with the "mtd:" prefix
0075 as the mount device argument. For example, to mount the MTD device named
0076 "fs_partition" on the /mnt directory::
0077
0078 $ mount -t cramfs mtd:fs_partition /mnt
0079
0080 To boot a kernel with this as root filesystem, suffice to specify
0081 something like "root=mtd:fs_partition" on the kernel command line.
0082
0083
0084 Tools
0085 -----
0086
0087 A version of mkcramfs that can take advantage of the latest capabilities
0088 described above can be found here:
0089
0090 https://github.com/npitre/cramfs-tools
0091
0092
0093 For /usr/share/magic
0094 --------------------
0095
0096 ===== ======================= =======================
0097 0 ulelong 0x28cd3d45 Linux cramfs offset 0
0098 >4 ulelong x size %d
0099 >8 ulelong x flags 0x%x
0100 >12 ulelong x future 0x%x
0101 >16 string >\0 signature "%.16s"
0102 >32 ulelong x fsid.crc 0x%x
0103 >36 ulelong x fsid.edition %d
0104 >40 ulelong x fsid.blocks %d
0105 >44 ulelong x fsid.files %d
0106 >48 string >\0 name "%.16s"
0107 512 ulelong 0x28cd3d45 Linux cramfs offset 512
0108 >516 ulelong x size %d
0109 >520 ulelong x flags 0x%x
0110 >524 ulelong x future 0x%x
0111 >528 string >\0 signature "%.16s"
0112 >544 ulelong x fsid.crc 0x%x
0113 >548 ulelong x fsid.edition %d
0114 >552 ulelong x fsid.blocks %d
0115 >556 ulelong x fsid.files %d
0116 >560 string >\0 name "%.16s"
0117 ===== ======================= =======================
0118
0119
0120 Hacker Notes
0121 ------------
0122
0123 See fs/cramfs/README for filesystem layout and implementation notes.
