fatd

fatd is the private FAT-family filesystem provider daemon behind vfsd. It is started by rootd after e2fsd and before vfsd, and it is reachable only through the provider endpoint delegated to vfsd.

EriX is a clean-room, capability-based microkernel operating system written entirely in Rust.

Technical requirements are tracked in the EriX requirements, conventions, and project documentation.

See:

• docs for design documents, specifications, and development plans.
• Related architecture repositories for kernel, services, libraries, drivers, and integration tooling.

Purpose of This Repository

This repository implements the EriX FAT-family filesystem provider. Its purpose in EriX is to serve validated FAT and exFAT media behind vfsd without exposing a public service.

Functionally, it parses FAT-family media, validates directory/allocation state, and implements provider file/directory operations. The repository keeps the implementation, interface contracts, tests, and documentation for that behavior in one reviewable ownership boundary.

The maintained responsibilities are:

• serve FAT-family and exFAT filesystems only through the private filesystem-provider ABI
• validate boot sectors, allocation metadata, directory entries, and name state before exposing mounts
• implement persistent file and directory operations through the assigned blockd endpoint
• keep provider authority private with no named entry or public client endpoint

Clean-Room Policy

EriX follows a strict clean-room philosophy:

• No external source code may be copied.
• No external Rust crates are allowed.
• No code generation tools that embed third-party code.
• All code must be authored within the project.

Violations will result in rejection of the contribution.

License

All EriX repositories are licensed under the ISC License.

Development Model

EriX development is modular, deterministic, reproducible, authority-explicit, security-first, and self-hosting oriented.

This repository follows the project roadmap and the validation rules documented in its own roadmap.

Current Status

The provider service, startup validation, generic ABI dispatch, CI, and block-backed FAT12/FAT16/FAT32/exFAT media engine are present. Mount reads device metadata and the boot sector through the private blockd endpoint, keeps runtime IPC, mount-validation, directory-scan, and FAT table scratch state in service-static buffers instead of large stack frames, batches mount-time FAT sector reads through bounded caches, classifies FAT12/FAT16/FAT32 by cluster-count thresholds, validates exFAT BPB, allocation bitmap, compressed upcase-table checksum, coverage, and mandatory mapping metadata for EXFAT provider-kind mounts, validates exFAT main and backup boot-region checksums before trusting BPB fields, checks mirrored FATs before accepting a FAT12/16/32 mount, safely repairs exactly one divergent FAT mirror when a writable volume has at least three mirrors and the remaining mirrors agree, validates FAT32 FSInfo signatures and range fields, parses FAT32 extended flags and backup boot-sector metadata, and validates FAT reserved entries, clean/dirty state, hard-error state, and volume ID/label/type metadata. fatd rejects read-write FAT16/FAT32 mounts when the format clean-shutdown or no-hard-error bit is clear, while read-only mounts may proceed after the full structural scan succeeds. It also rejects read-write FAT32 mounts with stale FSInfo counts or inconsistent primary/backup boot metadata. exFAT boot-region disagreement is fail-closed except for backup VolumeFlags and PercentInUse, which the format treats as stale. exFAT uses the primary VolumeFlags active-FAT selector to choose both the FAT and allocation bitmap; dirty or media-failure volumes are read-only-only, invalid reserved flag state fails closed, and successful writable metadata operations refresh primary PercentInUse from the allocation bitmap and clear the dirty bit before returning, while leaving backup checksum-excluded stale fields alone. exFAT root metadata validation rejects malformed allocation-bitmap entries, duplicate bitmap/upcase critical entries, bad upcase tables, and corrupt directory entry sets fail-closed before the mount is exposed. It parses Volume Label and Volume GUID entries as root metadata, preserves inert TexFAT padding and no-allocation benign vendor/unknown secondaries, rejects vendor allocation and unknown critical entry types, and treats every in-use benign metadata slot as occupied during allocation.

