STM32 NVS — flash-backed key-value store with wear leveling. More...

#include <StmNvs.h>

Inheritance diagram for StmNvs:

Collaboration diagram for StmNvs:

Classes
struct	CacheEntry
	RAM cache entry. More...

Public Member Functions
	StmNvs (const char *namespace_name="default", const hf_stm32_nvs_config_t &flash_config=hf_stm32_nvs_config_t()) noexcept
	Construct with namespace and flash configuration.

	~StmNvs () noexcept override

hf_nvs_err_t	Initialize () noexcept override
	Initialize the storage system and open the namespace.

hf_nvs_err_t	Deinitialize () noexcept override
	Deinitialize the storage system and close the namespace.

hf_nvs_err_t	SetU32 (const char *key, hf_u32_t value) noexcept override
	Store a 32-bit unsigned integer value.

hf_nvs_err_t	GetU32 (const char *key, hf_u32_t &value) noexcept override
	Retrieve a 32-bit unsigned integer value.

hf_nvs_err_t	SetString (const char key, const char value) noexcept override
	Store a string value.

hf_nvs_err_t	GetString (const char key, char buffer, size_t buffer_size, size_t *actual_size=nullptr) noexcept override
	Retrieve a string value.

hf_nvs_err_t	SetBlob (const char key, const void data, size_t data_size) noexcept override
	Store binary data (blob).

hf_nvs_err_t	GetBlob (const char key, void buffer, size_t buffer_size, size_t *actual_size=nullptr) noexcept override
	Retrieve binary data (blob).

hf_nvs_err_t	EraseKey (const char *key) noexcept override
	Remove a key from storage.

hf_nvs_err_t	Commit () noexcept override
	Commit any pending writes to non-volatile storage.

bool	KeyExists (const char *key) noexcept override
	Check if a key exists in storage.

hf_nvs_err_t	GetSize (const char *key, size_t &size) noexcept override
	Get the size of a stored value.

const char *	GetDescription () const noexcept override
	Get description of this storage implementation.

size_t	GetMaxKeyLength () const noexcept override
	Get maximum key length supported.

size_t	GetMaxValueSize () const noexcept override
	Get maximum value size supported.

const hf_stm32_nvs_config_t &	GetFlashConfig () const noexcept
	Get the flash configuration.

size_t	GetEntryCount () const noexcept
	Get number of stored entries.

size_t	GetFreeSpace () const noexcept
	Get available free space in current sector (bytes)

Public Member Functions inherited from BaseNvs
virtual	~BaseNvs () noexcept=default
	Virtual destructor to ensure proper cleanup.

	BaseNvs (const BaseNvs &)=delete

BaseNvs &	operator= (const BaseNvs &)=delete

bool	EnsureInitialized ()
	Ensures that the NVS storage is initialized (lazy initialization).

bool	EnsureDeinitialized ()
	Ensures that the NVS storage is deinitialized.

bool	IsInitialized () const noexcept
	Check if storage is initialized.

const char *	GetNamespace () const noexcept
	Get the namespace name.

virtual hf_nvs_err_t	ResetStatistics () noexcept
	Reset NVS operation statistics.

virtual hf_nvs_err_t	ResetDiagnostics () noexcept
	Reset NVS diagnostic information.

virtual hf_nvs_err_t	GetStatistics (hf_nvs_statistics_t &statistics) const noexcept
	Get NVS operation statistics.

virtual hf_nvs_err_t	GetDiagnostics (hf_nvs_diagnostics_t &diagnostics) const noexcept
	Get NVS diagnostic information.

Private Types
enum class	EntryType : hf_u8_t { U32 = 0x01 , STRING = 0x02 , BLOB = 0x03 , ERASED = 0xFF }
	NVS entry types. More...

Private Member Functions
struct	__attribute__ ((packed)) EntryHeader
	Entry header stored in flash (packed)

int	FindCacheEntry (const char *key) const noexcept
	Find entry in RAM cache by key.

int	AddOrUpdateCache (const char key, EntryType type, const void data, size_t data_size) noexcept
	Add or update entry in RAM cache.

bool	IsValidKey (const char *key) const noexcept
	Validate a key string.

hf_nvs_err_t	FlushToFlash () noexcept
	Write all dirty entries to flash.

hf_nvs_err_t	LoadFromFlash () noexcept
	Read entries from flash into RAM cache.

Static Private Member Functions
static hf_u32_t	ComputeCrc32 (const void *data, size_t length) noexcept
	Simple CRC32 for entry validation.

Private Attributes
hf_stm32_nvs_config_t	flash_config_
	Flash region config.

CacheEntry	cache_ [kMaxEntries]
	RAM cache.

size_t	entry_count_
	Current entry count.

hf_u32_t	write_offset_
	Current write position in flash.

Static Private Attributes
static constexpr size_t	kMaxEntries = 64
	Max cached entries.

Additional Inherited Members
Protected Member Functions inherited from BaseNvs
	BaseNvs (const char *namespace_name) noexcept
	Protected constructor with namespace specification.

