nv

NV（Non-Volatile）模块提供非易失性键值存储能力，支持数据的读写、删除、备份与恢复等操作，并提供属性配置、变更通知等扩展功能。

头文件清单

#include <middleware/utils/nv.h>

接口清单

接口名称	功能简述
uapi_nv_init	初始化NV模块
uapi_nv_write	写入NV数据项
uapi_nv_write_with_attr	写入NV数据项并配置属性及回调函数
uapi_nv_read	读取指定NV数据项的值
uapi_nv_read_with_attr	读取指定NV数据项的值并获取key属性
uapi_nv_get_key_attr	获取指定NV Key的长度和属性值
uapi_nv_delete_key	删除指定的NV Key
uapi_nv_get_store_status	获取NV存储的空间使用情况
uapi_nv_backup	执行NV备份
uapi_nv_set_restore_mode_all	设置NV全量恢复标志
uapi_nv_set_restore_mode_partitial	设置NV部分恢复标志
uapi_nv_flush	确保NV数据从RAM同步到Flash
uapi_nv_register_change_notify_proc	注册NV键值改变通知的回调函数

Functions

uapi_nv_init

nv_init uapi nv init uapi_nv_init

函数声明

void uapi_nv_init(void);

头文件清单

#include <middleware/utils/nv.h>

功能说明

• 初始化NV存储模块，在使用任何NV函数之前必须调用
• 内部调用uapi_nv_extra_init完成KV存储区域的初始化
• 调用完成后NV模块进入就绪状态，其他NV接口可正常调用

uapi_nv_write

nv_write uapi nv write uapi_nv_write

函数声明

errcode_t uapi_nv_write(uint16_t key, const uint8_t *kvalue, uint16_t kvalue_length);

头文件清单

#include <middleware/utils/nv.h>

功能说明

• 写入NV数据项，默认属性为Normal，没有回调函数
• 以key-value方式存储数据，key为NV项的索引ID
• 写入数据长度不超过NV_NORMAL_KVALUE_MAX_LEN（4060字节）

入参

名称	参数类型	详细说明	约束取值范围
key	uint16_t	要写入的NV项的key ID，用于索引	0x0001 ~ 0xFFFF
kvalue	const uint8_t *	指向要写入的NV项的值的指针	非NULL
kvalue_length	uint16_t	写入数据的长度（以字节为单位）	1 ~ 4060

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	数据写入成功
Other	其他错误码，参考errcode_t	执行失败

uapi_nv_write_with_attr

nv_write_with_attr uapi nv write with attr 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 <middleware/utils/nv.h>

功能说明

• 写入NV数据项，并根据业务需求配置属性及回调函数
• NV的加密属性和永久属性不能修改，永久属性的kvalue不能修改
• 加密NV数据长度不超过NV_ENCRYPTED_KVALUE_MAX_LEN（4048字节）
• 回调函数在kvalue写入Flash后被调用

前置条件

• NV模块已通过uapi_nv_init()初始化完成

入参

名称	参数类型	详细说明	约束取值范围
key	uint16_t	要写入的NV项的key ID，用于索引	0x0001 ~ 0xFFFF
kvalue	const uint8_t *	指向要写入的NV项的值的指针	非NULL
kvalue_length	uint16_t	写入数据的长度（以字节为单位）	1 ~ 4060（加密NV: 1 ~ 4048）
attr	nv_key_attr_t *	要配置的NV项的属性	非NULL
func	nv_storage_completed_callback	kvalue写入Flash后调用的回调函数	函数指针或NULL

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	数据写入成功
ERRCODE_NV_ILLEGAL_OPERATION(0x80003088)	非法操作	试图修改永久属性的kvalue或修改加密/永久属性
Other	其他错误码，参考errcode_t	执行失败

uapi_nv_read

nv_read uapi nv read uapi_nv_read

函数声明

errcode_t uapi_nv_read(uint16_t key, uint16_t kvalue_max_length, uint16_t *kvalue_length, uint8_t *kvalue);

头文件清单

#include <middleware/utils/nv.h>

功能说明

