NVS 分区生成程序

[English]

介绍

NVS 分区生成程序 (nvs_flash/nvs_partition_generator/nvs_partition_gen.py) 根据 CSV 文件中的键值对生成二进制文件。该二进制文件与 非易失性存储器 (NVS) 中定义的 NVS 结构兼容。NVS 分区生成程序适合用于生成二进制数据(Blob),其中包括设备生产时可从外部烧录的 ODM/OEM 数据。这也使得生产制造商在使用同一个固件的基础上,通过自定义参数,如序列号等,为每个设备生成不同配置。

准备工作

在加密模式下使用该程序,需安装下列软件包:
  • cryptography package

根目录下的 requirements.txt 包含必需 python 包,请预先安装。

CSV 文件格式

.csv 文件每行需包含四个参数,以逗号隔开。具体参数描述见下表:

序号 参数 描述 说明
1 Key 主键,应用程序可通过查询此键来获取数据。  
2 Type 支持 filedatanamespace  
3 Encoding 支持 u8i8u16u32i32stringhex2binbase64binary。 决定二进制 bin 文件中 value 被编码成的类型。 stringbinary 编码的区别在于, string 数据以 NULL 字符结尾,binary 数据则不是。 file 类型当前仅支持 hex2binbase64stringbinary 编码。
4 Value Data value namespace 字段的 encodingvalue 应为空。 namespaceencodingvalue 为固定值,不可设置。 这些单元格中的所有值都会被忽视。

注解

CSV 文件的第一行应为列标题,不可设置。

此类 CSV 文件的 Dump 示例如下:

key,type,encoding,value     <-- 列标题
namespace_name,namespace,,  <-- 第一个条目为 "namespace"
key1,data,u8,1
key2,file,string,/path/to/file

注解

请确保:
  • 逗号 ‘,’ 前后无空格;
  • CSV 文件每行末尾无空格。

NVS 条目和命名空间 (namespace)

如 CSV 文件中出现命名空间条目,后续条目均会被视为该命名空间的一部分,直至找到下一个命名空间条目。找到新命名空间条目后,后续所有条目都会被视为新命名空间的一部分。

注解

CSV 文件中第一个条目应始终为 namespace

支持多页 Blob

默认情况下,二进制 Blob 可跨多页,格式参考 条目结构 章节。如需使用旧版格式,可在程序中禁用该功能。

支持加密

NVS 分区生成程序还可使用 AES-XTS 加密生成二进制加密文件。更多信息详见 NVS 加密

支持解密

如果 NVS 二进制文件采用了 AES-XTS 加密,该程序还可对此类文件进行解密,更多信息详见 NVS 加密

运行程序

使用方法:

python nvs_partition_gen.py [-h] {generate,generate-key,encrypt,decrypt} ...

可选参数

序号 参数 描述
1 -h, –help 显示帮助信息并退出

命令:

运行 nvs_partition_gen.py {command} -h 查看更多帮助信息
序号 参数 描述
1 generate 生成 NVS 分区
2 generate-key 生成加密密钥
3 encrypt 加密 NVS 分区
4 decrypt 解密 NVS 分区

生成 NVS 分区(默认模式)

使用方法:

python nvs_partition_gen.py generate [-h] [--version {1,2}] [--outdir OUTDIR]
                                         input output size

位置参数

参数 描述
input 待解析的 CSV 文件路径
output NVS 二进制文件的输出路径
size NVS 分区大小(以字节为单位,且为 4096 的整数倍)

可选参数

参数 描述
-h, –help 显示帮助信息并退出
–version {1,2}
  • 设置多页 Blob 版本。
  • 版本 1:禁用多页 Blob;
  • 版本 2:启用多页 Blob;
  • 默认版本:版本 2。
–outdir OUTDIR 输出目录,用于存储创建的文件。(默认当前目录)

运行如下命令创建 NVS 分区,该程序同时会提供 CSV 示例文件:

python nvs_partition_gen.py generate sample_singlepage_blob.csv sample.bin 0x3000

仅生成加密密钥

使用方法:

python nvs_partition_gen.py generate-key [-h] [--keyfile KEYFILE]
                                             [--outdir OUTDIR]

可选参数

