cfn_hal_nvm.h File Reference

NVM (Non-Volatile Memory) HAL API. More...

#include "cfn_hal.h"
#include "cfn_hal_base.h"
#include "cfn_hal_types.h"

Go to the source code of this file.

Data Structures
struct	cfn_hal_nvm_info_t
	NVM memory organization information. More...
struct	cfn_hal_nvm_config_t
	NVM configuration structure. More...
struct	cfn_hal_nvm_phy_t
	NVM hardware physical mapping. More...
struct	cfn_hal_nvm_api_s
	NVM Virtual Method Table (VMT). More...

Typedefs
typedef struct cfn_hal_nvm_s	cfn_hal_nvm_t
typedef struct cfn_hal_nvm_api_s	cfn_hal_nvm_api_t
typedef void(*	cfn_hal_nvm_callback_t) (cfn_hal_nvm_t *driver, uint32_t event_mask, uint32_t error_mask, void *user_arg)
	NVM callback signature.

Enumerations
enum	cfn_hal_nvm_event_t { CFN_HAL_NVM_EVENT_NONE = 0 , CFN_HAL_NVM_EVENT_WRITE_COMPLETE = CFN_HAL_BIT(0) , CFN_HAL_NVM_EVENT_ERASE_COMPLETE = CFN_HAL_BIT(1) }
	NVM nominal event flags. More...
enum	cfn_hal_nvm_error_t { CFN_HAL_NVM_ERROR_NONE = 0 , CFN_HAL_NVM_ERROR_PROTECTED = CFN_HAL_BIT(0) , CFN_HAL_NVM_ERROR_ALIGNMENT = CFN_HAL_BIT(1) , CFN_HAL_NVM_ERROR_GENERAL = CFN_HAL_BIT(2) }
	NVM exception error flags. More...

Functions
	CFN_HAL_VMT_CHECK (struct cfn_hal_nvm_api_s)
	CFN_HAL_CREATE_DRIVER_TYPE (nvm, cfn_hal_nvm_config_t, cfn_hal_nvm_api_t, cfn_hal_nvm_phy_t, cfn_hal_nvm_callback_t)
CFN_HAL_INLINE void	cfn_hal_nvm_populate (cfn_hal_nvm_t *driver, uint32_t peripheral_id, struct cfn_hal_clock_s *clock, void *dependency, const cfn_hal_nvm_api_t *api, const cfn_hal_nvm_phy_t *phy, const cfn_hal_nvm_config_t *config, cfn_hal_nvm_callback_t callback, void *user_arg)
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_nvm_config_validate (const cfn_hal_nvm_t *driver, const cfn_hal_nvm_config_t *config)
	Validates the NVM configuration.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_nvm_init (cfn_hal_nvm_t *driver)
	Initializes the NVM controller driver.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_nvm_deinit (cfn_hal_nvm_t *driver)
	Deinitializes the NVM controller driver.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_nvm_config_set (cfn_hal_nvm_t *driver, const cfn_hal_nvm_config_t *config)
	Sets the NVM configuration.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_nvm_config_get (cfn_hal_nvm_t *driver, cfn_hal_nvm_config_t *config)
	Gets the current NVM configuration.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_nvm_callback_register (cfn_hal_nvm_t *driver, const cfn_hal_nvm_callback_t callback, void *user_arg)
	Registers a callback for NVM events and errors.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_nvm_power_state_set (cfn_hal_nvm_t *driver, cfn_hal_power_state_t state)
	Sets the NVM power state.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_nvm_event_enable (cfn_hal_nvm_t *driver, uint32_t event_mask)
	Enables one or more NVM nominal events.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_nvm_event_disable (cfn_hal_nvm_t *driver, uint32_t event_mask)
	Disables one or more NVM nominal events.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_nvm_event_get (cfn_hal_nvm_t *driver, uint32_t *event_mask)
	Retrieves the current NVM nominal event status.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_nvm_error_enable (cfn_hal_nvm_t *driver, uint32_t error_mask)
	Enables one or more NVM exception errors.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_nvm_error_disable (cfn_hal_nvm_t *driver, uint32_t error_mask)
	Disables one or more NVM exception errors.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_nvm_error_get (cfn_hal_nvm_t *driver, uint32_t *error_mask)
	Retrieves the current NVM exception error status.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_nvm_read (cfn_hal_nvm_t *driver, uint32_t addr, uint8_t *buffer, size_t size, uint32_t timeout)
	Reads data from non-volatile memory.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_nvm_write (cfn_hal_nvm_t *driver, uint32_t addr, const uint8_t *data, size_t size, uint32_t timeout)
	Programs data into non-volatile memory.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_nvm_erase_sector (cfn_hal_nvm_t *driver, uint32_t sector_addr, uint32_t timeout)
	Erases a specific sector or page of memory.
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_nvm_erase_chip (cfn_hal_nvm_t *driver, uint32_t timeout)
	Erases the entire non-volatile memory (Bulk Erase).
