Zpal-nvm#

Defines a platform abstraction layer for the Z-Wave NVM.

How to use the entropy API

The ZPAL NVM provides a way for an application to safely store and retrieve variable size data in a page-based non-volatile memory (NVM). Data are identified with 20-bit identifiers denoted as data_id.

The following outlines an example of use:

Initialize module with zpal_nvm_init().
Invoke zpal_nvm_write() to store data.
Invoke zpal_nvm_read() to get data.

Enumerations#

enum

zpal_nvm_area_t {

ZPAL_NVM_AREA_APPLICATION

ZPAL_NVM_AREA_ZAF

ZPAL_NVM_AREA_STACK

ZPAL_NVM_AREA_MANUFACTURER_TOKENS

}

Defines the different areas of NVM storage.

Typedefs#

typedef uint32_t

zpal_nvm_object_key_t

Data id type.

typedef void *

zpal_nvm_handle_t

Defines the NVM handle type.

Functions#

zpal_nvm_handle_t

zpal_nvm_init(zpal_nvm_area_t area)

Initializes the NVM for a given area.

zpal_status_t

zpal_nvm_close(zpal_nvm_handle_t handle)

Closes the NVM of a given handle.

zpal_status_t

zpal_nvm_read(zpal_nvm_handle_t handle, zpal_nvm_object_key_t key, void *object, size_t object_size)

Reads object from a given area handle and given object key.

zpal_status_t

zpal_nvm_read_object_part(zpal_nvm_handle_t handle, zpal_nvm_object_key_t key, void *object, size_t offset, size_t object_size)

Reads part of object from a given area handle and given object key.

zpal_status_t

zpal_nvm_write(zpal_nvm_handle_t handle, zpal_nvm_object_key_t key, const void *object, size_t object_size)

Writes object to a given area handle and given object key.

zpal_status_t

zpal_nvm_erase_all(zpal_nvm_handle_t handle)

Erases everything in a given area.

zpal_status_t

zpal_nvm_erase_object(zpal_nvm_handle_t handle, zpal_nvm_object_key_t key)

Delete an object from NVM.

zpal_status_t

zpal_nvm_get_object_size(zpal_nvm_handle_t handle, zpal_nvm_object_key_t key, size_t *len)

Get the object size identified with a given key from NVM.

size_t

zpal_nvm_enum_objects(zpal_nvm_handle_t handle, zpal_nvm_object_key_t *key_list, size_t key_list_size, zpal_nvm_object_key_t key_min, zpal_nvm_object_key_t key_max)

Create a list of key for valid objects in NVM.

zpal_status_t

zpal_nvm_backup_open(void)

Opens the NVM for a backup/restore operation.

void

zpal_nvm_backup_close(void)

Closes the NVM after backup/restore operation.

zpal_status_t

zpal_nvm_backup_read(uint32_t offset, void *data, size_t data_length)

Reads raw data from the NVM.

zpal_status_t

zpal_nvm_backup_write(uint32_t offset, const void *data, size_t data_length)

Writes raw data to the NVM.

size_t

zpal_nvm_backup_get_size(void)

Get size of raw NVM area.

zpal_status_t

zpal_nvm_lock(zpal_nvm_handle_t handle)

Set write protection for storage.

zpal_status_t

zpal_nvm_migrate_legacy_app_file_system(void)

Migrates 800s legacy application file system to shared app/protocol file system.

Enumeration Documentation#

zpal_nvm_area_t#

zpal_nvm_area_t

Defines the different areas of NVM storage.

Enumerator
ZPAL_NVM_AREA_APPLICATION	Reserved for application data.
ZPAL_NVM_AREA_ZAF	Reserved for ZAF data.
ZPAL_NVM_AREA_STACK	Reserved for stack data.
ZPAL_NVM_AREA_MANUFACTURER_TOKENS	Reserved for manufacturer tokens.

Typedef Documentation#

zpal_nvm_object_key_t#

