esp-idf/components/nvs_flash/nvs_partition_generator/README_CN.rst

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 数据。这也使得生产制造商在使用同一个固件的基础上，通过自定义参数，如序列号等，为每个设备生成不同配置。

准备工作
-------------

在加密模式下使用该程序，需安装下列软件包：
    - cryptography package

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


CSV 文件格式
---------------

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

+------+----------+--------------------------------------------------------------+-----------------------------------------------------------------+
| 序号 |   参数   |                             描述                             |                               说明                              |
+======+==========+==============================================================+=================================================================+
|    1 | Key      | 主键，应用程序可通过查询此键来获取数据。                     |                                                                 |
+------+----------+--------------------------------------------------------------+-----------------------------------------------------------------+
|    2 | Type     | 支持 ``file``、``data`` 和 ``namespace``。                   |                                                                 |
+------+----------+--------------------------------------------------------------+-----------------------------------------------------------------+
|    3 | Encoding | 支持 ``u8``、``i8``、``u16``、``u32``、                      | ``file``                                                        |
|      |          | ``i32``、``string``、``hex2bin``、``base64`` 和 ``binary``。 | 类型当前仅支持                                                  |
|      |          | 决定二进制 ``bin`` 文件中 value 被编码成的类型。             | ``hex2bin``、``base64``、                                       |
|      |          | ``string`` 和 ``binary`` 编码的区别在于，                    | ``string`` 和 ``binary`` 编码。                                 |
|      |          | ``string`` 数据以 NULL 字符结尾，``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 分区生成程序还可使用 AES-XTS 加密生成二进制加密文件。更多信息详见 :ref:`nvs_encryption`。

支持解密
-------------------
如果 NVS 二进制文件采用了 AES-XTS 加密，该程序还可对此类文件进行解密，更多信息详见 :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]
        
**可选参数**：

+-------------------+------------------------------------------------+
|        参数       |                      描述                      |
+-------------------+------------------------------------------------+
| -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_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 位数据类型。