safe_data.h

Go to the documentation of this file.

/*
 * Copyright (c) 2026 The safety-toolbox contributors
 * SPDX-License-Identifier: Apache-2.0
 *
 * Safe Data API - generic CRC-protected (optionally redundant) containers.
 *
 * A "safe container" bundles a user payload together with a mutex and an
 * integrity tag (CRC, plus an optional inverted shadow copy). All access goes
 * through a small set of functions/macros that hold the lock across the whole
 * read-modify-write and (re)seal the integrity tag automatically, so a stale
 * tag or a torn update cannot happen "by construction".
 *
 * The heavy lifting lives in a single type-erased core (safe_data.c); the
 * macros below only derive (&payload, sizeof(payload), &crc, &lock, shadow)
 * from a typed container and forward to that core.
 */
 
#ifndef SAFE_DATA_H_
#define SAFE_DATA_H_
 
#include <stdint.h>
#include <stddef.h>
#include <errno.h>
 
#include <zephyr/kernel.h>
#include <zephyr/sys/util.h>
#include <zephyr/toolchain.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/*
 * The library may be built standalone (e.g. for host unit testing) without the
 * Kconfig fragment present. Provide safe defaults so the header is usable
 * either way.
 */
#if !defined(CONFIG_SAFE_DATA_REDUNDANT)
#define CONFIG_SAFE_DATA_REDUNDANT 0
#endif
 
/* Locking defaults to on; standalone builds without the Kconfig fragment get a
 * mutex per container too. Set CONFIG_SAFE_DATA_LOCKING=n to drop the mutex when
 * the data is only ever accessed from a single context.
 */
#if !defined(CONFIG_SAFE_DATA_LOCKING) && !defined(CONFIG_SAFE_DATA)
#define CONFIG_SAFE_DATA_LOCKING 1
#endif
 
/* Remaining standalone defaults (Kconfig fragment absent): wait forever for
 * the lock, keep the full API surface.
 */
#if !defined(CONFIG_SAFE_DATA)
#if !defined(CONFIG_SAFE_DATA_LOCK_TIMEOUT_MS)
#define CONFIG_SAFE_DATA_LOCK_TIMEOUT_MS 0
#endif
#if !defined(CONFIG_SAFE_DATA_GNU_EXTENSIONS)
#define CONFIG_SAFE_DATA_GNU_EXTENSIONS 1
#endif
#if !defined(CONFIG_SAFE_DATA_ALLOW_UNCHECKED_COMMIT)
#define CONFIG_SAFE_DATA_ALLOW_UNCHECKED_COMMIT 1
#endif
#endif /* !CONFIG_SAFE_DATA */


#define SAFE_DATA_RECOVERED (-EAGAIN)

typedef int (*safe_data_mutator_t)(void *payload, void *user);
 /* safe_data_core_apis */


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,
};

struct safe_data_fault_info {
    enum safe_data_fault_kind kind;
    const void *payload;
    size_t len;
};

typedef void (*safe_data_fault_cb_t)(const struct safe_data_fault_info *info);

int safe_data_fault_handler_register(safe_data_fault_cb_t cb);

void safe_data_fault_handler(const void *payload, size_t len);

struct safe_data_stats {
    uint32_t recovered_tag;
    uint32_t recovered_payload;
    uint32_t unrecoverable;
    uint32_t lock_timeouts;
    uint32_t overwritten;
    uint32_t mutator_clamped;
};

int safe_data_stats_get(struct safe_data_stats *out);

void safe_data_stats_reset(void);
 
#if defined(CONFIG_SAFE_DATA_SELFTEST) || defined(__DOXYGEN__)
int safe_data_selftest(void);

int safe_data_selftest_result(void);
#endif /* CONFIG_SAFE_DATA_SELFTEST */
 /* safe_data_diag_apis */
 
/* ------------------------------------------------------------------------- *
 * Type-erased core API. Prefer the typed macros below in application code.
 * All functions return 0 on success or a negative errno; NULL pointers for
 * required arguments yield -EINVAL. The @p lock argument is optional: pass NULL
 * (as the typed macros do when CONFIG_SAFE_DATA_LOCKING=n) to skip locking.
 * ------------------------------------------------------------------------- */


int safe_data_init(struct k_mutex *lock, void *payload, size_t len,
           uint32_t *crc, void *shadow);