typedef uint32_t zpal_nvm_object_key_t

Data id type.

Only the 20 least significant bits are used.

zpal_nvm_handle_t#

typedef void* zpal_nvm_handle_t

Defines the NVM handle type.

Function Documentation#

zpal_nvm_init#

zpal_nvm_handle_t zpal_nvm_init (zpal_nvm_area_t area)

Initializes the NVM for a given area.

Parameters

Type	Direction	Argument Name	Description
zpal_nvm_area_t	[in]	area	NVM area to initialize.

Returns

A valid NVM handle if successfully initialized. Otherwise it returns NULL.

zpal_nvm_close#

zpal_status_t zpal_nvm_close (zpal_nvm_handle_t handle)

Closes the NVM of a given handle.

Parameters

Type	Direction	Argument Name	Description
zpal_nvm_handle_t	[in]	handle	NVM area handle.

Returns

ZPAL_STATUS_OK if the file system was successfully closed and ZPAL_STATUS_FAIL otherwise.

zpal_nvm_read#

zpal_status_t zpal_nvm_read (zpal_nvm_handle_t handle, zpal_nvm_object_key_t key, void * object, size_t object_size)

Reads object from a given area handle and given object key.

Parameters

Type	Direction	Argument Name	Description
zpal_nvm_handle_t	[in]	handle	NVM area handle.
zpal_nvm_object_key_t	[in]	key	Object key.
void *	[out]	object	Address of array where object can be written to.
size_t	[in]	object_size	Size of the stored object.

Returns

ZPAL_STATUS_OK if the object was successfully read and ZPAL_STATUS_FAIL otherwise.

zpal_nvm_read_object_part#

zpal_status_t zpal_nvm_read_object_part (zpal_nvm_handle_t handle, zpal_nvm_object_key_t key, void * object, size_t offset, size_t object_size)

Reads part of object from a given area handle and given object key.

Parameters

Type	Direction	Argument Name	Description
zpal_nvm_handle_t	[in]	handle	NVM area handle.
zpal_nvm_object_key_t	[in]	key	Object key.
void *	[out]	object	Address of array where object can be written to.
size_t	[in]	offset	The offset where object shall be read from.
size_t	[in]	object_size	Size of the stored object.

Returns

ZPAL_STATUS_OK if the object was successfully read and ZPAL_STATUS_FAIL otherwise.

zpal_nvm_write#

zpal_status_t zpal_nvm_write (zpal_nvm_handle_t handle, zpal_nvm_object_key_t key, const void * object, size_t object_size)

Writes object to a given area handle and given object key.

Parameters

Type	Direction	Argument Name	Description
zpal_nvm_handle_t	[in]	handle	NVM area handle.
zpal_nvm_object_key_t	[in]	key	Object key.
const void *	[out]	object	Address of array of object that must be written.
size_t	[in]	object_size	Size of the object to be stored.

Returns

ZPAL_STATUS_OK if the object was successfully written and ZPAL_STATUS_FAIL otherwise.

zpal_nvm_erase_all#

zpal_status_t zpal_nvm_erase_all (zpal_nvm_handle_t handle)

Erases everything in a given area.

Parameters

Type	Direction	Argument Name	Description
zpal_nvm_handle_t	[in]	handle	NVM area handle.

Returns

ZPAL_STATUS_OK if the all objects was successfully erased and ZPAL_STATUS_FAIL otherwise.

zpal_nvm_erase_object#

zpal_status_t zpal_nvm_erase_object (zpal_nvm_handle_t handle, zpal_nvm_object_key_t key)

Delete an object from NVM.

Parameters

Type	Direction	Argument Name	Description
zpal_nvm_handle_t	[in]	handle	Nvm storage handle.
zpal_nvm_object_key_t	[in]	key	Object key.

Returns

ZPAL_STATUS_OK on success and ZPAL_STATUS_FAIL otherwise.

zpal_nvm_get_object_size#

