update

README.md

@@ -0,0 +1,90 @@
+# 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.