编辑语：
芯片开放社区（OCC）面向开发者推出RISC-V系列内容，通过多角度、全方位解读RISC-V，系统性梳理总结相关理论知识，构建RISC-V知识图谱，促进开发者对RISC-V生态全貌的了解。
为了帮助广大开发者快速上手YoC基础软件平台，实现RISC-V生态应用的极简开发，我们推出了YoC组件介绍系列内容，并向大家介绍了其中的
CSI组件、
AT组件 AV（多媒体）组件和
PARTITION组件。本期我们将为大家讲解YoC的KV组件，通过KV组件的简介、设计概述、主要原理描述以及示例四部分内容，带大家全面了解该组件。
01 介绍
KV是基于Nor Flash的一种Key-Value 数据存储系统，该系统采用极小的代码及内存开销（最小资源 rom：3K bytes，ram：100bytes），在小规模的Nor Flash上实现数据的存储管理能力，支持断电保护、磨损均衡、坏块处理等功能，并提供标准的aos kv接口进行访问。
KV 存储系统支持只读模式与读写模式共存，只读模式可以用于工厂生产数据，读写模式可用于运行时的数据存储。
02 设计概述
2.1 数据格式
为了简化设计，降低复杂性，减少代码规模及内存开销，又考虑到只读KV与读写KV的兼容性，KV系统未采用传统KV系统或文件系统中采用的HEAD描述结构，采用的链式遍历方式设计。
根据FLASH 的特点，以block 为单位，每一个block 都是一个独立的存储单元，限制一个KV必须存储在一个block上。
KV格式：
- 只读：=\n
- 读写：<key><\0><size_lo><size_hi><version>=<value><size_hi><erase_flag>
如下表
| 字节数 | n | 1 | 4 | ||||||
| 字段 | KEY | SIZE_LO | SIZE_HI | VERSION | = | VALUE | ERASE FLAG |
- 字段具体说明
| 空间（Byte） | 说明 | |
| 用户传入的key，由字母、数字等可打印字符组成 | ||
| 0位 | 数值0的特殊值，紧跟在KEY后，是检索的关键标记值 | |
| SIZE_LO/ | 2 | 占两个字节，保存KEY的长度与Value的长度，Value占高10位，KEY占低6位（允许最大KEY长度为63字节，Value理论长度为1023，但由到block 的大小限制，最大长度不得超出block）SIZE_LO为value 长度的低8位，SIZE_HI 的低2位为value 长度的高2位 |
| Version | 版本，用于保存KEY被修改的次数，当一个KV被多次修改时，Version最累加，累加到255时掉头为1；该字符用于保证KV修改的有效性，在写入时断电可能会造成KV的重复，采用最新版本的KV为有效KV，删除历史版本的KV； | |
| 等号位 | 即字符”c”，占位及检索标记位，用于识别有效KV | |
| Value | 用户传入的value值，长度由实际Value 长度决定，受block 及 key 长度限制 | |
| / | 保存上述SIZE_HI 数据，该位用于校检KV的有效性 | |
| Erase flag | KV删除标记位，由四个字节组成，非0时为有效KV，为0时，表示该KV已被删除 |
2.2 重点功能设计概述
2.2.1 断电保护
断电保护的设计是为了在修改KV时，能保证KV不会被破坏的事务处理机制，即要写入失败，要么写入成功，对于已经存的KV，写失败后，KV的值仍然为旧值。对于不存在的KV，写失败后，KV不存在。
2.2.2 磨损均衡
在通常的应用中，部分KV被经常修改，由于FLASH物理特性，擦写的次数有一定的限制，擦写次数超过次数时，该块会损坏不能使用。磨损均衡的设计是将KV的写入分散到多 block上，避免存储在固定的位置上，达到磨损均衡的效果。磨损均衡主要依赖以下两个策略来实现：
- 异地更新策略 Key-Value键值对采用顺序写入、异地更新的方式，即不再在原存储位置擦除重写，而是在其余空闲位置写入新键值并将原键值标记无效等待回收。这样既可以减少flash的擦除操作次数，又可以提高flash的空间利用率，也避免了对“特定”存储区块过度使用的问题。
- 垃圾回收策略 当free block总数接近gc下限时，会触发gc操作。flash数据在gc前，存在有效键值和无效键值交织的情况；gc后，把有效文件数据归并到free block，原区域则被擦除并置入free block。gc循环向后搬运键值。
2.2.3 坏块处理
Nor flash有一定的擦写次数限制，如果达到这个限制，或者由于物理方面的损坏，会导致这些block写入有问题。KV系统采用直接片上链式读取，擦除与写入时校验数据正确性，不采用特殊的标识信息来处理坏块，当block 擦除失败或者写失败后，会重新申请新的数据块，避免坏块被错误使用。
03 主要原理描述
3.1 关键过程处理流程
- 格式化
将所有块擦除后，若擦除失败则置为坏块。
- 初始化
遍历整个系统，统计每个block 上KV的个数、占用空间、可用位置，删除KV的数量，清理无效的KV，回收无用的block，若cache功能打开，则还会将所有key信息存入cache中。
- 写键值
3.1 查找系统中是否已存在该键值
3.2 分配新的kvnode，计算版本号、长度，将kvnode 写入block
3.3 删除已存在的键值
- 读取及删除键值
4.1 查找系统中是否已存在该键值
4.2 读取或删除已存在的键值
3.2 GC处理流程
当free block总数接近gc下限时，会触发gc操作。如下图，flash数据在gc前，存在有效键值和无效键值交织的情况；gc后，把有效文件数据归并到free block，原区域则被擦除并置入free block。gc循环向后搬运键值
3.3 CACHE功能
对于资源相对丰富的芯片，可以通过打开在package.yaml中配置CONFIG_KV_ENABLE_CACHE来打开cache功能，cache打开后，KV初始化时会统一将所有key的信息存储到cache中，之后的读写删等操作通过cache可快速定位到flash上的位置，减少对flash的遍历操作，从而可提升读速率30%，写速率95%，删除速率50%。
04 示例
#include <aos/kv.h>
void kv_test(void)
{
int ret =aos_kv_init("kv"); //初始化kv，注意需要将partition先处理化
if (ret != 0) {
printf("kv init failed");
return;
}
aos_kv_set("test_key", "hello"); //向kv里写入"hello"
char buffer[6];
aos_kv_get("test_key", buffer, 6); //从kv里读取数据到buffer
printf("kv read: %s\r\n", buffer);
} 05 下期预告
本文是YoC组件介绍系列的完结篇，下期内容将为大家讲解如何上传组件到OCC进行开源。欢迎大家持续关注RISC-V系列内容。