mirror of
https://github.com/espressif/esp-idf.git
synced 2025-07-30 18:57:19 +02:00
docs: update sdmmc and vfs cn trans
This commit is contained in:
intern
@ -5,6 +5,7 @@ Wear Levelling API
|
|||||||
|
|
||||||
Overview
|
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.
|
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>`.
|
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.
|
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>` 协同工作。
|
磨损均衡组件包含了通过分区组件对外部 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.
|
For card configuration and data transfer, choose the pair of functions relevant to your case from the table below.
|
||||||
|
|
||||||
========================================================================= ================================= =================================
|
.. list-table::
|
||||||
Action Read Function Write Function
|
:widths: 55 25 20
|
||||||
========================================================================= ================================= =================================
|
:header-rows: 1
|
||||||
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`
|
* - Action
|
||||||
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`
|
- 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.
|
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
|
.. only:: esp32
|
||||||
|
|
||||||
There is a component ESSL (ESP Serial Slave Link) to use if you are communicating with an 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`.
|
||||||
SDIO slave. See :doc:`/api-reference/protocols/esp_serial_slave_link` and example :example:`peripherals/sdio/host`.
|
|
||||||
|
|
||||||
Combo (memory + IO) cards
|
Combo (memory + IO) cards
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|||||||
@ -6,4 +6,3 @@ API Reference
|
|||||||
.. include-build-file:: inc/esp_vfs.inc
|
.. include-build-file:: inc/esp_vfs.inc
|
||||||
|
|
||||||
.. include-build-file:: inc/esp_vfs_dev.inc
|
.. include-build-file:: inc/esp_vfs_dev.inc
|
||||||
|
|
||||||
|
|||||||
@ -3,18 +3,12 @@ SD/SDIO/MMC 驱动程序
|
|||||||
|
|
||||||
:link_to_translation:`en:[English]`
|
:link_to_translation:`en:[English]`
|
||||||
|
|
||||||
.. only:: esp32c3
|
|
||||||
|
|
||||||
.. warning::
|
|
||||||
|
|
||||||
本文档尚未针对 ESP32-C3 进行更新。
|
|
||||||
|
|
||||||
概述
|
概述
|
||||||
--------
|
--------
|
||||||
|
|
||||||
SD/SDIO/MMC 驱动是一种基于 SDMMC 和 SD SPI 主机驱动的协议级驱动程序，目前已支持 SD 存储器、SDIO 卡和 eMMC 芯片。
|
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 文件，查看更多详细信息。
|
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 主机驱动不兼容。
|
该驱动程序不支持 SD 复合卡，复合卡会被视为 IO 卡。
|
||||||
|
|
||||||
如需初始化 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 卡。
|
|
||||||
|
|
||||||
|
|
||||||
线程安全
|
线程安全
|
||||||
@ -99,6 +110,7 @@ SDIO 卡初始化和检测过程与 SD 存储卡相同，唯一的区别是 SDIO
|
|||||||
|
|
||||||
多数应用程序仅需在一个任务中使用协议层。因此，协议层在 :cpp:class:`sdmmc_card_t` 结构体或在访问 SDMMC 或 SD SPI 主机驱动程序时不使用任何类型的锁。这种锁通常在较高层级实现，例如文件系统驱动程序。
|
多数应用程序仅需在一个任务中使用协议层。因此，协议层在 :cpp:class:`sdmmc_card_t` 结构体或在访问 SDMMC 或 SD SPI 主机驱动程序时不使用任何类型的锁。这种锁通常在较高层级实现，例如文件系统驱动程序。
|
||||||
|
|
||||||
|
|
||||||
API 参考
|
API 参考
|
||||||
-------------
|
-------------
|
||||||
|
|
||||||
|
|||||||
@ -1,12 +1,5 @@
|
|||||||
.. include:: ../../../../components/vfs/README_CN.rst
|
.. include:: ../../../../components/vfs/README_CN.rst
|
||||||
|
|
||||||
应用示例
|
|
||||||
-------------------
|
|
||||||
|
|
||||||
`指南`_ （未完成）
|
|
||||||
|
|
||||||
.. _指南: ../../template.html
|
|
||||||
|
|
||||||
API 参考
|
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:
|
Please note that this utility only creates manufacturing binary images which then need to be flashed onto your devices using:
|
||||||
|
|
||||||
- `esptool.py`_
|
- `esptool.py`_.
|
||||||
- `Flash Download tool`_ (available on Windows only).Just download it, unzip, and follow the instructions inside the *doc* folder.
|
- `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.
|
- Direct flash programming using custom production tools.
|
||||||
|
|
||||||
|
|
||||||
@ -21,7 +21,7 @@ Prerequisites
|
|||||||
**This utility is dependent on esp-idf's NVS partition utility.**
|
**This utility is dependent on esp-idf's NVS partition utility.**
|
||||||
|
|
||||||
* Operating System requirements:
|
* Operating System requirements:
|
||||||
- Linux / MacOS / Windows (standard distributions)
|
- Linux/macOS/Windows (standard distributions)
|
||||||
|
|
||||||
* The following packages are needed to use this utility:
|
* The following packages are needed to use this utility:
|
||||||
- `Python <https://www.python.org/downloads/>`_
|
- `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.
|
.. 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.
|
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.
|
||||||
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.*
|
*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} ...
|
python mfg_gen.py [-h] {generate,generate-key} ...
|
||||||
|
|
||||||
Optional Arguments:
|
**Optional Arguments**:
|
||||||
+-----+------------+----------------------------------------------------------------------+
|
|
||||||
| No. | Parameter | Description |
|
+-----+------------+----------------------------------------------------------------------+
|
||||||
+=====+============+======================================================================+
|
| No. | Parameter | Description |
|
||||||
| 1 | -h, --help | show this help message and exit |
|
+=====+============+======================================================================+
|
||||||
+-----+------------+----------------------------------------------------------------------+
|
| 1 | -h, --help | show this help message and exit |
|
||||||
|
+-----+------------+----------------------------------------------------------------------+
|
||||||
|
|
||||||
|
**Commands**:
|
||||||
|
|
||||||
Commands:
|
|
||||||
Run mfg_gen.py {command} -h for additional help
|
Run mfg_gen.py {command} -h for additional help
|
||||||
+-----+--------------+--------------------------------------------------------------------+
|
|
||||||
| No. | Parameter | Description |
|
+-----+--------------+--------------------------------------------------------------------+
|
||||||
+=====+==============+====================================================================+
|
| No. | Parameter | Description |
|
||||||
| 1 | generate | Generate NVS partition |
|
+=====+==============+====================================================================+
|
||||||
+-----+--------------+--------------------------------------------------------------------+
|
| 1 | generate | Generate NVS partition |
|
||||||
| 2 | generate-key | Generate keys for encryption |
|
+-----+--------------+--------------------------------------------------------------------+
|
||||||
+-----+--------------+--------------------------------------------------------------------+
|
| 2 | generate-key | Generate keys for encryption |
|
||||||
|
+-----+--------------+--------------------------------------------------------------------+
|
||||||
|
|
||||||
**To generate factory images for each device (Default):**
|
**To generate factory images for each device (Default):**
|
||||||
**Usage**::
|
|
||||||
|
|
||||||
python mfg_gen.py generate [-h] [--fileid FILEID] [--version {1,2}] [--keygen]
|
**Usage**::
|
||||||
[--keyfile KEYFILE] [--inputkey INPUTKEY]
|
|
||||||
[--outdir OUTDIR]
|
|
||||||
conf values prefix size
|
|
||||||
|
|
||||||
Positional Arguments:
|
python mfg_gen.py generate [-h] [--fileid FILEID] [--version {1,2}] [--keygen]
|
||||||
+--------------+----------------------------------------------------------------------+
|
[--keyfile KEYFILE] [--inputkey INPUTKEY]
|
||||||
| Parameter | Description |
|
[--outdir OUTDIR]
|
||||||
+==============+======================================================================+
|
conf values prefix size
|
||||||
| 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:
|
**Positional Arguments**:
|
||||||
+---------------------+--------------------------------------------------------------------+
|
|
||||||
| Parameter | Description |
|
+--------------+----------------------------------------------------------------------+
|
||||||
+=====================+====================================================================+
|
| Parameter | Description |
|
||||||
| -h, --help | show this help message and exit |
|
+==============+======================================================================+
|
||||||
+---------------------+--------------------------------------------------------------------+
|
| conf | Path to configuration csv file to parse |
|
||||||
| --fileid FILEID | Unique file identifier(any key in values file) |
|
+--------------+----------------------------------------------------------------------+
|
||||||
| | for each filename suffix (Default: numeric value(1,2,3...) |
|
| values | Path to values csv file to parse |
|
||||||
+---------------------+--------------------------------------------------------------------+
|
+--------------+----------------------------------------------------------------------+
|
||||||
| --version {1,2} | Set multipage blob version. |
|
| prefix | Unique name for each output filename prefix |
|
||||||
| | Version 1 - Multipage blob support disabled. |
|
+-----+--------------+----------------------------------------------------------------+
|
||||||
| | Version 2 - Multipage blob support enabled. |
|
| size | Size of NVS partition in bytes |
|
||||||
| | Default: Version 2 |
|
| | (must be multiple of 4096) |
|
||||||
+---------------------+--------------------------------------------------------------------+
|
+--------------+----------------------------------------------------------------------+
|
||||||
| --keygen | Generates key for encrypting NVS partition |
|
|
||||||
+---------------------+--------------------------------------------------------------------+
|
**Optional Arguments**:
|
||||||
| --inputkey INPUTKEY | File having key for encrypting NVS partition |
|
|
||||||
+---------------------+--------------------------------------------------------------------+
|
+---------------------+--------------------------------------------------------------------+
|
||||||
| --outdir OUTDIR | Output directory to store files created |
|
| Parameter | Description |
|
||||||
| | (Default: current directory) |
|
+=====================+====================================================================+
|
||||||
+---------------------+--------------------------------------------------------------------+
|
| -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::
|
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
|
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:**
|
**To generate only encryption keys:**
|
||||||
**Usage**::
|
|
||||||
|
|
||||||
python mfg_gen.py generate-key [-h] [--keyfile KEYFILE] [--outdir OUTDIR]
|
**Usage**::
|
||||||
|
|
||||||
Optional Arguments:
|
python mfg_gen.py generate-key [-h] [--keyfile KEYFILE] [--outdir OUTDIR]
|
||||||
+--------------------+----------------------------------------------------------------------+
|
|
||||||
| Parameter | Description |
|
**Optional Arguments**:
|
||||||
+====================+======================================================================+
|
|
||||||
| -h, --help | show this help message and exit |
|
+--------------------+----------------------------------------------------------------------+
|
||||||
+--------------------+----------------------------------------------------------------------+
|
| Parameter | Description |
|
||||||
| --keyfile KEYFILE | Path to output encryption keys file |
|
+====================+======================================================================+
|
||||||
+--------------------+----------------------------------------------------------------------+
|
| -h, --help | show this help message and exit |
|
||||||
| --outdir OUTDIR | Output directory to store files created. |
|
+--------------------+----------------------------------------------------------------------+
|
||||||
| | (Default: current directory) |
|
| --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::
|
You can run the utility to generate only encryption keys using the command below::
|
||||||
|
|
||||||
|
|||||||
@ -10,9 +10,9 @@
|
|||||||
|
|
||||||
注意，该程序仅创建用于量产的二进制映像，您需要使用以下工具将映像烧录到设备上：
|
注意，该程序仅创建用于量产的二进制映像，您需要使用以下工具将映像烧录到设备上：
|
||||||
|
|
||||||
- esptool.py
|
- `esptool.py`_。
|
||||||
- Flash 下载工具（仅适用于 Windows）
|
- `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::
|
.. note::
|
||||||
|
|
||||||
@ -50,7 +50,7 @@
|
|||||||
CSV 配置文件
|
CSV 配置文件
|
||||||
----------------------
|
----------------------
|
||||||
|
|
||||||
CSV 配置文件中包含设备待烧录的配置信息，定义了待烧录的配置项。例如定义 ``firmware_key`` (``key``) 的 ``type`` 为 ``data``，``encoding`` 为 ``hex2bin``。
|
CSV 配置文件中包含设备待烧录的配置信息，定义了待烧录的配置项。
|
||||||
|
|
||||||
配置文件中数据格式如下（`REPEAT` 标签可选）::
|
配置文件中数据格式如下（`REPEAT` 标签可选）::
|
||||||
|
|
||||||
@ -69,11 +69,13 @@ CSV 配置文件中包含设备待烧录的配置信息，定义了待烧录的
|
|||||||
|
|
||||||
CSV 配置文件示例如下::
|
CSV 配置文件示例如下::
|
||||||
|
|
||||||
|
|
||||||
app,namespace,
|
app,namespace,
|
||||||
firmware_key,data,hex2bin
|
firmware_key,data,hex2bin
|
||||||
serial_no,data,string,REPEAT <-- "serial_no" 被标记为 "REPEAT"
|
serial_no,data,string,REPEAT <-- "serial_no" 被标记为 "REPEAT"
|
||||||
device_no,data,i32
|
device_no,data,i32
|
||||||
|
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
请确保：
|
请确保：
|
||||||
@ -84,14 +86,12 @@ CSV 配置文件示例如下::
|
|||||||
主 CSV 文件
|
主 CSV 文件
|
||||||
---------------------
|
---------------------
|
||||||
|
|
||||||
主 CSV 文件中包含设备待烧录的详细信息，文件中每行均对应一个设备实体。主 CSV 文件中的 ``key`` 应首先在 CSV 配置文件中定义。
|
主 CSV 文件中包含设备待烧录的详细信息，文件中每行均对应一个设备实体。
|
||||||
|
|
||||||
主 CSV 文件的数据格式如下::
|
主 CSV 文件的数据格式如下::
|
||||||
|
|
||||||
key1,key2,key3,.....
|
key1,key2,key3,.....
|
||||||
value1,value2,value3,.... <-- 对应一个设备实体
|
value1,value2,value3,....
|
||||||
value4,value5,value6,.... <-- 对应一个设备实体
|
|
||||||
value7,value8,value9,.... <-- 对应一个设备实体
|
|
||||||
|
|
||||||
.. note:: 文件中键 (``key``) 名应始终置于文件首行。从配置文件中获取的键，在此文件中的排列顺序应与其在配置文件中的排列顺序相同。主 CSV 文件同时可以包含其它列（键），这些列将被视为元数据，而不会编译进最终二进制文件。
|
.. note:: 文件中键 (``key``) 名应始终置于文件首行。从配置文件中获取的键，在此文件中的排列顺序应与其在配置文件中的排列顺序相同。主 CSV 文件同时可以包含其它列（键），这些列将被视为元数据，而不会编译进最终二进制文件。
|
||||||
|
|
||||||
@ -106,10 +106,10 @@ CSV 配置文件示例如下::
|
|||||||
|
|
||||||
主 CSV 文件示例如下::
|
主 CSV 文件示例如下::
|
||||||
|
|
||||||
id,firmware_key,serial_no,device_no
|
id,firmware_key,serial_no,device_no
|
||||||
1,1a2b3c4d5e6faabb,A1,101 <-- 对应一个设备实体（在 CSV 配置文件中标记为 `REPEAT` 的键，除第一个条目外，其他均为空）
|
1,1a2b3c4d5e6faabb,A1,101
|
||||||
2,1a2b3c4d5e6fccdd,,102 <-- 对应一个设备实体
|
2,1a2b3c4d5e6fccdd,,102
|
||||||
3,1a2b3c4d5e6feeff,,103 <-- 对应一个设备实体
|
3,1a2b3c4d5e6feeff,,103
|
||||||
|
|
||||||
.. note:: 如果出现 `REPEAT` 标签，则会在相同目录下生成一个新的主 CSV 文件用作主输入文件，并在每行为带有 `REPEAT` 标签的键插入键值。
|
.. note:: 如果出现 `REPEAT` 标签，则会在相同目录下生成一个新的主 CSV 文件用作主输入文件，并在每行为带有 `REPEAT` 标签的键插入键值。
|
||||||
|
|
||||||
@ -124,6 +124,7 @@ CSV 配置文件示例如下::
|
|||||||
|
|
||||||
此步骤将为每一设备生成一个中间 CSV 文件。
|
此步骤将为每一设备生成一个中间 CSV 文件。
|
||||||
|
|
||||||
|
|
||||||
运行量产程序
|
运行量产程序
|
||||||
-------------------
|
-------------------
|
||||||
|
|
||||||
@ -236,7 +237,8 @@ CSV 配置文件示例如下::
|
|||||||
+-------------------+----------------------------------------------+
|
+-------------------+----------------------------------------------+
|
||||||
| --outdir OUTDIR | 输出目录，用于存储创建的文件（默认当前目录） |
|
| --outdir OUTDIR | 输出目录，用于存储创建的文件（默认当前目录） |
|
||||||
+-------------------+----------------------------------------------+
|
+-------------------+----------------------------------------------+
|
||||||
|
|
||||||
|
|
||||||
运行以下命令仅生成加密密钥::
|
运行以下命令仅生成加密密钥::
|
||||||
|
|
||||||
python mfg_gen.py generate-key
|
python mfg_gen.py generate-key
|
||||||
@ -254,3 +256,5 @@ CSV 配置文件示例如下::
|
|||||||
- ``csv/`` 存储生成的中间 CSV 文件
|
- ``csv/`` 存储生成的中间 CSV 文件
|
||||||
- ``keys/`` 存储加密密钥（创建工厂加密映像时会用到）
|
- ``keys/`` 存储加密密钥（创建工厂加密映像时会用到）
|
||||||
|
|
||||||
|
.. _esptool.py: https://github.com/espressif/esptool/#readme
|
||||||
|
.. _Flash 下载工具: https://www.espressif.com/en/support/download/other-tools?keys=flash+download+tools
|
||||||
Reference in New Issue
Block a user