• 读取指定NV数据项的值
• 默认情况下不获取NV属性值
• 调用者需提供足够大小的缓冲区存放读取数据

前置条件

• NV模块已通过uapi_nv_init()初始化完成

入参

名称	参数类型	详细说明	约束取值范围
key	uint16_t	要读取的NV项的key ID，用于索引	0x0001 ~ 0xFFFF
kvalue_max_length	uint16_t	允许存储数据的最大长度（以字节为单位）	1 ~ 4060

出参

名称	数据类型	输出说明
kvalue_length	uint16_t *	实际读取到的数据长度
kvalue	uint8_t *	指向保存读取数据的buffer的指针

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	数据读取成功
ERRCODE_NV_KEY_NOT_FOUND(0x80003081)	Key未找到	指定key不存在
ERRCODE_NV_GET_BUFFER_TOO_SMALL(0x80003082)	缓冲区过小	kvalue_max_length小于实际数据长度
Other	其他错误码，参考errcode_t	执行失败

uapi_nv_read_with_attr

nv_read_with_attr uapi nv read with attr 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 <middleware/utils/nv.h>

功能说明

• 读取指定NV数据项的值，同时获取key的属性值
• 除读取数据外，还通过attr出参返回key的属性信息
• 调用者需提供足够大小的缓冲区存放读取数据

前置条件

• NV模块已通过uapi_nv_init()初始化完成

入参

名称	参数类型	详细说明	约束取值范围
key	uint16_t	要读取的NV项的key ID，用于索引	0x0001 ~ 0xFFFF
kvalue_max_length	uint16_t	允许存储数据的最大长度（以字节为单位）	1 ~ 4060

出参

名称	数据类型	输出说明
kvalue_length	uint16_t *	实际读取到的数据长度
kvalue	uint8_t *	指向保存读取数据的buffer的指针
attr	nv_key_attr_t *	获取到的NV项的属性

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	数据读取成功
ERRCODE_NV_KEY_NOT_FOUND(0x80003081)	Key未找到	指定key不存在
ERRCODE_NV_GET_BUFFER_TOO_SMALL(0x80003082)	缓冲区过小	kvalue_max_length小于实际数据长度
Other	其他错误码，参考errcode_t	执行失败

uapi_nv_get_key_attr

nv_get_key_attr uapi nv get key attr uapi_nv_get_key_attr

函数声明

errcode_t uapi_nv_get_key_attr(uint16_t key, uint16_t *length, nv_key_attr_t *attr);

头文件清单

#include <middleware/utils/nv.h>

功能说明

• 只获取指定NV Key的长度和属性值，而不读取NV key的数据
• 用于查询key是否存在及其属性，无需读取完整数据

前置条件

• NV模块已通过uapi_nv_init()初始化完成

入参

名称	参数类型	详细说明	约束取值范围
key	uint16_t	要读取的NV项的key ID，用于索引	0x0001 ~ 0xFFFF

出参

名称	数据类型	输出说明
length	uint16_t *	获取到的NV项的数据长度
attr	nv_key_attr_t *	获取到的NV项的属性

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	属性获取成功
ERRCODE_NV_KEY_NOT_FOUND(0x80003081)	Key未找到	指定key不存在
ERRCODE_NV_INVALID_PARAM(0x80003083)	参数无效	length或attr为NULL
Other	其他错误码，参考errcode_t	执行失败

uapi_nv_delete_key

nv_delete_key uapi nv delete key uapi_nv_delete_key

函数声明

errcode_t uapi_nv_delete_key(uint16_t key, bool completely);

头文件清单

#include <middleware/utils/nv.h>

功能说明

• 删除指定的NV Key
• 彻底删除（completely为true）指该Key的数据在物理上进行数据覆盖
• 非彻底删除仅将Key标记为无效

前置条件

• NV模块已通过uapi_nv_init()初始化完成
• 需开启CONFIG_NV_SUPPORT_DELETE_KEY特性宏

入参

