Safe-State Transitions and Checked Assertions

Layer-agnostic fault-reaction facility (ADR-004). More...

Files
file	src/utils/safestate/rte_safestate.c
	Implementation of the safe-state transition facility (ADR-004).

Macros
#define	RTE_SAFESTATE_REASON_UNSPECIFIED   ((rte_safestate_reason_t)0U)
#define	RTE_SAFESTATE_REASON_ASSERT_FAILED   ((rte_safestate_reason_t)1U)
#define	RTE_SAFESTATE_REASON_CHECKPOINT_TIMEOUT   ((rte_safestate_reason_t)2U)
#define	RTE_SAFESTATE_REASON_SETUP_AFTER_INIT   ((rte_safestate_reason_t)3U)
#define	RTE_SAFESTATE_REASON_OSA_RT_ATTRIBUTE   ((rte_safestate_reason_t)4U)
#define	RTE_SAFESTATE_REASON_CLOCK_FAILED   ((rte_safestate_reason_t)5U)
#define	RTE_SAFESTATE_REASON_APPLICATION_BASE   ((rte_safestate_reason_t)4096U)
#define	RTE_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 RTE_SAFESTATE_LEVEL_SAFE with reason RTE_SAFESTATE_REASON_ASSERT_FAILED.
#define	RTE_SAFESTATE(level, reason)
	Explicitly enters the given safe-state level with a reason code, capturing the call site automatically.
#define	RTE_REBOOT(reason)
	Enters RTE_SAFESTATE_LEVEL_REBOOT with the given reason code. Equivalent to RTE_SAFESTATE(RTE_SAFESTATE_LEVEL_REBOOT, reason).

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

Enumerations
enum	rte_safestate_level_t { RTE_SAFESTATE_LEVEL_DEGRADED = 0 , RTE_SAFESTATE_LEVEL_SAFE = 1 , RTE_SAFESTATE_LEVEL_REBOOT = 2 }
	Safe-state severity levels (ADR-004 section 2.1). More...

