1.. SPDX-License-Identifier: GPL-2.0 2 3=========================================== 4Cramfs - cram a filesystem onto a small ROM 5=========================================== 6 7cramfs is designed to be simple and small, and to compress things well. 8 9It uses the zlib routines to compress a file one page at a time, and 10allows random page access. The meta-data is not compressed, but is 11expressed in a very terse representation to make it use much less 12diskspace than traditional filesystems. 13 14You can't write to a cramfs filesystem (making it compressible and 15compact also makes it _very_ hard to update on-the-fly), so you have to 16create the disk image with the "mkcramfs" utility. 17 18 19Usage Notes 20----------- 21 22File sizes are limited to less than 16MB. 23 24Maximum filesystem size is a little over 256MB. (The last file on the 25filesystem is allowed to extend past 256MB.) 26 27Only the low 8 bits of gid are stored. The current version of 28mkcramfs simply truncates to 8 bits, which is a potential security 29issue. 30 31Hard links are not preserved. mkcramfs deduplicates files with 32identical content, but two names for the same on-disk inode in the 33source tree become two separate (content-shared) entries in the 34image, and cramfs always reports a link count of 1. 35 36Cramfs directories have no ``.`` or ``..`` entries. Directories (like 37every other file on cramfs) always have a link count of 1. (There's 38no need to use -noleaf in ``find``, btw.) 39 40No timestamps are stored in a cramfs, so these default to the epoch 41(1970 GMT). Recently-accessed files may have updated timestamps, but 42the update lasts only as long as the inode is cached in memory, after 43which the timestamp reverts to 1970, i.e. moves backwards in time. 44 45The on-disk layout is host-endian: the kernel does not swab, and 46refuses to mount an image whose endianness does not match the CPU. 47For cross-builds, mkcramfs -B / -L forces the output endianness so 48that a host of one endianness can produce an image for a target of 49the other. 50 51The on-disk block size is fixed at 4096 bytes. On systems with a 52larger PAGE_SIZE you can change the #define in mkcramfs.c, with the 53caveat that the resulting image will only be readable on kernels 54configured for the same PAGE_SIZE. 55 56 57Memory Mapped cramfs image 58-------------------------- 59 60The CRAMFS_MTD Kconfig option adds support for loading data directly from 61a physical linear memory range (usually non volatile memory like Flash) 62instead of going through the block device layer. This saves some memory 63since no intermediate buffering is necessary to hold the data before 64decompressing. 65 66And when data blocks are kept uncompressed and properly aligned, they will 67automatically be mapped directly into user space whenever possible providing 68eXecute-In-Place (XIP) from ROM of read-only segments. Data segments mapped 69read-write (hence they have to be copied to RAM) may still be compressed in 70the cramfs image in the same file along with non compressed read-only 71segments. Both MMU and no-MMU systems are supported. This is particularly 72handy for tiny embedded systems with very tight memory constraints. 73 74The location of the cramfs image in memory is system dependent. You must 75know the proper physical address where the cramfs image is located and 76configure an MTD device for it. Also, that MTD device must be supported 77by a map driver that implements the "point" method. Examples of such 78MTD drivers are cfi_cmdset_0001 (Intel/Sharp CFI flash) or physmap 79(Flash device in physical memory map). MTD partitions based on such devices 80are fine too. Then that device should be specified with the "mtd:" prefix 81as the mount device argument. For example, to mount the MTD device named 82"fs_partition" on the /mnt directory:: 83 84 $ mount -t cramfs mtd:fs_partition /mnt 85 86To boot a kernel with this as root filesystem, suffice to specify 87something like "root=mtd:fs_partition" on the kernel command line. 88 89 90Tools 91----- 92 93A version of mkcramfs that can take advantage of the latest capabilities 94described above can be found here: 95 96https://github.com/npitre/cramfs-tools 97 98 99For /usr/share/magic 100-------------------- 101 102===== ======================= ======================= 1030 ulelong 0x28cd3d45 Linux cramfs offset 0 104>4 ulelong x size %d 105>8 ulelong x flags 0x%x 106>12 ulelong x future 0x%x 107>16 string >\0 signature "%.16s" 108>32 ulelong x fsid.crc 0x%x 109>36 ulelong x fsid.edition %d 110>40 ulelong x fsid.blocks %d 111>44 ulelong x fsid.files %d 112>48 string >\0 name "%.16s" 113512 ulelong 0x28cd3d45 Linux cramfs offset 512 114>516 ulelong x size %d 115>520 ulelong x flags 0x%x 116>524 ulelong x future 0x%x 117>528 string >\0 signature "%.16s" 118>544 ulelong x fsid.crc 0x%x 119>548 ulelong x fsid.edition %d 120>552 ulelong x fsid.blocks %d 121>556 ulelong x fsid.files %d 122>560 string >\0 name "%.16s" 123===== ======================= ======================= 124 125 126Hacker Notes 127------------ 128 129See fs/cramfs/README for filesystem layout and implementation notes. 130