名称	参数类型	详细说明	约束取值范围
key	uint16_t	要删除的NV项的key ID，用于索引	0x0001 ~ 0xFFFF
completely	bool	是否彻底删除	- true：物理覆盖删除 - false：标记为无效

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	Key删除成功
ERRCODE_NV_KEY_NOT_FOUND(0x80003081)	Key未找到	指定key不存在
Other	其他错误码，参考errcode_t	执行失败

uapi_nv_get_store_status

nv_get_store_status uapi nv get store status uapi_nv_get_store_status

函数声明

errcode_t uapi_nv_get_store_status(nv_store_status_t *status);

头文件清单

#include <middleware/utils/nv.h>

功能说明

• 获取NV存储的空间使用情况
• 查询NV空间状态，包括总空间、已使用空间、可回收空间、损坏空间、最大单NV项空间

前置条件

• NV模块已通过uapi_nv_init()初始化完成

出参

名称	数据类型	输出说明
status	nv_store_status_t *	返回NV空间状态信息

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	状态查询成功
Other	其他错误码，参考errcode_t	执行失败

uapi_nv_backup

nv_backup uapi nv backup uapi_nv_backup

函数声明

errcode_t uapi_nv_backup(const nv_backup_mode_t *backup_mode);

头文件清单

#include <middleware/utils/nv.h>

功能说明

• 执行NV备份，将工作区指定区域的NV数据备份到备份区
• 通过backup_mode参数指定需要备份的key_id区域
• 需开启CONFIG_NV_SUPPORT_BACKUP_RESTORE特性宏

前置条件

• NV模块已通过uapi_nv_init()初始化完成
• 需开启CONFIG_NV_SUPPORT_BACKUP_RESTORE特性宏

入参

名称	参数类型	详细说明	约束取值范围
backup_mode	const nv_backup_mode_t *	指向保存NV备份区域选择的指针	非NULL

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	备份成功
ERRCODE_NV_INVALID_PARAM(0x80003083)	参数无效	backup_mode为NULL
ERRCODE_NOT_SUPPORT	不支持	未开启备份恢复功能
Other	其他错误码，参考errcode_t	执行失败

uapi_nv_set_restore_mode_all

nv_set_restore_mode_all uapi nv set restore mode all uapi_nv_set_restore_mode_all

函数声明

errcode_t uapi_nv_set_restore_mode_all(void);

头文件清单

#include <middleware/utils/nv.h>

功能说明

• 设置NV全量恢复标志，所有区域的NV数据将在恢复出厂设置时被恢复
• 需开启CONFIG_NV_SUPPORT_BACKUP_RESTORE特性宏

前置条件

• NV模块已通过uapi_nv_init()初始化完成
• 需开启CONFIG_NV_SUPPORT_BACKUP_RESTORE特性宏

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	设置成功
Other	其他错误码，参考errcode_t	执行失败

uapi_nv_set_restore_mode_partitial

nv_set_restore_mode_partitial uapi nv set restore mode partitial uapi_nv_set_restore_mode_partitial

函数声明

errcode_t uapi_nv_set_restore_mode_partitial(const nv_restore_mode_t *restore_mode);

头文件清单

#include <middleware/utils/nv.h>

功能说明

• 设置NV部分恢复标志，仅恢复指定区域的NV数据
• 通过restore_mode参数指定需要恢复的key_id区域
• 需开启CONFIG_NV_SUPPORT_BACKUP_RESTORE特性宏

前置条件

• NV模块已通过uapi_nv_init()初始化完成
• 需开启CONFIG_NV_SUPPORT_BACKUP_RESTORE特性宏

入参

名称	参数类型	详细说明	约束取值范围
restore_mode	const nv_restore_mode_t *	指向保存NV各区域是否恢复标志的指针	非NULL

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	设置成功
ERRCODE_NV_INVALID_PARAM(0x80003083)	参数无效	restore_mode为NULL
Other	其他错误码，参考errcode_t	执行失败

uapi_nv_flush

nv_flush uapi nv flush uapi_nv_flush

函数声明

errcode_t uapi_nv_flush(void);

头文件清单

#include <middleware/utils/nv.h>

功能说明

