Integrity-event reporting: fault handler, statistics, self-test. More...

Data Structures
struct	safe_data_fault_info
	Event descriptor passed to the registered fault handler. More...
struct	safe_data_stats
	Global fault/recovery statistics (CONFIG_SAFE_DATA_STATS). More...

Typedefs
typedef void(*	safe_data_fault_cb_t) (const struct safe_data_fault_info *info)
	Fault/diagnostic event callback.

Enumerations
enum	safe_data_fault_kind { SAFE_DATA_FAULT_KIND_UNRECOVERABLE , SAFE_DATA_FAULT_KIND_RECOVERED_TAG , SAFE_DATA_FAULT_KIND_RECOVERED_PAYLOAD , SAFE_DATA_FAULT_KIND_LOCK_TIMEOUT , SAFE_DATA_FAULT_KIND_OVERWRITTEN , SAFE_DATA_FAULT_KIND_MUTATOR_CLAMPED }
	Kind of integrity event reported to the fault handler / statistics. More...

Functions
int	safe_data_fault_handler_register (safe_data_fault_cb_t cb)
	Register the fault handler callback.
void	safe_data_fault_handler (const void *payload, size_t len)
	Legacy user-overridable (weak) fault handler.
int	safe_data_stats_get (struct safe_data_stats *out)
	Snapshot the global statistics.
void	safe_data_stats_reset (void)
	Reset all statistics counters to zero.
int	safe_data_selftest (void)
	Self-test of the integrity mechanism itself.
int	safe_data_selftest_result (void)
	Result of the boot-time self-test (CONFIG_SAFE_DATA_SELFTEST_BOOT).

Detailed Description

Integrity-event reporting: fault handler, statistics, self-test.

The observability interface a health monitor hooks into. Every integrity event (recovery, unrecoverable corruption, lock timeout, overwritten contents, clamped mutator return) is reported exactly once per detection.

Typedef Documentation

◆ safe_data_fault_cb_t

typedef void(* safe_data_fault_cb_t) (const struct safe_data_fault_info *info)

Fault/diagnostic event callback.

May be invoked while the affected container's lock is held: the handler must not block and must not access any safe container (AoU: record the event, set a flag/semaphore for a monitor thread, or drive the safe state).

Parameters

info	Event descriptor (kind, affected payload, size). Only valid for the duration of the call; copy what you need.

Definition at line 149 of file safe_data.h.

Enumeration Type Documentation

◆ safe_data_fault_kind

enum safe_data_fault_kind

Kind of integrity event reported to the fault handler / statistics.

Enumerator
SAFE_DATA_FAULT_KIND_UNRECOVERABLE	Corruption detected, no redundant copy could vouch for the data.
SAFE_DATA_FAULT_KIND_RECOVERED_TAG	Stored tag was stale/corrupt; payload+shadow consistent, resealed.
SAFE_DATA_FAULT_KIND_RECOVERED_PAYLOAD	Payload was corrupt; restored from the shadow copy.
SAFE_DATA_FAULT_KIND_LOCK_TIMEOUT	A container lock could not be acquired within the configured bound.
SAFE_DATA_FAULT_KIND_OVERWRITTEN	Pre-write check found the old contents corrupt (observe-only).
SAFE_DATA_FAULT_KIND_MUTATOR_CLAMPED	A mutator returned a positive value (contract violation, clamped).

Definition at line 114 of file safe_data.h.

Function Documentation

◆ safe_data_fault_handler()

void safe_data_fault_handler	(	const void *	payload,
		size_t	len )

Legacy user-overridable (weak) fault handler.

Called for unrecoverable faults when CONFIG_SAFE_DATA_FAULT_HANDLER is selected and no callback is registered via safe_data_fault_handler_register() (the registered callback takes precedence). The default implementation logs and returns. The same execution-context constraints apply as for safe_data_fault_cb_t.

Parameters

payload	Pointer to the payload whose integrity check failed.
len	Payload size in bytes.

Definition at line 90 of file safe_data.c.

Referenced by safe_event().

Satisfies requirement SD-REQ-011 (Configurable unrecoverable-fault reaction).

◆ safe_data_fault_handler_register()

int safe_data_fault_handler_register ( safe_data_fault_cb_t cb )

Register the fault handler callback.

When registered, the callback receives ALL integrity events (recoveries, timeouts, overwritten-corrupt, clamped returns), independent of the configured CONFIG_SAFE_DATA_FAULT_* reaction - which still governs the control-flow response to an unrecoverable fault (return vs panic).

Parameters

cb	Handler, or NULL to unregister.

Returns: 0 on success, -EALREADY if a (different) handler is registered.

Definition at line 97 of file safe_data.c.

References fault_cb.

Satisfies requirement SD-REQ-013 (Fault-handler registration and event reporting).

◆ safe_data_selftest()

int safe_data_selftest ( void )

Self-test of the integrity mechanism itself.

Runs a known-answer test of the configured CRC backend and a seal/corrupt/detect(/recover) round trip on a scratch container, without invoking the configured fault reaction and without polluting the statistics.