From: Nicolas Pitre <nico@fluxnic.net>
Date: Wed, 22 Apr 2026 21:10:38 +0000 (-0400)
Subject: Documentation: filesystems: cramfs: correct stale hard-link and endianness claims
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=077f0972192390191279700194b6a230a5662127;p=thirdparty%2Fkernel%2Flinux.git

Documentation: filesystems: cramfs: correct stale hard-link and endianness claims

Two paragraphs in cramfs.rst have been misleading for a long time:

 - "Hard links are supported, but hard linked files will still have
   a link count of 1": mkcramfs does not preserve hard links; it
   deduplicates by content (eliminate_doubles()).  Two names for
   the same on-disk inode in the source tree become two separate
   (content-shared) entries in the image, and cramfs always reports
   a link count of 1.

 - "Currently, cramfs must be written and read with architectures of
   the same endianness ... PAGE_SIZE == 4096 ... is a bug, but it
   hasn't been decided what the best fix is": the endianness
   situation has been settled for years -- the kernel checks for
   CRAMFS_MAGIC_WEND in cramfs_fill_super() and refuses the mount,
   and mkcramfs has gained -B / -L for producing images of the
   opposite endianness from the build host (useful for cross-builds,
   but the reader still needs to match).  Restate this accurately.

Signed-off-by: Nicolas Pitre <nico@fluxnic.net>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260422211039.270552-1-nico@fluxnic.net>
---

diff --git a/Documentation/filesystems/cramfs.rst b/Documentation/filesystems/cramfs.rst
index afbdbde98bd25..221c0bf91b9c8 100644
--- a/Documentation/filesystems/cramfs.rst
+++ b/Documentation/filesystems/cramfs.rst
@@ -28,8 +28,10 @@ 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 supported, but hard linked files
-will still have a link count of 1 in the cramfs image.
+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 cramfs 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
@@ -40,12 +42,16 @@ No timestamps are stored in a cramfs, so these default to the epoch
 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.
 
-Currently, cramfs must be written and read with architectures of the
-same endianness, and can be read only by kernels with PAGE_SIZE
-== 4096.  At least the latter of these is a bug, but it hasn't been
-decided what the best fix is.  For the moment if you have larger pages
-you can just change the #define in mkcramfs.c, so long as you don't
-mind the filesystem becoming unreadable to future kernels.
+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.
 
 
 Memory Mapped cramfs image