• 确保NV数据从RAM同步到Flash
• 仅在NV支持异步存储（CONFIG_NV_SUPPORT_ASYNCHRONOUS_STORE）时调用有效
• 将RAM中未刷新到Flash的NV数据全部写入Flash

前置条件

• NV模块已通过uapi_nv_init()初始化完成
• 需开启CONFIG_NV_SUPPORT_ASYNCHRONOUS_STORE特性宏

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	数据同步成功
Other	其他错误码，参考errcode_t	执行失败

uapi_nv_register_change_notify_proc

nv_register_change_notify_proc uapi nv register change notify proc 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 <middleware/utils/nv.h>

功能说明

• 注册NV键值改变通知的回调函数
• 当指定key范围内的NV数据发生变化时，触发回调通知
• 需开启CONFIG_NV_SUPPORT_CHANGE_NOTIFY特性宏

前置条件

• NV模块已通过uapi_nv_init()初始化完成
• 需开启CONFIG_NV_SUPPORT_CHANGE_NOTIFY特性宏

入参

名称	参数类型	详细说明	约束取值范围
min_key	uint16_t	注册回调支持的最小key-ID	0x0001 ~ 0xFFFF
max_key	uint16_t	注册回调支持的最大key-ID	0x0001 ~ 0xFFFF
func	nv_changed_notify_func	回调函数	非NULL

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	注册成功
ERRCODE_NV_NOTIFY_LIST_FULL(0x80003091)	通知列表已满	注册数量超过最大限制
ERRCODE_NV_NOTIFY_SEGMENT_ERR(0x80003094)	区间重叠	注册的key区间与已有区间重叠
Other	其他错误码，参考errcode_t	执行失败

Type definitions

nv_storage_completed_callback

typedef void (*nv_storage_completed_callback)(errcode_t result);

调用时机

• uapi_nv_write_with_attr接口的回调函数类型，在kvalue写入Flash后被调用

nv_changed_notify_func

typedef void (*nv_changed_notify_func)(uint16_t key);

调用时机

• uapi_nv_register_change_notify_proc接口的回调函数类型，在指定key范围内的NV数据发生变化时触发

Enumerations

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：[0x0001,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

nv_key_attr_t

typedef struct {
    bool permanent;     /*!< 是否为永久NV */
    bool encrypted;     /*!< 是否为密文存储 */
    bool non_upgrade;   /*!< 是否不可升级 */
    uint8_t reserve;    /*!< 保留字段 */
} nv_key_attr_t;

成员说明

成员名称	数据类型	描述
permanent	bool	是否为永久NV，永久NV的kvalue不可修改
encrypted	bool	是否为密文存储
non_upgrade	bool	是否不可升级
reserve	uint8_t	保留字段

nv_store_status_t

typedef struct {
    uint32_t total_space;       /*!< 当前核的总NV空间 */
    uint32_t used_space;        /*!< 当前核已使用的NV空间 */
    uint32_t reclaimable_space; /*!< 当前核的NV可回收空间 */
    uint32_t corrupted_space;   /*!< 当前核已损坏了的NV空间 */
    uint32_t max_key_space;     /*!< 可存储的最大单NV项空间 */
} nv_store_status_t;

成员说明

成员名称	数据类型	描述
total_space	uint32_t	当前核的总NV空间
used_space	uint32_t	当前核已使用的NV空间
reclaimable_space	uint32_t	当前核的NV可回收空间，擦除后可重新使用
corrupted_space	uint32_t	当前核已损坏的NV空间，数据异常但擦除后可重新使用
max_key_space	uint32_t	可存储的最大单NV项空间

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]	恢复出厂区域标志配置，true代表要恢复

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]	备份区域标志配置，true代表要备份

Macros

NV_NORMAL_KVALUE_MAX_LEN

#define NV_NORMAL_KVALUE_MAX_LEN     4060

NV_ENCRYPTED_KVALUE_MAX_LEN

#define NV_ENCRYPTED_KVALUE_MAX_LEN  4048

NV_YES

#define NV_YES                       1

NV_NO

#define NV_NO                        0