mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
docs: update sdmmc and vfs cn trans
This commit is contained in:
intern
parent
c166160f64
commit
615e67bd6b
@ -5,6 +5,7 @@ Wear Levelling API
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
Most of flash memory and especially SPI flash that is used in {IDF_TARGET_NAME} has a sector-based organization and also has a limited number of erase/modification cycles per memory sector. The wear levelling component helps to distribute wear and tear among sectors more evenly without requiring any attention from the user.
|
||||
|
||||
The wear levelling component provides API functions related to reading, writing, erasing, and memory mapping of data in external SPI flash through the partition component. The component also has higher-level API functions which work with the FAT filesystem defined in :doc:`FAT filesystem </api-reference/storage/fatfs>`.
|
||||
@ -46,4 +47,3 @@ Memory Size
|
||||
-----------
|
||||
|
||||
The memory size is calculated in the wear levelling module based on partition parameters. The module uses some sectors of flash for internal data.
|
||||
|
||||
|
||||
@ -6,7 +6,7 @@
|
||||
概述
|
||||
--------
|
||||
|
||||
ESP32 所使用的 flash，特别是 SPI flash 多数具备扇区结构，且每个扇区仅允许有限次数的擦除/修改操作。为了避免过度使用某一扇区，乐鑫提供了磨损均衡组件，无需用户介入即可帮助用户均衡各个扇区之间的磨损。
|
||||
{IDF_TARGET_NAME} 所使用的 flash，特别是 SPI flash 多数具备扇区结构，且每个扇区仅允许有限次数的擦除/修改操作。为了避免过度使用某一扇区，乐鑫提供了磨损均衡组件，无需用户介入即可帮助用户均衡各个扇区之间的磨损。
|
||||
|
||||
磨损均衡组件包含了通过分区组件对外部 SPI flash 进行数据读取、写入、擦除和存储器映射相关的 API 函数。磨损均衡组件还具有软件上更高级别的 API 函数，与 :doc:`FAT 文件系统 </api-reference/storage/fatfs>` 协同工作。
|
||||
|
||||
|
||||
@ -74,13 +74,22 @@ An example which combines the SDMMC driver with the FATFS library is provided in
|
||||
|
||||
For card configuration and data transfer, choose the pair of functions relevant to your case from the table below.
|
||||
|
||||
========================================================================= ================================= =================================
|
||||
Action Read Function Write Function
|
||||
========================================================================= ================================= =================================
|
||||
Read and write a single byte using IO_RW_DIRECT (CMD52) :cpp:func:`sdmmc_io_read_byte` :cpp:func:`sdmmc_io_write_byte`
|
||||
Read and write multiple bytes using IO_RW_EXTENDED (CMD53) in byte mode :cpp:func:`sdmmc_io_read_bytes` :cpp:func:`sdmmc_io_write_bytes`
|
||||
Read and write blocks of data using IO_RW_EXTENDED (CMD53) in block mode :cpp:func:`sdmmc_io_read_blocks` :cpp:func:`sdmmc_io_write_blocks`
|
||||
========================================================================= ================================= =================================
|
||||
.. list-table::
|
||||
:widths: 55 25 20
|
||||
:header-rows: 1
|
||||
|
||||
* - Action
|
||||
- Read Function
|
||||
- Write Function
|
||||
* - Read and write a single byte using IO_RW_DIRECT (CMD52)
|
||||
- :cpp:func:`sdmmc_io_read_byte`
|
||||
- :cpp:func:`sdmmc_io_write_byte`
|
||||
* - Read and write multiple bytes using IO_RW_EXTENDED (CMD53) in byte modes
|
||||
- :cpp:func:`sdmmc_io_read_bytes`
|
||||
- :cpp:func:`sdmmc_io_write_bytes`
|
||||
* - Read and write blocks of data using IO_RW_EXTENDED (CMD53) in block modes
|
||||
- :cpp:func:`sdmmc_io_read_blocks`
|
||||
- :cpp:func:`sdmmc_io_write_blocks`
|
||||
|
||||
SDIO interrupts can be enabled by the application using the function :cpp:func:`sdmmc_io_enable_int`. When using SDIO in 1-line mode, the D1 line also needs to be connected to use SDIO interrupts.
|
||||
|
||||
@ -88,8 +97,7 @@ An example which combines the SDMMC driver with the FATFS library is provided in
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
There is a component ESSL (ESP Serial Slave Link) to use if you are communicating with an ESP32
|
||||
SDIO slave. See :doc:`/api-reference/protocols/esp_serial_slave_link` and example :example:`peripherals/sdio/host`.
|
||||
There is a component ESSL (ESP Serial Slave Link) to use if you are communicating with an ESP32 SDIO slave. See :doc:`/api-reference/protocols/esp_serial_slave_link` and example :example:`peripherals/sdio/host`.
|
||||
|
||||
Combo (memory + IO) cards
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@ -6,4 +6,3 @@ API Reference
|
||||
.. include-build-file:: inc/esp_vfs.inc
|
||||
|
||||
.. include-build-file:: inc/esp_vfs_dev.inc
|
||||
|
||||
|
||||
@ -3,18 +3,12 @@ SD/SDIO/MMC 驱动程序
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
.. only:: esp32c3
|
||||
|
||||
.. warning::
|
||||
|
||||
本文档尚未针对 ESP32-C3 进行更新。
|
||||
|
||||
概述
|
||||
--------
|
||||
|
||||
SD/SDIO/MMC 驱动是一种基于 SDMMC 和 SD SPI 主机驱动的协议级驱动程序，目前已支持 SD 存储器、SDIO 卡和 eMMC 芯片。
|
||||
|
||||
SDMMC 主机驱动和 SD SPI 主机驱动（:component_file:`driver/include/driver/sdmmc_host.h`）为以下功能提供 API：
|
||||
SDMMC 主机驱动和 SD SPI 主机驱动（:component_file:`driver/include/driver/sdmmc_host.h` 和 :component_file:`driver/include/driver/sdspi_host.h`）为以下功能提供 API：
|
||||
|
||||
- 发送命令至从设备
|
||||
- 接收和发送数据
|
||||
@ -22,76 +16,93 @@ SDMMC 主机驱动和 SD SPI 主机驱动（:component_file:`driver/include/driv
|
||||
|
||||
初始化函数及配置函数：
|
||||
|
||||
.. only:: esp32
|
||||
.. list::
|
||||
|
||||
- 如需初始化和配置 SDMMC 主机，请参阅 :doc:`SDMMC 主机 API <../peripherals/sdmmc_host>`
|
||||
:SOC_SDMMC_HOST_SUPPORTED: - 如需初始化和配置 SDMMC 主机，请参阅 :doc:`SDMMC 主机 API <../peripherals/sdmmc_host>`
|
||||
- 如需初始化和配置 SD SPI 主机，请参阅 :doc:`SD SPI 主机 API <../peripherals/sdspi_host>`
|
||||
|
||||
|
||||
- 如需初始化和配置 SD SPI 主机，请参阅 :doc:`SD SPI 主机 API <../peripherals/sdspi_host>`
|
||||
.. only:: SOC_SDMMC_HOST_SUPPORTED
|
||||
|
||||
本文档中所述的 SDMMC 协议层仅处理 SD 协议相关事项，例如卡初始化和数据传输命令。
|
||||
本文档中所述的 SDMMC 协议层仅处理 SD 协议相关事项，例如卡初始化和数据传输命令。
|
||||
|
||||
协议层通过 :cpp:class:`sdmmc_host_t` 结构体和主机协同工作，该结构体包含指向主机各类函数的指针。
|
||||
|
||||
协议层通过 :cpp:class:`sdmmc_host_t` 结构体和主机协同工作，该结构体包含指向主机各类函数的指针。
|
||||
|
||||
应用示例
|
||||
-------------------
|
||||
|
||||
ESP-IDF :example:`storage/sd_card` 目录下提供了 SDMMC 驱动与 FatFs 库组合使用的示例，演示了先初始化卡，然后使用 POSIX 和 C 库 API 向卡读写数据。请参考示例目录下 README.md 文件，查看更多详细信息。
|
||||
|
||||
协议层 API
|
||||
------------------
|
||||
.. only:: SOC_SDMMC_HOST_SUPPORTED
|
||||
|
||||
协议层具备 :cpp:class:`sdmmc_host_t` 结构体，此结构体描述了 SD/MMC 主机驱动，列出了其功能，并提供指向驱动程序函数的指针。协议层将卡信息储存于 :cpp:class:`sdmmc_card_t` 结构体中。向 SD/MMC 主机发送命令时，协议层调用时需要一个 :cpp:class:`sdmmc_command_t` 结构体来描述命令、参数、预期返回值和需传输的数据（如有）。
|
||||
协议层 API
|
||||
------------------
|
||||
|
||||
用于 SD 存储卡的 API
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
协议层具备 :cpp:class:`sdmmc_host_t` 结构体，此结构体描述了 SD/MMC 主机驱动，列出了其功能，并提供指向驱动程序函数的指针。协议层将卡信息储存于 :cpp:class:`sdmmc_card_t` 结构体中。向 SD/MMC 主机发送命令时，协议层使用 :cpp:class:`sdmmc_command_t` 结构体来描述命令、参数、预期返回值和需传输的数据（如有）。
|
||||
|
||||
1. 初始化主机，请调用主机驱动函数，例如 :cpp:func:`sdmmc_host_init` 和 :cpp:func:`sdmmc_host_init_slot`；
|
||||
2. 初始化卡，请调用 :cpp:func:`sdmmc_card_init`，并将参数 ``host`` （即主机驱动信息）和参数 ``card`` （指向 :cpp:class:`sdmmc_card_t` 结构体的指针）传递给此函数。函数运行结束后，将会向 :cpp:class:`sdmmc_card_t` 结构体填充该卡的信息；
|
||||
3. 读取或写入卡的扇区，请分别调用 :cpp:func:`sdmmc_read_sectors` 和 :cpp:func:`sdmmc_write_sectors`，并将参数 ``card`` （指向卡信息结构的指针）传递给函数；
|
||||
4. 如果不再使用该卡，请调用主机驱动函数，例如 :cpp:func:`sdmmc_host_deinit`，以禁用主机外设，并释放驱动程序分配的资源。
|
||||
|
||||
用于 eMMC 芯片的 API
|
||||
用于 SD 存储卡的 API
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
1. 初始化主机，请调用主机驱动函数，例如 :cpp:func:`sdmmc_host_init` 和 :cpp:func:`sdmmc_host_init_slot`；
|
||||
2. 初始化卡，请调用 :cpp:func:`sdmmc_card_init`，并将参数 ``host`` （即主机驱动信息）和参数 ``card`` （指向 :cpp:class:`sdmmc_card_t` 结构体的指针）传递给此函数。函数运行结束后，将会向 :cpp:class:`sdmmc_card_t` 结构体填充该卡的信息；
|
||||
3. 读取或写入卡的扇区，请分别调用 :cpp:func:`sdmmc_read_sectors` 和 :cpp:func:`sdmmc_write_sectors`，并将参数 ``card`` （指向卡信息结构的指针）传递给函数；
|
||||
4. 如果不再使用该卡，请调用主机驱动函数，例如 :cpp:func:`sdmmc_host_deinit`，以禁用主机外设，并释放驱动程序分配的资源。
|
||||
|
||||
|
||||
用于 eMMC 芯片的 API
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
从协议层的角度而言，eMMC 存储芯片与 SD 存储卡相同。尽管 eMMC 是芯片，不具备卡的外形，但由于协议相似 (`sdmmc_card_t`, `sdmmc_card_init`)，用于 SD 卡的一些概念同样适用于 eMMC 芯片。注意，eMMC 芯片不可通过 SPI 使用，因此它与 SD API 主机驱动不兼容。
|
||||
|
||||
如需初始化 eMMC 内存并执行读/写操作，请参照上一章节 SD 卡操作步骤。
|
||||
|
||||
|
||||
用于 SDIO 卡的 API
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
SDIO 卡初始化和检测过程与 SD 存储卡相同，唯一的区别是 SDIO 模式下数据传输命令不同。
|
||||
|
||||
在卡初始化和卡检测（通过运行 :cpp:func:`sdmmc_card_init`）期间，驱动仅配置 IO 卡如下寄存器：
|
||||
|
||||
1. I/O 中止 (0x06) 寄存器：在该寄存器中设置 RES 位可重置卡的 IO 部分；
|
||||
2. 总线接口控制 (0x07) 寄存器：如果主机和插槽配置中启用 4 线模式，则驱动程序会尝试在该寄存器中设置总线宽度字段。如果字段设置成功，则从机支持 4 线模式，主机也切换至 4 线模式；
|
||||
3. 高速（0x13）寄存器：如果主机配置中启用高速模式，则该寄存器的 SHS 位会被设置。
|
||||
|
||||
注意，驱动程序不会在 (1) I/O 使能寄存器和 Int 使能寄存器，及 (2) I/O 块大小中，设置任何位。应用程序可通过调用 :cpp:func:`sdmmc_io_write_byte` 来设置相关位。
|
||||
|
||||
如需卡配置或传输数据，请根据您的具体情况选择下表中的函数：
|
||||
|
||||
.. list-table::
|
||||
:widths: 55 25 20
|
||||
:header-rows: 1
|
||||
|
||||
* - 操作
|
||||
- 函数读取
|
||||
- 函数写入
|
||||
* - 使用 IO_RW_DIRECT (CMD52) 读写单个字节。
|
||||
- :cpp:func:`sdmmc_io_read_byte`
|
||||
- :cpp:func:`sdmmc_io_write_byte`
|
||||
* - 使用 IO_RW_EXTENDED (CMD53) 的字节模式读写多个字节。
|
||||
- :cpp:func:`sdmmc_io_read_bytes`
|
||||
- :cpp:func:`sdmmc_io_write_bytes`
|
||||
* - 块模式下，使用 IO_RW_EXTENDED (CMD53) 读写数据块。
|
||||
- :cpp:func:`sdmmc_io_read_blocks`
|
||||
- :cpp:func:`sdmmc_io_write_blocks`
|
||||
|
||||
使用 :cpp:func:`sdmmc_io_enable_int` 函数，应用程序可启用 SDIO 中断。在单线模式下使用 SDIO 时，还需要连接 D1 线来启用 SDIO 中断。
|
||||
|
||||
如果您需要应用程序保持等待直至发生 SDIO 中断，请使用 :cpp:func:`sdmmc_io_wait_int` 函数。
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
如果您需要与 ESP32 的 SDIO 从设备通信，请使用 ESSL 组件（ESP 串行从设备链接）。请参阅 :doc:`/api-reference/protocols/esp_serial_slave_link` 和 :example:`peripherals/sdio/host`。
|
||||
|
||||
复合卡（存储 + IO）
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
从协议层的角度而言，eMMC 存储芯片与 SD 存储卡相同。尽管 eMMC 是芯片，不具备卡的外形，但由于协议相似 (`sdmmc_card_t`, `sdmmc_card_init`)，用于 SD 卡的一些概念同样适用于 eMMC 芯片。注意，eMMC 芯片不可通过 SPI 使用，因此它与 SD API 主机驱动不兼容。
|
||||
|
||||
如需初始化 eMMC 内存并执行读/写操作，请参照上一章节 SD 卡操作步骤。
|
||||
|
||||
用于 SDIO 卡的 API
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
SDIO 卡初始化和检测过程与 SD 存储卡相同，唯一的区别是 SDIO 模式下数据传输命令不同。
|
||||
|
||||
在卡初始化和卡检测（通过运行 :cpp:func:`sdmmc_card_init`）期间，驱动仅配置 SDIO 卡如下寄存器：
|
||||
|
||||
1. I/O 中止 (0x06) 寄存器：在该寄存器中设置 RES 位可重置卡的 I/O 部分；
|
||||
2. 总线接口控制 (0x07) 寄存器：如果主机和插槽配置中启用 4 线模式，则驱动程序会尝试在该寄存器中设置总线宽度字段。如果字段设置成功，则从机支持 4 线模式，主机也切换至 4 线模式；
|
||||
3. 高速（0x13）寄存器：如果主机配置中启用高速模式，则会在该寄存器中设置 SHS 位。
|
||||
|
||||
注意，驱动程序不会在 (1) I/O 使能寄存器和 Int 使能寄存器，及 (2) I/O 块大小中，设置任何位。应用程序可通过调用 :cpp:func:`sdmmc_io_write_byte` 来设置相关位。
|
||||
|
||||
如需设置卡配置或传输数据，请根据您的具体情况选择下表中的函数：
|
||||
|
||||
========================================================================= ================================= =================================
|
||||
操作 读函数 写函数
|
||||
========================================================================= ================================= =================================
|
||||
使用 IO_RW_DIRECT (CMD52) 读写单个字节。 :cpp:func:`sdmmc_io_read_byte` :cpp:func:`sdmmc_io_write_byte`
|
||||
使用 IO_RW_EXTENDED (CMD53) 的字节模式读写多个字节。 :cpp:func:`sdmmc_io_read_bytes` :cpp:func:`sdmmc_io_write_bytes`
|
||||
块模式下，使用 IO_RW_EXTENDED (CMD53) 读写数据块。 :cpp:func:`sdmmc_io_read_blocks` :cpp:func:`sdmmc_io_write_blocks`
|
||||
========================================================================= ================================= =================================
|
||||
|
||||
使用 :cpp:func:`sdmmc_io_enable_int` 函数，应用程序可启用 SDIO 中断。
|
||||
|
||||
在单线模式下使用 SDIO 时，还需要连接 D1 线来启用 SDIO 中断。
|
||||
|
||||
如果您需要应用程序保持等待直至发生 SDIO 中断，请使用 :cpp:func:`sdmmc_io_wait_int` 函数。
|
||||
|
||||
|
||||
复合卡（存储 + SDIO）
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
该驱动程序不支持 SDIO 复合卡，复合卡会被视为 SDIO 卡。
|
||||
该驱动程序不支持 SD 复合卡，复合卡会被视为 IO 卡。
|
||||
|
||||
|
||||
线程安全
|
||||
@ -99,6 +110,7 @@ SDIO 卡初始化和检测过程与 SD 存储卡相同，唯一的区别是 SDIO
|
||||
|
||||
多数应用程序仅需在一个任务中使用协议层。因此，协议层在 :cpp:class:`sdmmc_card_t` 结构体或在访问 SDMMC 或 SD SPI 主机驱动程序时不使用任何类型的锁。这种锁通常在较高层级实现，例如文件系统驱动程序。
|
||||
|
||||
|
||||
API 参考
|
||||
-------------
|
||||
|
||||
|
||||
@ -1,12 +1,5 @@
|
||||
.. include:: ../../../../components/vfs/README_CN.rst
|
||||
|
||||
应用示例
|
||||
-------------------
|
||||
|
||||
`指南`_ （未完成）
|
||||
|
||||
.. _指南: ../../template.html
|
||||
|
||||
API 参考
|
||||
-------------
|
||||
|
||||
|
||||
@ -10,8 +10,8 @@ This utility is designed to create instances of factory NVS partition images on
|
||||
|
||||
Please note that this utility only creates manufacturing binary images which then need to be flashed onto your devices using:
|
||||
|
||||
- `esptool.py`_
|
||||
- `Flash Download tool`_ (available on Windows only).Just download it, unzip, and follow the instructions inside the *doc* folder.
|
||||
- `esptool.py`_.
|
||||
- `Flash Download tool`_ (available on Windows only). Just download it, unzip, and follow the instructions inside the *doc* folder.
|
||||
- Direct flash programming using custom production tools.
|
||||
|
||||
|
||||
@ -21,7 +21,7 @@ Prerequisites
|
||||
**This utility is dependent on esp-idf's NVS partition utility.**
|
||||
|
||||
* Operating System requirements:
|
||||
- Linux / MacOS / Windows (standard distributions)
|
||||
- Linux/macOS/Windows (standard distributions)
|
||||
|
||||
* The following packages are needed to use this utility:
|
||||
- `Python <https://www.python.org/downloads/>`_
|
||||
@ -63,8 +63,7 @@ The data in the configuration file has the following format (the `REPEAT` tag is
|
||||
|
||||
.. note:: The first line in this file should always be the ``namespace`` entry.
|
||||
|
||||
Each line should have three parameters: ``key,type,encoding``, separated by a comma.
|
||||
If the ``REPEAT`` tag is present, the value corresponding to this key in the master value CSV file will be the same for all devices.
|
||||
Each line should have three parameters: ``key,type,encoding``, separated by a comma. If the ``REPEAT`` tag is present, the value corresponding to this key in the master value CSV file will be the same for all devices.
|
||||
|
||||
*Please refer to README of the NVS Partition Generator utility for detailed description of each parameter.*
|
||||
|
||||
@ -133,66 +132,72 @@ Running the utility
|
||||
|
||||
python mfg_gen.py [-h] {generate,generate-key} ...
|
||||
|
||||
Optional Arguments:
|
||||
+-----+------------+----------------------------------------------------------------------+
|
||||
| No. | Parameter | Description |
|
||||
+=====+============+======================================================================+
|
||||
| 1 | -h, --help | show this help message and exit |
|
||||
+-----+------------+----------------------------------------------------------------------+
|
||||
**Optional Arguments**:
|
||||
|
||||
+-----+------------+----------------------------------------------------------------------+
|
||||
| No. | Parameter | Description |
|
||||
+=====+============+======================================================================+
|
||||
| 1 | -h, --help | show this help message and exit |
|
||||
+-----+------------+----------------------------------------------------------------------+
|
||||
|
||||
**Commands**:
|
||||
|
||||
Commands:
|
||||
Run mfg_gen.py {command} -h for additional help
|
||||
+-----+--------------+--------------------------------------------------------------------+
|
||||
| No. | Parameter | Description |
|
||||
+=====+==============+====================================================================+
|
||||
| 1 | generate | Generate NVS partition |
|
||||
+-----+--------------+--------------------------------------------------------------------+
|
||||
| 2 | generate-key | Generate keys for encryption |
|
||||
+-----+--------------+--------------------------------------------------------------------+
|
||||
|
||||
+-----+--------------+--------------------------------------------------------------------+
|
||||
| No. | Parameter | Description |
|
||||
+=====+==============+====================================================================+
|
||||
| 1 | generate | Generate NVS partition |
|
||||
+-----+--------------+--------------------------------------------------------------------+
|
||||
| 2 | generate-key | Generate keys for encryption |
|
||||
+-----+--------------+--------------------------------------------------------------------+
|
||||
|
||||
**To generate factory images for each device (Default):**
|
||||
**Usage**::
|
||||
|
||||
python mfg_gen.py generate [-h] [--fileid FILEID] [--version {1,2}] [--keygen]
|
||||
[--keyfile KEYFILE] [--inputkey INPUTKEY]
|
||||
[--outdir OUTDIR]
|
||||
conf values prefix size
|
||||
**Usage**::
|
||||
|
||||
Positional Arguments:
|
||||
+--------------+----------------------------------------------------------------------+
|
||||
| Parameter | Description |
|
||||
+==============+======================================================================+
|
||||
| conf | Path to configuration csv file to parse |
|
||||
+--------------+----------------------------------------------------------------------+
|
||||
| values | Path to values csv file to parse |
|
||||
+--------------+----------------------------------------------------------------------+
|
||||
| prefix | Unique name for each output filename prefix |
|
||||
+-----+--------------+----------------------------------------------------------------+
|
||||
| size | Size of NVS partition in bytes |
|
||||
| | (must be multiple of 4096) |
|
||||
+--------------+----------------------------------------------------------------------+
|
||||
python mfg_gen.py generate [-h] [--fileid FILEID] [--version {1,2}] [--keygen]
|
||||
[--keyfile KEYFILE] [--inputkey INPUTKEY]
|
||||
[--outdir OUTDIR]
|
||||
conf values prefix size
|
||||
|
||||
Optional Arguments:
|
||||
+---------------------+--------------------------------------------------------------------+
|
||||
| Parameter | Description |
|
||||
+=====================+====================================================================+
|
||||
| -h, --help | show this help message and exit |
|
||||
+---------------------+--------------------------------------------------------------------+
|
||||
| --fileid FILEID | Unique file identifier(any key in values file) |
|
||||
| | for each filename suffix (Default: numeric value(1,2,3...) |
|
||||
+---------------------+--------------------------------------------------------------------+
|
||||
| --version {1,2} | Set multipage blob version. |
|
||||
| | Version 1 - Multipage blob support disabled. |
|
||||
| | Version 2 - Multipage blob support enabled. |
|
||||
| | Default: Version 2 |
|
||||
+---------------------+--------------------------------------------------------------------+
|
||||
| --keygen | Generates key for encrypting NVS partition |
|
||||
+---------------------+--------------------------------------------------------------------+
|
||||
| --inputkey INPUTKEY | File having key for encrypting NVS partition |
|
||||
+---------------------+--------------------------------------------------------------------+
|
||||
| --outdir OUTDIR | Output directory to store files created |
|
||||
| | (Default: current directory) |
|
||||
+---------------------+--------------------------------------------------------------------+
|
||||
**Positional Arguments**:
|
||||
|
||||
+--------------+----------------------------------------------------------------------+
|
||||
| Parameter | Description |
|
||||
+==============+======================================================================+
|
||||
| conf | Path to configuration csv file to parse |
|
||||
+--------------+----------------------------------------------------------------------+
|
||||
| values | Path to values csv file to parse |
|
||||
+--------------+----------------------------------------------------------------------+
|
||||
| prefix | Unique name for each output filename prefix |
|
||||
+-----+--------------+----------------------------------------------------------------+
|
||||
| size | Size of NVS partition in bytes |
|
||||
| | (must be multiple of 4096) |
|
||||
+--------------+----------------------------------------------------------------------+
|
||||
|
||||
**Optional Arguments**:
|
||||
|
||||
+---------------------+--------------------------------------------------------------------+
|
||||
| Parameter | Description |
|
||||
+=====================+====================================================================+
|
||||
| -h, --help | show this help message and exit |
|
||||
+---------------------+--------------------------------------------------------------------+
|
||||
| --fileid FILEID | Unique file identifier(any key in values file) |
|
||||
| | for each filename suffix (Default: numeric value(1,2,3...) |
|
||||
+---------------------+--------------------------------------------------------------------+
|
||||
| --version {1,2} | Set multipage blob version. |
|
||||
| | Version 1 - Multipage blob support disabled. |
|
||||
| | Version 2 - Multipage blob support enabled. |
|
||||
| | Default: Version 2 |
|
||||
+---------------------+--------------------------------------------------------------------+
|
||||
| --keygen | Generates key for encrypting NVS partition |
|
||||
+---------------------+--------------------------------------------------------------------+
|
||||
| --inputkey INPUTKEY | File having key for encrypting NVS partition |
|
||||
+---------------------+--------------------------------------------------------------------+
|
||||
| --outdir OUTDIR | Output directory to store files created |
|
||||
| | (Default: current directory) |
|
||||
+---------------------+--------------------------------------------------------------------+
|
||||
|
||||
You can run the utility to generate factory images for each device using the command below. A sample CSV file is provided with the utility::
|
||||
|
||||
@ -216,21 +221,23 @@ You can run the utility to encrypt factory images for each device using the comm
|
||||
python mfg_gen.py generate samples/sample_config.csv samples/sample_values_singlepage_blob.csv Sample 0x3000 --inputkey keys/sample_keys.bin
|
||||
|
||||
**To generate only encryption keys:**
|
||||
**Usage**::
|
||||
|
||||
python mfg_gen.py generate-key [-h] [--keyfile KEYFILE] [--outdir OUTDIR]
|
||||
**Usage**::
|
||||
|
||||
Optional Arguments:
|
||||
+--------------------+----------------------------------------------------------------------+
|
||||
| Parameter | Description |
|
||||
+====================+======================================================================+
|
||||
| -h, --help | show this help message and exit |
|
||||
+--------------------+----------------------------------------------------------------------+
|
||||
| --keyfile KEYFILE | Path to output encryption keys file |
|
||||
+--------------------+----------------------------------------------------------------------+
|
||||
| --outdir OUTDIR | Output directory to store files created. |
|
||||
| | (Default: current directory) |
|
||||
+--------------------+----------------------------------------------------------------------+
|
||||
python mfg_gen.py generate-key [-h] [--keyfile KEYFILE] [--outdir OUTDIR]
|
||||
|
||||
**Optional Arguments**:
|
||||
|
||||
+--------------------+----------------------------------------------------------------------+
|
||||
| Parameter | Description |
|
||||
+====================+======================================================================+
|
||||
| -h, --help | show this help message and exit |
|
||||
+--------------------+----------------------------------------------------------------------+
|
||||
| --keyfile KEYFILE | Path to output encryption keys file |
|
||||
+--------------------+----------------------------------------------------------------------+
|
||||
| --outdir OUTDIR | Output directory to store files created. |
|
||||
| | (Default: current directory) |
|
||||
+--------------------+----------------------------------------------------------------------+
|
||||
|
||||
You can run the utility to generate only encryption keys using the command below::
|
||||
|
||||
|
||||
@ -10,9 +10,9 @@
|
||||
|
||||
注意，该程序仅创建用于量产的二进制映像，您需要使用以下工具将映像烧录到设备上：
|
||||
|
||||
- esptool.py
|
||||
- Flash 下载工具（仅适用于 Windows）
|
||||
- 直接烧录程序
|
||||
- `esptool.py`_。
|
||||
- `Flash 下载工具`_ （仅适用于 Windows）。下载后解压，然后按照 doc 文件夹中的说明操作。
|
||||
- 使用定制的生产工具直接烧录程序。
|
||||
|
||||
|
||||
准备工作
|
||||
@ -21,10 +21,10 @@
|
||||
**该程序需要用到分区公用程序。**
|
||||
|
||||
* 操作系统要求：
|
||||
- Linux、MacOS 或 Windows（标准版）
|
||||
- Linux、macOS 或 Windows（标准版）
|
||||
|
||||
* 安装依赖包：
|
||||
- Python： https://www.python.org/downloads/。
|
||||
- `Python <https://www.python.org/downloads/>`_。
|
||||
|
||||
.. note::
|
||||
|
||||
@ -50,7 +50,7 @@
|
||||
CSV 配置文件
|
||||
----------------------
|
||||
|
||||
CSV 配置文件中包含设备待烧录的配置信息，定义了待烧录的配置项。例如定义 ``firmware_key`` (``key``) 的 ``type`` 为 ``data``，``encoding`` 为 ``hex2bin``。
|
||||
CSV 配置文件中包含设备待烧录的配置信息，定义了待烧录的配置项。
|
||||
|
||||
配置文件中数据格式如下（`REPEAT` 标签可选）::
|
||||
|
||||
@ -69,11 +69,13 @@ CSV 配置文件中包含设备待烧录的配置信息，定义了待烧录的
|
||||
|
||||
CSV 配置文件示例如下::
|
||||
|
||||
|
||||
app,namespace,
|
||||
firmware_key,data,hex2bin
|
||||
serial_no,data,string,REPEAT <-- "serial_no" 被标记为 "REPEAT"
|
||||
device_no,data,i32
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
请确保：
|
||||
@ -84,14 +86,12 @@ CSV 配置文件示例如下::
|
||||
主 CSV 文件
|
||||
---------------------
|
||||
|
||||
主 CSV 文件中包含设备待烧录的详细信息，文件中每行均对应一个设备实体。主 CSV 文件中的 ``key`` 应首先在 CSV 配置文件中定义。
|
||||
主 CSV 文件中包含设备待烧录的详细信息，文件中每行均对应一个设备实体。
|
||||
|
||||
主 CSV 文件的数据格式如下::
|
||||
|
||||
key1,key2,key3,.....
|
||||
value1,value2,value3,.... <-- 对应一个设备实体
|
||||
value4,value5,value6,.... <-- 对应一个设备实体
|
||||
value7,value8,value9,.... <-- 对应一个设备实体
|
||||
value1,value2,value3,....
|
||||
|
||||
.. note:: 文件中键 (``key``) 名应始终置于文件首行。从配置文件中获取的键，在此文件中的排列顺序应与其在配置文件中的排列顺序相同。主 CSV 文件同时可以包含其它列（键），这些列将被视为元数据，而不会编译进最终二进制文件。
|
||||
|
||||
@ -106,10 +106,10 @@ CSV 配置文件示例如下::
|
||||
|
||||
主 CSV 文件示例如下::
|
||||
|
||||
id,firmware_key,serial_no,device_no
|
||||
1,1a2b3c4d5e6faabb,A1,101 <-- 对应一个设备实体（在 CSV 配置文件中标记为 `REPEAT` 的键，除第一个条目外，其他均为空）
|
||||
2,1a2b3c4d5e6fccdd,,102 <-- 对应一个设备实体
|
||||
3,1a2b3c4d5e6feeff,,103 <-- 对应一个设备实体
|
||||
id,firmware_key,serial_no,device_no
|
||||
1,1a2b3c4d5e6faabb,A1,101
|
||||
2,1a2b3c4d5e6fccdd,,102
|
||||
3,1a2b3c4d5e6feeff,,103
|
||||
|
||||
.. note:: 如果出现 `REPEAT` 标签，则会在相同目录下生成一个新的主 CSV 文件用作主输入文件，并在每行为带有 `REPEAT` 标签的键插入键值。
|
||||
|
||||
@ -124,6 +124,7 @@ CSV 配置文件示例如下::
|
||||
|
||||
此步骤将为每一设备生成一个中间 CSV 文件。
|
||||
|
||||
|
||||
运行量产程序
|
||||
-------------------
|
||||
|
||||
@ -236,7 +237,8 @@ CSV 配置文件示例如下::
|
||||
+-------------------+----------------------------------------------+
|
||||
| --outdir OUTDIR | 输出目录，用于存储创建的文件（默认当前目录） |
|
||||
+-------------------+----------------------------------------------+
|
||||
|
||||
|
||||
|
||||
运行以下命令仅生成加密密钥::
|
||||
|
||||
python mfg_gen.py generate-key
|
||||
@ -254,3 +256,5 @@ CSV 配置文件示例如下::
|
||||
- ``csv/`` 存储生成的中间 CSV 文件
|
||||
- ``keys/`` 存储加密密钥（创建工厂加密映像时会用到）
|
||||
|
||||
.. _esptool.py: https://github.com/espressif/esptool/#readme
|
||||
.. _Flash 下载工具: https://www.espressif.com/en/support/download/other-tools?keys=flash+download+tools
|
||||
Loading…
Reference in New Issue
Block a user