File syn_settings.h¶

FileList > src > syntropic > storage > syn_settings.h

Persistent settings manager with change detection. More...

#include "../common/syn_defs.h"
#include "../storage/syn_param.h"
#include <stdbool.h>
#include <stdint.h>

Classes¶

Type	Name
struct	SYN_DualBankSettings Dual-bank settings container for atomic power-loss safe writes.
struct	SYN_Settings Persistent settings instance — flash-backed with change detection.

Public Types¶

Type	Name
typedef void(*	SYN_SettingsChangeCallback Called when syn_settings_save() detects the data has changed.

Public Functions¶

Type	Name
bool	syn_settings_changed (const SYN_Settings * s) Check if settings have changed since last save/load.
SYN_Status	syn_settings_dual_bank_init (SYN_DualBankSettings * db, uint32_t flash_base_a, uint32_t flash_base_b, uint8_t sector_count, void * data, uint16_t data_size, const void * defaults) Initialize dual-bank transactional settings manager.
SYN_Status	syn_settings_dual_bank_save (SYN_DualBankSettings * db) Atomically save settings to inactive bank and switch active bank upon CRC32 verification.
int	syn_settings_export (const SYN_Settings * s, void * buf, size_t len) Export current settings to a binary buffer.
SYN_Status	syn_settings_export_vfs (const SYN_Settings * s, const char * filepath) Export settings directly to a VFS file.
SYN_Status	syn_settings_import (SYN_Settings * s, const void * buf, size_t len, bool save) Import settings from a binary buffer and validate.
SYN_Status	syn_settings_import_vfs (SYN_Settings * s, const char * filepath, bool save) Import settings directly from a VFS file.
SYN_Status	syn_settings_init (SYN_Settings * s, uint32_t flash_base, uint8_t sector_count, void * data, uint16_t data_size, const void * defaults) Initialize the settings manager.
void	syn_settings_on_change (SYN_Settings * s, SYN_SettingsChangeCallback cb, void * ctx) Register a change callback.
SYN_Status	syn_settings_reload (SYN_Settings * s) Reload settings from flash, discarding any unsaved changes.
SYN_Status	syn_settings_reset (SYN_Settings * s) Reset settings to defaults and save.
SYN_Status	syn_settings_save (SYN_Settings * s) Save current settings to flash.

Public Static Functions¶

Type	Name
uint16_t	syn_settings_checksum (const SYN_Settings * s) Get the current CRC-16 checksum of the settings data.

Detailed Description¶

Wraps syn_param (wear-leveled flash storage) with: * Automatic CRC-16 checksum for change detection * Default values initialization * Load-or-default on init * Dirty tracking (has data changed since last save?) * Optional change callback

Eliminates the repetitive InitSettings / LoadSettings / SaveSettings / update_checksum boilerplate seen in every firmware module.

** **

typedef struct {
    int32_t velocity_max;
    int32_t acceleration;
    int32_t power_max;
} MoverSettings;

static const MoverSettings defaults = { 500, 200, 80 };
static MoverSettings settings;
static SYN_Settings store;

// Init — loads from flash or applies defaults:
syn_settings_init(&store, FLASH_MOVER_BASE, 2,
                  &settings, sizeof(settings), &defaults);

// Modify and save:
settings.velocity_max = 600;
syn_settings_save(&store);  // CRC updated, writes flash

// Remote sync — check if remote copy is stale:
if (remote_checksum != syn_settings_checksum(&store)) {
    send_settings_to_remote(&settings);
}

Public Types Documentation¶

typedef SYN_SettingsChangeCallback¶

Called when syn_settings_save() detects the data has changed.

typedef void(* SYN_SettingsChangeCallback) (void *data, void *ctx);

Parameters:

data Pointer to the settings struct.
ctx User context.

Public Functions Documentation¶

function syn_settings_changed¶

Check if settings have changed since last save/load.

bool syn_settings_changed (
    const SYN_Settings * s
)

Recomputes CRC-16 and compares to stored checksum. Does NOT save — use this for polling change detection.

Parameters:

s Settings instance.

Returns:

true if data has changed.

function syn_settings_dual_bank_init¶

Initialize dual-bank transactional settings manager.

SYN_Status syn_settings_dual_bank_init (
    SYN_DualBankSettings * db,
    uint32_t flash_base_a,
    uint32_t flash_base_b,
    uint8_t sector_count,
    void * data,
    uint16_t data_size,
    const void * defaults
)

Parameters:

db Dual-bank settings instance.
flash_base_a Base flash address for Bank A.
flash_base_b Base flash address for Bank B.
sector_count Sectors per bank.
data Pointer to RAM settings struct.
data_size Size of settings struct in bytes.
defaults Pointer to default values in ROM.

Returns:

SYN_OK on success.

function syn_settings_dual_bank_save¶

Atomically save settings to inactive bank and switch active bank upon CRC32 verification.

SYN_Status syn_settings_dual_bank_save (
    SYN_DualBankSettings * db
)

Parameters:

db Dual-bank settings instance.

Returns:

SYN_OK on success.

function syn_settings_export¶

Export current settings to a binary buffer.

int syn_settings_export (
    const SYN_Settings * s,
    void * buf,
    size_t len
)

Parameters:

s Settings instance.
buf Destination buffer.
len Capacity of buffer.

Returns:

Bytes written on success, or negative error code if buffer too small.

function syn_settings_export_vfs¶

Export settings directly to a VFS file.

SYN_Status syn_settings_export_vfs (
    const SYN_Settings * s,
    const char * filepath
)

Parameters:

s Settings instance.
filepath Target VFS path (e.g. "/sd/config.bin").

Returns:

SYN_OK on success, error code otherwise.

function syn_settings_import¶

Import settings from a binary buffer and validate.

SYN_Status syn_settings_import (
    SYN_Settings * s,
    const void * buf,
    size_t len,
    bool save
)

Parameters:

s Settings instance.
buf Source buffer containing exported settings.
len Length of buffer.
save If true, automatically save to flash if valid.

Returns:

SYN_OK on success, SYN_INVALID_PARAM on size mismatch.

function syn_settings_import_vfs¶

Import settings directly from a VFS file.

SYN_Status syn_settings_import_vfs (
    SYN_Settings * s,
    const char * filepath,
    bool save
)

Parameters:

s Settings instance.
filepath Source VFS path (e.g. "/sd/config.bin").
save If true, save imported settings to flash upon verification.

Returns:

SYN_OK on success, error code otherwise.

function syn_settings_init¶

Initialize the settings manager.

SYN_Status syn_settings_init (
    SYN_Settings * s,
    uint32_t flash_base,
    uint8_t sector_count,
    void * data,
    uint16_t data_size,
    const void * defaults
)

Attempts to load settings from flash. If flash contains valid data (matching size + CRC), it's loaded into *data. Otherwise, *defaults are copied into *data and saved to flash.

Parameters:

s Settings instance.
flash_base Base address of the flash region for this setting.
sector_count Number of flash sectors to use (more = longer wear life).
data Pointer to the user's settings struct (RAM).
data_size Size of the settings struct in bytes.
defaults Pointer to default values (const, typically in ROM).

Returns:

SYN_OK on success.

function syn_settings_on_change¶

Register a change callback.

void syn_settings_on_change (
    SYN_Settings * s,
    SYN_SettingsChangeCallback cb,
    void * ctx
)

Called when syn_settings_save() detects that data has changed.

Parameters:

s Settings instance.
cb Callback function.
ctx User context.

function syn_settings_reload¶

Reload settings from flash, discarding any unsaved changes.

SYN_Status syn_settings_reload (
    SYN_Settings * s
)

Parameters:

s Settings instance.

Returns:

SYN_OK if loaded, SYN_ERR_NOT_FOUND if flash has no valid data.

function syn_settings_reset¶

Reset settings to defaults and save.

SYN_Status syn_settings_reset (
    SYN_Settings * s
)

Copies defaults into the data struct, saves to flash.

Parameters:

s Settings instance.

Returns:

SYN_OK on success.

function syn_settings_save¶

Save current settings to flash.

SYN_Status syn_settings_save (
    SYN_Settings * s
)

Computes CRC-16 of the current data. If it differs from the last known checksum, writes to flash and calls the change callback. If unchanged, this is a no-op (no flash write).

Parameters:

s Settings instance.

Returns:

SYN_OK on success, or flash write error.

Public Static Functions Documentation¶

function syn_settings_checksum¶

Get the current CRC-16 checksum of the settings data.

static inline uint16_t syn_settings_checksum (
    const SYN_Settings * s
)

Useful for comparing against a remote copy to detect staleness. This returns the checksum computed at the last save/load, NOT a live recomputation. Call syn_settings_save() first to update.

Parameters:

s Settings instance.

Returns:

CRC-16 checksum.

The documentation for this class was generated from the following file src/syntropic/storage/syn_settings.h