update

tests/G3-MANUAL-SETUP.md

@@ -0,0 +1,71 @@
+# G3 Manual Test Setup
+
+This setup supports only TC041-TC066, TC141, TC148, TC149, TC152, and
+TC153. It prepares deterministic fixtures and native probes; it does not assign
+runtime results.
+
+## Host Preparation
+
+From the `repo-pre-15` root, use an absent output directory:
+
+```sh
+git rev-parse HEAD
+tests/prepare_g3_fixtures.sh /work/build/repo-pre15-g3
+python3 -B tests/pre15/fixtures/g3.py verify \
+  --output /work/build/repo-pre15-g3
+sha256sum /work/build/repo-pre15-g3/G3-MANIFEST.json
+```
+
+The maintained generator is `tests/pre15/fixtures/g3.py`. The compatibility
+entry point `tests/g3_fixtures.py` delegates to it. Normal generation does not
+read `tests/results/`; B01 separately proves that the migrated metadata and
+final-review sets match both archived scripts byte for byte.
+
+`G3-MANIFEST.json` records the generator SHA256, erofs-utils identity, exact
+`mkfs.erofs` argv, canonical source-tree inventories, image hashes, and expected
+directory sets. Record this manifest, all checksum files, the exact source
+commit, and the KLD SHA256. Transfer the fixtures, sources, and only these native
+probes to the FreeBSD 15 guest:
+
+```text
+readdir_probe.c g3_vfs_probe.c stat_special.c nfs_fh_tool.c
+mmap_fault.c sparse_hole_probe.c
+```
+
+## Guest Preparation
+
+Build the KLD natively from an archive exported from the recorded commit. Build
+the probes directly:
+
+```sh
+cc -O2 -Wall -Wextra -Werror -std=c17 readdir_probe.c -o readdir_probe
+cc -O2 -Wall -Wextra -Werror -std=c17 g3_vfs_probe.c -o g3_vfs_probe
+cc -O2 -Wall -Wextra -Werror -std=c17 stat_special.c -o stat_special
+cc -O2 -Wall -Wextra -Werror -std=c17 nfs_fh_tool.c -o nfs_fh_tool
+cc -O2 -Wall -Wextra -Werror -std=c17 mmap_fault.c -o mmap_fault
+cc -O2 -Wall -Wextra -Werror -std=c17 sparse_hole_probe.c \
+  -o sparse_hole_probe
+```
+
+Before the first test, require no EROFS mount, no md provider, and no stale
+EROFS KLD. Load only the exact KLD under test. For each test, attach a fresh
+dynamic vnode md, mount read-only, execute that numbered Markdown procedure,
+then unmount and detach before continuing.
+
+The report records the literal command, exit status or syscall errno, relevant
+fixture/data/KLD hashes, dmesg delta, and cleanup state for every test.
+
+## Common Mount Pattern
+
+```sh
+mkdir -p /tmp/repo-pre15-g3/mnt
+unit=$(mdconfig -a -t vnode -f IMAGE)
+mount -t erofs -o ro "/dev/$unit" /tmp/repo-pre15-g3/mnt
+# Execute exactly one numbered test.
+umount /tmp/repo-pre15-g3/mnt
+mdconfig -d -u "$unit"
+```
+
+TC153 additionally creates and removes its documented multi-terabyte sparse
+provider. Final cleanup requires zero EROFS mounts, zero owned md providers, the
+test KLD unloaded, and all guest-generated sparse files removed.