1*4882a593Smuzhiyun.. SPDX-License-Identifier: GPL-2.0 2*4882a593Smuzhiyun 3*4882a593Smuzhiyun=========================================== 4*4882a593SmuzhiyunCramfs - cram a filesystem onto a small ROM 5*4882a593Smuzhiyun=========================================== 6*4882a593Smuzhiyun 7*4882a593Smuzhiyuncramfs is designed to be simple and small, and to compress things well. 8*4882a593Smuzhiyun 9*4882a593SmuzhiyunIt uses the zlib routines to compress a file one page at a time, and 10*4882a593Smuzhiyunallows random page access. The meta-data is not compressed, but is 11*4882a593Smuzhiyunexpressed in a very terse representation to make it use much less 12*4882a593Smuzhiyundiskspace than traditional filesystems. 13*4882a593Smuzhiyun 14*4882a593SmuzhiyunYou can't write to a cramfs filesystem (making it compressible and 15*4882a593Smuzhiyuncompact also makes it _very_ hard to update on-the-fly), so you have to 16*4882a593Smuzhiyuncreate the disk image with the "mkcramfs" utility. 17*4882a593Smuzhiyun 18*4882a593Smuzhiyun 19*4882a593SmuzhiyunUsage Notes 20*4882a593Smuzhiyun----------- 21*4882a593Smuzhiyun 22*4882a593SmuzhiyunFile sizes are limited to less than 16MB. 23*4882a593Smuzhiyun 24*4882a593SmuzhiyunMaximum filesystem size is a little over 256MB. (The last file on the 25*4882a593Smuzhiyunfilesystem is allowed to extend past 256MB.) 26*4882a593Smuzhiyun 27*4882a593SmuzhiyunOnly the low 8 bits of gid are stored. The current version of 28*4882a593Smuzhiyunmkcramfs simply truncates to 8 bits, which is a potential security 29*4882a593Smuzhiyunissue. 30*4882a593Smuzhiyun 31*4882a593SmuzhiyunHard links are supported, but hard linked files 32*4882a593Smuzhiyunwill still have a link count of 1 in the cramfs image. 33*4882a593Smuzhiyun 34*4882a593SmuzhiyunCramfs directories have no ``.`` or ``..`` entries. Directories (like 35*4882a593Smuzhiyunevery other file on cramfs) always have a link count of 1. (There's 36*4882a593Smuzhiyunno need to use -noleaf in ``find``, btw.) 37*4882a593Smuzhiyun 38*4882a593SmuzhiyunNo timestamps are stored in a cramfs, so these default to the epoch 39*4882a593Smuzhiyun(1970 GMT). Recently-accessed files may have updated timestamps, but 40*4882a593Smuzhiyunthe update lasts only as long as the inode is cached in memory, after 41*4882a593Smuzhiyunwhich the timestamp reverts to 1970, i.e. moves backwards in time. 42*4882a593Smuzhiyun 43*4882a593SmuzhiyunCurrently, cramfs must be written and read with architectures of the 44*4882a593Smuzhiyunsame endianness, and can be read only by kernels with PAGE_SIZE 45*4882a593Smuzhiyun== 4096. At least the latter of these is a bug, but it hasn't been 46*4882a593Smuzhiyundecided what the best fix is. For the moment if you have larger pages 47*4882a593Smuzhiyunyou can just change the #define in mkcramfs.c, so long as you don't 48*4882a593Smuzhiyunmind the filesystem becoming unreadable to future kernels. 49*4882a593Smuzhiyun 50*4882a593Smuzhiyun 51*4882a593SmuzhiyunMemory Mapped cramfs image 52*4882a593Smuzhiyun-------------------------- 53*4882a593Smuzhiyun 54*4882a593SmuzhiyunThe CRAMFS_MTD Kconfig option adds support for loading data directly from 55*4882a593Smuzhiyuna physical linear memory range (usually non volatile memory like Flash) 56*4882a593Smuzhiyuninstead of going through the block device layer. This saves some memory 57*4882a593Smuzhiyunsince no intermediate buffering is necessary to hold the data before 58*4882a593Smuzhiyundecompressing. 59*4882a593Smuzhiyun 60*4882a593SmuzhiyunAnd when data blocks are kept uncompressed and properly aligned, they will 61*4882a593Smuzhiyunautomatically be mapped directly into user space whenever possible providing 62*4882a593SmuzhiyuneXecute-In-Place (XIP) from ROM of read-only segments. Data segments mapped 63*4882a593Smuzhiyunread-write (hence they have to be copied to RAM) may still be compressed in 64*4882a593Smuzhiyunthe cramfs image in the same file along with non compressed read-only 65*4882a593Smuzhiyunsegments. Both MMU and no-MMU systems are supported. This is particularly 66*4882a593Smuzhiyunhandy for tiny embedded systems with very tight memory constraints. 67*4882a593Smuzhiyun 68*4882a593SmuzhiyunThe location of the cramfs image in memory is system dependent. You must 69*4882a593Smuzhiyunknow the proper physical address where the cramfs image is located and 70*4882a593Smuzhiyunconfigure an MTD device for it. Also, that MTD device must be supported 71*4882a593Smuzhiyunby a map driver that implements the "point" method. Examples of such 72*4882a593SmuzhiyunMTD drivers are cfi_cmdset_0001 (Intel/Sharp CFI flash) or physmap 73*4882a593Smuzhiyun(Flash device in physical memory map). MTD partitions based on such devices 74*4882a593Smuzhiyunare fine too. Then that device should be specified with the "mtd:" prefix 75*4882a593Smuzhiyunas the mount device argument. For example, to mount the MTD device named 76*4882a593Smuzhiyun"fs_partition" on the /mnt directory:: 77*4882a593Smuzhiyun 78*4882a593Smuzhiyun $ mount -t cramfs mtd:fs_partition /mnt 79*4882a593Smuzhiyun 80*4882a593SmuzhiyunTo boot a kernel with this as root filesystem, suffice to specify 81*4882a593Smuzhiyunsomething like "root=mtd:fs_partition" on the kernel command line. 82*4882a593Smuzhiyun 83*4882a593Smuzhiyun 84*4882a593SmuzhiyunTools 85*4882a593Smuzhiyun----- 86*4882a593Smuzhiyun 87*4882a593SmuzhiyunA version of mkcramfs that can take advantage of the latest capabilities 88*4882a593Smuzhiyundescribed above can be found here: 89*4882a593Smuzhiyun 90*4882a593Smuzhiyunhttps://github.com/npitre/cramfs-tools 91*4882a593Smuzhiyun 92*4882a593Smuzhiyun 93*4882a593SmuzhiyunFor /usr/share/magic 94*4882a593Smuzhiyun-------------------- 95*4882a593Smuzhiyun 96*4882a593Smuzhiyun===== ======================= ======================= 97*4882a593Smuzhiyun0 ulelong 0x28cd3d45 Linux cramfs offset 0 98*4882a593Smuzhiyun>4 ulelong x size %d 99*4882a593Smuzhiyun>8 ulelong x flags 0x%x 100*4882a593Smuzhiyun>12 ulelong x future 0x%x 101*4882a593Smuzhiyun>16 string >\0 signature "%.16s" 102*4882a593Smuzhiyun>32 ulelong x fsid.crc 0x%x 103*4882a593Smuzhiyun>36 ulelong x fsid.edition %d 104*4882a593Smuzhiyun>40 ulelong x fsid.blocks %d 105*4882a593Smuzhiyun>44 ulelong x fsid.files %d 106*4882a593Smuzhiyun>48 string >\0 name "%.16s" 107*4882a593Smuzhiyun512 ulelong 0x28cd3d45 Linux cramfs offset 512 108*4882a593Smuzhiyun>516 ulelong x size %d 109*4882a593Smuzhiyun>520 ulelong x flags 0x%x 110*4882a593Smuzhiyun>524 ulelong x future 0x%x 111*4882a593Smuzhiyun>528 string >\0 signature "%.16s" 112*4882a593Smuzhiyun>544 ulelong x fsid.crc 0x%x 113*4882a593Smuzhiyun>548 ulelong x fsid.edition %d 114*4882a593Smuzhiyun>552 ulelong x fsid.blocks %d 115*4882a593Smuzhiyun>556 ulelong x fsid.files %d 116*4882a593Smuzhiyun>560 string >\0 name "%.16s" 117*4882a593Smuzhiyun===== ======================= ======================= 118*4882a593Smuzhiyun 119*4882a593Smuzhiyun 120*4882a593SmuzhiyunHacker Notes 121*4882a593Smuzhiyun------------ 122*4882a593Smuzhiyun 123*4882a593SmuzhiyunSee fs/cramfs/README for filesystem layout and implementation notes. 124