Flash KVStore¶
1 功能概述¶
本例程演示如何使用 KVStore 组件，对 SoC Flash 的 KVStore 分区进行 key 的读、写、覆盖、删除等操作。
重要
出于安全考虑，请勿在中断服务程序（ISR）中调用 KVStore 相关接口。
2 环境准备¶
硬件设备与线材：
PAN107X EVB 核心板与底板各一块
JLink 仿真器（用于烧录例程程序）
USB-TypeC 线一条（用于底板供电和查看串口打印 Log）
杜邦线数根或跳线帽数个（用于连接各个硬件设备）
硬件接线：
将 EVB 核心板插到底板上
使用 USB-TypeC 线，将 PC USB 插口与 EVB 底板 USB->UART 插口相连
使用杜邦线将 EVB 底板上的 TX 引脚接至核心板 P16，RX 引脚接至核心板 P17
使用杜邦线将 JLink 仿真器的：
SWD_CLK 引脚与 EVB 底板的 P00 排针相连
SWD_DAT 引脚与 EVB 底板的 P01 排针相连
SWD_GND 引脚与 EVB 底板的 GND 排针相连
PC 软件:
串口调试助手（UartAssist）或终端工具（SecureCRT），波特率 921600（用于接收串口打印 Log）
3 编译和烧录¶
例程位置：<PAN10XX-NDK>\01_SDK\nimble\samples\component\flash_kvstore\keil_107x
双击 Keil Project 文件打开工程进行编译烧录。
4 例程演示说明¶
烧录完成后，芯片会通过串口打印例程 Log：
Try to load HW calibration data.. DONE. - Chip Info : 0x61 - Chip CP Version : 255 - Chip FT Version : 7 - Chip MAC Address : E11000014DE5 - Chip UID : B90801465454455354 - Chip Flash UID : 4250315A3538380B01FD8B435603EF78 - Chip Flash Size : 512 KB (Inc. 4KB Panchip Info Area) - Current Flash Map : +-------------------------+ <- Addr: 0x00000 | App Partition | | (480 KB) | +-------------------------+ <- Addr: 0x78000 | KVStore Partition | | ( 16 KB) | +-------------------------+ <- Addr: 0x7C000 | User Custom Partition | | ( 12 KB) | +-------------------------+ <- Addr: 0x7F000 | Panchip Info Area | | (4 KB, Hidden) | +-------------------------+ <- End : 0x80000 (512 KB) [I] App started.. [I] Try to write kv data, key="test_data", len=4 [I] kv_write_data[0]: 0x11 [I] kv_write_data[1]: 0x22 [I] kv_write_data[2]: 0x33 [I] kv_write_data[3]: 0x44 [I] KV write done, return code: 0x0 (KVSTORE_OK) [I] Try to read kv data, key:"test_data", len:4 [I] KV read done, return code: 0x0 (KVSTORE_OK) [I] Actual read length = 4 [I] kv_read_data[0]: 0x11 [I] kv_read_data[1]: 0x22 [I] kv_read_data[2]: 0x33 [I] kv_read_data[3]: 0x44 [I] Try to write kv data again, key:"test_data", len:3 [I] kv_write_data[0]: 0x55 [I] kv_write_data[1]: 0x66 [I] kv_write_data[2]: 0x77 [I] KV write done, return code: 0x0 (KVSTORE_OK) [I] Try to read kv data again, key:"test_data", len:10 [I] KV read done, return code: 0x0 (KVSTORE_OK) [I] Actual read length = 3 [I] kv_read_data[0]: 0x55 [I] kv_read_data[1]: 0x66 [I] kv_read_data[2]: 0x77 [I] Try to check if the key "test_data" exists.. [I] KV key check done, return code: 0x0 (KVSTORE_OK) [I] Try to delte the key "test_data".. [I] KV key delete done, return code: 0x0 (KVSTORE_OK) [I] Try to check again if the key "test_data" exists.. [I] KV key check done, return code: 0x9420005 (KVSTORE_ITEM_NOT_FOUND_ERROR)
由上述 Log 可知，本例程：
KVStore 区域被配置在 Flash 0x78000 地址，大小为 16KB
向 KVStore 区域先写入一个名为 test_data 的键值（Key-Value），然后分别尝试读取、更改、删除操作，并确认操作成功
5 开发者说明¶
KVStore（Key Value Storage Library）是一个开源的键值对存储（Key-Value Pair Storage）框架，其支持各种非易失存储器（如 Flash）、支持多实例、可抵御电源故障（be resilient to power failures）、促进存储器均匀磨损（promote even wear of the storage）以延长使用寿命。我们对其做了一些修改后，使其成为 PAN10xx NDK 的组件提供给开发者使用。
开发者可通过如下步骤使能 KVStore 组件：
将 KVStore 源码和头文件目录加入 Keil 工程：
mtb_init.c（位于
<PAN10xx-NDK>/nimble/component/kv_store/目录）mtb_kvstore.c（位于
<PAN10xx-NDK>/nimble/component/kv_store/目录）头文件目录（
<PAN10xx-NDK>/nimble/component/kv_store/）
在 Keil 工程中配置 KVstore 组件：
打开工程配置
sdk_config.h文件将 KVStore Flash 分区（Flash/Image Config : Flash Partition Config : KVStore Flash Partition Size (KB)）大小配置为非 0 值以使能 KVStore 组件；注意此分区大小必须为 8 (KB) 的倍数
当前例程的 KVStore 组件 config 配置如下：
KVStore component config¶
需要说明的是，KVStore 在 Flash 使用上有如下特点：
内部存在交换区（Swap Area），因此实际可用的 Flash 区域只有 KVStore 分区大小的一半
每个 Item（键值对）占用的 Flash 至少是一个 Flash Page（256字节）大小
根据上述特性，我们可以计算出本例程中 KVStore 区域（16KB）实际最多可以存储的有效 Item（键值对）的数量为 (16 * 1024) / 2 / 256 = 32 个。
KVStore 实际上是通过冗余的 Flash 空间来换取存储的可靠性和均匀磨损的，因此项目中我们要根据实际需求合理规划 KVStore 分区大小，若分区设置得太小可能会导致存储空间不够，若分区设置得太大则会比较浪费 Flash 空间。
另外需注意，若项目中使用到了蓝牙功能，并且开启了加密/配对功能，则蓝牙 Host 内部会使用 KVStore 来存储配对信息，所以此场景下 KVStore 组件也是必须使能的。