sapi_safestate.h File Reference

Safe-state transitions and checked assertions (ADR-004). More...

#include "safeapi/utils/status/sapi_status.h"
#include "safeapi/utils/types/sapi_types.h"

Include dependency graph for sapi_safestate.h:

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

Go to the source code of this file.

Macros
#define	SAPI_SAFESTATE_REASON_UNSPECIFIED   ((sapi_safestate_reason_t)0U)
#define	SAPI_SAFESTATE_REASON_ASSERT_FAILED   ((sapi_safestate_reason_t)1U)
#define	SAPI_SAFESTATE_REASON_CHECKPOINT_TIMEOUT   ((sapi_safestate_reason_t)2U)
#define	SAPI_SAFESTATE_REASON_APPLICATION_BASE   ((sapi_safestate_reason_t)4096U)
#define	SAPI_ASSERT(cond)
	Checked assertion. Always active in every build configuration, including production (ADR-004 section 2.5) - unlike standard assert(), which CLAUDE.md prohibits in production paths. On failure, enters SAPI_SAFESTATE_LEVEL_SAFE with reason SAPI_SAFESTATE_REASON_ASSERT_FAILED.
#define	SAPI_SAFESTATE(level, reason)
	Explicitly enters the given safe-state level with a reason code, capturing the call site automatically.
#define	SAPI_REBOOT(reason)
	Enters SAPI_SAFESTATE_LEVEL_REBOOT with the given reason code. Equivalent to SAPI_SAFESTATE(SAPI_SAFESTATE_LEVEL_REBOOT, reason).

Typedefs
typedef uint16_t	sapi_safestate_reason_t
	Diagnostic reason code accompanying a safe-state transition.
typedef void(*)	sapi_safestate_handler_t(sapi_safestate_level_t level, sapi_safestate_reason_t reason, const char *file, int32_t line, const char *message)
	Application-supplied reaction for one safe-state level.

Enumerations
enum	sapi_safestate_level_t { SAPI_SAFESTATE_LEVEL_DEGRADED = 0 , SAPI_SAFESTATE_LEVEL_SAFE = 1 , SAPI_SAFESTATE_LEVEL_REBOOT = 2 }
	Safe-state severity levels (ADR-004 section 2.1). More...

Functions
sapi_status_t	sapi_safestate_register_handler (sapi_safestate_level_t level, sapi_safestate_handler_t handler)
	Registers the reaction handler for one safe-state level. This is how an integrator supplies their own implementation of "what happens when this level is entered" (ADR-004 section 2.2).
void	sapi_safestate_enter (sapi_safestate_level_t level, sapi_safestate_reason_t reason, const char *file, int32_t line, const char *message)
	Enters a safe-state level: invokes the registered handler (if any), then, for SAPI_SAFESTATE_LEVEL_SAFE and SAPI_SAFESTATE_LEVEL_REBOOT, guarantees the call never returns (REQ-COMMON-SAFESTATE-002) even if no handler was registered or the handler itself returns.

Detailed Description

Safe-state transitions and checked assertions (ADR-004).

A layer-agnostic fault-reaction facility usable from any layer (OAL, the future L1, and L2 RBC core): SAPI_ASSERT() replaces the production-banned standard assert(); SAPI_SAFESTATE()/SAPI_REBOOT() let any code explicitly declare "this fault requires the system to leave normal operation."

This module has no OS dependency (see ADR-002 section 4, ADR-004 section 2.3): the actual fail-safe reaction is supplied by the integrator via sapi_safestate_register_handler(), not by this module calling into src/os itself.

REQ-COMMON-SAFESTATE-001: no dynamic allocation; handler storage is a fixed array of 3 slots (one per level). REQ-COMMON-SAFESTATE-002: SAPI_SAFESTATE_LEVEL_SAFE and SAPI_SAFESTATE_LEVEL_REBOOT shall never return control to the caller, even if no handler is registered or the registered handler itself returns (see sapi_safestate_enter()).

Definition in file sapi_safestate.h.