update

docs/erofs.5

@@ -0,0 +1,271 @@
+.\" Copyright (c) 2026
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd August 9, 2026
+.Dt EROFS 5
+.Os
+.Sh NAME
+.Nm erofs
+.Nd Enhanced Read-Only File System
+.Sh SYNOPSIS
+To mount an
+.Nm
+volume:
+.Bd -literal -offset indent
+mount -t erofs /dev/da0 /mnt
+.Ed
+.Sh DESCRIPTION
+The
+.Nm
+driver provides read-only support for the Enhanced Read-Only File System
+(EROFS), a modern compressed read-only filesystem designed for space
+efficiency and performance.
+EROFS is widely used in Linux distributions and mobile systems for root
+filesystems, firmware images, and container layers.
+.Pp
+The
+.Fx
+implementation supports multiple compression algorithms, various data layouts,
+extended attributes, and multi-device configurations.
+.Pp
+The currently qualified build target is
+.Fx 15
+on
+.Sy amd64 .
+The module Makefile rejects other architectures because they have not been
+validated against this implementation's kernel ABI.
+.Sh FEATURES
+.Ss Inode Types
+The
+.Nm
+driver supports both compact and extended inode formats:
+.Bl -bullet -compact
+.It
+Compact inodes (32 bytes) for typical files
+.It
+Extended inodes (64 bytes) with extended metadata
+.It
+Special handling for single-link files
+.It
+Inline data (tailpacking) for small files
+.El
+.Ss Data Layouts
+.Bl -bullet -compact
+.It
+.Sy FLAT_PLAIN :
+Uncompressed contiguous data
+.It
+.Sy FLAT_INLINE :
+Uncompressed data with inline tail
+.It
+.Sy Chunk-based :
+Fixed-size chunks for multi-device support
+.It
+.Sy Compressed :
+LZ4, DEFLATE, zstd, or LZMA compressed data with pcluster mapping
+.El
+.Ss Compression Algorithms
+.Bl -tag -width "MicroLZMA"
+.It Sy LZ4
+Fast decompression for general-purpose use, including ztailpacking
+(compressed tail in inode metadata)
+.It Sy DEFLATE
+Standard compression with good compression ratio
+.It Sy zstd
+High compression ratio when the module is built with
+.Va WITH_ZSTDIO=1 .
+ZSTD support is disabled by default
+.Pq Va WITH_ZSTDIO=0 ,
+and an enabled module requires a kernel built with
+.Cd "options ZSTDIO" .
+.It Sy LZMA/MicroLZMA
+Maximum compression ratio for space-constrained environments
+.El
+.Ss Extended Attributes
+.Bl -bullet -compact
+.It
+Shared extended attributes with metabox container support
+.It
+Inline extended attributes
+.It
+Long-prefix extended attribute support
+.It
+Packed prefix table support
+.It
+POSIX ACL support (access and default ACLs)
+.El
+.Pp
+User namespace attributes are exposed without prefix; system namespace
+attributes retain their full qualified names (trusted.*, security.*).
+.Pp
+Linux POSIX access/default ACL xattrs are decoded into
+.Fx
+POSIX.1e ACLs when present.
+ACL and xattr mutation remains read-only.
+.Ss Advanced Features
+.Bl -bullet -compact
+.It
+Superblock CRC32C verification
+.It
+48-bit block count and root nid support
+.It
+Device table for multi-device volumes
+.It
+Qualified fragment-backed compressed files and metabox carriers
+.It
+VFS hash integration and namecache support
+.It
+Directory entry optimization (dot_omitted handling)
+.It
+NFS export with stable superblock-seeded per-inode file-handle generations
+.It
+.Fx
+local vnode pager support for read-only mappings
+.El
+.Sh MOUNT OPTIONS
+The
+.Nm
+filesystem supports standard read-only mount options and the following
+filesystem-specific option:
+.Bl -tag -width "device.N=/dev/mdN"
+.It Cm device.N= Ns Pa path
+Map one-based on-disk external device slot
+.Ar N
+to the disk provider at
+.Ar path .
+The slot number is part of the option name, so option order has no effect.
+Every declared external slot must be supplied exactly once when external blob
+providers are used.
+Reusing the primary provider or one external provider for
+multiple slots is rejected.
+.El
+.Pp
+There is no filesystem-specific
+.Pa /sbin/mount_erofs
+utility in this repository.
+Use the generic
+.Xr mount 8
+frontend with
+.Fl t Cm erofs ;
+it passes the filesystem-specific option names to
+.Xr nmount 2 .
+.Pp
+If the image has a device table and no
+.Cm device.N
+options are supplied, the primary provider is treated as a flatdev image.
+It
+must contain every declared device range at its on-disk unified block address.
+The driver forces every successful mount read-only.
+An explicit
+.Fl o Cm rw
+request therefore still produces a read-only mount; it does not enable writes
+and is not rejected solely because
+.Cm rw
+was requested.
+Mutating vnode operations fail with
+.Er EROFS .
+.Sh EXAMPLES
+Mount an EROFS image from a disk device:
+.Bd -literal -offset indent
+mount -t erofs -o ro /dev/da0s1 /mnt
+.Ed
+.Pp
+Mount an EROFS image from a regular file using
+.Xr mdconfig 8 :
+.Bd -literal -offset indent
+mdconfig -a -t vnode -f rootfs.img -u 0
+mount -t erofs -o ro /dev/md0 /mnt
+.Ed
+.Pp
+Mount a split image with two external blob slots.
+The deliberately reversed
+option order demonstrates that slot mapping is deterministic:
+.Bd -literal -offset indent
+mdconfig -a -t vnode -f primary.img -u 90
+mdconfig -a -t vnode -f blob1.img -u 91
+mdconfig -a -t vnode -f blob2.img -u 92
+mount -t erofs -o ro -o device.2=/dev/md92 \
+    -o device.1=/dev/md91 /dev/md90 /mnt
+.Ed
+.Pp
+Mount a flatdev image containing the primary image followed by all declared
+unified device ranges:
+.Bd -literal -offset indent
+mdconfig -a -t vnode -f combined-flatdev.img -u 90
+mount -t erofs -o ro /dev/md90 /mnt
+.Ed
+.Pp
+Unmount an EROFS filesystem:
+.Bd -literal -offset indent
+umount /mnt
+.Ed
+.Sh DIAGNOSTICS
+Error messages are logged via
+.Xr printf 9
+when filesystem inconsistencies are detected, such as:
+.Bl -bullet -compact
+.It
+Invalid superblock magic number
+.It
+Superblock CRC32C checksum mismatch
+.It
+Unsupported compression algorithm
+.It
+Invalid inode format
+.It
+Invalid or unrepresentable inode timestamps
+.It
+Corrupted directory entries
+.It
+Compressed extent address arithmetic overflow
+.It
+Inline data crossing its inode metadata block or declared backing bounds
+.It
+Missing, short, or orphaned external providers
+.It
+Malformed or overlapping device-table ranges
+.El
+.Sh SEE ALSO
+.Xr nmount 2 ,
+.Xr mdconfig 8 ,
+.Xr mount 8 ,
+.Xr umount 8 ,
+.Xr printf 9
+.Sh HISTORY
+EROFS was originally developed for Linux by Huawei in 2019.
+The
+.Fx
+implementation first appeared in 2026.
+.Sh AUTHORS
+.An Ruicheng Pan
+.Sh BUGS
+.Bl -bullet -compact
+.It
+The driver is read-only and does not claim support for every future EROFS
+incompat feature or every dedupe encoding.
+.It
+There is no automated kernel regression harness; the repository records
+.Fx 15
+manual-test procedures and results.
+.El