int safe_data_verify(const void *payload, size_t len, uint32_t crc,
             const void *shadow);

int safe_data_verify_repair(void *payload, size_t len, uint32_t crc,
                void *shadow);

int safe_data_read(struct k_mutex *lock, void *payload, size_t len,
           uint32_t *crc, void *shadow, void *out);

int safe_data_write(struct k_mutex *lock, void *payload, size_t len,
            uint32_t *crc, void *shadow, const void *in);

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);
 
#if defined(CONFIG_SAFE_DATA_ALLOW_UNCHECKED_COMMIT) || defined(__DOXYGEN__)
int safe_data_commit(struct k_mutex *lock, void *payload, size_t len,
             uint32_t *crc, void *shadow);
#endif /* CONFIG_SAFE_DATA_ALLOW_UNCHECKED_COMMIT */
 /* safe_data_core_apis */
 
/* Implementation details shared with the SAFE_SECTION macro. */
void z_safe_data_seal(void *payload, size_t len, uint32_t *crc, void *shadow);
void z_safe_data_lock_failed(void);
 
/* Bound on lock acquisition; 0 keeps the legacy wait-forever behaviour. */
#if CONFIG_SAFE_DATA_LOCK_TIMEOUT_MS > 0
#define Z_SAFE_LOCK_TIMEOUT K_MSEC(CONFIG_SAFE_DATA_LOCK_TIMEOUT_MS)
#else
#define Z_SAFE_LOCK_TIMEOUT K_FOREVER
#endif
 
/* NULL-tolerant lock helpers: a NULL lock (locking disabled) is a no-op. Used
 * by the core and by SAFE_SECTION so the same code works with or without a mutex.
 *
 * Returns 0 when the lock is held (or not needed), -ETIMEDOUT when the
 * configured acquisition bound expired. Never legal from an ISR.
 */
static inline int z_safe_lock(struct k_mutex *lock)
{
    if (lock != NULL) {
        __ASSERT(!k_is_in_isr(),
             "safe_data: locking API is not ISR-safe");
        if (k_mutex_lock(lock, Z_SAFE_LOCK_TIMEOUT) != 0) {
            /* Map -EAGAIN (kernel timeout) away from the
             * SAFE_DATA_RECOVERED alias.
             */
            return -ETIMEDOUT;
        }
    }
    return 0;
}
 
static inline void z_safe_unlock(struct k_mutex *lock)
{
    if (lock != NULL) {
        k_mutex_unlock(lock);
    }
}
 
/* ------------------------------------------------------------------------- *
 * Typed convenience layer.
 * ------------------------------------------------------------------------- */

 
/* Detection strength of a CRC collapses once the payload outgrows it. These
 * bounds keep the configured tag inside its useful Hamming-distance range; use
 * SAFE_CONTAINER_DEFINE_UNCHECKED only with a documented deviation.
 */
#if defined(CONFIG_SAFE_DATA_CRC8_CCITT)
#define Z_SAFE_DATA_MAX_PAYLOAD 16
#elif defined(CONFIG_SAFE_DATA_CRC16_CCITT)
#define Z_SAFE_DATA_MAX_PAYLOAD 256
#else /* CRC32 */
#define Z_SAFE_DATA_MAX_PAYLOAD SIZE_MAX
#endif
 
#define Z_SAFE_CONTAINER_BODY(_payload_type)                                   \
        IF_ENABLED(CONFIG_SAFE_DATA_LOCKING, (struct k_mutex _lock;))   \
        uint32_t _crc;                                                 \
        IF_ENABLED(CONFIG_SAFE_DATA_REDUNDANT,                         \
               (uint8_t _shadow[sizeof(_payload_type)];))          \
        _payload_type payload;

#define SAFE_CONTAINER_DEFINE(_container_name, _payload_type)                  \
    struct _container_name {                                               \
        BUILD_ASSERT(sizeof(_payload_type) > 0,                        \
                 "safe_data: zero-size payload");                  \
        BUILD_ASSERT(sizeof(_payload_type) <= Z_SAFE_DATA_MAX_PAYLOAD, \
                 "safe_data: payload too large for the configured" \
                 " integrity tag (see Z_SAFE_DATA_MAX_PAYLOAD)");  \
        Z_SAFE_CONTAINER_BODY(_payload_type)                           \
    }

