[PATCH 1/2] Documentation: filesystems: cramfs: correct stale hard-link and endianness claims

[PATCH 1/2] Documentation: filesystems: cramfs: correct stale hard-link and endianness claims

[Nicolas Pitre]

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>
---
 Documentation/filesystems/cramfs.rst | 22 ++++++++++++++--------
 1 file changed, 14 insertions(+), 8 deletions(-)

diff --git a/Documentation/filesystems/cramfs.rst b/Documentation/filesystems/cramfs.rst
index afbdbde98bd2..221c0bf91b9c 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
-- 
2.53.0

[PATCH 2/2] cramfs: drop obsolete Future Development notes and update tools URL

[Nicolas Pitre]

fs/cramfs/README still carries a "Future Development" section written
around the Linux 2.3.39 era discussing design decisions that have long
since been settled:

  - Block size is 4096 and matches PAGE_SIZE on the reader.
  - Endianness is host-endian; mkcramfs -B / -L handles cross-builds.
  - Block-pointer extensions (CRAMFS_FLAG_EXT_BLOCK_POINTERS) ended up
    being the answer to layout flexibility rather than inode growth.

Drop the stale forward-looking section -- the factual format
description above remains accurate and is kept as-is.

While here, replace the dead sourceforge URL in the "Tools" section
with the current location of the user-space tools on github.

Signed-off-by: Nicolas Pitre <nico@fluxnic.net>
---
 fs/cramfs/README | 92 +-----------------------------------------------
 1 file changed, 1 insertion(+), 91 deletions(-)

diff --git a/fs/cramfs/README b/fs/cramfs/README
index 778df5c4d70b..c0052a11aa28 100644
--- a/fs/cramfs/README
+++ b/fs/cramfs/README
@@ -104,94 +104,4 @@ Tools
 -----
 
 The cramfs user-space tools, including mkcramfs and cramfsck, are
-located at <http://sourceforge.net/projects/cramfs/>.
-
-
-Future Development
-==================
-
-Block Size
-----------
-
-(Block size in cramfs refers to the size of input data that is
-compressed at a time.  It's intended to be somewhere around
-PAGE_SIZE for cramfs_read_folio's convenience.)
-
-The superblock ought to indicate the block size that the fs was
-written for, since comments in <linux/pagemap.h> indicate that
-PAGE_SIZE may grow in future (if I interpret the comment
-correctly).
-
-Currently, mkcramfs #define's PAGE_SIZE as 4096 and uses that
-for blksize, whereas Linux-2.3.39 uses its PAGE_SIZE, which in
-turn is defined as PAGE_SIZE (which can be as large as 32KB on arm).
-This discrepancy is a bug, though it's not clear which should be
-changed.
-
-One option is to change mkcramfs to take its PAGE_SIZE from
-<asm/page.h>.  Personally I don't like this option, but it does
-require the least amount of change: just change `#define
-PAGE_SIZE (4096)' to `#include <asm/page.h>'.  The disadvantage
-is that the generated cramfs cannot always be shared between different
-kernels, not even necessarily kernels of the same architecture if
-PAGE_SIZE is subject to change between kernel versions
-(currently possible with arm and ia64).
-
-The remaining options try to make cramfs more sharable.
-
-One part of that is addressing endianness.  The two options here are
-`always use little-endian' (like ext2fs) or `writer chooses
-endianness; kernel adapts at runtime'.  Little-endian wins because of
-code simplicity and little CPU overhead even on big-endian machines.
-
-The cost of swabbing is changing the code to use the le32_to_cpu
-etc. macros as used by ext2fs.  We don't need to swab the compressed
-data, only the superblock, inodes and block pointers.
-
-
-The other part of making cramfs more sharable is choosing a block
-size.  The options are:
-
-  1. Always 4096 bytes.
-
-  2. Writer chooses blocksize; kernel adapts but rejects blocksize >
-     PAGE_SIZE.
-
-  3. Writer chooses blocksize; kernel adapts even to blocksize >
-     PAGE_SIZE.
-
-It's easy enough to change the kernel to use a smaller value than
-PAGE_SIZE: just make cramfs_read_folio read multiple blocks.
-
-The cost of option 1 is that kernels with a larger PAGE_SIZE
-value don't get as good compression as they can.
-
-The cost of option 2 relative to option 1 is that the code uses
-variables instead of #define'd constants.  The gain is that people
-with kernels having larger PAGE_SIZE can make use of that if
-they don't mind their cramfs being inaccessible to kernels with
-smaller PAGE_SIZE values.
-
-Option 3 is easy to implement if we don't mind being CPU-inefficient:
-e.g. get read_folio to decompress to a buffer of size MAX_BLKSIZE (which
-must be no larger than 32KB) and discard what it doesn't need.
-Getting read_folio to read into all the covered pages is harder.
-
-The main advantage of option 3 over 1, 2, is better compression.  The
-cost is greater complexity.  Probably not worth it, but I hope someone
-will disagree.  (If it is implemented, then I'll re-use that code in
-e2compr.)
-
-
-Another cost of 2 and 3 over 1 is making mkcramfs use a different
-block size, but that just means adding and parsing a -b option.
-
-
-Inode Size
-----------
-
-Given that cramfs will probably be used for CDs etc. as well as just
-silicon ROMs, it might make sense to expand the inode a little from
-its current 12 bytes.  Inodes other than the root inode are followed
-by filename, so the expansion doesn't even have to be a multiple of 4
-bytes.
+located at <https://github.com/npitre/cramfs-tools>.
-- 
2.53.0

Re: [PATCH 1/2] Documentation: filesystems: cramfs: correct stale hard-link and endianness claims

[Jonathan Corbet]

Nicolas Pitre <nico@fluxnic.net> writes:

> 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>
> ---
>  Documentation/filesystems/cramfs.rst | 22 ++++++++++++++--------
>  1 file changed, 14 insertions(+), 8 deletions(-)

I've applied both patches, thanks.

jon