sapi_watchdog.c File Reference

Real watchdog implementation: a fixed-size pool of watchdog slots, timed via the already-portable sapi_timer_now() OAL primitive rather than any new OS-specific timing code of its own (REQ-OAL-COMMON-010: no dynamic allocation). More...

#include "safeapi/redundancy/watchdog/sapi_watchdog.h"
#include "safeapi/utils/lifecycle/sapi_lifecycle.h"
#include "safeapi/oal/log/sapi_log.h"
#include "safeapi/utils/safestate/sapi_safestate.h"
#include "safeapi/oal/timer/sapi_timer.h"
#include <stdbool.h>
#include <string.h>

Include dependency graph for sapi_watchdog.c:

Go to the source code of this file.

Data Structures
struct	sapi_watchdog_t
	Watchdog handle (opaque). More...

Macros
#define	SAPI_WATCHDOG_MAX_COUNT   8U

Functions
static bool	is_valid_handle (sapi_watchdog_t watchdog)
	Defensive check that handle actually points at one of this module's own live pool slots, not an arbitrary caller pointer.
static bool	is_valid_action (sapi_watchdog_action_t action)
	Checks whether action is one of the defined sapi_watchdog_action_t enumerators.
sapi_status_t	sapi_watchdog_manager_initialize (void)
	Initialize watchdog manager (call once at startup).
sapi_status_t	sapi_watchdog_manager_shutdown (void)
	Shutdown watchdog manager (call once at shutdown).
sapi_status_t	sapi_watchdog_create (sapi_watchdog_t *handle_out, const sapi_watchdog_config_t *config)
	Create a watchdog.
sapi_status_t	sapi_watchdog_start (sapi_watchdog_t watchdog)
	Start watchdog timer.
sapi_status_t	sapi_watchdog_stop (sapi_watchdog_t watchdog)
	Stop watchdog timer.
sapi_status_t	sapi_watchdog_kick (sapi_watchdog_t watchdog)
	Kick (pet) watchdog - prove liveness.
sapi_status_t	sapi_watchdog_get_status (sapi_watchdog_t watchdog, sapi_watchdog_status_t *status_out)
	Get watchdog status.
sapi_status_t	sapi_watchdog_destroy (sapi_watchdog_t watchdog)
	Destroy watchdog.
void	sapi_watchdog_timeout_handler (uint32_t watchdog_id)
	Watchdog timeout handler (INTERNAL - called by framework).
void	sapi_watchdog_timer_tick (void)
	Poll all active watchdogs for expiry (call periodically).

Variables
static sapi_watchdog_s	g_watchdog_pool [SAPI_WATCHDOG_MAX_COUNT]
	Fixed-size static pool backing every sapi_watchdog_t handle.
static uint8_t	g_manager_initialized = 0U
	1 once sapi_watchdog_manager_initialize() has been called.

Detailed Description

Real watchdog implementation: a fixed-size pool of watchdog slots, timed via the already-portable sapi_timer_now() OAL primitive rather than any new OS-specific timing code of its own (REQ-OAL-COMMON-010: no dynamic allocation).

Timeout detection is polling-based: something (the application's own loop, or a periodic sapi_timer callback) must call sapi_watchdog_timer_tick() regularly for a fired watchdog to actually be detected - see that function's own doc for why a poll-driven design was chosen here over a true ISR/thread-driven one.

Replaces a previous stub where kick()/start()/get_status() were all no-ops and no timeout was ever detected (see git history) - discovered while wiring a real per-role watchdog into safeAPIRBC2oo2.

Definition in file sapi_watchdog.c.

Macro Definition Documentation

SAPI_WATCHDOG_MAX_COUNT

#define SAPI_WATCHDOG_MAX_COUNT   8U

Fixed pool size. sapi_watchdog_create() returns SAPI_STATUS_RESOURCE_EXHAUSTED once this many watchdogs are live at once - no dynamic growth, per this framework's no-malloc rule.

Definition at line 34 of file sapi_watchdog.c.

Function Documentation

is_valid_handle()

bool is_valid_handle ( sapi_watchdog_t watchdog )

static

Defensive check that handle actually points at one of this module's own live pool slots, not an arbitrary caller pointer.

Pointer comparison against both ends of the same array object is well-defined in C (unlike comparing unrelated pointers).

Parameters

watchdog

Handle to validate.

Returns

true if watchdog points at an in-use slot of g_watchdog_pool; false otherwise (including NULL).

Definition at line 81 of file sapi_watchdog.c.

is_valid_action()

bool is_valid_action ( sapi_watchdog_action_t action )

static

Checks whether action is one of the defined sapi_watchdog_action_t enumerators.

Parameters

action

Value to validate.

Returns

true if action is a recognized enumerator; false otherwise.

Definition at line 94 of file sapi_watchdog.c.

Variable Documentation

g_watchdog_pool

sapi_watchdog_s g_watchdog_pool[SAPI_WATCHDOG_MAX_COUNT]

static

Fixed-size static pool backing every sapi_watchdog_t handle.

Definition at line 62 of file sapi_watchdog.c.

g_manager_initialized

uint8_t g_manager_initialized = 0U

static

1 once sapi_watchdog_manager_initialize() has been called.

Definition at line 64 of file sapi_watchdog.c.