ra8_fs_check.h File Reference

Read-only on-device volume consistency check (fsck) for ra8_fs. More...

#include <stdint.h>
#include "ra8_err.h"
#include "ra8_fs.h"

Include dependency graph for ra8_fs_check.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ra8_fs_check_fault_t
	Where and what the first consistency finding was. More...
struct	ra8_fs_check_report_t
	The structured result of one ra8_fs_check run. More...

Enumerations
enum	ra8_fs_check_const_t : uint32_t { k_ra8_fs_check_unknown }
	Sentinels the check reports for values it could not determine. More...
enum	ra8_fs_check_fault_kind_t : uint8_t {   k_ra8_fs_check_fault_none = 0 ,   k_ra8_fs_check_fault_bad_fat_value = 1 ,   k_ra8_fs_check_fault_crosslink = 2 ,   k_ra8_fs_check_fault_lost_cluster = 3 ,   k_ra8_fs_check_fault_bad_chain = 4 ,   k_ra8_fs_check_fault_bad_dir_entry = 5 ,   k_ra8_fs_check_fault_bad_set_checksum = 6 ,   k_ra8_fs_check_fault_bad_name_hash = 7 ,   k_ra8_fs_check_fault_bitmap_ref_unset = 8 ,   k_ra8_fs_check_fault_free_count_bad = 9 ,   k_ra8_fs_check_fault_scan_truncated = 10 }
	The category of a single consistency finding. More...

Functions
ra8_err_t	ra8_fs_check (ra8_fs_mount_t *handle, uint8_t *bitmap, uint32_t bitmap_bytes, ra8_fs_check_report_t *report)
	Scan a mounted volume for consistency, read-only, and report findings.

Detailed Description

Read-only on-device volume consistency check (fsck) for ra8_fs.

The fsck.fat -n / fsck.exfat -n a headless product cannot outsource to a PC: ra8_fs_check walks a mounted volume, classifies every cluster, follows every directory chain and diffs what is referenced against what is allocated, and reports the findings in a ra8_fs_check_report_t. It is the answer to "can I trust this volume before I write to it" – because writing to an already-inconsistent volume is how partial damage becomes total damage.

It is read-only. There is no repair path here by design: a repair that runs on a volume already known to be inconsistent, in a firmware with no journal and no undo, is how a recoverable card becomes an empty one. A return of k_ra8_ok means the check RAN, not that the volume is clean – inspect ra8_fs_check_report_t::faults_total for that.

What it checks

FAT12 / FAT16 / FAT32:

• every FAT entry value is free, a valid in-range next-cluster, an end-of-chain marker, or the defective-cluster marker – anything else is a bad FAT value;
• directory entries reference a valid first cluster;
• no cluster is reached by two chains (cross-link) and no chain runs into free space or off the volume (bad chain);
• allocated clusters that no chain reaches are lost;
• on FAT32, the FSInfo free count agrees with the scan when its signatures validate.

exFAT:

• each File entry set's SetChecksum recomputes to the stored value;
• each Stream entry's NameHash recomputes to the stored value;
• the allocation bitmap agrees, in BOTH directions, with the clusters the entry sets (plus the bitmap, up-case and directory system runs) actually reference: a bit set with nothing referencing it is a lost cluster, a cluster referenced with its bit clear is a bitmap mismatch.

The caller-supplied bitmap

The reference / lost analysis needs one bit per data cluster to record which clusters a walk has visited – 128 KB for a 32 GB FAT32 card – which the platform's zero-heap rule (NASA P10 Rule 3) says must be caller-supplied. Pass a bitmap of at least (clusters_total + 7) / 8 bytes and the full check runs. Pass bitmap == NULL (or one too small) and the check falls back to the FAT / bitmap CLASSIFICATION pass only: the total / free / used / bad counts are still reported, ra8_fs_check_report_t::clusters_lost reads k_ra8_fs_check_unknown, and the reference-dependent fields stay zero.

Copyright

Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since

0.1.0

Definition in file ra8_fs_check.h.

Enumeration Type Documentation

ra8_fs_check_const_t

enum ra8_fs_check_const_t : uint32_t

