1f1fa0e60SMauro Carvalho Chehab.. SPDX-License-Identifier: GPL-2.0 2f1fa0e60SMauro Carvalho Chehab 3f1fa0e60SMauro Carvalho Chehab=========================================== 4f1fa0e60SMauro Carvalho ChehabCramfs - cram a filesystem onto a small ROM 5f1fa0e60SMauro Carvalho Chehab=========================================== 6f1fa0e60SMauro Carvalho Chehab 7f1fa0e60SMauro Carvalho Chehabcramfs is designed to be simple and small, and to compress things well. 8f1fa0e60SMauro Carvalho Chehab 9f1fa0e60SMauro Carvalho ChehabIt uses the zlib routines to compress a file one page at a time, and 10f1fa0e60SMauro Carvalho Chehaballows random page access. The meta-data is not compressed, but is 11f1fa0e60SMauro Carvalho Chehabexpressed in a very terse representation to make it use much less 12f1fa0e60SMauro Carvalho Chehabdiskspace than traditional filesystems. 13f1fa0e60SMauro Carvalho Chehab 14f1fa0e60SMauro Carvalho ChehabYou can't write to a cramfs filesystem (making it compressible and 15f1fa0e60SMauro Carvalho Chehabcompact also makes it _very_ hard to update on-the-fly), so you have to 16f1fa0e60SMauro Carvalho Chehabcreate the disk image with the "mkcramfs" utility. 17f1fa0e60SMauro Carvalho Chehab 18f1fa0e60SMauro Carvalho Chehab 19f1fa0e60SMauro Carvalho ChehabUsage Notes 20f1fa0e60SMauro Carvalho Chehab----------- 21f1fa0e60SMauro Carvalho Chehab 22f1fa0e60SMauro Carvalho ChehabFile sizes are limited to less than 16MB. 23f1fa0e60SMauro Carvalho Chehab 24f1fa0e60SMauro Carvalho ChehabMaximum filesystem size is a little over 256MB. (The last file on the 25f1fa0e60SMauro Carvalho Chehabfilesystem is allowed to extend past 256MB.) 26f1fa0e60SMauro Carvalho Chehab 27f1fa0e60SMauro Carvalho ChehabOnly the low 8 bits of gid are stored. The current version of 28f1fa0e60SMauro Carvalho Chehabmkcramfs simply truncates to 8 bits, which is a potential security 29f1fa0e60SMauro Carvalho Chehabissue. 30f1fa0e60SMauro Carvalho Chehab 31f1fa0e60SMauro Carvalho ChehabHard links are supported, but hard linked files 32f1fa0e60SMauro Carvalho Chehabwill still have a link count of 1 in the cramfs image. 33f1fa0e60SMauro Carvalho Chehab 34f1fa0e60SMauro Carvalho ChehabCramfs directories have no ``.`` or ``..`` entries. Directories (like 35f1fa0e60SMauro Carvalho Chehabevery other file on cramfs) always have a link count of 1. (There's 36f1fa0e60SMauro Carvalho Chehabno need to use -noleaf in ``find``, btw.) 37f1fa0e60SMauro Carvalho Chehab 38f1fa0e60SMauro Carvalho ChehabNo timestamps are stored in a cramfs, so these default to the epoch 39f1fa0e60SMauro Carvalho Chehab(1970 GMT). Recently-accessed files may have updated timestamps, but 40f1fa0e60SMauro Carvalho Chehabthe update lasts only as long as the inode is cached in memory, after 41f1fa0e60SMauro Carvalho Chehabwhich the timestamp reverts to 1970, i.e. moves backwards in time. 42f1fa0e60SMauro Carvalho Chehab 43f1fa0e60SMauro Carvalho ChehabCurrently, cramfs must be written and read with architectures of the 44f1fa0e60SMauro Carvalho Chehabsame endianness, and can be read only by kernels with PAGE_SIZE 45f1fa0e60SMauro Carvalho Chehab== 4096. At least the latter of these is a bug, but it hasn't been 46f1fa0e60SMauro Carvalho Chehabdecided what the best fix is. For the moment if you have larger pages 47f1fa0e60SMauro Carvalho Chehabyou can just change the #define in mkcramfs.c, so long as you don't 48f1fa0e60SMauro Carvalho Chehabmind the filesystem becoming unreadable to future kernels. 49f1fa0e60SMauro Carvalho Chehab 50f1fa0e60SMauro Carvalho Chehab 51f1fa0e60SMauro Carvalho ChehabMemory Mapped cramfs image 52f1fa0e60SMauro Carvalho Chehab-------------------------- 53f1fa0e60SMauro Carvalho Chehab 54f1fa0e60SMauro Carvalho ChehabThe CRAMFS_MTD Kconfig option adds support for loading data directly from 55f1fa0e60SMauro Carvalho Chehaba physical linear memory range (usually non volatile memory like Flash) 56f1fa0e60SMauro Carvalho Chehabinstead of going through the block device layer. This saves some memory 57f1fa0e60SMauro Carvalho Chehabsince no intermediate buffering is necessary to hold the data before 58f1fa0e60SMauro Carvalho Chehabdecompressing. 59f1fa0e60SMauro Carvalho Chehab 60f1fa0e60SMauro Carvalho ChehabAnd when data blocks are kept uncompressed and properly aligned, they will 61f1fa0e60SMauro Carvalho Chehabautomatically be mapped directly into user space whenever possible providing 62f1fa0e60SMauro Carvalho ChehabeXecute-In-Place (XIP) from ROM of read-only segments. Data segments mapped 63f1fa0e60SMauro Carvalho Chehabread-write (hence they have to be copied to RAM) may still be compressed in 64f1fa0e60SMauro Carvalho Chehabthe cramfs image in the same file along with non compressed read-only 65f1fa0e60SMauro Carvalho Chehabsegments. Both MMU and no-MMU systems are supported. This is particularly 66f1fa0e60SMauro Carvalho Chehabhandy for tiny embedded systems with very tight memory constraints. 67f1fa0e60SMauro Carvalho Chehab 68f1fa0e60SMauro Carvalho ChehabThe location of the cramfs image in memory is system dependent. You must 69f1fa0e60SMauro Carvalho Chehabknow the proper physical address where the cramfs image is located and 70f1fa0e60SMauro Carvalho Chehabconfigure an MTD device for it. Also, that MTD device must be supported 71f1fa0e60SMauro Carvalho Chehabby a map driver that implements the "point" method. Examples of such 72f1fa0e60SMauro Carvalho ChehabMTD drivers are cfi_cmdset_0001 (Intel/Sharp CFI flash) or physmap 73f1fa0e60SMauro Carvalho Chehab(Flash device in physical memory map). MTD partitions based on such devices 74f1fa0e60SMauro Carvalho Chehabare fine too. Then that device should be specified with the "mtd:" prefix 75f1fa0e60SMauro Carvalho Chehabas the mount device argument. For example, to mount the MTD device named 76f1fa0e60SMauro Carvalho Chehab"fs_partition" on the /mnt directory:: 77f1fa0e60SMauro Carvalho Chehab 78f1fa0e60SMauro Carvalho Chehab $ mount -t cramfs mtd:fs_partition /mnt 79f1fa0e60SMauro Carvalho Chehab 80f1fa0e60SMauro Carvalho ChehabTo boot a kernel with this as root filesystem, suffice to specify 81f1fa0e60SMauro Carvalho Chehabsomething like "root=mtd:fs_partition" on the kernel command line. 82f1fa0e60SMauro Carvalho Chehab 83f1fa0e60SMauro Carvalho Chehab 84f1fa0e60SMauro Carvalho ChehabTools 85f1fa0e60SMauro Carvalho Chehab----- 86f1fa0e60SMauro Carvalho Chehab 87f1fa0e60SMauro Carvalho ChehabA version of mkcramfs that can take advantage of the latest capabilities 88f1fa0e60SMauro Carvalho Chehabdescribed above can be found here: 89f1fa0e60SMauro Carvalho Chehab 90f1fa0e60SMauro Carvalho Chehabhttps://github.com/npitre/cramfs-tools 91f1fa0e60SMauro Carvalho Chehab 92f1fa0e60SMauro Carvalho Chehab 93f1fa0e60SMauro Carvalho ChehabFor /usr/share/magic 94f1fa0e60SMauro Carvalho Chehab-------------------- 95f1fa0e60SMauro Carvalho Chehab 96f1fa0e60SMauro Carvalho Chehab===== ======================= ======================= 97f1fa0e60SMauro Carvalho Chehab0 ulelong 0x28cd3d45 Linux cramfs offset 0 98f1fa0e60SMauro Carvalho Chehab>4 ulelong x size %d 99f1fa0e60SMauro Carvalho Chehab>8 ulelong x flags 0x%x 100f1fa0e60SMauro Carvalho Chehab>12 ulelong x future 0x%x 101f1fa0e60SMauro Carvalho Chehab>16 string >\0 signature "%.16s" 102f1fa0e60SMauro Carvalho Chehab>32 ulelong x fsid.crc 0x%x 103f1fa0e60SMauro Carvalho Chehab>36 ulelong x fsid.edition %d 104f1fa0e60SMauro Carvalho Chehab>40 ulelong x fsid.blocks %d 105f1fa0e60SMauro Carvalho Chehab>44 ulelong x fsid.files %d 106f1fa0e60SMauro Carvalho Chehab>48 string >\0 name "%.16s" 107f1fa0e60SMauro Carvalho Chehab512 ulelong 0x28cd3d45 Linux cramfs offset 512 108f1fa0e60SMauro Carvalho Chehab>516 ulelong x size %d 109f1fa0e60SMauro Carvalho Chehab>520 ulelong x flags 0x%x 110f1fa0e60SMauro Carvalho Chehab>524 ulelong x future 0x%x 111f1fa0e60SMauro Carvalho Chehab>528 string >\0 signature "%.16s" 112f1fa0e60SMauro Carvalho Chehab>544 ulelong x fsid.crc 0x%x 113f1fa0e60SMauro Carvalho Chehab>548 ulelong x fsid.edition %d 114f1fa0e60SMauro Carvalho Chehab>552 ulelong x fsid.blocks %d 115f1fa0e60SMauro Carvalho Chehab>556 ulelong x fsid.files %d 116f1fa0e60SMauro Carvalho Chehab>560 string >\0 name "%.16s" 117f1fa0e60SMauro Carvalho Chehab===== ======================= ======================= 118f1fa0e60SMauro Carvalho Chehab 119f1fa0e60SMauro Carvalho Chehab 120f1fa0e60SMauro Carvalho ChehabHacker Notes 121f1fa0e60SMauro Carvalho Chehab------------ 122f1fa0e60SMauro Carvalho Chehab 123f1fa0e60SMauro Carvalho ChehabSee fs/cramfs/README for filesystem layout and implementation notes. 124