Loading...
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 supported, but hard linked files
32will still have a link count of 1 in the cramfs image.
33
34Cramfs directories have no ``.`` or ``..`` entries. Directories (like
35every other file on cramfs) always have a link count of 1. (There's
36no need to use -noleaf in ``find``, btw.)
37
38No timestamps are stored in a cramfs, so these default to the epoch
39(1970 GMT). Recently-accessed files may have updated timestamps, but
40the update lasts only as long as the inode is cached in memory, after
41which the timestamp reverts to 1970, i.e. moves backwards in time.
42
43Currently, cramfs must be written and read with architectures of the
44same endianness, and can be read only by kernels with PAGE_SIZE
45== 4096. At least the latter of these is a bug, but it hasn't been
46decided what the best fix is. For the moment if you have larger pages
47you can just change the #define in mkcramfs.c, so long as you don't
48mind the filesystem becoming unreadable to future kernels.
49
50
51Memory Mapped cramfs image
52--------------------------
53
54The CRAMFS_MTD Kconfig option adds support for loading data directly from
55a physical linear memory range (usually non volatile memory like Flash)
56instead of going through the block device layer. This saves some memory
57since no intermediate buffering is necessary to hold the data before
58decompressing.
59
60And when data blocks are kept uncompressed and properly aligned, they will
61automatically be mapped directly into user space whenever possible providing
62eXecute-In-Place (XIP) from ROM of read-only segments. Data segments mapped
63read-write (hence they have to be copied to RAM) may still be compressed in
64the cramfs image in the same file along with non compressed read-only
65segments. Both MMU and no-MMU systems are supported. This is particularly
66handy for tiny embedded systems with very tight memory constraints.
67
68The location of the cramfs image in memory is system dependent. You must
69know the proper physical address where the cramfs image is located and
70configure an MTD device for it. Also, that MTD device must be supported
71by a map driver that implements the "point" method. Examples of such
72MTD drivers are cfi_cmdset_0001 (Intel/Sharp CFI flash) or physmap
73(Flash device in physical memory map). MTD partitions based on such devices
74are fine too. Then that device should be specified with the "mtd:" prefix
75as the mount device argument. For example, to mount the MTD device named
76"fs_partition" on the /mnt directory::
77
78 $ mount -t cramfs mtd:fs_partition /mnt
79
80To boot a kernel with this as root filesystem, suffice to specify
81something like "root=mtd:fs_partition" on the kernel command line.
82
83
84Tools
85-----
86
87A version of mkcramfs that can take advantage of the latest capabilities
88described above can be found here:
89
90https://github.com/npitre/cramfs-tools
91
92
93For /usr/share/magic
94--------------------
95
96===== ======================= =======================
970 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"
107512 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"
117===== ======================= =======================
118
119
120Hacker Notes
121------------
122
123See fs/cramfs/README for filesystem layout and implementation notes.
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 supported, but hard linked files
32will still have a link count of 1 in the cramfs image.
33
34Cramfs directories have no ``.`` or ``..`` entries. Directories (like
35every other file on cramfs) always have a link count of 1. (There's
36no need to use -noleaf in ``find``, btw.)
37
38No timestamps are stored in a cramfs, so these default to the epoch
39(1970 GMT). Recently-accessed files may have updated timestamps, but
40the update lasts only as long as the inode is cached in memory, after
41which the timestamp reverts to 1970, i.e. moves backwards in time.
42
43Currently, cramfs must be written and read with architectures of the
44same endianness, and can be read only by kernels with PAGE_SIZE
45== 4096. At least the latter of these is a bug, but it hasn't been
46decided what the best fix is. For the moment if you have larger pages
47you can just change the #define in mkcramfs.c, so long as you don't
48mind the filesystem becoming unreadable to future kernels.
49
50
51Memory Mapped cramfs image
52--------------------------
53
54The CRAMFS_MTD Kconfig option adds support for loading data directly from
55a physical linear memory range (usually non volatile memory like Flash)
56instead of going through the block device layer. This saves some memory
57since no intermediate buffering is necessary to hold the data before
58decompressing.
59
60And when data blocks are kept uncompressed and properly aligned, they will
61automatically be mapped directly into user space whenever possible providing
62eXecute-In-Place (XIP) from ROM of read-only segments. Data segments mapped
63read-write (hence they have to be copied to RAM) may still be compressed in
64the cramfs image in the same file along with non compressed read-only
65segments. Both MMU and no-MMU systems are supported. This is particularly
66handy for tiny embedded systems with very tight memory constraints.
67
68The location of the cramfs image in memory is system dependent. You must
69know the proper physical address where the cramfs image is located and
70configure an MTD device for it. Also, that MTD device must be supported
71by a map driver that implements the "point" method. Examples of such
72MTD drivers are cfi_cmdset_0001 (Intel/Sharp CFI flash) or physmap
73(Flash device in physical memory map). MTD partitions based on such devices
74are fine too. Then that device should be specified with the "mtd:" prefix
75as the mount device argument. For example, to mount the MTD device named
76"fs_partition" on the /mnt directory::
77
78 $ mount -t cramfs mtd:fs_partition /mnt
79
80To boot a kernel with this as root filesystem, suffice to specify
81something like "root=mtd:fs_partition" on the kernel command line.
82
83
84Tools
85-----
86
87A version of mkcramfs that can take advantage of the latest capabilities
88described above can be found here:
89
90https://github.com/npitre/cramfs-tools
91
92
93For /usr/share/magic
94--------------------
95
96===== ======================= =======================
970 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"
107512 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"
117===== ======================= =======================
118
119
120Hacker Notes
121------------
122
123See fs/cramfs/README for filesystem layout and implementation notes.