Cramfs - cram a filesystem onto a small ROM

cramfs is designed to be simple and small, and to compress things well. 

It uses the zlib routines to compress a file one page at a time, and
allows random page access.  The meta-data is not compressed, but is
expressed in a very terse representation to make it use much less
diskspace than traditional filesystems. 

You can't write to a cramfs filesystem (making it compressible and
compact also makes it _very_ hard to update on-the-fly), so you have to
create the disk image with the "mkcramfs" utility.


Usage Notes
-----------

File sizes are limited to less than 16MB.

Maximum filesystem size is a little over 256MB.  (The last file on the
filesystem is allowed to extend past 256MB.)

Only the low 8 bits of gid are stored.  The current version of
mkcramfs simply truncates to 8 bits, which is a potential security
issue.

Hard links are not preserved.  mkcramfs deduplicates files with
identical content, but two names for the same on-disk inode in the
source tree become two separate (content-shared) entries in the
image, and the kernel always reports a link count of 1.

Cramfs directories have no `.' or `..' entries.  Directories (like
every other file on cramfs) always have a link count of 1.  (There's
no need to use -noleaf in `find', btw.)

No timestamps are stored in a cramfs, so these default to the epoch
(1970 GMT).  Recently-accessed files may have updated timestamps, but
the update lasts only as long as the inode is cached in memory, after
which the timestamp reverts to 1970, i.e. moves backwards in time.

This version of mkcramfs implements block pointer extensions that allows
for uncompressed blocks and random block placementt. Currently this is
used to avoid compressing small files that end up taking more space once
"compressed" (enabled with mkcramfs -x). A kernel with the appropriate
support is required (from Linux v4.15).

It is possible to have some files, or portions of some files, kept
uncompressed and properly aligned to allow direct mapping into user
space for eXecute-In-Place (XIP) of program files. This requires that
the cramfs image be stored in ROM or Flash and accessible via the memory
bus. This is currently performed on the read-only segments of ELF files
with mkcramfs -X (or -X twice for target systems with a MMU for which a
greater alignment is necessary). This implies -x as described above.

The on-disk layout is host-endian: the kernel does not swab, and
refuses to mount an image whose endianness does not match the CPU.
For cross-builds, mkcramfs -B / -L forces the output endianness so
that a host of one endianness can produce an image for a target of
the other.

The on-disk block size is fixed at 4096 bytes.  On systems with a
larger PAGE_SIZE you can change the #define in mkcramfs.c, with the
caveat that the resulting image will only be readable on kernels
configured for the same PAGE_SIZE.


Tools
-----

This repository provides two user-space tools:

  mkcramfs <dir> <image>
      Build a cramfs image from a directory tree.  Options:
        -e N      set edition number (part of fsid)
        -n NAME   set filesystem name
        -i FILE   insert FILE as a pre-built image
        -D FILE   use FILE as a device table
        -p        pad the first 512 bytes for boot code
        -q        squash ownership to root
        -z        emit explicit holes (requires kernel >= 2.3.39)
        -x        use extended block pointers; skip compression for
                  blocks that would grow (requires kernel >= 4.15)
        -X        align read-only ELF segments for XIP (implies -x);
                  pass twice for MMU-grade alignment
        -B / -L   force big- or little-endian output
        -E        treat warnings as errors
        -s        (accepted for compatibility, ignored)
        -v        verbose

  cramfsck [-v] [-c] [-x DIR] <image>
      Check a cramfs image and optionally extract it.  -x DIR
      extracts the image below DIR.  -v prints each inode as it is
      visited; -c continues past recoverable errors and reports an
      aggregate exit code at the end.

Hacker Notes
------------

See NOTES in this directory for filesystem layout and implementation
notes.  The equivalent file in the Linux kernel tree lives at
Documentation/filesystems/cramfs.rst (historically fs/cramfs/README).

Altered cramfs inode representations exist in the field, presumably as an
attempt by some vendor at obfuscating their firmware images. Please see
#10 for details.