Sentinels the check reports for values it could not determine.

Enumerator
k_ra8_fs_check_unknown	A count the check could not determine (no bitmap supplied).

Definition at line 77 of file ra8_fs_check.h.

ra8_fs_check_fault_kind_t

enum ra8_fs_check_fault_kind_t : uint8_t

The category of a single consistency finding.

Recorded in ra8_fs_check_report_t::first_fault to name what the first finding was; the per-category counts in the report say how many of each kind the whole scan found.

See also

ra8_fs_check_fault_t

ra8_fs_check_report_t

Since

0.1.0

Enumerator
k_ra8_fs_check_fault_none	No fault (a clean scan).
k_ra8_fs_check_fault_bad_fat_value	FAT entry is out of range / reserved.
k_ra8_fs_check_fault_crosslink	A cluster is reached by more than one chain.
k_ra8_fs_check_fault_lost_cluster	A cluster is allocated but referenced by none.
k_ra8_fs_check_fault_bad_chain	A chain runs into free space or off-volume.
k_ra8_fs_check_fault_bad_dir_entry	A directory entry's first cluster is invalid.
k_ra8_fs_check_fault_bad_set_checksum	exFAT entry-set SetChecksum mismatch.
k_ra8_fs_check_fault_bad_name_hash	exFAT Stream NameHash mismatch.
k_ra8_fs_check_fault_bitmap_ref_unset	exFAT: referenced, but its bitmap bit is 0.
k_ra8_fs_check_fault_free_count_bad	FAT32 FSInfo free count disagrees.
k_ra8_fs_check_fault_scan_truncated	The directory worklist hit its static bound.

Definition at line 99 of file ra8_fs_check.h.

Function Documentation

ra8_fs_check()

ra8_err_t ra8_fs_check ( ra8_fs_mount_t * handle, uint8_t * bitmap, uint32_t bitmap_bytes, ra8_fs_check_report_t * report )

nodiscard

Scan a mounted volume for consistency, read-only, and report findings.

Runs the passes described in this header's file comment for handle's filesystem and fills report. Nothing on the volume is written, so it is safe on a volume already suspected to be damaged – that is the whole point.

A return of k_ra8_ok means the scan COMPLETED, not that the volume is clean: a clean volume and a volume with a thousand lost clusters both return k_ra8_ok, and only report->faults_total tells them apart. A non-k_ra8_ok return means the scan could not run to completion – a null argument, an unmounted handle, or a backend read failure – and report retains its entry value. Findings are assembled in a private candidate and published only after the full scan succeeds, so callers cannot mistake partial counts for a completed check.

Pass bitmap of at least (report->clusters_total + 7) / 8 bytes to enable the reference / lost-cluster / cross-link analysis; pass bitmap == NULL (or fewer bytes) to run the classification pass alone (see the file comment). The bitmap is scratch: its contents on entry are ignored and on return undefined.

Parameters

[in]	handle	Mount handle from ra8_fs_mount().
[in]	bitmap	Scratch visited-cluster bitmap, or NULL for the classification-only pass. Not read on entry.
[in]	bitmap_bytes	Size of bitmap in bytes (0 when bitmap is NULL).
[out]	report	Receives the structured findings.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Scan completed; inspect report->faults_total.
k_ra8_err_null_ptr	handle or report is NULL.
k_ra8_err_invalid_state	Mount is not in use.
k_ra8_err_*	Backend read failure while scanning.

Precondition

handle and report are non-NULL.

Mount is in use; no file open on it is mid-write.

Postcondition

On k_ra8_ok report->faults_total == 0 iff the volume is consistent within the scope this checker covers.

On error report retains its entry value.

No volume state is modified, on any return path.

Note

Not thread-safe unless a lock is installed (see ra8_fs_set_lock()).

Warning

Read-only: this never repairs. Do not treat a non-zero faults_total as "then fix it" – image the card off-device first.

See also

ra8_fs_check_report_t

Since

0.1.0

Definition at line 892 of file ra8_fs_fat_check.c.

References internal_check_locked(), priv_lock_acquire(), priv_lock_release(), and ra8_fs_check().

Referenced by ra8_fs_check().