NV用户数据管理(NV DATA)¶

1、简介¶

NV DATA（Non-Volatile Data，非易失数据）组件提供基于FLASH的键值对（KV）存储能力，用于保存音量、配置项、自学习命令词等掉电不丢失的用户数据。

特性：

以ID（uint32_t）为键的数据项读写、删除
写入采用追加（append）方式，不立即擦除，写满一个块后再整块搬迁擦除，减少擦写次数
支持热ID注册（频繁读的项缓存到RAM）
数据块头部带魔数（CINV_FLASH_BASE_ADDR，0xABCDEF03）与版本校验
擦除块大小固定4KB（CINV_FLASH_ERASE_BLOCK_SIZE）

2、API¶

函数名	描述
cinv_init	NVDATA初始化（FLASH基地址、总大小）
cinv_item_init	初始化（创建）一个数据项
cinv_item_read	读取一个数据项（可获取实际长度）
cinv_item_write	写入（更新）一个数据项
cinv_item_delete	删除一个数据项
cinv_register_hotid	注册热ID（RAM缓存加速读取）

3、关键类型¶

类型	说明
cinv_item_ret_t	返回值：CINV_ITEM_UNINIT、CINV_OPER_FAILED、CINV_OPER_SUCCESS、CINV_ITEM_LEN_ERR

SDK预定义的数据项ID：

ID宏	值	说明
NVDATA_ID_VOLUME	0x50000001	音量数据
NVDATA_ID_CWSL_START	0x50001000	离线命令词自学习数据起始ID
NVDATA_ID_VP_MOULD_INFO	0xA0000001	声纹模型信息
NVDATA_ID_USER_START	0x60000001	用户自定义ID起始（必须大于该值）
NVDATA_ID_USER_END	0xF0000000	用户自定义ID结束（必须小于该值）

注意

用户自定义ID请在 NVDATA_ID_USER_START（0x60000001）~ NVDATA_ID_USER_END（0xF0000000）范围内选取，避开系统保留ID（0xFF000000 ~ 0xFFFFFFFF不可用）。

4、示例¶

1) 以下代码定义一个用户数据项并完成读写：

#include "ci_nvdata_manage.h"

#define NVDATA_ID_USER_DEMO   (0x60000002)  //用户自定义ID

//用户数据结构
typedef struct
{
    uint8_t mode;
    uint16_t threshold;
}user_cfg_t;

user_cfg_t g_user_cfg = {0};

void nvdata_demo(void)
{
    uint16_t real_len = 0;

    //第一次上电：创建数据项并写入默认值
    if (CINV_ITEM_UNINIT == cinv_item_init(NVDATA_ID_USER_DEMO,
                                           sizeof(user_cfg_t), &g_user_cfg))
    {
        g_user_cfg.mode = 1;
        g_user_cfg.threshold = 100;
        cinv_item_write(NVDATA_ID_USER_DEMO, sizeof(user_cfg_t), &g_user_cfg);
    }

    //读取数据项
    cinv_item_read(NVDATA_ID_USER_DEMO, sizeof(user_cfg_t),
                   &g_user_cfg, &real_len);

    //更新数据项（掉电保存）
    g_user_cfg.threshold = 200;
    cinv_item_write(NVDATA_ID_USER_DEMO, sizeof(user_cfg_t), &g_user_cfg);
}

2) 以下代码注册热ID加速频繁读取的项（SDK音量保存流程）：

#include "ci_nvdata_manage.h"

void hotid_demo(void)
{
    //音量项频繁读取，注册为热ID
    cinv_register_hotid(NVDATA_ID_VOLUME);
}

5、其它¶

cinv_init 的FLASH地址与大小需与分区表中NV数据区（nv_data_offset / nv_data_size）一致，SDK已在初始化流程中完成。
数据项长度固定后不建议修改（追加写机制按ID+长度定位最新记录）；结构体升级请使用新ID或预留字段。
频繁写入场景（如每次识别都保存）会加速块搬迁，建议控制写入频率。
NVDATA底层通过flash_control组件访问FLASH，与其他FLASH操作天然互斥，应用层可放心调用。

6、API 参考¶

本模块接口声明于 components\ci_nvdm\ci_nvdata_manage.h，实现位于 components\ci_nvdm\src\ci_nvdata_manage.c。