erofs-freebsd-out-tree/docs/pre13-h04-root-validation.md

Pre13 H04 Root Inode Validation

Scope

H04 adds one mount-time format check in src/super.c: the decoded root inode must have FreeBSD vnode type VDIR.

The check runs after packed and metabox inode initialization and before xattr prefix initialization or publication of mp->mnt_data. No vnode is created and no permanent root inode reference is retained.

Error Contract

A decodable non-directory root violates the EROFS filesystem structure. The mount therefore fails with positive FreeBSD errno EINTEGRITY.

This intentionally differs from Linux's negative EINVAL return while keeping the same format rejection. EINTEGRITY matches the existing FreeBSD EROFS contract for decodable on-disk metadata that violates filesystem invariants.

Ownership Review

• The temporary struct erofs_node is stack-owned and has no independent allocations or vnode references.
• Decode failures and the type rejection use the existing fail path.
• erofs_sb_free() releases extent-cache state, internal inodes, external devices, and the primary GEOM device in the established reverse order.
• The failure occurs before xattr prefixes, mount data, mount flags, or a root vnode are published.
• The legal directory-root path is unchanged after the new check.

Validation Gate

The required targeted QEMU validation is:

1. Build and load the current DUT module.
2. Mount the valid paired fixture, verify mode 040755, read its proof file, and unmount it.
3. Mount the non-directory-root fixture and require exact errno EINTEGRITY.
4. Verify mount, md, KLD, and GEOM resources return to zero, then remount the valid fixture.
5. Verify the kernel log has no panic, trap, or lock warning.

No full feature suite is part of H04.