void	SetInitialized (bool initialized) noexcept
	Set the initialized state.

Protected Attributes inherited from BaseNvs
const char *	namespace_name_
	Namespace name.

bool	initialized_
	Initialization status.

hf_nvs_statistics_t	statistics_
	NVS operation statistics.

hf_nvs_diagnostics_t	diagnostics_
	NVS diagnostic information.

Detailed Description

STM32 NVS — flash-backed key-value store with wear leveling.

Design:

Uses a flat log of {key_len, key[], type, data_len, data[]} entries
New writes append; reads scan from end to find latest value
Commit triggers flash write of dirty entries
When sector is full, compact (copy live entries to backup sector, erase, swap)
Supports U32, String, and Blob value types

Note: Flash operations require HAL_FLASH_Unlock/Lock — handled internally.

Member Enumeration Documentation

◆ EntryType

enum class StmNvs::EntryType : hf_u8_t

strongprivate

NVS entry types.

Enumerator
U32
STRING
BLOB
ERASED

Constructor & Destructor Documentation

◆ StmNvs()

StmNvs::StmNvs	(	const char *	namespace_name = "default",
		const hf_stm32_nvs_config_t &	flash_config = hf_stm32_nvs_config_t() )

explicitnoexcept

Construct with namespace and flash configuration.

Parameters

namespace_name	Logical namespace (for multi-partition support)
flash_config	Flash region configuration

◆ ~StmNvs()

StmNvs::~StmNvs ( )

overridenoexcept

Member Function Documentation

◆ attribute()

struct StmNvs::__attribute__ ( (packed) )

inlineprivate

Entry header stored in flash (packed)

< Key string length (not including null)

< Value type

< Data length in bytes

< CRC32 of key + data

◆ AddOrUpdateCache()

int StmNvs::AddOrUpdateCache	(	const char *	key,
		EntryType	type,
		const void *	data,
		size_t	data_size )

privatenoexcept

Add or update entry in RAM cache.

◆ Commit()

hf_nvs_err_t StmNvs::Commit ( )

overridevirtualnoexcept

Commit any pending writes to non-volatile storage.

Returns: hf_nvs_err_t::NVS_SUCCESS if successful, error code otherwise

Implements BaseNvs.

◆ ComputeCrc32()

hf_u32_t StmNvs::ComputeCrc32	(	const void *	data,
		size_t	length )

staticprivatenoexcept

Simple CRC32 for entry validation.

◆ Deinitialize()

hf_nvs_err_t StmNvs::Deinitialize ( )

overridevirtualnoexcept

Deinitialize the storage system and close the namespace.

Returns: hf_nvs_err_t::NVS_SUCCESS if successful, error code otherwise

Implements BaseNvs.

◆ EraseKey()

hf_nvs_err_t StmNvs::EraseKey ( const char * key )

overridevirtualnoexcept

Remove a key from storage.

Parameters

key	Storage key to remove

Returns: hf_nvs_err_t::NVS_SUCCESS if successful, error code otherwise

Implements BaseNvs.

◆ FindCacheEntry()

int StmNvs::FindCacheEntry ( const char * key ) const

privatenoexcept

Find entry in RAM cache by key.

◆ FlushToFlash()

hf_nvs_err_t StmNvs::FlushToFlash ( )

privatenoexcept

Write all dirty entries to flash.

◆ GetBlob()

hf_nvs_err_t StmNvs::GetBlob	(	const char *	key,
		void *	buffer,
		size_t	buffer_size,
		size_t *	actual_size = nullptr )

overridevirtualnoexcept

Retrieve binary data (blob).

Parameters

key	Storage key (null-terminated string)
buffer	Buffer to store the retrieved data
buffer_size	Size of the buffer in bytes
actual_size	Actual size of the data (optional)

Returns: hf_nvs_err_t::NVS_SUCCESS if successful, error code otherwise

Implements BaseNvs.

◆ GetDescription()

const char * StmNvs::GetDescription ( ) const

overridevirtualnoexcept

Get description of this storage implementation.

Returns: Description string

Implements BaseNvs.

◆ GetEntryCount()

size_t StmNvs::GetEntryCount ( ) const

inlinenoexcept

Get number of stored entries.

◆ GetFlashConfig()

const hf_stm32_nvs_config_t & StmNvs::GetFlashConfig ( ) const

inlinenoexcept

Get the flash configuration.

◆ GetFreeSpace()

size_t StmNvs::GetFreeSpace ( ) const

noexcept

Get available free space in current sector (bytes)

◆ GetMaxKeyLength()

size_t StmNvs::GetMaxKeyLength ( ) const

overridevirtualnoexcept

Get maximum key length supported.

Returns: Maximum key length in characters

Implements BaseNvs.

◆ GetMaxValueSize()

size_t StmNvs::GetMaxValueSize ( ) const

overridevirtualnoexcept

Get maximum value size supported.

Returns: Maximum value size in bytes

Implements BaseNvs.