#define SAFE_CONTAINER_DEFINE_UNCHECKED(_container_name, _payload_type)        \
    struct _container_name {                                               \
        BUILD_ASSERT(sizeof(_payload_type) > 0,                        \
                 "safe_data: zero-size payload");                  \
        Z_SAFE_CONTAINER_BODY(_payload_type)                           \
    }
 
/* Resolve the shadow pointer to either &_shadow[0] or NULL at compile time. */
#define _SAFE_SHADOW(_c)                                                       \
    COND_CODE_1(CONFIG_SAFE_DATA_REDUNDANT, ((_c)->_shadow), (NULL))
 
/* Resolve the lock pointer to either &_lock or NULL at compile time. When
 * locking is disabled the core functions receive NULL and skip serialisation.
 */
#define _SAFE_LOCK(_c)                                                         \
    COND_CODE_1(CONFIG_SAFE_DATA_LOCKING, (&(_c)->_lock), (NULL))

#define SAFE_INIT(_c)                                                          \
    safe_data_init(_SAFE_LOCK(_c), &(_c)->payload, sizeof((_c)->payload),  \
               &(_c)->_crc, _SAFE_SHADOW(_c))

#define SAFE_VERIFY(_c)                                                        \
    safe_data_verify(&(_c)->payload, sizeof((_c)->payload), (_c)->_crc,    \
             _SAFE_SHADOW(_c))

#define SAFE_READ(_c, _out_ptr)                                                \
    safe_data_read(_SAFE_LOCK(_c), &(_c)->payload, sizeof((_c)->payload),  \
               &(_c)->_crc, _SAFE_SHADOW(_c), (_out_ptr))

#define SAFE_WRITE(_c, _in_ptr)                                                \
    safe_data_write(_SAFE_LOCK(_c), &(_c)->payload, sizeof((_c)->payload), \
            &(_c)->_crc, _SAFE_SHADOW(_c), (_in_ptr))

#define SAFE_UPDATE(_c, _fn, _user)                                            \
    safe_data_update(_SAFE_LOCK(_c), &(_c)->payload, sizeof((_c)->payload),\
             &(_c)->_crc, _SAFE_SHADOW(_c), (_fn), (_user))
 
#if defined(CONFIG_SAFE_DATA_ALLOW_UNCHECKED_COMMIT) || defined(__DOXYGEN__)
#define SAFE_COMMIT(_c)                                                        \
    safe_data_commit(_SAFE_LOCK(_c), &(_c)->payload,                       \
             sizeof((_c)->payload), &(_c)->_crc, _SAFE_SHADOW(_c))
#endif /* CONFIG_SAFE_DATA_ALLOW_UNCHECKED_COMMIT */

#if defined(CONFIG_SAFE_DATA_GNU_EXTENSIONS) || defined(__DOXYGEN__)
#define SAFE_SECTION(_c, _pvar)                                                \
    for (int _sd_st = ((z_safe_lock(_SAFE_LOCK(_c)) == 0)                  \
               ? safe_data_verify_repair(&(_c)->payload,           \
                        sizeof((_c)->payload), (_c)->_crc, \
                        _SAFE_SHADOW(_c))                  \
               : (z_safe_data_lock_failed(), -ETIMEDOUT));         \
         /* enter on valid (0) or recovered (-EAGAIN) */                   \
         ({ bool _ok = (_sd_st == 0 || _sd_st == SAFE_DATA_RECOVERED);     \
        if (!_ok && _sd_st != -ETIMEDOUT) {                            \
            z_safe_unlock(_SAFE_LOCK(_c));                         \
        }                                                              \
        _ok; });                                                       \
         z_safe_data_seal(&(_c)->payload, sizeof((_c)->payload),           \
                  &(_c)->_crc, _SAFE_SHADOW(_c)),                  \
         z_safe_unlock(_SAFE_LOCK(_c)), _sd_st = 1)                        \
        for (__typeof__((_c)->payload) *_pvar = &(_c)->payload;        \
             _pvar != NULL; _pvar = NULL)
#endif /* CONFIG_SAFE_DATA_GNU_EXTENSIONS */
 /* safe_data_container_apis */
 
#ifdef __cplusplus
}
#endif
 
#endif /* SAFE_DATA_H_ */