zpal_status_t zpal_nvm_get_object_size (zpal_nvm_handle_t handle, zpal_nvm_object_key_t key, size_t * len)

Get the object size identified with a given key from NVM.

Parameters

Type	Direction	Argument Name	Description
zpal_nvm_handle_t	[in]	handle	Nvm storage handle.
zpal_nvm_object_key_t	[in]	key	Object key.
size_t *	[out]	len	Object size.

Returns

ZPAL_STATUS_OK on success and ZPAL_STATUS_FAIL otherwise.

zpal_nvm_enum_objects#

size_t zpal_nvm_enum_objects (zpal_nvm_handle_t handle, zpal_nvm_object_key_t * key_list, size_t key_list_size, zpal_nvm_object_key_t key_min, zpal_nvm_object_key_t key_max)

Create a list of key for valid objects in NVM.

Parameters

Type	Direction	Argument Name	Description
zpal_nvm_handle_t	[in]	handle	Nvm storage handle.
zpal_nvm_object_key_t *	[out]	key_list	A pointer to a buffer for the key list.
size_t	[in]	key_list_size	The size of the key list buffer.
zpal_nvm_object_key_t	[in]	key_min	The lower search key.
zpal_nvm_object_key_t	[in]	key_max	The upper search key.

Returns

The number of keys written to the key list. This value is less than or equal to key_list_size.

zpal_nvm_backup_open#

zpal_status_t zpal_nvm_backup_open (void )

Opens the NVM for a backup/restore operation.

Parameters

Type	Direction	Argument Name	Description
void	N/A

Returns

ZPAL_STATUS_OK on success and ZPAL_STATUS_FAIL otherwise.

zpal_nvm_backup_close#

void zpal_nvm_backup_close (void )

Closes the NVM after backup/restore operation.

Parameters

Type	Direction	Argument Name	Description
void	N/A

zpal_nvm_backup_read#

zpal_status_t zpal_nvm_backup_read (uint32_t offset, void * data, size_t data_length)

Reads raw data from the NVM.

Parameters

Type	Direction	Argument Name	Description
uint32_t	[in]	offset	The offset where data shall be read from.
void *	[out]	data	Address of array where data can be written to.
size_t	[in]	data_length	Length of the stored data.

Returns

ZPAL_STATUS_OK if the data was successfully read and ZPAL_STATUS_FAIL otherwise.

zpal_nvm_backup_write#

zpal_status_t zpal_nvm_backup_write (uint32_t offset, const void * data, size_t data_length)

Writes raw data to the NVM.

Parameters

Type	Direction	Argument Name	Description
uint32_t	[in]	offset	The offset where data shall be written to.
const void *	[out]	data	Address of array of data that must be written.
size_t	[in]	data_length	Length of the data to be stored.

Returns

ZPAL_STATUS_OK if the data was successfully written and ZPAL_STATUS_FAIL otherwise.

zpal_nvm_backup_get_size#

size_t zpal_nvm_backup_get_size (void )

Get size of raw NVM area.

Parameters

Type	Direction	Argument Name	Description
void	N/A

Returns

Size of raw NVM area.

zpal_nvm_lock#

zpal_status_t zpal_nvm_lock (zpal_nvm_handle_t handle)

Set write protection for storage.

Parameters

Type	Direction	Argument Name	Description
zpal_nvm_handle_t	[in]	handle	Nvm storage handle.

Returns

ZPAL_STATUS_OK if the lock was set successfully, ZPAL_STATUS_FAIL otherwise.

zpal_nvm_migrate_legacy_app_file_system#

zpal_status_t zpal_nvm_migrate_legacy_app_file_system (void )

Migrates 800s legacy application file system to shared app/protocol file system.

Parameters

Type	Direction	Argument Name	Description
void	N/A

Returns

ZPAL_STATUS_OK if the file system was successfully migrated and ZPAL_STATUS_FAIL otherwise.