CFN_HAL_INLINE cfn_hal_error_code_t	cfn_hal_nvm_get_info (cfn_hal_nvm_t *driver, uint32_t addr, cfn_hal_nvm_info_t *info)
	Retrieves information about memory organization and endurance for a specific address.
cfn_hal_error_code_t	cfn_hal_nvm_construct (cfn_hal_nvm_t *driver, const cfn_hal_nvm_config_t *config, const cfn_hal_nvm_phy_t *phy, struct cfn_hal_clock_s *clock, void *dependency, cfn_hal_nvm_callback_t callback, void *user_arg)
cfn_hal_error_code_t	cfn_hal_nvm_destruct (cfn_hal_nvm_t *driver)

Detailed Description

NVM (Non-Volatile Memory) HAL API.

Copyright (c) 2026 Hisham Moussa Daou https://www.whileone.me

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Typedef Documentation

cfn_hal_nvm_api_t

typedef struct cfn_hal_nvm_api_s cfn_hal_nvm_api_t

cfn_hal_nvm_callback_t

typedef void(* cfn_hal_nvm_callback_t) (cfn_hal_nvm_t *driver, uint32_t event_mask, uint32_t error_mask, void *user_arg)

NVM callback signature.

Parameters

driver	Pointer to the NVM driver instance.
event_mask	Mask of triggered nominal events.
error_mask	Mask of triggered exception errors.
user_arg	User-defined argument passed during registration.

cfn_hal_nvm_t

typedef struct cfn_hal_nvm_s cfn_hal_nvm_t

Enumeration Type Documentation

cfn_hal_nvm_error_t

enum cfn_hal_nvm_error_t

NVM exception error flags.

Enumerator
CFN_HAL_NVM_ERROR_NONE
CFN_HAL_NVM_ERROR_PROTECTED	Access to protected area denied
CFN_HAL_NVM_ERROR_ALIGNMENT	Invalid address or size alignment
CFN_HAL_NVM_ERROR_GENERAL	General hardware error

cfn_hal_nvm_event_t

enum cfn_hal_nvm_event_t

NVM nominal event flags.

Enumerator
CFN_HAL_NVM_EVENT_NONE
CFN_HAL_NVM_EVENT_WRITE_COMPLETE	Page or byte write finished
CFN_HAL_NVM_EVENT_ERASE_COMPLETE	Sector or chip erase finished

Function Documentation

CFN_HAL_CREATE_DRIVER_TYPE()

CFN_HAL_CREATE_DRIVER_TYPE	(	nvm	,
		cfn_hal_nvm_config_t	,
		cfn_hal_nvm_api_t	,
		cfn_hal_nvm_phy_t	,
		cfn_hal_nvm_callback_t
	)

cfn_hal_nvm_callback_register()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_nvm_callback_register	(	cfn_hal_nvm_t *	driver,
		const cfn_hal_nvm_callback_t	callback,
		void *	user_arg
	)

Registers a callback for NVM events and errors.

Parameters

driver	Pointer to the NVM driver instance.
callback	The callback function to register.
user_arg	User-defined argument passed to the callback.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_nvm_config_get()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_nvm_config_get	(	cfn_hal_nvm_t *	driver,
		cfn_hal_nvm_config_t *	config
	)

Gets the current NVM configuration.

Parameters

driver	Pointer to the NVM driver instance.
config	[out] Pointer to store the configuration.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_nvm_config_set()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_nvm_config_set	(	cfn_hal_nvm_t *	driver,
		const cfn_hal_nvm_config_t *	config
	)

Sets the NVM configuration.

Parameters

driver	Pointer to the NVM driver instance.
config	Pointer to the configuration structure.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_nvm_config_validate()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_nvm_config_validate	(	const cfn_hal_nvm_t *	driver,
		const cfn_hal_nvm_config_t *	config
	)

Validates the NVM configuration.

Parameters

driver	Pointer to the NVM driver instance.
config	Pointer to the configuration structure.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_nvm_construct()

cfn_hal_error_code_t cfn_hal_nvm_construct	(	cfn_hal_nvm_t *	driver,
		const cfn_hal_nvm_config_t *	config,
		const cfn_hal_nvm_phy_t *	phy,
		struct cfn_hal_clock_s *	clock,
		void *	dependency,
		cfn_hal_nvm_callback_t	callback,
		void *	user_arg
	)

cfn_hal_nvm_deinit()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_nvm_deinit

(

cfn_hal_nvm_t *

driver

)

Deinitializes the NVM controller driver.

Parameters

driver

Pointer to the NVM driver instance.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_nvm_destruct()

cfn_hal_error_code_t cfn_hal_nvm_destruct

(

cfn_hal_nvm_t *

driver

)

