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