hotswap.h File Reference

Safeties for removable storage that can vanish mid-write (PC_ENABLE_HOTSWAP). More...

#include "protocore_config.h"
#include <stddef.h>
#include <stdint.h>

Go to the source code of this file.

Detailed Description

Safeties for removable storage that can vanish mid-write (PC_ENABLE_HOTSWAP).

An SD card is a connector, and a connector can be pulled - during a log append, an upload, a core-dump save. The failure is nasty because it is quiet: the driver keeps handing back a mounted volume, every write reports an error nobody checks, and the code carries on believing it has storage. What should happen instead is that the medium is declared unusable, stale handles are dropped, and callers are told to stop rather than write into nothing.

That is what this owns. One state machine per volume:

ABSENT  --probe finds a card, mount succeeds-->  READY
READY   --fail_threshold consecutive I/O errors-->  FAULTED  (unmount fires immediately)
FAULTED --probe interval elapses, remount succeeds-->  READY

The threshold matters: a single failed write is not proof a card left (a transient bus error, a full volume), so one error does not tear down a working volume. A run of them is proof enough. Any success resets the run, so intermittent noise never accumulates into a false removal.

Callers gate on pc_hotswap_ready() and report every filesystem outcome through pc_hotswap_io(). It is deliberately fail-closed: while not READY, ready() is false, so a caller that honors it writes nothing rather than writing into a stale mount.

The core is pure and takes an explicit now, so the whole state machine is host-testable with a synthetic clock; the device binding is three app callbacks (mount / unmount / optional card-detect), because how a volume is mounted is the application's business, not this owner's.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file hotswap.h.