91 lines
3.5 KiB
Markdown
91 lines
3.5 KiB
Markdown
# EROFS for FreeBSD
|
|
|
|
## Build Kernel Module
|
|
|
|
Build on FreeBSD 15 amd64 with a matching FreeBSD source tree. The default
|
|
source path is `/usr/src`:
|
|
|
|
```sh
|
|
WITH_ZSTDIO=0 ./build.sh
|
|
```
|
|
|
|
Use `FREEBSD_SRC=/path/to/freebsd-src` when the source tree is elsewhere. The
|
|
script is a native FreeBSD wrapper around `src/Makefile` and `bsd.kmod.mk`; the
|
|
Makefile is the authoritative module name, source list, architecture gate, and
|
|
per-source flag definition. Each run rebuilds `build/obj` and writes
|
|
`build/erofs.ko`.
|
|
|
|
Only `MACHINE_ARCH=amd64` is currently qualified. Other architectures are
|
|
rejected explicitly instead of inheriting amd64 ABI flags. Build ZSTD support
|
|
with:
|
|
|
|
```sh
|
|
WITH_ZSTDIO=1 ./build.sh
|
|
```
|
|
|
|
The enabled module references the FreeBSD kernel ZSTD API and therefore
|
|
requires a running kernel built with `options ZSTDIO`. `WITH_ZSTDIO=0` builds a
|
|
module without those references and rejects ZSTD-compressed images at mount.
|
|
|
|
## Mount
|
|
|
|
EROFS is read-only. Mount a single-device image with:
|
|
|
|
```sh
|
|
mount -t erofs -o ro /dev/md0 /mnt/erofs
|
|
```
|
|
|
|
For an image with external blob devices, map every one-based on-disk device
|
|
slot explicitly with `device.<slot>=<provider>`:
|
|
|
|
```sh
|
|
mount -t erofs -o ro \
|
|
-o device.2=/dev/md92 \
|
|
-o device.1=/dev/md91 \
|
|
/dev/md90 /mnt/erofs
|
|
```
|
|
|
|
Slot names make the mapping independent of option order. Every external slot
|
|
must be present exactly once; assigning the same GEOM provider to multiple
|
|
slots is rejected. The same names and values may be passed directly as
|
|
`nmount(2)` iovec entries.
|
|
|
|
There is no repo-local `mount_erofs` binary; FreeBSD's generic `/sbin/mount`
|
|
frontend passes these distinct option names through to `nmount(2)`. The driver
|
|
forces every successful mount read-only, so even `-o rw` produces a read-only
|
|
mount rather than enabling writes.
|
|
|
|
If an image has a device table but no `device.<slot>` options are supplied,
|
|
the primary provider is treated as a Linux-compatible flatdev image. It must
|
|
contain the external ranges at their declared `uniaddr` block offsets, for
|
|
example a deterministic concatenation of the primary image and its blobs.
|
|
|
|
## Qualified Semantics
|
|
|
|
- Compact/extended metadata, Linux device-number decode, plain/inline/chunk
|
|
data, and LZ4/MicroLZMA/DEFLATE/ZSTD compressed reads.
|
|
- Inline tails are confined to the inode metadata block and declared image or
|
|
metabox backing bounds.
|
|
- Directory lookup/readdir share strict validation while accepting Linux-style
|
|
nonzero unused bytes after the final name NUL.
|
|
- Compressed `st_blocks` reflects the inode's on-disk compressed block count;
|
|
uncompressed and chunk files retain logical block rounding.
|
|
- FreeBSD 15 local vnode pager sync/async entry points are used for real mmap
|
|
faults.
|
|
- NFS export uses full 64-bit NIDs and a generation derived from the
|
|
superblock seed and inode metadata. Replacing metadata changes the generation
|
|
and makes old handles stale; a metadata-identical, payload-only replacement
|
|
is not guaranteed to return `ESTALE`.
|
|
|
|
See `docs/features.md` for the bounded feature claim and
|
|
`tests/results/manual/2026-08-09T1804Z-final-review-independent/manual-test-report.md`
|
|
for the final-review evidence.
|
|
|
|
## Test Fixtures
|
|
|
|
`tests/prepare_directory_fixtures.sh` creates the deterministic TC048/141/148
|
|
directory fixtures. `tests/prepare_error_fixtures.sh` and
|
|
`tests/erofs_fixture.py` create and self-check the structured TC002/086/087/102
|
|
and TC112-TC116/119 fixtures. Generated trees, images, overlays, and `build/`
|
|
outputs are test artifacts and are not committed.
|