NV#
NV(Non-Volatile storage)提供基于 key-value 的非易失性数据存储能力,支持按 key ID 写入、读取、备份与恢复 NV 数据项,可配置加密、永久、不可升级等属性,并支持 NV 键值变更通知回调。模块源自 include/middleware/utils/NV.h。
模块公共头文件
#include "include/middleware/utils/nv.h"
接口清单#
接口名称 |
功能简述 |
|---|---|
初始化 NV 模块,使用 NV 功能前必须调用 |
|
写入 NV 数据项,默认属性为 Normal 且无回调 |
|
写入 NV 数据项,并配置属性及写入完成回调函数 |
|
读取指定 key ID 对应的 NV 数据项 |
|
读取指定 key ID 对应的 NV 数据项,同时获取 key 的属性值 |
|
获取当前核 NV 存储的空间使用状态 |
|
按 NV 区域备份标志执行 NV 数据备份 |
|
设置 NV 全量恢复标志 |
|
设置 NV 部分区域恢复标志 |
|
将 RAM 中的 NV 数据同步刷写到 flash |
|
注册 NV 键值变更通知回调函数 |
Functions#
uapi_nv_init #
void uapi_nv_init(void)
声明头文件
#include "include/middleware/utils/nv.h"
功能说明
初始化 NV 模块,为后续 NV 读写、备份、恢复等接口提供运行环境。
前置条件
调用时序约束:必须在 NV 模块其它对外接口(如
uapi_nv_write、uapi_nv_read)之前调用。依赖关系:依赖底层 flash 与 NV 直接控制初始化逻辑已就绪。
参考案例
src/application/ws53/ws53_application/main.c
uapi_nv_write #
errcode_t uapi_nv_write(uint16_t key, const uint8_t *kvalue, uint16_t kvalue_length)
声明头文件
#include "include/middleware/utils/nv.h"
功能说明
写入 NV 数据项,使用默认属性 Normal,且不注册写入完成回调函数。
通过 key ID 索引关联待写入的 kvalue 数据。
写入完成后触发错误码上报(当
CONFIG_ERRCODE_SUPPORT_REPORT开启时)。
前置条件
调用时序约束:必须在
uapi_nv_init成功返回后调用。依赖关系:依赖 flash 存储介质可用,底层 NV 写入逻辑就绪。
上下文限制:禁止在中断上下文调用。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
key |
uint16_t |
要写入的 NV 项的 key ID,用于索引 |
KEY_ID_REGION0(1, 0x1000) ~ KEY_ID_REGION15(0xF000, 0xFFFF) 区域内合法 key ID |
kvalue |
const uint8_t * |
指向待写入 NV 项值的指针 |
不为 NULL |
kvalue_length |
uint16_t |
写入数据的长度,单位 Bytes |
大于 0,普通 NV 不超过 NV_NORMAL_KVALUE_MAX_LEN(4060),加密 NV 不超过 NV_ENCRYPTED_KVALUE_MAX_LEN(4032) |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
执行成功 |
NV 数据项写入成功 |
ERRCODE_NV_INVALID_PARAMS:0x80003083 |
参数无效 |
kvalue 为 NULL 或 kvalue_length 为 0 |
ERRCODE_NV_ILLEGAL_OPERATION:0x80003088 |
非法操作 |
当前未支持加密但配置了加密属性 |
Other |
其他错误码,参考 |
执行失败 |
参考案例
src/application/samples/bt/sle/sle_speed_server/src/sle_speed_server.c
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_ERRCODE_SUPPORT_REPORT |
特性宏 |
支持错误码上报分支(分支级,DFX Kconfig 声明) |
n |
uapi_nv_write_with_attr #
errcode_t uapi_nv_write_with_attr(uint16_t key, const uint8_t *kvalue, uint16_t kvalue_length, nv_key_attr_t *attr,
nv_storage_completed_callback func)
声明头文件
#include "include/middleware/utils/nv.h"
功能说明
写入 NV 数据项,并按业务需求配置 key 的存储属性。
支持注册写入完成回调函数,在 kvalue 写入 flash 后被调用。
加密属性与永久属性不可修改,永久属性 key 的 kvalue 不可修改。
前置条件
调用时序约束:必须在
uapi_nv_init成功返回后调用。依赖关系:依赖 flash 存储介质可用,底层 NV 写入逻辑就绪。
上下文限制:禁止在中断上下文调用。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
key |
uint16_t |
要写入的 NV 项的 key ID,用于索引 |
KEY_ID_REGION0(1, 0x1000) ~ KEY_ID_REGION15(0xF000, 0xFFFF) 区域内合法 key ID |
kvalue |
const uint8_t * |
指向待写入 NV 项值的指针 |
不为 NULL |
kvalue_length |
uint16_t |
写入数据的长度,单位 Bytes |
大于 0,普通 NV 不超过 NV_NORMAL_KVALUE_MAX_LEN(4060),加密 NV 不超过 NV_ENCRYPTED_KVALUE_MAX_LEN(4032) |
attr |
指向 NV 项属性配置的指针,传入 NULL 表示使用默认属性 Normal |
NULL 或合法属性结构指针 |
|
func |
kvalue 写入 flash 完成后调用的回调函数,传入 NULL 表示不注册回调 |
NULL 或合法回调函数指针 |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
执行成功 |
NV 数据项写入成功 |
ERRCODE_NV_INVALID_PARAMS:0x80003083 |
参数无效 |
kvalue 为 NULL 或 kvalue_length 为 0 |
ERRCODE_NV_ILLEGAL_OPERATION:0x80003088 |
非法操作 |
当前未支持加密但配置了加密属性 |
Other |
其他错误码,参考 |
执行失败 |
参考案例
middleware/chips/ws53/factory/factory.c
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_NV_SUPPORT_ENCRYPT |
特性宏 |
支持加密写分支(分支级,nv_config.h 宏,默认 NV_YES) |
y |
uapi_nv_read #
errcode_t uapi_nv_read(uint16_t key, uint16_t kvalue_max_length, uint16_t *kvalue_length, uint8_t *kvalue)
声明头文件
#include "include/middleware/utils/nv.h"
功能说明
读取指定 key ID 对应的 NV 数据项。
默认情况下不获取 NV 属性值。
读取完成后触发错误码上报(当
CONFIG_ERRCODE_SUPPORT_REPORT开启时)。
前置条件
调用时序约束:必须在
uapi_nv_init成功返回后调用。依赖关系:依赖 flash 存储介质可用,目标 key ID 对应数据已写入。
上下文限制:禁止在中断上下文调用。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
key |
uint16_t |
要读取的 NV 项的 key ID,用于索引 |
KEY_ID_REGION0(1, 0x1000) ~ KEY_ID_REGION15(0xF000, 0xFFFF) 区域内合法 key ID |
kvalue_max_length |
uint16_t |
允许拷贝到 kvalue 缓冲区的最大长度,单位 Bytes |
大于等于实际读取数据长度 |
出参
名称 |
数据类型 |
输出说明 |
|---|---|---|
kvalue_length |
uint16_t * |
实际读取到的 NV 数据长度,单位 Bytes,由调用方分配内存、函数填充 |
kvalue |
uint8_t * |
指向保存读取数据的缓冲区指针,由调用方分配内存、函数填充 |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
执行成功 |
NV 数据项读取成功 |
ERRCODE_NV_INVALID_PARAMS:0x80003083 |
参数无效 |
kvalue_length、kvalue 或 attr 指针为 NULL |
Other |
其他错误码,参考 |
执行失败 |
参考案例
src/application/samples/bt/sle/sle_speed_server/src/sle_speed_server.csrc/application/ws53/ws53_application/bt_customize.c
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_ERRCODE_SUPPORT_REPORT |
特性宏 |
支持错误码上报分支(分支级,DFX Kconfig 声明) |
n |
uapi_nv_read_with_attr #
errcode_t uapi_nv_read_with_attr(uint16_t key, uint16_t kvalue_max_length, uint16_t *kvalue_length, uint8_t *kvalue,
nv_key_attr_t *attr)
声明头文件
#include "include/middleware/utils/nv.h"
功能说明
读取指定 key ID 对应的 NV 数据项,并同时获取该 key 的属性值。
适用于需要读取 NV 数据并感知其加密、永久、不可升级等属性的场景。
前置条件
调用时序约束:必须在
uapi_nv_init成功返回后调用。依赖关系:依赖 flash 存储介质可用,目标 key ID 对应数据已写入。
上下文限制:禁止在中断上下文调用。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
key |
uint16_t |
要读取的 NV 项的 key ID,用于索引 |
KEY_ID_REGION0(1, 0x1000) ~ KEY_ID_REGION15(0xF000, 0xFFFF) 区域内合法 key ID |
kvalue_max_length |
uint16_t |
允许拷贝到 kvalue 缓冲区的最大长度,单位 Bytes |
大于等于实际读取数据长度 |
出参
名称 |
数据类型 |
输出说明 |
|---|---|---|
kvalue_length |
uint16_t * |
实际读取到的 NV 数据长度,单位 Bytes,由调用方分配内存、函数填充 |
kvalue |
uint8_t * |
指向保存读取数据的缓冲区指针,由调用方分配内存、函数填充 |
attr |
获取到的 NV 项属性,由调用方分配内存、函数填充 |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
执行成功 |
NV 数据项读取成功 |
ERRCODE_NV_INVALID_PARAMS:0x80003083 |
参数无效 |
kvalue_length、kvalue 或 attr 指针为 NULL |
Other |
其他错误码,参考 |
执行失败 |
参考案例
middleware/chips/ws53/factory/factory.c
uapi_nv_get_store_status #
errcode_t uapi_nv_get_store_status(nv_store_status_t *status)
声明头文件
#include "include/middleware/utils/nv.h"
功能说明
查询当前核的 NV 存储空间使用状态。
输出总空间、已用空间、可回收空间、已损坏空间、单 NV 项最大可存储空间等指标。
适用于上层业务感知 NV 容量占用、决定是否触发回收或备份恢复。
前置条件
调用时序约束:必须在
uapi_nv_init成功返回后调用。依赖关系:依赖 NV 模块已正确初始化并完成 NV 区域扫描。
上下文限制:禁止在中断上下文调用。
出参
名称 |
数据类型 |
输出说明 |
|---|---|---|
status |
指向保存 NV 状态数据的指针,由调用方分配内存、函数填充 |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
执行成功 |
NV 存储状态查询成功 |
ERRCODE_NV_INVALID_PARAMS:0x80003083 |
参数无效 |
status 指针为 NULL |
Other |
其他错误码,参考 |
执行失败 |
uapi_nv_backup #
errcode_t uapi_nv_backup(const nv_backup_mode_t *backup_mode)
声明头文件
#include "include/middleware/utils/nv.h"
功能说明
按 NV 区域备份标志执行 NV 数据备份。
备份区域由
nv_backup_mode_t中各 region 标志位决定,标志位为 true 表示对应区域需要备份。仅在启用 NV 备份恢复特性时有效。
前置条件
调用时序约束:必须在
uapi_nv_init成功返回后调用。依赖关系:依赖 flash 存储介质可用,且
CONFIG_NV_SUPPORT_BACKUP_RESTORE已开启。上下文限制:禁止在中断上下文调用。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
backup_mode |
指向 NV 备份区域标志配置的指针 |
不为 NULL |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
执行成功 |
NV 备份成功 |
ERRCODE_NV_INVALID_PARAMS:0x80003083 |
参数无效 |
backup_mode 指针为 NULL |
ERRCODE_NOT_SUPPORT:0x80000002 |
不支持 |
未开启 |
Other |
其他错误码,参考 |
执行失败 |
参考案例
middleware/chips/ws53/factory/factory.c
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_NV_SUPPORT_BACKUP_RESTORE |
特性宏 |
支持备份/恢复功能(接口级,nv_config.h 宏,默认 NV_YES) |
y |
uapi_nv_set_restore_mode_all #
errcode_t uapi_nv_set_restore_mode_all(void)
声明头文件
#include "include/middleware/utils/nv.h"
功能说明
设置 NV 全量恢复标志,标记全部 NV 区域在下次启动时恢复出厂数据。
仅在启用 NV 备份恢复特性时有效。
前置条件
调用时序约束:必须在
uapi_nv_init成功返回后调用。依赖关系:依赖
CONFIG_NV_SUPPORT_BACKUP_RESTORE已开启。上下文限制:禁止在中断上下文调用。
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
执行成功 |
全量恢复标志设置成功 |
ERRCODE_NOT_SUPPORT:0x80000002 |
不支持 |
未开启 |
Other |
其他错误码,参考 |
执行失败 |
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_NV_SUPPORT_BACKUP_RESTORE |
特性宏 |
支持备份/恢复功能(接口级,nv_config.h 宏,默认 NV_YES) |
y |
uapi_nv_set_restore_mode_partitial #
errcode_t uapi_nv_set_restore_mode_partitial(const nv_restore_mode_t *restore_mode)
声明头文件
#include "include/middleware/utils/nv.h"
功能说明
设置 NV 部分区域恢复标志,按
nv_restore_mode_t中各 region 标志位决定恢复范围。标志位为 true 表示对应区域在下次启动时恢复出厂数据。
仅在启用 NV 备份恢复特性时有效。
前置条件
调用时序约束:必须在
uapi_nv_init成功返回后调用。依赖关系:依赖
CONFIG_NV_SUPPORT_BACKUP_RESTORE已开启。上下文限制:禁止在中断上下文调用。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
restore_mode |
指向 NV 恢复区域标志配置的指针 |
不为 NULL |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
执行成功 |
部分区域恢复标志设置成功 |
ERRCODE_NOT_SUPPORT:0x80000002 |
不支持 |
未开启 |
Other |
其他错误码,参考 |
执行失败 |
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_NV_SUPPORT_BACKUP_RESTORE |
特性宏 |
支持备份/恢复功能(接口级,nv_config.h 宏,默认 NV_YES) |
y |
uapi_nv_flush #
errcode_t uapi_nv_flush(void)
声明头文件
#include "include/middleware/utils/nv.h"
功能说明
将当前驻留在 RAM 中的 NV 数据同步刷写到 flash。
仅在 NV 启用异步存储特性时调用才有效。
适用于同步存储语义的业务场景。
前置条件
调用时序约束:必须在
uapi_nv_init成功返回后调用,且 NV 异步存储特性已开启。依赖关系:依赖
CONFIG_NV_SUPPORT_ASYNCHRONOUS_STORE已开启。上下文限制:禁止在中断上下文调用。
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
执行成功 |
RAM 中 NV 数据成功刷写到 flash |
ERRCODE_NOT_SUPPORT:0x80000002 |
不支持 |
未开启 |
Other |
其他错误码,参考 |
执行失败 |
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_NV_SUPPORT_ASYNCHRONOUS_STORE |
特性宏 |
支持异步落盘功能(接口级,nv_config.h 宏,默认 NV_NO) |
n |
uapi_nv_register_change_notify_proc #
errcode_t uapi_nv_register_change_notify_proc(uint16_t min_key, uint16_t max_key, nv_changed_notify_func func)
声明头文件
#include "include/middleware/utils/nv.h"
功能说明
注册 NV 键值变更通知回调函数,绑定回调生效的 key ID 区间。
当指定区间内的 NV key 值发生变更时,触发已注册的回调。
仅在启用 NV 键值变更通知特性时生效。
前置条件
调用时序约束:必须在
uapi_nv_init成功返回后调用。依赖关系:依赖
CONFIG_NV_SUPPORT_CHANGE_NOTIFY已开启,且系统已分配通知注册槽位。上下文限制:禁止在中断上下文调用。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
min_key |
uint16_t |
注册回调支持的最小 key ID |
min_key 不大于 max_key |
max_key |
uint16_t |
注册回调支持的最大 key ID |
max_key 不小于 min_key |
func |
NV 键值变更通知回调函数指针 |
不为 NULL |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
执行成功 |
回调函数注册成功 |
ERRCODE_NV_INVALID_PARAMS:0x80003083 |
参数无效 |
min_key 大于 max_key、func 为 NULL 或通知注册槽位数为 0 |
ERRCODE_NOT_SUPPORT:0x80000002 |
不支持 |
未开启 |
Other |
其他错误码,参考 |
执行失败 |
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_NV_SUPPORT_CHANGE_NOTIFY |
特性宏 |
支持变更通知功能(接口级,nv_config.h 宏,默认 NV_NO) |
n |
Type definitions#
typedef_nv_storage_completed_callback #
// 源码原始定义
typedef void (*nv_storage_completed_callback)(errcode_t result);
使用说明
NV 存储完成回调函数指针类型,作为 uapi_nv_write_with_attr 入参 func 的类型,在 kvalue 写入 flash 完成后被调用,参数 result 为写入操作的最终结果。
typedef_nv_changed_notify_func #
// 源码原始定义
typedef void (*nv_changed_notify_func)(uint16_t key);
使用说明
NV 键值变更通知回调函数指针类型,作为 uapi_nv_register_change_notify_proc 入参 func 的类型,在已注册 key ID 区间内的 NV 键值发生变更时被调用,参数 key 为发生变更的 NV 项 key ID。
Enumerations#
enum_nv_key_id_region_t #
// 源码原始定义
typedef enum {
KEY_ID_REGION0,
KEY_ID_REGION1,
KEY_ID_REGION2,
KEY_ID_REGION3,
KEY_ID_REGION4,
KEY_ID_REGION5,
KEY_ID_REGION6,
KEY_ID_REGION7,
KEY_ID_REGION8,
KEY_ID_REGION9,
KEY_ID_REGION10,
KEY_ID_REGION11,
KEY_ID_REGION12,
KEY_ID_REGION13,
KEY_ID_REGION14,
KEY_ID_REGION15,
KEY_ID_REGION_MAX_NUM,
} nv_key_id_region_t;
枚举成员 |
取值 |
描述 |
|---|---|---|
KEY_ID_REGION0 |
0 |
key_id 取值区域 0:[1, 0x1000) |
KEY_ID_REGION1 |
1 |
key_id 取值区域 1:[0x1000, 0x2000) |
KEY_ID_REGION2 |
2 |
key_id 取值区域 2:[0x2000, 0x3000) |
KEY_ID_REGION3 |
3 |
key_id 取值区域 3:[0x3000, 0x4000) |
KEY_ID_REGION4 |
4 |
key_id 取值区域 4:[0x4000, 0x5000) |
KEY_ID_REGION5 |
5 |
key_id 取值区域 5:[0x5000, 0x6000) |
KEY_ID_REGION6 |
6 |
key_id 取值区域 6:[0x6000, 0x7000) |
KEY_ID_REGION7 |
7 |
key_id 取值区域 7:[0x7000, 0x8000) |
KEY_ID_REGION8 |
8 |
key_id 取值区域 8:[0x8000, 0x9000) |
KEY_ID_REGION9 |
9 |
key_id 取值区域 9:[0x9000, 0xA000) |
KEY_ID_REGION10 |
10 |
key_id 取值区域 10:[0xA000, 0xB000) |
KEY_ID_REGION11 |
11 |
key_id 取值区域 11:[0xB000, 0xC000) |
KEY_ID_REGION12 |
12 |
key_id 取值区域 12:[0xC000, 0xD000) |
KEY_ID_REGION13 |
13 |
key_id 取值区域 13:[0xD000, 0xE000) |
KEY_ID_REGION14 |
14 |
key_id 取值区域 14:[0xE000, 0xF000) |
KEY_ID_REGION15 |
15 |
key_id 取值区域 15:[0xF000, 0xFFFF] |
KEY_ID_REGION_MAX_NUM |
16 |
key_id 的取值区域数量 |
Structures#
struct_nv_key_attr_t #
// 源码原始定义
typedef struct {
bool permanent;
bool encrypted;
bool non_upgrade;
uint8_t reserve;
} nv_key_attr_t;
成员说明
成员名称 |
数据类型 |
描述 |
|---|---|---|
permanent |
bool |
是否为永久 NV,永久属性 key 的 kvalue 不可修改 |
encrypted |
bool |
是否为密文存储 |
non_upgrade |
bool |
是否不可升级 |
reserve |
uint8_t |
保留字段 |
struct_nv_store_status_t #
// 源码原始定义
typedef struct {
uint32_t total_space;
uint32_t used_space;
uint32_t reclaimable_space;
uint32_t corrupted_space;
uint32_t max_key_space;
} nv_store_status_t;
成员说明
成员名称 |
数据类型 |
描述 |
|---|---|---|
total_space |
uint32_t |
当前核的 NV 总空间,单位 Bytes |
used_space |
uint32_t |
当前核已使用的 NV 空间,单位 Bytes |
reclaimable_space |
uint32_t |
当前核的 NV 可回收空间,擦除后可复用,单位 Bytes |
corrupted_space |
uint32_t |
当前核已损坏的 NV 空间,数据有效但异常,擦除后可复用,单位 Bytes |
max_key_space |
uint32_t |
可存储的最大单 NV 项空间,单位 Bytes |
struct_nv_restore_mode_t #
// 源码原始定义
typedef struct {
bool region_mode[KEY_ID_REGION_MAX_NUM];
} nv_restore_mode_t;
成员说明
成员名称 |
数据类型 |
描述 |
|---|---|---|
region_mode |
bool[KEY_ID_REGION_MAX_NUM] |
恢复出厂区域标志配置,数组下标对应 |
struct_nv_backup_mode_t #
// 源码原始定义
typedef struct {
bool region_mode[KEY_ID_REGION_MAX_NUM];
} nv_backup_mode_t;
成员说明
成员名称 |
数据类型 |
描述 |
|---|---|---|
region_mode |
bool[KEY_ID_REGION_MAX_NUM] |
备份区域标志配置,数组下标对应 |
Macros#
NV_NORMAL_KVALUE_MAX_LEN #
#define NV_NORMAL_KVALUE_MAX_LEN 4060 /* 普通NV的最大数据长度 */
NV_ENCRYPTED_KVALUE_MAX_LEN #
#define NV_ENCRYPTED_KVALUE_MAX_LEN 4032 /* 加密NV的最大数据长度 */