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:

  1. Initialize module with zpal_nvm_init().

  2. Invoke zpal_nvm_write() to store data.

  3. 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.


Definition at line 45 of file /mnt/raid/workspaces/ws.WDdsgIAV6/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_nvm.h

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.


Definition at line 56 of file /mnt/raid/workspaces/ws.WDdsgIAV6/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_nvm.h

zpal_nvm_handle_t#

typedef void* zpal_nvm_handle_t

Defines the NVM handle type.


Definition at line 61 of file /mnt/raid/workspaces/ws.WDdsgIAV6/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_nvm.h

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
[in]area

NVM area to initialize.

Returns

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


Definition at line 69 of file /mnt/raid/workspaces/ws.WDdsgIAV6/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_nvm.h

zpal_nvm_close#

zpal_status_t zpal_nvm_close (zpal_nvm_handle_t handle)

Closes the NVM of a given handle.

Parameters
[in]handle

NVM area handle.

Returns

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


Definition at line 77 of file /mnt/raid/workspaces/ws.WDdsgIAV6/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_nvm.h

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
[in]handle

NVM area handle.

[in]key

Object key.

[out]object

Address of array where object can be written to.

[in]object_size

Size of the stored object.

Returns


Definition at line 88 of file /mnt/raid/workspaces/ws.WDdsgIAV6/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_nvm.h

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
[in]handle

NVM area handle.

[in]key

Object key.

[out]object

Address of array where object can be written to.

[in]offset

The offset where object shall be read from.

[in]object_size

Size of the stored object.

Returns


Definition at line 100 of file /mnt/raid/workspaces/ws.WDdsgIAV6/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_nvm.h

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
[in]handle

NVM area handle.

[in]key

Object key.

[out]object

Address of array of object that must be written.

[in]object_size

Size of the object to be stored.

Returns


Definition at line 111 of file /mnt/raid/workspaces/ws.WDdsgIAV6/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_nvm.h

zpal_nvm_erase_all#

zpal_status_t zpal_nvm_erase_all (zpal_nvm_handle_t handle)

Erases everything in a given area.

Parameters
[in]handle

NVM area handle.

Returns


Definition at line 119 of file /mnt/raid/workspaces/ws.WDdsgIAV6/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_nvm.h

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
[in]handle

Nvm storage handle.

[in]key

Object key.

Returns


Definition at line 128 of file /mnt/raid/workspaces/ws.WDdsgIAV6/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_nvm.h

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
[in]handle

Nvm storage handle.

[in]key

Object key.

[out]len

Object size.

Returns


Definition at line 138 of file /mnt/raid/workspaces/ws.WDdsgIAV6/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_nvm.h

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
[in]handle

Nvm storage handle.

[out]key_list

A pointer to a buffer for the key list.

[in]key_list_size

The size of the key list buffer.

[in]key_min

The lower search key.

[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.


Definition at line 150 of file /mnt/raid/workspaces/ws.WDdsgIAV6/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_nvm.h

zpal_nvm_backup_open#

zpal_status_t zpal_nvm_backup_open (void )

Opens the NVM for a backup/restore operation.

Parameters
N/A

Returns


Definition at line 161 of file /mnt/raid/workspaces/ws.WDdsgIAV6/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_nvm.h

zpal_nvm_backup_close#

void zpal_nvm_backup_close (void )

Closes the NVM after backup/restore operation.

Parameters
N/A

Definition at line 166 of file /mnt/raid/workspaces/ws.WDdsgIAV6/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_nvm.h

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
[in]offset

The offset where data shall be read from.

[out]data

Address of array where data can be written to.

[in]data_length

Length of the stored data.

Returns


Definition at line 176 of file /mnt/raid/workspaces/ws.WDdsgIAV6/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_nvm.h

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
[in]offset

The offset where data shall be written to.

[out]data

Address of array of data that must be written.

[in]data_length

Length of the data to be stored.

Returns


Definition at line 186 of file /mnt/raid/workspaces/ws.WDdsgIAV6/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_nvm.h

zpal_nvm_backup_get_size#

size_t zpal_nvm_backup_get_size (void )

Get size of raw NVM area.

Parameters
N/A

Returns

  • Size of raw NVM area.


Definition at line 193 of file /mnt/raid/workspaces/ws.WDdsgIAV6/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_nvm.h

zpal_nvm_lock#

zpal_status_t zpal_nvm_lock (zpal_nvm_handle_t handle)

Set write protection for storage.

Parameters
[in]handle

Nvm storage handle.

Returns


Definition at line 201 of file /mnt/raid/workspaces/ws.WDdsgIAV6/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_nvm.h

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
N/A

Returns

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


Definition at line 208 of file /mnt/raid/workspaces/ws.WDdsgIAV6/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_nvm.h