K-FSW health monitoring

Data Structures
struct	kfsw_health_component
struct	kfsw_health_status

Macros
#define	KFSW_HEALTH_MAX_COMPONENTS   CONFIG_KFSW_HEALTH_MAX_COMPONENTS
#define	KFSW_HEALTH_NAME_SIZE   16U

Enumerations
enum	kfsw_health_event { KFSW_EVENT_HEALTH_FAULT = 1 }
enum	kfsw_health_state { KFSW_HEALTH_OK = 0 , KFSW_HEALTH_FAULTED = 1 , KFSW_HEALTH_STOPPED = 2 }

Functions
int	kfsw_health_register (const char *name, uint32_t deadline_ms, uint8_t *handle)
int	kfsw_health_unregister (uint8_t handle)
int	kfsw_health_report (uint8_t handle)
int	kfsw_health_start (void)
int	kfsw_health_evaluate (void)
int	kfsw_health_get_status (struct kfsw_health_status *status)
int	kfsw_health_get_component (uint8_t index, struct kfsw_health_component *component)
const char *	kfsw_health_state_name (enum kfsw_health_state state)
uint32_t	kfsw_health_get_interval_ms (void)
int	kfsw_health_check_interval_ms (uint32_t interval_ms)
int	kfsw_health_set_interval_ms (uint32_t interval_ms)

Description

Components report periodically, and the watchdog is fed only while all of them are within their deadlines.

If one stops reporting, the watchdog resets the board. Each component has its own deadline.

Macro Documentation

KFSW_HEALTH_MAX_COMPONENTS

#define KFSW_HEALTH_MAX_COMPONENTS   CONFIG_KFSW_HEALTH_MAX_COMPONENTS

#include <health.h>

Largest number of components that can be watched.

KFSW_HEALTH_NAME_SIZE

#define KFSW_HEALTH_NAME_SIZE   16U

#include <health.h>

Longest component name kept, including the terminator.

Enumeration Documentation

kfsw_health_event

enum kfsw_health_event

#include <health.h>

Event IDs of this service.

Enumerator
KFSW_EVENT_HEALTH_FAULT	A watched component missed its deadline; the watchdog is withheld.

kfsw_health_state

enum kfsw_health_state

#include <health.h>

Current health state.

Enumerator
KFSW_HEALTH_OK	Registered components are all reporting within their deadlines.
KFSW_HEALTH_FAULTED	At least one component is overdue; the watchdog is no longer fed.
KFSW_HEALTH_STOPPED	Supervision has not been started.

Function Documentation

kfsw_health_check_interval_ms()

int kfsw_health_check_interval_ms

(

uint32_t

interval_ms

)

#include <health.h>

Whether an interval is safe to use, without applying it.

Parameters

interval_ms

Milliseconds between checks.

Return values

0	Safe, or no watchdog is armed.
-EINVAL	interval_ms is zero.
-ERANGE	The interval is slower than the watchdog's feed interval.

kfsw_health_evaluate()

int kfsw_health_evaluate

(

void

)

#include <health.h>

Check component deadlines and feed the watchdog if all are met.

Called on a timer while supervision runs; public so tests can call it.

Return values

0	Everything is within its deadline and the watchdog was fed.
-ETIMEDOUT	At least one component is overdue; the feed was withheld.
-EINVAL	Supervision is not running.

kfsw_health_get_component()

int kfsw_health_get_component	(	uint8_t	index,
		struct kfsw_health_component *	component
	)

#include <health.h>

Read one component's entry.

Parameters

	index	Position in the table, below the registered count.
[out]	component	Destination entry.

Return values

0	The entry was written.
-EINVAL	component is NULL.
-ENOENT	index is not registered.

kfsw_health_get_interval_ms()

uint32_t kfsw_health_get_interval_ms

(

void

)

#include <health.h>

Milliseconds between deadline checks.

kfsw_health_get_status()

int kfsw_health_get_status

(

struct kfsw_health_status *

status

)

#include <health.h>

Read a consistent snapshot of the service.

Parameters

[out]

status

Destination snapshot.

Return values

0	The snapshot was written.
-EINVAL	status is NULL.

kfsw_health_register()

int kfsw_health_register	(	const char *	name,
		uint32_t	deadline_ms,
		uint8_t *	handle
	)

#include <health.h>

Register a component to be watched.

Parameters

	name	Short name, truncated to KFSW_HEALTH_NAME_SIZE.
	deadline_ms	How long this component may go without reporting. Must be long enough to cover its slowest normal cycle.
[out]	handle	Identifier to report with.

Return values

0	Registered.
-EINVAL	name or handle is NULL, name is empty, or deadline_ms is zero.
-ENOSPC	No room is left in the table.
-EEXIST	A component of that name is already registered.

kfsw_health_report()

int kfsw_health_report

(

uint8_t

handle

)

#include <health.h>

Report that a component is still running.

Parameters

handle

Identifier from kfsw_health_register.

Return values

0	Recorded.
-EINVAL	The handle is not registered.

kfsw_health_set_interval_ms()

int kfsw_health_set_interval_ms

(

uint32_t

interval_ms

)

#include <health.h>

Change how often deadlines are checked.

Refused when the interval is slower than the running watchdog's feed interval.

Parameters

interval_ms

Milliseconds between checks.

Return values

0	Applied from the next cycle.
-EINVAL	interval_ms is zero.
-ERANGE	The interval would outlast the watchdog.

kfsw_health_start()

int kfsw_health_start

(

void

)

#include <health.h>

Start supervising and take over feeding the watchdog.

Every registered component counts as having just reported.

Return values

0	Supervision is running.
-EALREADY	It was already running.
-ENODEV	There is no watchdog to take over.

Returns

A negative errno value from the platform on failure.

kfsw_health_state_name()

const char * kfsw_health_state_name

(

enum kfsw_health_state

state

)

#include <health.h>

Human-readable name for a state.

Parameters

state

One of kfsw_health_state.

Returns

A stable lowercase name; "unknown" for an unrecognised value.

kfsw_health_unregister()

int kfsw_health_unregister

(

uint8_t

handle

)

#include <health.h>

Stop watching a component, for example when its service is stopped.

Parameters

handle

Identifier from kfsw_health_register.

Return values

0	No longer watched.
-EINVAL	The handle is not registered.