◆ GetSize()

hf_nvs_err_t StmNvs::GetSize	(	const char *	key,
		size_t &	size )

overridevirtualnoexcept

Get the size of a stored value.

Parameters

key	Storage key
size	Reference to store the size

Returns: hf_nvs_err_t::NVS_SUCCESS if successful, error code otherwise

Implements BaseNvs.

◆ GetString()

hf_nvs_err_t StmNvs::GetString	(	const char *	key,
		char *	buffer,
		size_t	buffer_size,
		size_t *	actual_size = nullptr )

overridevirtualnoexcept

Retrieve a string value.

Parameters

key	Storage key (null-terminated string)
buffer	Buffer to store the retrieved string
buffer_size	Size of the buffer in bytes
actual_size	Actual size of the string (optional)

Returns: hf_nvs_err_t::NVS_SUCCESS if successful, error code otherwise

Implements BaseNvs.

◆ GetU32()

hf_nvs_err_t StmNvs::GetU32	(	const char *	key,
		hf_u32_t &	value )

overridevirtualnoexcept

Retrieve a 32-bit unsigned integer value.

Parameters

key	Storage key (null-terminated string)
value	Reference to store the retrieved value

Returns: hf_nvs_err_t::NVS_SUCCESS if successful, error code otherwise

Implements BaseNvs.

◆ Initialize()

hf_nvs_err_t StmNvs::Initialize ( )

overridevirtualnoexcept

Initialize the storage system and open the namespace.

Returns: hf_nvs_err_t::NVS_SUCCESS if successful, error code otherwise

Implements BaseNvs.

◆ IsValidKey()

bool StmNvs::IsValidKey ( const char * key ) const

privatenoexcept

Validate a key string.

◆ KeyExists()

bool StmNvs::KeyExists ( const char * key )

overridevirtualnoexcept

Check if a key exists in storage.

Parameters

key	Storage key to check

Returns: true if key exists, false otherwise

Implements BaseNvs.

◆ LoadFromFlash()

hf_nvs_err_t StmNvs::LoadFromFlash ( )

privatenoexcept

Read entries from flash into RAM cache.

◆ SetBlob()

hf_nvs_err_t StmNvs::SetBlob	(	const char *	key,
		const void *	data,
		size_t	data_size )

overridevirtualnoexcept

Store binary data (blob).

Parameters

key	Storage key (null-terminated string)
data	Pointer to data to store
data_size	Size of data in bytes

Returns: hf_nvs_err_t::NVS_SUCCESS if successful, error code otherwise

Implements BaseNvs.

◆ SetString()

hf_nvs_err_t StmNvs::SetString	(	const char *	key,
		const char *	value )

overridevirtualnoexcept

Store a string value.

Parameters

key	Storage key (null-terminated string)
value	String value to store

Returns: hf_nvs_err_t::NVS_SUCCESS if successful, error code otherwise

Implements BaseNvs.

◆ SetU32()

hf_nvs_err_t StmNvs::SetU32	(	const char *	key,
		hf_u32_t	value )

overridevirtualnoexcept

Store a 32-bit unsigned integer value.

Parameters

key	Storage key (null-terminated string)
value	Value to store

Returns: hf_nvs_err_t::NVS_SUCCESS if successful, error code otherwise

Implements BaseNvs.

Member Data Documentation

◆ cache_

CacheEntry StmNvs::cache_[kMaxEntries]

private

RAM cache.

◆ entry_count_

size_t StmNvs::entry_count_

private

Current entry count.

◆ flash_config_

hf_stm32_nvs_config_t StmNvs::flash_config_

private

Flash region config.

◆ kMaxEntries

constexpr size_t StmNvs::kMaxEntries = 64

staticconstexprprivate

Max cached entries.

◆ write_offset_

hf_u32_t StmNvs::write_offset_

private

Current write position in flash.

The documentation for this class was generated from the following files:

inc/mcu/stm32/StmNvs.h
src/mcu/stm32/StmNvs.cpp

Classes

Public Member Functions

Private Types

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ EntryType

Constructor & Destructor Documentation

◆ StmNvs()

◆ ~StmNvs()

Member Function Documentation

◆ __attribute__()

◆ AddOrUpdateCache()

◆ Commit()

◆ ComputeCrc32()

◆ Deinitialize()

◆ EraseKey()

◆ FindCacheEntry()

◆ FlushToFlash()

◆ GetBlob()

◆ GetDescription()

◆ GetEntryCount()

◆ GetFlashConfig()

◆ GetFreeSpace()

◆ GetMaxKeyLength()

◆ GetMaxValueSize()

◆ GetSize()

◆ GetString()

◆ GetU32()

◆ Initialize()

◆ IsValidKey()

◆ KeyExists()

◆ LoadFromFlash()

◆ SetBlob()

◆ SetString()

◆ SetU32()

Member Data Documentation

◆ cache_

◆ entry_count_

◆ flash_config_

◆ kMaxEntries

◆ write_offset_

◆ attribute()