Runtime state stores mount records and open handles; file and directory operations resolve media directory entries on demand. The FAT engine supports FAT12 12-bit entries, FAT16 fixed root directories, FAT32 cluster-root/FSInfo metadata, exFAT allocation bitmap/upcase-table/directory-entry-set metadata, exFAT upcase-table filename keys and stream NameHash validation, VFAT long-name decode/write with strict ordinal/checksum/termination validation, media short-alias validation that accepts OEM bytes only behind valid VFAT LFN records, ASCII-only standalone short-name decoding, escaped leading 0xE5 rejection, deterministic 8.3 alias generation with duplicate-alias rejection, NT lowercase direct short entries, Unicode casefold lookup through lib-fs-name, mirrored FAT entry updates, exFAT bitmap/FAT updates, cluster allocation/freeing, malformed-chain rejection, mount-time referenced-chain validation for file and directory loops, bad cluster markers, out-of-range starts, and cross-linked chains, plus exFAT allocation-bitmap reconciliation across reachable FAT-chain and no-FAT-chain file/directory streams, metadata streams, duplicate ownership, leaked clusters, bitmap/FAT mismatches, loops, and out-of-range clusters, active-FAT selection when FAT32 mirroring is disabled, safe single mirror repair, persistent file data writeback, and FAT regular-file truncate with allocation shrink/free and zero-filled growth. FAT and exFAT directory-entry metadata is decoded and preserved for create/access/modify timestamps, read-only/hidden/system/archive attributes, directory type bits, and other primary-entry fields that the provider does not own. FAT additionally preserves volume-label entries and NT lowercase short-name flags. New FAT and exFAT entries use the FAT epoch in UTC because fatd has no ambient wall-clock authority; caller-supplied set_metadata timestamps are encoded as explicit UTC date/time fields. FAT access time is exposed at date-only precision and FAT modification time is rounded to two-second precision, while exFAT preserves creation and modification 10 ms increments and applies valid per-field UTC offsets deterministically. Creation time remains stat-only metadata because the v1 ABI has no creation-time mutation flag. Unit coverage includes FAT12 entry packing, FAT16 fixed-root create/write/read, FAT reserved-entry validation, dirty/error read-only-only policy, reserved-entry writeback preservation, FAT timestamp encoding, attribute preservation/mutation, lowercase short-name flags, valid VFAT LFN records with OEM-byte aliases, invalid attribute-combination rejection, malformed standalone short-name byte and NT flag rejection, ambiguous LFN/short visible-name rejection, FAT rename metadata preservation, compatible file and empty-directory replacement, cycle and non-empty-directory replacement rejection, FAT truncate coverage for shrink-to-zero, in-cluster shrink, cross-cluster shrink, zero-filled growth, FAT32 FSInfo update, and active-FAT policy, FAT32 active-FAT selection, missing/corrupt backup boot sectors, exFAT mount validation, active-FAT/active-bitmap selection, dirty/media-failure policy, clean dirty-bit writeback, malformed upcase rejection, exFAT NameHash validation, duplicate upcase-equivalent name rejection, malformed UTF-16 name rejection, exFAT create/write/read/readdir/unlink/rename persistence, exFAT compatible rename replacement with no-FAT-chain destination cleanup, Unicode casefold lookups, alias collision handling including dense suffix growth, strict VFAT malformed-chain rejection, duplicate short-alias rejection, exact valid UTF-16 payload preservation, fragmented multi-cluster files, directory growth/deep paths, open-target unlink denial, read-only write denial, and single divergent mirror repair. The VM and host-media corpus covers FAT12 and FAT16 ESP media in addition to primary-only, mirrored, active-FAT, and malformed-backup FAT32 fixtures plus clean, dirty, hard-error, and malformed reserved-entry FAT32 metadata fixtures and FAT12/FAT16/FAT32 directory-metadata fixtures verified with host FAT tools, plus a focused FAT32 metadata-set fixture that validates host-created timestamps and VFS-updated atime/mtime/attribute fields with mtools and direct directory-entry checks. FAT-04 adds host-tool-generated VFAT Unicode/dense-alias media plus patched ordinal, orphan-chain, duplicate-alias, short-byte, NT-flag, and ambiguous-LFN negative media; FAT-05 adds fragmented allocation, grown-directory/free-slot reuse, sparse-looking writeback, cross-linked-file, looped-chain, bad-cluster, out-of-range-chain, and inconsistent-FSInfo coverage; focused FAT12/FAT16/FAT32 truncate VM scenarios verify shrink/grow/zero-fill through vfsd and post-VM host mtools, fsck.fat, and direct FAT/FSInfo checks; exFAT now has deterministic ESP media generation, one-FAT/two-FAT active-state scenario definitions, boot-region positive/negative coverage, upcase-table Unicode lookup and NameHash positive/negative coverage, allocation-reconciliation positive/negative coverage, stream ValidDataLength/DataLength coverage, path truncate support, no-FAT-chain growth conversion, sparse-valid-data reads, fragmented-stream fixtures, and host-side image verification in integration. The provider dispatch also parses the expanded generic filesystem-provider ABI for rename, truncate, symlink/readlink, hard-link, and metadata-update requests. FAT and exFAT media implement rename, regular-file path truncate, and flagged metadata updates for supported attribute and timestamp fields; unsupported symlink/readlink, hard-link, and UID/GID ownership requests return explicit DENIED responses. exFAT media validates file-primary attributes, timestamp increments, and UTC offsets fail-closed, enforces read-only attributes across open/write/truncate/unlink paths, and preserves unsupported primary-entry fields across supported mutations.

Validation

• cargo fmt --all -- --check
• strict cargo clippy --all-targets --all-features -- -D warnings
• cargo test --all-targets --all-features
• integration image builds through the Filesystem provider work fixture path

Governance Principles

fatd governance is scoped to private FAT-family and exFAT filesystem service behind vfsd.

The scoped governance rules are:

• It serves FAT-family media only through the generic private provider ABI.
• It must reject malformed boot sectors, unsafe mirror divergence, invalid allocation metadata, and unsupported partial mounts.
• It performs media mutation only through the provider-local blockd endpoint.
• It never exposes a public named service endpoint or peer-provider authority.

Authority Boundaries

• fatd receives only its provider endpoint and provider-local blockd endpoint.
• It does not receive keyd, deviced, driver, or peer-filesystem authority.

Contact

Development occurs in EriX organization and discussions happen in issues and design documents.

No decisions are considered valid without documented rationale.

Maintainers can be reached via email: admin@erikinkinen.fi.