cfn_hal_nvm_erase_chip()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_nvm_erase_chip	(	cfn_hal_nvm_t *	driver,
		uint32_t	timeout
	)

Erases the entire non-volatile memory (Bulk Erase).

Parameters

driver	Pointer to the NVM driver instance.
timeout	Maximum time to wait for completion in milliseconds.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_nvm_erase_sector()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_nvm_erase_sector	(	cfn_hal_nvm_t *	driver,
		uint32_t	sector_addr,
		uint32_t	timeout
	)

Erases a specific sector or page of memory.

Parameters

driver	Pointer to the NVM driver instance.
sector_addr	Address within the sector to be erased.
timeout	Maximum time to wait for completion in milliseconds.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_nvm_error_disable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_nvm_error_disable	(	cfn_hal_nvm_t *	driver,
		uint32_t	error_mask
	)

Disables one or more NVM exception errors.

Parameters

driver	Pointer to the NVM driver instance.
error_mask	Mask of errors to disable.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_nvm_error_enable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_nvm_error_enable	(	cfn_hal_nvm_t *	driver,
		uint32_t	error_mask
	)

Enables one or more NVM exception errors.

Parameters

driver	Pointer to the NVM driver instance.
error_mask	Mask of errors to enable.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_nvm_error_get()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_nvm_error_get	(	cfn_hal_nvm_t *	driver,
		uint32_t *	error_mask
	)

Retrieves the current NVM exception error status.

Parameters

driver	Pointer to the NVM driver instance.
error_mask	[out] Pointer to store the error mask.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_nvm_event_disable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_nvm_event_disable	(	cfn_hal_nvm_t *	driver,
		uint32_t	event_mask
	)

Disables one or more NVM nominal events.

Parameters

driver	Pointer to the NVM driver instance.
event_mask	Mask of events to disable.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_nvm_event_enable()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_nvm_event_enable	(	cfn_hal_nvm_t *	driver,
		uint32_t	event_mask
	)

Enables one or more NVM nominal events.

Parameters

driver	Pointer to the NVM driver instance.
event_mask	Mask of events to enable.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_nvm_event_get()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_nvm_event_get	(	cfn_hal_nvm_t *	driver,
		uint32_t *	event_mask
	)

Retrieves the current NVM nominal event status.

Parameters

driver	Pointer to the NVM driver instance.
event_mask	[out] Pointer to store the event mask.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_nvm_get_info()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_nvm_get_info	(	cfn_hal_nvm_t *	driver,
		uint32_t	addr,
		cfn_hal_nvm_info_t *	info
	)

Retrieves information about memory organization and endurance for a specific address.

Parameters

driver	Pointer to the NVM driver instance.
addr	Address within the target sector/region.
info	[out] Pointer to the information structure.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_nvm_init()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_nvm_init

(

cfn_hal_nvm_t *

driver

)

Initializes the NVM controller driver.

Parameters

driver

Pointer to the NVM driver instance.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_nvm_populate()

CFN_HAL_INLINE void cfn_hal_nvm_populate	(	cfn_hal_nvm_t *	driver,
		uint32_t	peripheral_id,
		struct cfn_hal_clock_s *	clock,
		void *	dependency,
		const cfn_hal_nvm_api_t *	api,
		const cfn_hal_nvm_phy_t *	phy,
		const cfn_hal_nvm_config_t *	config,
		cfn_hal_nvm_callback_t	callback,
		void *	user_arg
	)

cfn_hal_nvm_power_state_set()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_nvm_power_state_set	(	cfn_hal_nvm_t *	driver,
		cfn_hal_power_state_t	state
	)

Sets the NVM power state.

Parameters

driver	Pointer to the NVM driver instance.
state	Target power state.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_nvm_read()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_nvm_read	(	cfn_hal_nvm_t *	driver,
		uint32_t	addr,
		uint8_t *	buffer,
		size_t	size,
		uint32_t	timeout
	)

Reads data from non-volatile memory.

Parameters

driver	Pointer to the NVM driver instance.
addr	Source memory address.
buffer	Pointer to the buffer where data will be stored.
size	Number of bytes to read.
timeout	Maximum time to wait for completion in milliseconds.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

cfn_hal_nvm_write()

CFN_HAL_INLINE cfn_hal_error_code_t cfn_hal_nvm_write	(	cfn_hal_nvm_t *	driver,
		uint32_t	addr,
		const uint8_t *	data,
		size_t	size,
		uint32_t	timeout
	)

Programs data into non-volatile memory.

Parameters

driver	Pointer to the NVM driver instance.
addr	Destination memory address.
data	Pointer to the data to be written.
size	Number of bytes to write.
timeout	Maximum time to wait for completion in milliseconds.

Returns

CFN_HAL_ERROR_OK on success, or a specific error code on failure.

CFN_HAL_VMT_CHECK()

CFN_HAL_VMT_CHECK

(

struct cfn_hal_nvm_api_s

)