safe_data.h File Reference

#include <stdint.h>
#include <stddef.h>
#include <errno.h>
#include <zephyr/kernel.h>
#include <zephyr/sys/util.h>
#include <zephyr/toolchain.h>

Go to the source code of this file.

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...

Macros
#define	SAFE_DATA_RECOVERED   (-EAGAIN)
	Return code for a fault that the redundant shadow copy covers.
#define	SAFE_CONTAINER_DEFINE(_container_name, _payload_type)
	Declare a CRC-protected container type wrapping _payload_type.
#define	SAFE_CONTAINER_DEFINE_UNCHECKED(_container_name, _payload_type)
	As SAFE_CONTAINER_DEFINE but without the tag-strength size bound. For documented deviations only.
#define	SAFE_INIT(_c)
	Initialise and seal a container.
#define	SAFE_VERIFY(_c)
	Verify integrity only (pure, never modifies the payload).
#define	SAFE_READ(_c, _out_ptr)
	Validated copy out into _out_ptr.
#define	SAFE_WRITE(_c, _in_ptr)
	Validated copy in from _in_ptr + reseal.
#define	SAFE_UPDATE(_c, _fn, _user)
	Atomic read-modify-write via callback.
#define	SAFE_COMMIT(_c)
	Reseal after an explicit external modification.
#define	SAFE_SECTION(_c, _pvar)
	Scoped lock + verify ... reseal + unlock around a block.

Typedefs
typedef int(*	safe_data_mutator_t) (void *payload, void *user)
	Mutator callback used by safe_data_update() / SAFE_UPDATE().
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).
int	safe_data_init (struct k_mutex *lock, void *payload, size_t len, uint32_t *crc, void *shadow)
	Initialise the lock and seal the current payload contents.
int	safe_data_verify (const void *payload, size_t len, uint32_t crc, const void *shadow)
	Verify payload integrity. Pure: read-only and lock-free; it NEVER modifies the payload, so it is safe to call concurrently with writers (a transient mismatch may then be reported - callers needing atomicity should use the higher-level helpers).
int	safe_data_verify_repair (void *payload, size_t len, uint32_t crc, void *shadow)
	Verify payload integrity and repair a recoverable fault in place.
int	safe_data_read (struct k_mutex *lock, void *payload, size_t len, uint32_t *crc, void *shadow, void *out)
	Verify under lock and copy the payload out to out.
int	safe_data_write (struct k_mutex *lock, void *payload, size_t len, uint32_t *crc, void *shadow, const void *in)
	Copy in into the payload under lock and reseal the integrity tag.
int	safe_data_update (struct k_mutex *lock, void *payload, size_t len, uint32_t *crc, void *shadow, safe_data_mutator_t fn, void *user)
	Atomic read-modify-write: lock, verify, run fn, reseal on success.
int	safe_data_commit (struct k_mutex *lock, void *payload, size_t len, uint32_t *crc, void *shadow)
	Reseal after an explicit external modification (advanced use). Lock, recompute the integrity tag, unlock.