Replace all TRM urls will generic template variable and remove duplicate sections
All references to TRM had the section duplicated for both targets using .. only:: , replaced these with a generic template url
This commit is contained in:
Marius Vikhammer
Angus Gratton
parent
b9effd8c06
commit
268816649c
16 changed files with 103 additions and 126 deletions
|
|
@ -154,13 +154,7 @@ To display or set contents of memory use "Memory" tab at the bottom of "Debug" p
|
|||
|
||||
With the "Memory" tab, we will read from and write to the memory location ``0x3FF44004`` labeled as ``GPIO_OUT_REG`` used to set and clear individual GPIO's.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual <https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`__, chapter IO_MUX and GPIO Matrix.
|
||||
|
||||
.. only:: esp32s2beta
|
||||
|
||||
For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual <https://www.espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_en.pdf>`__, chapter IO_MUX and GPIO Matrix.
|
||||
For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`__, chapter IO_MUX and GPIO Matrix.
|
||||
|
||||
Being in the same ``blink.c`` project as before, set two breakpoints right after ``gpio_set_level`` instruction. Click "Memory" tab and then "Add Memory Monitor" button. Enter ``0x3FF44004`` in provided dialog.
|
||||
|
||||
|
|
@ -522,13 +516,7 @@ Displaying the contents of memory is done with command ``x``. With additional pa
|
|||
|
||||
We will demonstrate how ``x`` and ``set`` work by reading from and writing to the memory location ``0x3FF44004`` labeled as ``GPIO_OUT_REG`` used to set and clear individual GPIO's.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual <https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`__, chapter IO_MUX and GPIO Matrix.
|
||||
|
||||
.. only:: esp32s2beta
|
||||
|
||||
For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual <https://www.espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_en.pdf>`__, chapter IO_MUX and GPIO Matrix.
|
||||
For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`__, chapter IO_MUX and GPIO Matrix.
|
||||
|
||||
Being in the same ``blink.c`` project as before, set two breakpoints right after ``gpio_set_level`` instruction. Enter two times ``c`` to get to the break point followed by ``x /1wx 0x3FF44004`` to display contents of ``GPIO_OUT_REG`` memory location::
|
||||
|
||||
|
|
|
|||
|
|
@ -175,7 +175,7 @@ A code example showing how to use these functions can be found in :example:`peri
|
|||
Interrupt Handling
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
During driver installation, an interrupt handler is installed by default. However, you can register your own interrupt handler instead of the default one by calling the function :cpp:func:`i2c_isr_register`. When implementing your own interrupt handler, refer to the `ESP32 Technical Reference Manual <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf#page=292>`_ for the description of interrupts triggered by the I2C controller.
|
||||
During driver installation, an interrupt handler is installed by default. However, you can register your own interrupt handler instead of the default one by calling the function :cpp:func:`i2c_isr_register`. When implementing your own interrupt handler, refer to the `{IDF_TARGET_NAME} Technical Reference Manual (PDF) <{IDF_TARGET_TRM_EN_URL}>`_ for the description of interrupts triggered by the I2C controller.
|
||||
|
||||
To delete an interrupt handler, call :cpp:func:`i2c_isr_free`.
|
||||
|
||||
|
|
|
|||
|
|
@ -144,7 +144,7 @@ The advantage of high speed mode is glitch-free changeover of the timer settings
|
|||
The advantage of high speed mode is hardware-supported, glitch-free changeover of the timer settings. This means that if the timer settings are modified, the changes will be applied automatically on the next overflow interrupt of the timer. In contrast, when updating the low-speed timer, the change of settings should be explicitly triggered by software. The LEDC driver handles it in the background, e.g., when :cpp:func:`ledc_timer_config` or :cpp:func:`ledc_timer_set` is called.
|
||||
|
||||
|
||||
For additional details regarding speed modes, refer to `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_URL}>`_ (PDF). Please note that the support for ``SLOW_CLOCK`` mentioned in this manual is not yet supported in the LEDC driver.
|
||||
For additional details regarding speed modes, refer to `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_ (PDF). Please note that the support for ``SLOW_CLOCK`` mentioned in this manual is not yet supported in the LEDC driver.
|
||||
|
||||
.. only:: esp32s2
|
||||
|
||||
|
|
|
|||
|
|
@ -171,7 +171,7 @@ Examples of using MCPWM for motor control: :example:`peripherals/mcpwm`:
|
|||
* Brushed DC motor control - :example:`peripherals/mcpwm/mcpwm_brushed_dc_control`
|
||||
* Servo motor control - :example:`peripherals/mcpwm/mcpwm_servo_control`
|
||||
|
||||
.. _{IDF_TARGET_NAME} Technical Reference Manual: {IDF_TARGET_TRM_URL}
|
||||
.. _{IDF_TARGET_NAME} Technical Reference Manual: {IDF_TARGET_TRM_EN_URL}
|
||||
|
||||
|
||||
API Reference
|
||||
|
|
|
|||
|
|
@ -217,7 +217,7 @@ To resolve the conflict, you have the following options:
|
|||
|
||||
If running from an automated flashing script, ``espefuse.py`` has an option ``--do-not-confirm``.
|
||||
|
||||
For more details, see the `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_URL}>`_ (PDF).
|
||||
For more details, see the `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_ (PDF).
|
||||
|
||||
2. **If using 1-bit SD mode or SPI mode**, disconnect the DAT2 pin and make sure it is pulled high. For this, do one the following:
|
||||
|
||||
|
|
|
|||
|
|
@ -232,7 +232,7 @@ The UART controller supports a number of communication modes. A mode can be sele
|
|||
Using Interrupts
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
There are many interrupts that can be generated following specific UART states or detected errors. The full list of available interrupts is provided in the SoC Technical Reference Manual. You can enable or disable specific interrupts by calling :cpp:func:`uart_enable_intr_mask` or :cpp:func:`uart_disable_intr_mask` respectively. The mask of all interrupts is available as :c:macro:`UART_INTR_MASK`.
|
||||
There are many interrupts that can be generated following specific UART states or detected errors. The full list of available interrupts is provided `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_ (PDF).. You can enable or disable specific interrupts by calling :cpp:func:`uart_enable_intr_mask` or :cpp:func:`uart_disable_intr_mask` respectively. The mask of all interrupts is available as :c:macro:`UART_INTR_MASK`.
|
||||
|
||||
By default, the :cpp:func:`uart_driver_install` function installs the driver's internal interrupt handler to manage the Tx and Rx ring buffers and provides high-level API functions like events (see below). It is also possible to register a lower level interrupt handler instead using :cpp:func:`uart_isr_register`, and to free it again using :cpp:func:`uart_isr_free`. Some UART driver functions which use the Tx and Rx ring buffers, events, etc. will not automatically work in this case - it is necessary to handle the interrupts directly in the ISR. Inside the custom handler implementation, clear the interrupt status bits using :cpp:func:`uart_clear_intr_status`.
|
||||
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ Some of system parameters are using these eFuse bits directly by hardware module
|
|||
|
||||
.. only:: esp32
|
||||
|
||||
For more details see `ESP32 Technical Reference Manual <https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`_ in part 20 eFuse controller. Some eFuse bits are available for user applications.
|
||||
For more details see `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_ in part 20 eFuse controller. Some eFuse bits are available for user applications.
|
||||
|
||||
ESP32 has 4 eFuse blocks each of the size of 256 bits (not all bits are available):
|
||||
|
||||
|
|
@ -27,7 +27,7 @@ Some of system parameters are using these eFuse bits directly by hardware module
|
|||
|
||||
.. only:: esp32s2
|
||||
|
||||
For more details see `ESP32-S2 Technical Reference Manual <https://www.espressif.com/sites/default/files/documentation/esp32s2_technical_reference_manual_en.pdf>`_. Some eFuse bits are available for user applications.
|
||||
For more details see `{IDF_TARGET_NAME} Technical Reference Manual <{IDF_TARGET_TRM_EN_URL}>`_. Some eFuse bits are available for user applications.
|
||||
|
||||
{IDF_TARGET_NAME} has 11 eFuse blocks each of the size of 256 bits (not all bits are available):
|
||||
|
||||
|
|
|
|||
|
|
@ -127,7 +127,7 @@ There is couple of tips, how you can make your documentation even better and mor
|
|||
5. Use markdown to make your documentation even more readable. You will add headers, links, tables and more. ::
|
||||
|
||||
*
|
||||
* [ESP32 Technical Reference Manual](https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf)
|
||||
* [{IDF_TARGET_NAME} Technical Reference Manual]({IDF_TARGET_TRM_EN_URL})
|
||||
*
|
||||
|
||||
.. note::
|
||||
|
|
|
|||
|
|
@ -6,8 +6,7 @@
|
|||
.. toctree::
|
||||
:maxdepth: 3
|
||||
|
||||
:esp32: Technical Reference Manual (PDF) <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>
|
||||
:esp32s2beta: Technical Reference Manual (PDF) <https://espressif.com/sites/default/files/documentation/esp32s2_technical_reference_manual_en.pdf>
|
||||
Technical Reference Manual (PDF) <{IDF_TARGET_TRM_EN_URL}>
|
||||
:esp32: Datasheet (PDF) <https://espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>
|
||||
:esp32s2: Datasheet (PDF) <https://espressif.com/sites/default/files/documentation/esp32s2_datasheet_en.pdf>
|
||||
:esp32: Hardware Design Guidelines (PDF) <https://espressif.com/sites/default/files/documentation/esp32_hardware_design_guidelines_en.pdf>
|
||||
|
|
|
|||
|
|
@ -4,17 +4,9 @@ Flash Encryption
|
|||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
.. only:: esp32
|
||||
This document provides introduction to Flash encryption concept on {IDF_TARGET_NAME} and demonstrates how this feature can be used during development as well as production by the user using a sample example. The primary intention of the document is to act as a quick start guide to test and verify flash encryption operations. The details of the flash encryption block can be found in the `{IDF_TARGET_NAME} Technical reference manual`_.
|
||||
|
||||
This document provides introduction to Flash encryption concept on {IDF_TARGET_NAME} and demonstrates how this feature can be used during development as well as production by the user using a sample example. The primary intention of the document is to act as a quick start guide to test and verify flash encryption operations. The details of the flash encryption block can be found in the `ESP32 Technical reference manual`_.
|
||||
|
||||
.. _ESP32 Technical Reference Manual: https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf
|
||||
|
||||
.. only:: esp32s2beta
|
||||
|
||||
This document provides introduction to Flash encryption concept on {IDF_TARGET_NAME} and demonstrates how this feature can be used during development as well as production by the user using a sample example. The primary intention of the document is to act as a quick start guide to test and verify flash encryption operations. The details of the flash encryption block can be found in the `ESP32-S2 Technical reference manual`_.
|
||||
|
||||
.. _ESP32-S2 Technical Reference Manual: https://www.espressif.com/sites/default/files/documentation/esp32s2_technical_reference_manual_en.pdf
|
||||
.. _{IDF_TARGET_NAME} Technical Reference Manual: {IDF_TARGET_TRM_EN_URL}
|
||||
|
||||
|
||||
Introduction
|
||||
|
|
|
|||
|
|
@ -4,9 +4,13 @@ TARGET_NAMES = {'esp32': 'ESP32', 'esp32s2': 'ESP32-S2'}
|
|||
TOOLCHAIN_NAMES = {'esp32': 'esp', 'esp32s2': 'esp32s2'}
|
||||
CONFIG_PREFIX = {'esp32': 'ESP32', 'esp32s2': 'ESP32S2'}
|
||||
|
||||
TRM_URL = {'esp32': 'https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf',
|
||||
TRM_EN_URL = {'esp32': 'https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf',
|
||||
'esp32s2': 'https://www.espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_en.pdf'}
|
||||
|
||||
TRM_CN_URL = {'esp32': 'https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_cn.pdf',
|
||||
'esp32s2': 'https://www.espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_cn.pdf'}
|
||||
|
||||
|
||||
class StringSubstituter:
|
||||
""" Allows for string substitution of target related strings
|
||||
before any markup is parsed
|
||||
|
|
@ -16,7 +20,8 @@ class StringSubstituter:
|
|||
{IDF_TARGET_PATH_NAME}, replaced with the path name, e.g. esp32s2
|
||||
{IDF_TARGET_TOOLCHAIN_NAME}, replaced with the toolchain name, e.g. esp32s2
|
||||
{IDF_TARGET_CFG_PREFIX}, replaced with the prefix used for config parameters, e.g. ESP32S2
|
||||
{IDF_TARGET_TRM_URL}, replaced with the url to the technical reference manual
|
||||
{IDF_TARGET_TRM_EN_URL}, replaced with the url to the English technical reference manual
|
||||
{IDF_TARGET_TRM_CH_URL}, replaced with the url to the Chinese technical reference manual
|
||||
|
||||
Also supports defines of local (single rst file) with the format:
|
||||
{IDF_TARGET_TX_PIN:default="IO3",esp32="IO4",esp32s2="IO5"}
|
||||
|
|
@ -40,7 +45,8 @@ class StringSubstituter:
|
|||
self.add_pair("{IDF_TARGET_PATH_NAME}", config.idf_target)
|
||||
self.add_pair("{IDF_TARGET_TOOLCHAIN_NAME}", TOOLCHAIN_NAMES[config.idf_target])
|
||||
self.add_pair("{IDF_TARGET_CFG_PREFIX}", CONFIG_PREFIX[config.idf_target])
|
||||
self.add_pair("{IDF_TARGET_TRM_URL}", TRM_URL[config.idf_target])
|
||||
self.add_pair("{IDF_TARGET_TRM_EN_URL}", TRM_EN_URL[config.idf_target])
|
||||
self.add_pair("{IDF_TARGET_TRM_CN_URL}", TRM_CN_URL[config.idf_target])
|
||||
|
||||
def add_local_subs(self, matches):
|
||||
|
||||
|
|
|
|||
|
|
@ -155,14 +155,7 @@
|
|||
|
||||
在 “Memory” 选项卡下，我们将在内存地址 ``0x3FF44004`` 处读取和写入内容。该地址也是 ``GPIO_OUT_REG`` 寄存器的地址，可以用来控制（设置或者清除）某个 GPIO 的电平。
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
关于该寄存器的更多详细信息，请参阅 `ESP32 技术参考手册 <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_cn.pdf>`_ 中的 IO_MUX 和 GPIO Matrix 章节。
|
||||
|
||||
.. only:: esp32s2beta
|
||||
|
||||
关于该寄存器的更多详细信息，请参阅 `ESP32-S2 技术参考手册 <https://espressif.com/sites/default/files/documentation/esp32s2_technical_reference_manual_cn.pdf>`_ 中的 IO_MUX 和 GPIO Matrix 章节。
|
||||
|
||||
关于该寄存器的更多详细信息，请参阅 `{IDF_TARGET_NAME} 技术参考手册 <{IDF_TARGET_TRM_CN_URL}>`_ 中的 IO_MUX 和 GPIO Matrix 章节。
|
||||
|
||||
同样在 ``blink.c`` 项目文件中，在两个 ``gpio_set_level`` 语句的后面各设置一个断点，单击 “Memory” 选项卡，然后单击 “Add Memory Monitor” 按钮，在弹出的对话框中输入 ``0x3FF44004``。
|
||||
|
||||
|
|
@ -521,7 +514,7 @@
|
|||
|
||||
使用命令 ``x`` 可以显示内存的内容，配合其余参数还可以调整所显示内存位置的格式和数量。运行 ``help x`` 可以查看更多相关细节。与 ``x`` 命令配合使用的命令是 ``set``，它允许你将值写入内存。
|
||||
|
||||
为了演示 ``x`` 和 ``set`` 的使用，我们将在内存地址 ``0x3FF44004`` 处读取和写入内容。该地址也是 ``GPIO_OUT_REG`` 寄存器的地址，可以用来控制（设置或者清除）某个 GPIO 的电平。关于该寄存器的更多详细信息，请参阅 `ESP32 技术参考手册 <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_cn.pdf>`_ 中的 IO_MUX 和 GPIO Matrix章节。
|
||||
为了演示 ``x`` 和 ``set`` 的使用，我们将在内存地址 ``0x3FF44004`` 处读取和写入内容。该地址也是 ``GPIO_OUT_REG`` 寄存器的地址，可以用来控制（设置或者清除）某个 GPIO 的电平。关于该寄存器的更多详细信息，请参阅 `{IDF_TARGET_NAME} 技术参考手册 <{IDF_TARGET_TRM_CN_URL}>`_ 中的 IO_MUX 和 GPIO Matrix章节。
|
||||
|
||||
同样在 ``blink.c`` 项目文件中，在两个 ``gpio_set_level`` 语句的后面各设置一个断点。输入两次 ``c`` 命令后停止在断点处，然后输入 ``x /1wx 0x3FF44004`` 来显示 ``GPIO_OUT_REG`` 寄存器的值::
|
||||
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@
|
|||
|
||||
ESP32 可支持最多 10 个电容式触摸板/GPIO，触摸板可以以矩阵或滑条等方式组合使用，从而覆盖更大触感区域及更多触感点。触摸传感由有限状态机 (FSM) 硬件控制，由软件或专用硬件计时器发起。
|
||||
|
||||
如需了解触摸传感器设计、操作及其控制寄存器等相关信息，请参考《`ESP32 技术参考手册 <https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_cn.pdf>`_》(PDF)，您也可以在《ESP32 技术参考手册》中查看这一子系统是如何运行的。
|
||||
如需了解触摸传感器设计、操作及其控制寄存器等相关信息，请参考《`{IDF_TARGET_NAME} 技术参考手册 <{IDF_TARGET_TRM_CN_URL}>`_》(PDF)，您也可以在《ESP32 技术参考手册》中查看这一子系统是如何运行的。
|
||||
|
||||
请参考 `触摸传感器应用方案简介 <https://github.com/espressif/esp-iot-solution/blob/master/documents/touch_pad_solution/touch_sensor_design_cn.md>`_，查看触摸传感器设计详情和固件开发指南。如果不想亲自在多种配置环境下测试触摸传感器，请查看 `ESP32 触摸功能开发套件 <https://github.com/espressif/esp-iot-solution/blob/master/documents/evaluation_boards/esp32_sense_kit_guide_cn.md>`_。
|
||||
|
||||
|
|
|
|||
|
|
@ -126,7 +126,7 @@ Doxygen 支持多种排版风格，对于文档中可以包含的细节非常灵
|
|||
5. 使用 markdown 增强文档可读性，添加页眉、链接、表格及更多内容。 ::
|
||||
|
||||
*
|
||||
* [ESP32 技术参考手册](https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_cn.pdf)
|
||||
* [{IDF_TARGET_NAME} 技术参考手册]({IDF_TARGET_TRM_CN_URL})
|
||||
*
|
||||
|
||||
.. note::
|
||||
|
|
|
|||
|
|
@ -6,8 +6,7 @@ ESP32 H/W 硬件参考
|
|||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
:esp32: ESP32 技术参考手册 (PDF) <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_cn.pdf>
|
||||
:esp32s2beta: ESP32-S2 技术参考手册 (PDF) <https://espressif.com/sites/default/files/documentation/esp32s2_technical_reference_manual_cn.pdf>
|
||||
{IDF_TARGET_NAME} 技术参考手册 (PDF) <{IDF_TARGET_TRM_CN_URL}>
|
||||
:esp32: ESP32 技术规格书 (PDF) <https://espressif.com/sites/default/files/documentation/esp32_datasheet_cn.pdf>
|
||||
:esp32s2: ESP32-S2 技术规格书 (PDF) <https://espressif.com/sites/default/files/documentation/esp32s2_datasheet_cn.pdf>
|
||||
:esp32: ESP32 硬件设计指南 (PDF) <https://espressif.com/sites/default/files/documentation/esp32_hardware_design_guidelines_cn.pdf>
|
||||
|
|
|
|||
|
|
@ -4,14 +4,14 @@ Flash 加密
|
|||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
本文档将介绍 ESP32 的 Flash 加密功能，并通过示例展示用户如何在开发及生产过程中使用此功能。本文档旨在引导用户快速入门如何测试及验证 Flash 加密的相关操作。有关 Flash 加密块的详细信息可参见 `ESP32 技术参考手册`_。
|
||||
本文档将介绍 {IDF_TARGET_NAME} 的 Flash 加密功能，并通过示例展示用户如何在开发及生产过程中使用此功能。本文档旨在引导用户快速入门如何测试及验证 Flash 加密的相关操作。有关 Flash 加密块的详细信息可参见 `{IDF_TARGET_NAME} 技术参考手册`_。
|
||||
|
||||
.. _ESP32 技术参考手册: https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_cn.pdf
|
||||
.. _{IDF_TARGET_NAME} 技术参考手册: {IDF_TARGET_TRM_CN_URL}
|
||||
|
||||
概述
|
||||
------
|
||||
|
||||
Flash 加密功能用于加密与 ESP32 搭载使用的 SPI Flash 中的内容。启用 Flash 加密功能后，物理读取 SPI Flash 便无法恢复大部分 Flash 内容。通过明文数据烧录 ESP32 可应用加密功能，（若已启用加密功能）引导加载程序会在首次启动时对数据进行加密。
|
||||
Flash 加密功能用于加密与 {IDF_TARGET_NAME} 搭载使用的 SPI Flash 中的内容。启用 Flash 加密功能后，物理读取 SPI Flash 便无法恢复大部分 Flash 内容。通过明文数据烧录 {IDF_TARGET_NAME} 可应用加密功能，（若已启用加密功能）引导加载程序会在首次启动时对数据进行加密。
|
||||
|
||||
启用 Flash 加密后，系统将默认加密下列类型的 Flash 数据：
|
||||
|
||||
|
|
@ -27,13 +27,13 @@ Flash 加密功能用于加密与 ESP32 搭载使用的 SPI Flash 中的内容
|
|||
Flash 加密与 :doc:`安全启动<secure-boot>` 功能各自独立，您可以在关闭安全启动的状态下使用 Flash 加密。但是，为了安全的计算机环境，二者应同时使用。在关闭安全启动的状态下，需运行其他配置来确保 Flash 加密的有效性。详细信息可参见 :ref:`flash-encryption-without-secure-boot`。
|
||||
|
||||
.. important::
|
||||
启用 Flash 加密将限制后续 ESP32 更新。请务必阅读本文档（包括 :ref:`flash-encryption-limitations`）了解启用 Flash 加密的影响。
|
||||
启用 Flash 加密将限制后续 {IDF_TARGET_NAME} 更新。请务必阅读本文档（包括 :ref:`flash-encryption-limitations`）了解启用 Flash 加密的影响。
|
||||
|
||||
.. _flash-encryption-efuse:
|
||||
|
||||
Flash 加密过程中使用的 eFuse
|
||||
------------------------------
|
||||
Flash 加密操作由 ESP32 上的多个 eFuse 控制。以下是这些 eFuse 列表及其描述：
|
||||
Flash 加密操作由 {IDF_TARGET_NAME} 上的多个 eFuse 控制。以下是这些 eFuse 列表及其描述：
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -68,7 +68,7 @@ Flash 加密操作由 ESP32 上的多个 eFuse 控制。以下是这些 eFuse
|
|||
奇数位（1，3，5，7）：
|
||||
启动时不加密 Flash
|
||||
|
||||
对上述位的读写访问由 ``efuse_wr_disable`` 和 ``efuse_rd_disable`` 寄存器中的相应位控制。有关 ESP32 eFuse 的详细信息可参见 :doc:`eFuse 管理器 <../api-reference/system/efuse>`。
|
||||
对上述位的读写访问由 ``efuse_wr_disable`` 和 ``efuse_rd_disable`` 寄存器中的相应位控制。有关 {IDF_TARGET_NAME} eFuse 的详细信息可参见 :doc:`eFuse 管理器 <../api-reference/system/efuse>`。
|
||||
|
||||
Flash 的加密过程
|
||||
------------------
|
||||
|
|
@ -84,7 +84,7 @@ Flash 的加密过程
|
|||
- 在 :ref:`flash_enc_development_mode` 下，第二阶段引导加载程序将仅改写 ``download_dis_decrypt`` 和 ``download_dis_cache`` 的 eFuse 位，从而允许 UART 引导加载程序重新烧录加密的二进制文件。同时将不会写保护 ``FLASH_CRYPT_CNT`` 的 eFuse 位。
|
||||
- 然后，第二阶段引导加载程序重启设备并开始执行加密映像，同时将透明解密 Flash 的内容并将其加载至 IRAM。
|
||||
|
||||
在开发阶段常需编写不同的明文 Flash 映像，以及测试 Flash 的加密过程。这要求 UART 下载模式能够根据需求不断加载新的明文映像。但是，在量产和生产过程中，出于安全考虑，UART 下载模式不应有权限访问 Flash 内容。因此需要有两种不同的 ESP32 配置：一种用于开发，另一种用于生产。以下章节介绍了 Flash 加密的 :ref:`flash_enc_development_mode` 和 :ref:`flash_enc_release_mode` 及其使用指南。
|
||||
在开发阶段常需编写不同的明文 Flash 映像，以及测试 Flash 的加密过程。这要求 UART 下载模式能够根据需求不断加载新的明文映像。但是，在量产和生产过程中，出于安全考虑，UART 下载模式不应有权限访问 Flash 内容。因此需要有两种不同的 {IDF_TARGET_NAME} 配置：一种用于开发，另一种用于生产。以下章节介绍了 Flash 加密的 :ref:`flash_enc_development_mode` 和 :ref:`flash_enc_release_mode` 及其使用指南。
|
||||
|
||||
.. important::
|
||||
顾名思义，开发模式应 **仅开发过程** 使用，因为该模式可以修改和回读加密的 Flash 内容。
|
||||
|
|
@ -97,14 +97,14 @@ Flash 的加密过程
|
|||
开发模式
|
||||
^^^^^^^^^^
|
||||
|
||||
可使用 ESP32 内部生成的密钥或外部主机生成的密钥在开发中运行 Flash 加密。
|
||||
可使用 {IDF_TARGET_NAME} 内部生成的密钥或外部主机生成的密钥在开发中运行 Flash 加密。
|
||||
|
||||
使用 ESP32 生成的 Flash 加密密钥
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
使用 {IDF_TARGET_NAME} 生成的 Flash 加密密钥
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
正如上文所说，:ref:`flash_enc_development_mode` 允许用户使用 UART 下载模式多次下载明文映像。需完成以下步骤测试 Flash 加密过程：
|
||||
|
||||
- 确保您的 ESP32 设备有 :ref:`flash-encryption-efuse` 中所示的 Flash 加密 eFuse 的默认设置。
|
||||
- 确保您的 {IDF_TARGET_NAME} 设备有 :ref:`flash-encryption-efuse` 中所示的 Flash 加密 eFuse 的默认设置。
|
||||
|
||||
- 可在 ``$IDF_PATH/examples/security/flash_encryption`` 文件夹中找到 Flash 加密的示例应用程序。该示例应用程序中有显示 Flash 加密的状态（启用或关闭）以及 ``FLASH_CRYPT_CNT`` eFuse 值。
|
||||
|
||||
|
|
@ -126,7 +126,7 @@ Flash 的加密过程
|
|||
|
||||
idf.py flash monitor
|
||||
|
||||
一旦烧录完成，设备将重置，在下次启动时，第二阶段引导加载程序将加密 Flash 的 app 分区，然后重置该分区。现在，示例应用程序将在运行时解密并执行命令。以下是首次启用 Flash 加密后 ESP32 启动时的样例输出。
|
||||
一旦烧录完成，设备将重置，在下次启动时，第二阶段引导加载程序将加密 Flash 的 app 分区，然后重置该分区。现在，示例应用程序将在运行时解密并执行命令。以下是首次启用 Flash 加密后 {IDF_TARGET_NAME} 启动时的样例输出。
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -248,7 +248,7 @@ Flash 的加密过程
|
|||
I (211) cpu_start: ELF file SHA256: 8770c886bdf561a7...
|
||||
I (217) cpu_start: ESP-IDF: v4.0-dev-850-gc4447462d-dirty
|
||||
I (224) cpu_start: Starting app cpu, entry point is 0x40080e4c
|
||||
0x40080e4c: call_start_cpu1 at esp-idf/esp-idf/components/esp32/cpu_start.c:265
|
||||
0x40080e4c: call_start_cpu1 at esp-idf/esp-idf/components/{IDF_TARGET_PATH_NAME}/cpu_start.c:265
|
||||
|
||||
I (0) cpu_start: App cpu up.
|
||||
I (235) heap_init: Initializing. RAM available for dynamic allocation:
|
||||
|
|
@ -262,7 +262,7 @@ Flash 的加密过程
|
|||
I (0) cpu_start: Starting scheduler on APP CPU.
|
||||
|
||||
Sample program to check Flash Encryption
|
||||
This is ESP32 chip with 2 CPU cores, WiFi/BT/BLE, silicon revision 1, 4MB external flash
|
||||
This is {IDF_TARGET_NAME} chip with 2 CPU cores, WiFi/BT/BLE, silicon revision 1, 4MB external flash
|
||||
Flash encryption feature is enabled
|
||||
Flash encryption mode is DEVELOPMENT
|
||||
Flash in encrypted mode with flash_crypt_cnt = 1
|
||||
|
|
@ -290,15 +290,15 @@ Flash 的加密过程
|
|||
使用主机生成的 Flash 加密密钥
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
可在主机中预生成 Flash 加密密钥，并将其烧录到 ESP32 的 eFuse 密钥块中。这样，无需明文 Flash 更新便可以在主机上预加密数据并将其烧录到 ESP32 中。该功能允许在 :ref:`flash_enc_development_mode` 和 :ref:`flash_enc_release_mode` modes 两模式下加密烧录。
|
||||
可在主机中预生成 Flash 加密密钥，并将其烧录到 {IDF_TARGET_NAME} 的 eFuse 密钥块中。这样，无需明文 Flash 更新便可以在主机上预加密数据并将其烧录到 {IDF_TARGET_NAME} 中。该功能允许在 :ref:`flash_enc_development_mode` 和 :ref:`flash_enc_release_mode` modes 两模式下加密烧录。
|
||||
|
||||
- 确保您的 ESP32 设备有 :ref:`flash-encryption-efuse` 中所示 Flash 加密 eFuse 的默认设置。
|
||||
- 确保您的 {IDF_TARGET_NAME} 设备有 :ref:`flash-encryption-efuse` 中所示 Flash 加密 eFuse 的默认设置。
|
||||
|
||||
- 使用 espsecure.py 随机生成一个密钥::
|
||||
|
||||
espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin
|
||||
|
||||
- 将该密钥烧录到设备上（一次性）。 **该步骤须在第一次加密启动前完成**，否则 ESP32 将随机生成一个软件无权限访问或修改的密钥::
|
||||
- 将该密钥烧录到设备上（一次性）。 **该步骤须在第一次加密启动前完成**，否则 {IDF_TARGET_NAME} 将随机生成一个软件无权限访问或修改的密钥::
|
||||
|
||||
espefuse.py --port PORT burn_key flash_encryption my_flash_encryption_key.bin
|
||||
|
||||
|
|
@ -337,7 +337,7 @@ Flash 的加密过程
|
|||
|
||||
在释放模式下，UART 引导加载程序无法执行 Flash 加密操作，**只能** 使用 OTA 方案下载新的明文映像，该方案将在写入 Flash 前加密明文映像。
|
||||
|
||||
- 确保您的 ESP32 设备有 :ref:`flash-encryption-efuse` 中所示 Flash 加密 eFuse 的默认设置。
|
||||
- 确保您的 {IDF_TARGET_NAME} 设备有 :ref:`flash-encryption-efuse` 中所示 Flash 加密 eFuse 的默认设置。
|
||||
|
||||
- 在第二阶段引导加载程序中启用 Flash 加密支持。请前往 :ref:`project-configuration-menu`，选择 “Security Features”。
|
||||
|
||||
|
|
@ -366,7 +366,7 @@ Flash 的加密过程
|
|||
可能出现的错误
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
启用 Flash 加密后，如果 ``FLASH_CRYPT_CNT`` eFuse 值中有奇数位，则所有（标有加密标志的）分区都应包含加密密文。以下为 ESP32 加载明文数据会产生的三种典型错误情况：
|
||||
启用 Flash 加密后，如果 ``FLASH_CRYPT_CNT`` eFuse 值中有奇数位，则所有（标有加密标志的）分区都应包含加密密文。以下为 {IDF_TARGET_NAME} 加载明文数据会产生的三种典型错误情况：
|
||||
|
||||
1. 如果通过明文引导加载程序映像重新更新了引导加载程序分区，则 ROM 加载器将无法加载 引导加载程序，并会显示以下错误类型：
|
||||
|
||||
|
|
@ -459,7 +459,7 @@ Flash 加密的要点
|
|||
|
||||
- `flash 加密算法` 采用的是 AES-256，其中密钥随着 Flash 的每个 32 字节块的偏移地址“调整”。这意味着，每个 32 字节块（2 个连续的 16 字节 AES 块）使用从 Flash 加密密钥中产生的一个特殊密钥进行加密。
|
||||
|
||||
- 通过 ESP32 的 Flash 缓存映射功能，Flash 可支持透明访问——读取任何映射到地址空间的 Flash 区域时，都将透明解密该区域。
|
||||
- 通过 {IDF_TARGET_NAME} 的 Flash 缓存映射功能，Flash 可支持透明访问——读取任何映射到地址空间的 Flash 区域时，都将透明解密该区域。
|
||||
|
||||
为便于访问，某些数据分区最好保持未加密状态，或者也可使用对已加密数据无效的 Flash 友好型更新算法。由于 NVS 库无法与 Flash 加密直接兼容，因此无法加密非易失性存储器的 NVS 分区。详情可参见 :ref:`NVS 加密 <nvs_encryption>`。
|
||||
|
||||
|
|
@ -470,14 +470,14 @@ Flash 加密的要点
|
|||
.. note:: 同时启用安全启动和 Flash 加密后，引导加载程序 app 二进制文件 ``bootloader.bin`` 可能会过大。参见 :ref:`secure-boot-bootloader-size`。
|
||||
|
||||
.. important::
|
||||
在首次启动加密过程中，请勿中断 ESP32 的电源。如果电源中断，Flash 的内容将受到破坏，并需要重新烧录未加密数据。而这类重新烧录将不计入烧录限制次数。
|
||||
在首次启动加密过程中，请勿中断 {IDF_TARGET_NAME} 的电源。如果电源中断，Flash 的内容将受到破坏，并需要重新烧录未加密数据。而这类重新烧录将不计入烧录限制次数。
|
||||
|
||||
.. _using-encrypted-flash:
|
||||
|
||||
使用加密的 Flash
|
||||
-------------------
|
||||
|
||||
ESP32 app 代码可通过调用函数 :cpp:func:`esp_flash_encryption_enabled` 来确认当前是否已启用 Flash 加密。同时，设备可通过调用函数 :cpp:func:`esp_get_flash_encryption_mode` 来识别使用的 Flash 加密模式。
|
||||
{IDF_TARGET_NAME} app 代码可通过调用函数 :cpp:func:`esp_flash_encryption_enabled` 来确认当前是否已启用 Flash 加密。同时，设备可通过调用函数 :cpp:func:`esp_get_flash_encryption_mode` 来识别使用的 Flash 加密模式。
|
||||
|
||||
启用 Flash 加密后，使用代码访问 Flash 内容时需加注意。
|
||||
|
||||
|
|
@ -533,7 +533,7 @@ OTA 更新
|
|||
关闭 Flash 加密
|
||||
-----------------
|
||||
|
||||
若因某些原因意外启用了 Flash 加密，则接下来烧录明文数据时将使 ESP32 软砖（设备不断重启，并报错 ``flash read err, 1000``）。
|
||||
若因某些原因意外启用了 Flash 加密，则接下来烧录明文数据时将使 {IDF_TARGET_NAME} 软砖（设备不断重启，并报错 ``flash read err, 1000``）。
|
||||
|
||||
可通过写入 ``FLASH_CRYPT_CNT`` eFuse 再次关闭 Flash 加密（仅适用于开发模式下）：
|
||||
|
||||
|
|
@ -545,7 +545,7 @@ OTA 更新
|
|||
|
||||
espefuse.py burn_efuse FLASH_CRYPT_CNT
|
||||
|
||||
重置 ESP32，Flash 加密应处于关闭状态，引导加载程序将正常启动。
|
||||
重置 {IDF_TARGET_NAME}，Flash 加密应处于关闭状态，引导加载程序将正常启动。
|
||||
|
||||
.. _flash-encryption-limitations:
|
||||
|
||||
|
|
@ -572,7 +572,7 @@ Flash 加密与安全启动
|
|||
推荐搭配使用 Flash 加密与安全启动。但是，如果已启用安全启动，则重新烧录设备时会受到其他限制：
|
||||
|
||||
- :ref:`updating-encrypted-flash-ota` 不受限制（如果新的 app 已使用安全启动签名密钥进行正确签名）。
|
||||
- 只有当选择 :ref:`可再次烧录 <CONFIG_SECURE_BOOTLOADER_MODE>` 安全启动模式，且安全启动密钥已预生成并烧录至 ESP32（可参见 :ref:`安全启动 <secure-boot-reflashable>`），则 :ref:`明文串行 flash 更新 <updating-encrypted-flash-serial>` 可实现。在该配置下，``idf.py bootloader`` 将生成简化的引导加载程序和安全启动摘要文件，用于在偏移量 0x0 处进行烧录。当进行明文串行重新烧录步骤时，须在烧录其他明文数据前重新烧录此文件。
|
||||
- 只有当选择 :ref:`可再次烧录 <CONFIG_SECURE_BOOTLOADER_MODE>` 安全启动模式，且安全启动密钥已预生成并烧录至 {IDF_TARGET_NAME}（可参见 :ref:`安全启动 <secure-boot-reflashable>`），则 :ref:`明文串行 flash 更新 <updating-encrypted-flash-serial>` 可实现。在该配置下，``idf.py bootloader`` 将生成简化的引导加载程序和安全启动摘要文件，用于在偏移量 0x0 处进行烧录。当进行明文串行重新烧录步骤时，须在烧录其他明文数据前重新烧录此文件。
|
||||
- 假设未重新烧录引导加载程序，:ref:`使用预生成的 Flash 加密密钥重新烧录 <pregenerated-flash-encryption-key>` 仍可实现。重新烧录引导加载程序时，需在安全启动配置中启用相同的 :ref:`可重新烧录 <CONFIG_SECURE_BOOTLOADER_MODE>` 选项。
|
||||
|
||||
.. _flash-encryption-without-secure-boot:
|
||||
|
|
|
|||
Loading…
Reference in a new issue