Functions
rte_status_t	rte_safestate_register_handler (rte_safestate_level_t level, rte_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	rte_safestate_enter (rte_safestate_level_t level, rte_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 RTE_SAFESTATE_LEVEL_SAFE and RTE_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

Layer-agnostic fault-reaction facility (ADR-004).

Macro Definition Documentation

RTE_SAFESTATE_REASON_UNSPECIFIED

#define RTE_SAFESTATE_REASON_UNSPECIFIED   ((rte_safestate_reason_t)0U)

Reserved framework reason codes (0-4095).

Definition at line 66 of file rte_safestate.h.

RTE_SAFESTATE_REASON_ASSERT_FAILED

#define RTE_SAFESTATE_REASON_ASSERT_FAILED   ((rte_safestate_reason_t)1U)

Set by RTE_ASSERT() when its condition evaluates to false.

Definition at line 68 of file rte_safestate.h.

RTE_SAFESTATE_REASON_CHECKPOINT_TIMEOUT

#define RTE_SAFESTATE_REASON_CHECKPOINT_TIMEOUT   ((rte_safestate_reason_t)2U)

Set by rte_channel_checkpoint() (ADR-017) when fewer than expected_node_count peers confirm a checkpoint within max_delay_ms.

Definition at line 71 of file rte_safestate.h.

RTE_SAFESTATE_REASON_SETUP_AFTER_INIT

#define RTE_SAFESTATE_REASON_SETUP_AFTER_INIT   ((rte_safestate_reason_t)3U)

Set by rte_lifecycle_check_setup_allowed() (REQ-LIFECYCLE-003, DEGRADED level) when a setup-only resource is requested after the setup phase was locked - an OSA rule violation (resources are created only during initialisation).

Definition at line 75 of file rte_safestate.h.

RTE_SAFESTATE_REASON_OSA_RT_ATTRIBUTE

#define RTE_SAFESTATE_REASON_OSA_RT_ATTRIBUTE   ((rte_safestate_reason_t)4U)

Reported by an OSAdapter (DEGRADED level) when a real-time attribute it was asked for could not be applied: thread priority / scheduling policy, fixed stack size, mutex priority inheritance.

Definition at line 78 of file rte_safestate.h.

RTE_SAFESTATE_REASON_CLOCK_FAILED

#define RTE_SAFESTATE_REASON_CLOCK_FAILED   ((rte_safestate_reason_t)5U)

Set by rte_watchdog_timer_tick() (REQ-WATCHDOG-004, SAFE level) when the monotonic time base rte_timer_now() failed while a liveness supervisor (a started, not yet fired watchdog) depended on it: a watchdog that can never expire is a silent failure, so the failed clock is itself a safe-state trigger.

Definition at line 82 of file rte_safestate.h.

RTE_SAFESTATE_REASON_APPLICATION_BASE

#define RTE_SAFESTATE_REASON_APPLICATION_BASE   ((rte_safestate_reason_t)4096U)

First reason code value applications are free to define their own meaning for.

Definition at line 84 of file rte_safestate.h.

RTE_ASSERT

#define RTE_ASSERT

(

cond

)

Value:

do                                                                       \
{                                                                        \
    if (!(cond))                                                         \
    {                                                                    \
        rte_safestate_enter(RTE_SAFESTATE_LEVEL_SAFE,                  \
                              RTE_SAFESTATE_REASON_ASSERT_FAILED,        \
                              __FILE__, (int32_t)__LINE__, #cond);        \
    }                                                                    \
} while (0)

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 RTE_SAFESTATE_LEVEL_SAFE with reason RTE_SAFESTATE_REASON_ASSERT_FAILED.

Definition at line 156 of file rte_safestate.h.

RTE_SAFESTATE

#define RTE_SAFESTATE	(		level,
			reason )

Value:

rte_safestate_enter((level), (reason), __FILE__, (int32_t)__LINE__, NULL)

Explicitly enters the given safe-state level with a reason code, capturing the call site automatically.

Definition at line 172 of file rte_safestate.h.

RTE_REBOOT

#define RTE_REBOOT

(

reason

)

Value:

rte_safestate_enter(RTE_SAFESTATE_LEVEL_REBOOT, (reason), __FILE__, (int32_t)__LINE__, NULL)

Enters RTE_SAFESTATE_LEVEL_REBOOT with the given reason code. Equivalent to RTE_SAFESTATE(RTE_SAFESTATE_LEVEL_REBOOT, reason).

Definition at line 180 of file rte_safestate.h.

Typedef Documentation

rte_safestate_reason_t

typedef uint16_t rte_safestate_reason_t

Diagnostic reason code accompanying a safe-state transition.

Values 0-4095 are reserved for the framework itself (see the RTE_SAFESTATE_REASON_* constants below). Application/RBC-specific reason codes shall use 4096 and above.

Definition at line 63 of file rte_safestate.h.

rte_safestate_handler_t

typedef void(*) rte_safestate_handler_t(rte_safestate_level_t level, rte_safestate_reason_t reason, const char *file, int32_t line, const char *message)

Application-supplied reaction for one safe-state level.

Parameters

level	The level being entered (matches the slot this handler was registered for).
reason	Diagnostic reason code.
file	Source file of the call site (from FILE), may be NULL.
line	Source line of the call site (from LINE).
message	Optional human-readable detail (e.g. the failed expression text from RTE_ASSERT), may be NULL.

Note

For RTE_SAFESTATE_LEVEL_SAFE and RTE_SAFESTATE_LEVEL_REBOOT this handler shall not return. If it does anyway, rte_safestate_enter() falls back to a defensive infinite loop (REQ-COMMON-SAFESTATE-002) rather than resuming the caller.

Definition at line 102 of file rte_safestate.h.

Enumeration Type Documentation

rte_safestate_level_t

enum rte_safestate_level_t

Safe-state severity levels (ADR-004 section 2.1).

Enumerator
RTE_SAFESTATE_LEVEL_DEGRADED	Continue operating with reduced functionality. The only level for which rte_safestate_enter() is permitted to return to the caller.
RTE_SAFESTATE_LEVEL_SAFE	Fail-safe restrictive state (e.g. withdraw movement authorities). rte_safestate_enter() does not return for this level.
RTE_SAFESTATE_LEVEL_REBOOT	SAFE is judged insufficient; a controlled restart is required. rte_safestate_enter() does not return for this level.

Definition at line 41 of file rte_safestate.h.

Function Documentation

rte_safestate_register_handler()

rte_status_t rte_safestate_register_handler	(	rte_safestate_level_t	level,
		rte_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).

Parameters

level	The level to register a handler for.
handler	Handler to invoke on entry to this level. Must not be NULL.

Returns

RTE_STATUS_INVALID_PARAM if handler is NULL or level is not a valid rte_safestate_level_t value; RTE_STATUS_OK otherwise. Registering again for the same level replaces the previous handler.

REQ-COMMON-SAFESTATE-010

Global functions

Definition at line 31 of file rte_safestate.c.

rte_safestate_enter()

void rte_safestate_enter	(	rte_safestate_level_t	level,
		rte_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 RTE_SAFESTATE_LEVEL_SAFE and RTE_SAFESTATE_LEVEL_REBOOT, guarantees the call never returns (REQ-COMMON-SAFESTATE-002) even if no handler was registered or the handler itself returns.

Parameters

level	Level to enter.
reason	Diagnostic reason code.
file	Call site file (typically FILE), may be NULL.
line	Call site line (typically LINE).
message	Optional human-readable detail, may be NULL.

Note

Prefer the RTE_ASSERT / RTE_SAFESTATE / RTE_REBOOT macros over calling this directly, so FILE/__LINE__ are captured correctly.

REQ-COMMON-SAFESTATE-011

Definition at line 52 of file rte_safestate.c.