参数 描述
-h, –help 显示帮助信息并退出
–keyfile KEYFILE 加密密钥文件的输出路径
–outdir OUTDIR 输出目录,用于存储创建的文件。(默认当前目录)

运行以下命令仅生成加密密钥:

python nvs_partition_gen.py generate-key

生成 NVS 加密分区

使用方法:

python nvs_partition_gen.py encrypt [-h] [--version {1,2}] [--keygen]
                                    [--keyfile KEYFILE] [--inputkey INPUTKEY]
                                    [--outdir OUTDIR]
                                    input output size

位置参数

参数 描述
input 待解析 CSV 文件的路径
output NVS 二进制文件的输出路径
size NVS 分区大小 (以字节为单位,且为 4096 的整数倍)

可选参数

参数 描述
-h, –help 显示帮助信息并退出
–version {1,2}
  • 设置多页 Blob 版本。
  • 版本 1:禁用多页 Blob;
  • 版本 2:启用多页 Blob;
  • 默认版本:版本 2。
–keygen 生成 NVS 分区加密密钥
–keyfile KEYFILE 密钥文件的输出路径
–inputkey INPUTKEY 内含 NVS 分区加密密钥的文件
–outdir OUTDIR 输出目录,用于存储创建的文件 (默认当前目录)

运行以下命令加密 NVS 分区,该程序同时会提供一个 CSV 示例文件。

  • 通过 NVS 分区生成程序生成加密密钥来加密:

    python nvs_partition_gen.py encrypt sample_singlepage_blob.csv sample_encr.bin 0x3000 --keygen
    

注解

创建的加密密钥格式为 <outdir>/keys/keys-<timestamp>.bin

  • 通过 NVS 分区生成程序生成加密密钥,并将密钥存储于自定义的文件中:

    python nvs_partition_gen.py encrypt sample_singlepage_blob.csv sample_encr.bin 0x3000 --keygen --keyfile sample_keys.bin
    

注解

创建的加密密钥格式为 <outdir>/keys/keys-<timestamp>.bin

注解

加密密钥存储于新建文件的 keys/ 目录下,与 NVS 密钥分区结构兼容。更多信息请参考 NVS 密钥分区

  • 将加密密钥用作二进制输入文件来进行加密:

    python nvs_partition_gen.py encrypt sample_singlepage_blob.csv sample_encr.bin 0x3000 --inputkey sample_keys.bin
    

解密 NVS 分区

使用方法:

python nvs_partition_gen.py decrypt [-h] [--outdir OUTDIR] input key output

位置参数

参数 描述
input 待解析的 NVS 加密分区文件路径
key 含有解密密钥的文件路径
output 已解密的二进制文件输出路径

可选参数

参数 描述
-h, –help 显示帮助信息并退出
–outdir OUTDIR 输出目录,用于存储创建的文件 (默认当前目录)

运行以下命令解密已加密的 NVS 分区:

python nvs_partition_gen.py decrypt sample_encr.bin sample_keys.bin sample_decr.bin

您可以自定义格式版本号:

  • 版本 1:禁用多页 Blob
  • 版本 2:启用多页 Blob

版本 1:禁用多页 Blob

如需禁用多页 Blob,请按照如下命令将版本参数设置为 1,以此格式运行分区生成程序。该程序同时会提供一个 CSV 示例文件:

python nvs_partition_gen.py generate sample_singlepage_blob.csv sample.bin 0x3000 --version 1

版本 2:启用多页 Blob

如需启用多页 Blob,请按照如下命令将版本参数设置为 2,以此格式运行分区生成程序。该程序同时会提供一个 CSV 示例文件:

python nvs_partition_gen.py generate sample_multipage_blob.csv sample.bin 0x4000 --version 2

注解

NVS 分区最小为 0x3000 字节。

注解

将二进制文件烧录至设备时,请确保与应用的 sdkconfig 设置一致。

说明

  • 分区生成程序不会对重复键进行检查,而将数据同时写入这两个重复键中。请注意不要使用同名的键;
  • 新页面创建后,前一页的空白处不会再写入数据。CSV 文件中的字段须按次序排列以优化内存;
  • 暂不支持 64 位数据类型。