mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
318 lines
12 KiB
ReStructuredText
318 lines
12 KiB
ReStructuredText
NVS 分区生成程序
|
||
===============================
|
||
|
||
:link_to_translation:`en:[English]`
|
||
|
||
介绍
|
||
------------
|
||
|
||
NVS 分区生成程序 (:component_file:`nvs_flash/nvs_partition_generator/nvs_partition_gen.py`) 根据 CSV 文件中的键值对生成二进制文件。该二进制文件与 :doc:`非易失性存储器 (NVS) </api-reference/storage/nvs_flash>` 中定义的 NVS 结构兼容。NVS 分区生成程序适合用于生成二进制数据(Blob),其中包括设备生产时可从外部烧录的 ODM/OEM 数据。这也使得生产制造商在使用同一个应用固件的基础上,通过自定义参数,如序列号,为每个设备生成不同配置的二进制 NVS 分区。
|
||
|
||
准备工作
|
||
-------------
|
||
|
||
在加密模式下使用该程序,需安装下列软件包:
|
||
- cryptography package
|
||
|
||
根目录下的 `requirements.txt` 包含必需 python 包,请预先安装。
|
||
|
||
CSV 文件格式
|
||
---------------
|
||
|
||
CSV 文件每行需包含四个参数,以逗号隔开。具体参数描述见下表:
|
||
|
||
.. list-table::
|
||
:widths: 10 20 35 35
|
||
:header-rows: 1
|
||
|
||
* - 序号
|
||
- 参数
|
||
- 描述
|
||
- 说明
|
||
* - 1
|
||
- Key
|
||
- 主键,应用程序可通过查询此键来获取数据。
|
||
-
|
||
* - 2
|
||
- Type
|
||
- 支持 ``file``、``data`` 和 ``namespace``。
|
||
-
|
||
* - 3
|
||
- Encoding
|
||
- 支持 ``u8``、``i8``、``u16``、``i16``、``u32``、``i32``、``u64``、``i64``、``string``、``hex2bin``、``base64`` 和 ``binary``。决定二进制 ``bin`` 文件中 value 被编码成的类型。``string`` 和 ``binary`` 编码的区别在于,``string`` 数据以 NULL 字符结尾,``binary`` 数据则不是。
|
||
- ``file`` 类型当前仅支持 ``hex2bin``、``base64``、 ``string`` 和 ``binary`` 编码。
|
||
* - 4
|
||
- Value
|
||
- Data value
|
||
- ``namespace`` 字段的 ``encoding`` 和 ``value`` 应为空。 ``namespace`` 的 ``encoding`` 和 ``value`` 为固定值,不可设置。这些单元格中的所有值都会被忽视。
|
||
|
||
.. note:: CSV 文件的第一行应始终为列标题,不可设置。
|
||
|
||
此类 CSV 文件的 Dump 示例如下::
|
||
|
||
key,type,encoding,value <-- 列标题
|
||
namespace_name,namespace,, <-- 第一个条目为 "namespace"
|
||
key1,data,u8,1
|
||
key2,file,string,/path/to/file
|
||
|
||
.. note::
|
||
|
||
请确保:
|
||
- 逗号 ',' 前后无空格;
|
||
- CSV 文件每行末尾无空格。
|
||
|
||
|
||
NVS 条目和命名空间 (namespace) 的关联
|
||
-----------------------------------------
|
||
|
||
如 CSV 文件中出现命名空间条目,后续条目均会被视为该命名空间的一部分,直至找到下一个命名空间条目。找到新命名空间条目后,后续所有条目都会被视为新命名空间的一部分。
|
||
|
||
.. note:: CSV 文件中第一个条目应始终为 ``namespace``。
|
||
|
||
|
||
支持多页 Blob
|
||
----------------------
|
||
|
||
默认情况下,二进制 Blob 可跨多页,格式参考 :ref:`structure_of_entry` 章节。如需使用旧版格式,可在程序中禁用该功能。
|
||
|
||
|
||
支持加密
|
||
-------------------
|
||
|
||
NVS 分区生成程序还可使用 XTS-AES 加密生成二进制加密文件。更多信息详见 :ref:`nvs_encryption`。
|
||
|
||
|
||
支持解密
|
||
-------------------
|
||
如果 NVS 二进制文件采用了 XTS-AES 加密,该程序还可对此类文件进行解密,更多信息详见 :ref:`nvs_encryption`。
|
||
|
||
运行程序
|
||
-------------------
|
||
|
||
**使用方法**::
|
||
|
||
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]
|
||
|
||
**可选参数**:
|
||
|
||
.. list-table::
|
||
:widths: 30 70
|
||
:header-rows: 1
|
||
|
||
* - 参数
|
||
- 描述
|
||
* - -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
|
||
|
||
.. note:: 创建的加密密钥格式为 ``<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
|
||
|
||
.. note:: 创建的加密密钥格式为 ``<outdir>/keys/keys-<timestamp>.bin``。
|
||
.. note:: 加密密钥存储于新建文件的 ``keys/`` 目录下,与 NVS 密钥分区结构兼容。更多信息请参考 :ref:`nvs_encr_key_partition`。
|
||
|
||
- 将加密密钥用作二进制输入文件来进行加密::
|
||
|
||
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
|
||
|
||
.. note:: NVS 分区最小为 0x3000 字节。
|
||
|
||
.. note:: 将二进制文件烧录至设备时,请确保与应用的 sdkconfig 设置一致。
|
||
|
||
|
||
说明
|
||
-------
|
||
|
||
- 分区生成程序不会对重复键进行检查,而将数据同时写入这两个重复键中。请注意不要使用同名的键;
|
||
- 新页面创建后,前一页的空白处不会再写入数据。CSV 文件中的字段须按次序排列以优化内存;
|
||
- 暂不支持 64 位数据类型。
|