From 268816649c41a2cbf0abca6b60e5f2d9bdaf80fa Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Thu, 19 Dec 2019 12:16:25 +0800 Subject: [PATCH] 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 --- .../jtag-debugging/debugging-examples.rst | 16 +-- docs/en/api-reference/peripherals/i2c.rst | 2 +- docs/en/api-reference/peripherals/ledc.rst | 2 +- docs/en/api-reference/peripherals/mcpwm.rst | 2 +- .../peripherals/sd_pullup_requirements.rst | 2 +- docs/en/api-reference/peripherals/uart.rst | 2 +- docs/en/api-reference/system/efuse.rst | 4 +- docs/en/contribute/documenting-code.rst | 28 +++--- docs/en/hw-reference/index.rst | 3 +- docs/en/security/flash-encryption.rst | 12 +-- docs/idf_extensions/format_idf_target.py | 12 ++- .../jtag-debugging/debugging-examples.rst | 11 +-- .../api-reference/peripherals/touch_pad.rst | 8 +- docs/zh_CN/contribute/documenting-code.rst | 24 ++--- docs/zh_CN/hw-reference/index.rst | 3 +- docs/zh_CN/security/flash-encryption.rst | 98 +++++++++---------- 16 files changed, 103 insertions(+), 126 deletions(-) diff --git a/docs/en/api-guides/jtag-debugging/debugging-examples.rst b/docs/en/api-guides/jtag-debugging/debugging-examples.rst index 8f2954bee..9448f412d 100644 --- a/docs/en/api-guides/jtag-debugging/debugging-examples.rst +++ b/docs/en/api-guides/jtag-debugging/debugging-examples.rst @@ -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 `__, chapter IO_MUX and GPIO Matrix. - -.. only:: esp32s2beta - - For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual `__, 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 `__, chapter IO_MUX and GPIO Matrix. - -.. only:: esp32s2beta - - For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual `__, 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:: diff --git a/docs/en/api-reference/peripherals/i2c.rst b/docs/en/api-reference/peripherals/i2c.rst index 0a4967871..9d72c333b 100644 --- a/docs/en/api-reference/peripherals/i2c.rst +++ b/docs/en/api-reference/peripherals/i2c.rst @@ -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 `_ 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`. diff --git a/docs/en/api-reference/peripherals/ledc.rst b/docs/en/api-reference/peripherals/ledc.rst index 492fe21c7..ea0d51e20 100644 --- a/docs/en/api-reference/peripherals/ledc.rst +++ b/docs/en/api-reference/peripherals/ledc.rst @@ -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 diff --git a/docs/en/api-reference/peripherals/mcpwm.rst b/docs/en/api-reference/peripherals/mcpwm.rst index 7ab6b657b..b17d5acdb 100644 --- a/docs/en/api-reference/peripherals/mcpwm.rst +++ b/docs/en/api-reference/peripherals/mcpwm.rst @@ -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 diff --git a/docs/en/api-reference/peripherals/sd_pullup_requirements.rst b/docs/en/api-reference/peripherals/sd_pullup_requirements.rst index 84e72a442..3485c8105 100644 --- a/docs/en/api-reference/peripherals/sd_pullup_requirements.rst +++ b/docs/en/api-reference/peripherals/sd_pullup_requirements.rst @@ -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: diff --git a/docs/en/api-reference/peripherals/uart.rst b/docs/en/api-reference/peripherals/uart.rst index f56373a8b..45b7953da 100644 --- a/docs/en/api-reference/peripherals/uart.rst +++ b/docs/en/api-reference/peripherals/uart.rst @@ -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`. diff --git a/docs/en/api-reference/system/efuse.rst b/docs/en/api-reference/system/efuse.rst index f50bda763..1a4ab011e 100644 --- a/docs/en/api-reference/system/efuse.rst +++ b/docs/en/api-reference/system/efuse.rst @@ -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 `_ 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 `_. 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): diff --git a/docs/en/contribute/documenting-code.rst b/docs/en/contribute/documenting-code.rst index dfd9d7613..57c02cde7 100644 --- a/docs/en/contribute/documenting-code.rst +++ b/docs/en/contribute/documenting-code.rst @@ -3,7 +3,7 @@ Documenting Code :link_to_translation:`zh_CN:[中文]` -The purpose of this description is to provide quick summary on documentation style used in `espressif/esp-idf`_ repository and how to add new documentation. +The purpose of this description is to provide quick summary on documentation style used in `espressif/esp-idf`_ repository and how to add new documentation. Introduction @@ -22,14 +22,14 @@ Typical comment block, that contains documentation of a function, looks like bel .. image:: ../../_static/doc-code-documentation-inline.png :align: center :alt: Sample inline code documentation - + Doxygen supports couple of formatting styles. It also gives you great flexibility on level of details to include in documentation. To get familiar with available features, please check data rich and very well organized `Doxygen Manual `_. Why we need it? --------------- -The ultimate goal is to ensure that all the code is consistently documented, so we can use tools like `Sphinx `_ and `Breathe `_ to aid preparation and automatic updates of API documentation when the code changes. +The ultimate goal is to ensure that all the code is consistently documented, so we can use tools like `Sphinx `_ and `Breathe `_ to aid preparation and automatic updates of API documentation when the code changes. With these tools the above piece of code renders like below: @@ -58,7 +58,7 @@ When writing code for this repository, please follow guidelines below. .. image:: ../../_static/doc-code-void-function.png :align: center :alt: Sample void function documented inline and after rendering - + 5. When documenting a ``define`` as well as members of a ``struct`` or ``enum``, place specific comment like below after each member. .. image:: ../../_static/doc-code-member.png @@ -75,7 +75,7 @@ When writing code for this repository, please follow guidelines below. * - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist * - other error codes from the underlying storage driver * - + 7. Overview of functionality of documented header file, or group of files that make a library, should be placed in the same directory in a separate ``README.rst`` file. If directory contains header files for different APIs, then the file name should be ``apiname-readme.rst``. @@ -118,7 +118,7 @@ There is couple of tips, how you can make your documentation even better and mor */ void first_similar_function (void); void second_similar_function (void); - /**@}*/ + /**@}*/ For practical example see :component_file:`nvs_flash/include/nvs.h`. @@ -127,14 +127,14 @@ 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:: Code snippets, notes, links, etc. will not make it to the documentation, if not enclosed in a comment block associated with one of documented objects. -6. Prepare one or more complete code examples together with description. Place description in a separate file ``README.md`` in specific folder of :idf:`examples` directory. +6. Prepare one or more complete code examples together with description. Place description in a separate file ``README.md`` in specific folder of :idf:`examples` directory. .. _link-custom-roles: @@ -199,9 +199,9 @@ The following types of diagrams are supported: * `Activity diagram `_ * `Logical network diagram `_ -With this suite of tools it is possible to generate beautiful diagram images from simple text format (similar to graphviz’s DOT format). The diagram elements are laid out automatically. The diagram code is then converted into ".png" graphics and integrated "behind the scenes" into **Sphinx** documents. +With this suite of tools it is possible to generate beautiful diagram images from simple text format (similar to graphviz’s DOT format). The diagram elements are laid out automatically. The diagram code is then converted into ".png" graphics and integrated "behind the scenes" into **Sphinx** documents. -For the diagram preparation you can use an on-line `interactive shell`_ that instantly shows the rendered image. +For the diagram preparation you can use an on-line `interactive shell`_ that instantly shows the rendered image. Below are couple of diagram examples: @@ -262,10 +262,10 @@ OK, but I am new to Sphinx! 3. You will likely want to see how documentation builds and looks like before posting it on the GitHub. There are two options to do so: * Install `Sphinx `_, `Breathe `_, `Blockdiag `_ and `Doxygen `_ to build it locally, see chapter below. - + * Set up an account on `Read the Docs `_ and build documentation in the cloud. Read the Docs provides document building and hosting for free and their service works really quick and great. -4. To preview documentation before building, use `Sublime Text `_ editor together with `OmniMarkupPreviewer `_ plugin. +4. To preview documentation before building, use `Sublime Text `_ editor together with `OmniMarkupPreviewer `_ plugin. .. _setup-for-building-documentation: @@ -348,13 +348,13 @@ Now you should be ready to build documentation by invoking:: make html -This may take couple of minutes. After completion, documentation will be placed in ``~/esp/esp-idf/docs/en/_build/html`` folder. To see it, open ``index.html`` in a web browser. +This may take couple of minutes. After completion, documentation will be placed in ``~/esp/esp-idf/docs/en/_build/html`` folder. To see it, open ``index.html`` in a web browser. Wrap up ------- -We love good code that is doing cool things. +We love good code that is doing cool things. We love it even better, if it is well documented, so we can quickly make it run and also do the cool things. Go ahead, contribute your code and documentation! diff --git a/docs/en/hw-reference/index.rst b/docs/en/hw-reference/index.rst index 7524a0202..6af93957d 100644 --- a/docs/en/hw-reference/index.rst +++ b/docs/en/hw-reference/index.rst @@ -6,8 +6,7 @@ .. toctree:: :maxdepth: 3 - :esp32: Technical Reference Manual (PDF) - :esp32s2beta: Technical Reference Manual (PDF) + Technical Reference Manual (PDF) <{IDF_TARGET_TRM_EN_URL}> :esp32: Datasheet (PDF) :esp32s2: Datasheet (PDF) :esp32: Hardware Design Guidelines (PDF) diff --git a/docs/en/security/flash-encryption.rst b/docs/en/security/flash-encryption.rst index f35ffbd70..e156a6e67 100644 --- a/docs/en/security/flash-encryption.rst +++ b/docs/en/security/flash-encryption.rst @@ -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 diff --git a/docs/idf_extensions/format_idf_target.py b/docs/idf_extensions/format_idf_target.py index 8a2204f44..65c33222b 100644 --- a/docs/idf_extensions/format_idf_target.py +++ b/docs/idf_extensions/format_idf_target.py @@ -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): diff --git a/docs/zh_CN/api-guides/jtag-debugging/debugging-examples.rst b/docs/zh_CN/api-guides/jtag-debugging/debugging-examples.rst index 2434431b0..411919d1e 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/debugging-examples.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/debugging-examples.rst @@ -155,14 +155,7 @@ 在 “Memory” 选项卡下，我们将在内存地址 ``0x3FF44004`` 处读取和写入内容。该地址也是 ``GPIO_OUT_REG`` 寄存器的地址，可以用来控制（设置或者清除）某个 GPIO 的电平。 -.. only:: esp32 - - 关于该寄存器的更多详细信息，请参阅 `ESP32 技术参考手册 `_ 中的 IO_MUX 和 GPIO Matrix 章节。 - -.. only:: esp32s2beta - - 关于该寄存器的更多详细信息，请参阅 `ESP32-S2 技术参考手册 `_ 中的 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 技术参考手册 `_ 中的 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`` 寄存器的值:: diff --git a/docs/zh_CN/api-reference/peripherals/touch_pad.rst b/docs/zh_CN/api-reference/peripherals/touch_pad.rst index c8ba473b6..1c9476fec 100644 --- a/docs/zh_CN/api-reference/peripherals/touch_pad.rst +++ b/docs/zh_CN/api-reference/peripherals/touch_pad.rst @@ -10,7 +10,7 @@ ESP32 可支持最多 10 个电容式触摸板/GPIO，触摸板可以以矩阵或滑条等方式组合使用，从而覆盖更大触感区域及更多触感点。触摸传感由有限状态机 (FSM) 硬件控制，由软件或专用硬件计时器发起。 -如需了解触摸传感器设计、操作及其控制寄存器等相关信息，请参考《`ESP32 技术参考手册 `_》(PDF)，您也可以在《ESP32 技术参考手册》中查看这一子系统是如何运行的。 +如需了解触摸传感器设计、操作及其控制寄存器等相关信息，请参考《`{IDF_TARGET_NAME} 技术参考手册 <{IDF_TARGET_TRM_CN_URL}>`_》(PDF)，您也可以在《ESP32 技术参考手册》中查看这一子系统是如何运行的。 请参考 `触摸传感器应用方案简介 `_，查看触摸传感器设计详情和固件开发指南。如果不想亲自在多种配置环境下测试触摸传感器，请查看 `ESP32 触摸功能开发套件 `_。 @@ -81,7 +81,7 @@ ESP32 可支持最多 10 个电容式触摸板/GPIO，触摸板可以以矩阵 .. figure:: ../../../_static/touch_pad-measurement-parameters.jpg :align: center - :alt: Touch Pad - relationship between measurement parameters + :alt: Touch Pad - relationship between measurement parameters :figclass: align-center 触摸板 - 测量参数之间的关系 @@ -115,7 +115,7 @@ ESP32 可支持最多 10 个电容式触摸板/GPIO，触摸板可以以矩阵 在对触摸监测启用中断之前，请先设置一个触摸监测阈值。然后使用 `触摸状态测量`_ 中所述的函数读取并显示触摸和释放触摸板时测得的结果。如果测量中存在噪声且相对电容变化较小，请使用滤波器。您也可以根据应用程序和环境条件，测试温度和电源电压变化对测量值的影响。 -确定监测阈值后就可以在初始化时调用 :cpp:func:`touch_pad_config` 设置此阈值，或在运行时调用 :cpp:func:`touch_pad_set_thresh` 设置此阈值。 +确定监测阈值后就可以在初始化时调用 :cpp:func:`touch_pad_config` 设置此阈值，或在运行时调用 :cpp:func:`touch_pad_set_thresh` 设置此阈值。 下一步就是设置如何触发中断。您可以设置在阈值以下或以上触发中断，具体触发模式由函数 :cpp:func:`touch_pad_set_trigger_mode` 设置。 @@ -135,7 +135,7 @@ ESP32 可支持最多 10 个电容式触摸板/GPIO，触摸板可以以矩阵 从睡眠模式唤醒 ^^^^^^^^^^^^^^^^^^^^^^ -如果使用触摸板中断将芯片从睡眠模式唤醒，您可以选择配置一些触摸板，例如 SET1 或 SET1 和 SET2，触摸这些触摸板将触发中断并唤醒芯片。请调用 :cpp:func:`touch_pad_set_trigger_source` 实现上述操作。 +如果使用触摸板中断将芯片从睡眠模式唤醒，您可以选择配置一些触摸板，例如 SET1 或 SET1 和 SET2，触摸这些触摸板将触发中断并唤醒芯片。请调用 :cpp:func:`touch_pad_set_trigger_source` 实现上述操作。 您可以使用以下函数管理 'SET' 中触摸板所需的位模式配置： diff --git a/docs/zh_CN/contribute/documenting-code.rst b/docs/zh_CN/contribute/documenting-code.rst index db4dc11e8..0da92bad6 100644 --- a/docs/zh_CN/contribute/documenting-code.rst +++ b/docs/zh_CN/contribute/documenting-code.rst @@ -21,14 +21,14 @@ Doxygen 会解析代码，提取命令和后续文本，生成代码文档。 .. image:: ../../_static/doc-code-documentation-inline.png :align: center :alt: 内联代码样本文档 - + Doxygen 支持多种排版风格，对于文档中可以包含的细节非常灵活。请参考数据丰富、条理清晰的 `Doxygen 手册 `_ 熟悉 Doxygen 特性。 为什么需要 Doxygen? -------------------- -使用 Doxygen 的最终目的是确保所有代码编写风格一致，以便在代码变更时使用 `Sphinx `_ 和 `Breathe `_ 等工具协助筹备、自动更新 API 文档。 +使用 Doxygen 的最终目的是确保所有代码编写风格一致，以便在代码变更时使用 `Sphinx `_ 和 `Breathe `_ 等工具协助筹备、自动更新 API 文档。 使用这类工具时，上文代码渲染后呈现效果如下： @@ -57,7 +57,7 @@ Doxygen 支持多种排版风格，对于文档中可以包含的细节非常灵 .. image:: ../../_static/doc-code-void-function.png :align: center :alt: 隐式内联函数样本文档及渲染后的效果 - + 5. 为 ``define``、``struct`` 和 ``enum`` 的成员编写文档时，请在每一项后添加注释，如下所示。 .. image:: ../../_static/doc-code-member.png @@ -74,7 +74,7 @@ Doxygen 支持多种排版风格，对于文档中可以包含的细节非常灵 * - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist * - other error codes from the underlying storage driver * - + 7. 头文件的功能概览和库文件应当存在同一个项目库之下，放入单独的 ``README.rst`` 文件。如果目录下包含不同 API 的头文件，应将文件命名为 ``apiname-readme.rst``。 @@ -117,7 +117,7 @@ Doxygen 支持多种排版风格，对于文档中可以包含的细节非常灵 */ void first_similar_function (void); void second_similar_function (void); - /**@}*/ + /**@}*/ 示例请参照 :component_file:`nvs_flash/include/nvs.h`。 @@ -126,14 +126,14 @@ 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. 准备一个或更多完整的代码示例和描述，将描述放入单独的 ``README.md`` 文件中，置于 :idf:`examples` 目录的特定文件夹中。 +6. 准备一个或更多完整的代码示例和描述，将描述放入单独的 ``README.md`` 文件中，置于 :idf:`examples` 目录的特定文件夹中。 .. _link-custom-roles: @@ -198,7 +198,7 @@ CI build 脚本中添加了检查功能，查找 RST 文件中的硬编码链接 * `活动图 `_ * `逻辑网络图 `_ -使用该工具包，可以将简单的文本（与 graphviz 的 DOT 格式类似）转换成美观的图片。图中内容自动排版。图标代码之后会转换为 ".png" 图片，在后台添加进 **Sphinx** 文档中。 +使用该工具包，可以将简单的文本（与 graphviz 的 DOT 格式类似）转换成美观的图片。图中内容自动排版。图标代码之后会转换为 ".png" 图片，在后台添加进 **Sphinx** 文档中。 要查看图表的渲染效果，可使用线上的 `interactive shell`_ 即时显示生成的图片。 @@ -262,10 +262,10 @@ Sphinx 新手怎么办 3. 想要查看在上传至 GitHub 前文档如何生成、呈现，有两种方式： * 安装`Sphinx `_、 `Breathe `_、 `Blockdiag `_ 和 `Doxygen `_ 本地生成文档，具体可查看下文。 - + * 在 `Read the Docs `_ 建立账号，在云端生成文档。 Read the Docs 免费提供文档生成和存储，且速度快、质量高。 -4. 在生成文档前预览，可使用 `Sublime Text `_ 编辑器和 `OmniMarkupPreviewer `_ 插件。 +4. 在生成文档前预览，可使用 `Sublime Text `_ 编辑器和 `OmniMarkupPreviewer `_ 插件。 .. _setup-for-building-documentation: @@ -291,7 +291,7 @@ Doxygen 的安装取决于操作系统： **Linux** -:: +:: sudo apt-get install doxygen @@ -348,7 +348,7 @@ Doxygen 的安装取决于操作系统： make html -这一步骤需要几分钟时间。完成后，文档会放置在 ``~/esp/esp-idf/docs/en/_build/html`` 文件夹下。您可以在网页浏览器中打开 ``index.html`` 查看。 +这一步骤需要几分钟时间。完成后，文档会放置在 ``~/esp/esp-idf/docs/en/_build/html`` 文件夹下。您可以在网页浏览器中打开 ``index.html`` 查看。 大功告成 diff --git a/docs/zh_CN/hw-reference/index.rst b/docs/zh_CN/hw-reference/index.rst index 4f22477b9..9d5e73e8a 100644 --- a/docs/zh_CN/hw-reference/index.rst +++ b/docs/zh_CN/hw-reference/index.rst @@ -6,8 +6,7 @@ ESP32 H/W 硬件参考 .. toctree:: :maxdepth: 2 - :esp32: ESP32 技术参考手册 (PDF) - :esp32s2beta: ESP32-S2 技术参考手册 (PDF) + {IDF_TARGET_NAME} 技术参考手册 (PDF) <{IDF_TARGET_TRM_CN_URL}> :esp32: ESP32 技术规格书 (PDF) :esp32s2: ESP32-S2 技术规格书 (PDF) :esp32: ESP32 硬件设计指南 (PDF) diff --git a/docs/zh_CN/security/flash-encryption.rst b/docs/zh_CN/security/flash-encryption.rst index 5905b823b..90e749d8f 100644 --- a/docs/zh_CN/security/flash-encryption.rst +++ b/docs/zh_CN/security/flash-encryption.rst @@ -4,18 +4,18 @@ 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 数据： - - 引导加载程序 + - 引导加载程序 - 分区表 - 所有 “app” 类型的分区 @@ -24,16 +24,16 @@ Flash 加密功能用于加密与 ESP32 搭载使用的 SPI Flash 中的内容 - 安全启动引导加载程序摘要（如果已启用安全启动） - 分区表中标有“加密”标记的分区 -Flash 加密与 :doc:`安全启动` 功能各自独立，您可以在关闭安全启动的状态下使用 Flash 加密。但是，为了安全的计算机环境，二者应同时使用。在关闭安全启动的状态下，需运行其他配置来确保 Flash 加密的有效性。详细信息可参见 :ref:`flash-encryption-without-secure-boot`。 +Flash 加密与 :doc:`安全启动` 功能各自独立，您可以在关闭安全启动的状态下使用 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 列表及其描述： :: @@ -48,27 +48,27 @@ Flash 加密操作由 ESP32 上的多个 eFuse 控制。以下是这些 eFuse 0: 256 bits 1: 192 bits 2: 128 bits - 最终的 AES 密钥根据 FLASH_CRYPT_CONFIG 的 + 最终的 AES 密钥根据 FLASH_CRYPT_CONFIG 的 值产生。 BLOCK1 存储 AES 密钥的 256 位宽 eFuse 块 是 x - + FLASH_CRYPT_CONFIG 4 位宽 eFuse，控制 AES 加密进程 是 0xF download_dis_encrypt 设置后，在 UART 下载模式运行时关闭 Flash 加 是 0 密操作 - + download_dis_decrypt 设置后，在 UART 下载模式运行时关闭 Flash 解 是 0 密操作 - + FLASH_CRYPT_CNT 7 位 eFuse，在启动时启用/关闭加密功能 是 0 - + 偶数位（0，2，4，6）： 启动时加密 Flash 奇数位（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 加密过程： +正如上文所说，: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 值。 @@ -117,7 +117,7 @@ Flash 的加密过程 - 在引导加载程序 config 下选择适当详细程度的日志。 - 启用 Flash 加密将增大引导加载程序，因而可能需更新分区表偏移。请参见 :ref:`secure-boot-bootloader-size`。 - + - 保存配置并退出。 构建并烧录完整的映像包括：引导加载程序、分区表和 app。这些分区最初以未加密形式写入 Flash。 @@ -126,7 +126,7 @@ Flash 的加密过程 idf.py flash monitor -一旦烧录完成，设备将重置，在下次启动时，第二阶段引导加载程序将加密 Flash 的 app 分区，然后重置该分区。现在，示例应用程序将在运行时解密并执行命令。以下是首次启用 Flash 加密后 ESP32 启动时的样例输出。 +一旦烧录完成，设备将重置，在下次启动时，第二阶段引导加载程序将加密 Flash 的 app 分区，然后重置该分区。现在，示例应用程序将在运行时解密并执行命令。以下是首次启用 Flash 加密后 {IDF_TARGET_NAME} 启动时的样例输出。 :: @@ -177,20 +177,20 @@ Flash 的加密过程 I (201) flash_encrypt: Disable UART bootloader MMU cache... I (208) flash_encrypt: Disable JTAG... I (212) flash_encrypt: Disable ROM BASIC interpreter fallback... - I (219) esp_image: segment 0: paddr=0x00001020 vaddr=0x3fff0018 size=0x00004 ( 4) - I (227) esp_image: segment 1: paddr=0x0000102c vaddr=0x3fff001c size=0x02104 ( 8452) - I (239) esp_image: segment 2: paddr=0x00003138 vaddr=0x40078000 size=0x03528 ( 13608) - I (249) esp_image: segment 3: paddr=0x00006668 vaddr=0x40080400 size=0x01a08 ( 6664) + I (219) esp_image: segment 0: paddr=0x00001020 vaddr=0x3fff0018 size=0x00004 ( 4) + I (227) esp_image: segment 1: paddr=0x0000102c vaddr=0x3fff001c size=0x02104 ( 8452) + I (239) esp_image: segment 2: paddr=0x00003138 vaddr=0x40078000 size=0x03528 ( 13608) + I (249) esp_image: segment 3: paddr=0x00006668 vaddr=0x40080400 size=0x01a08 ( 6664) I (657) esp_image: segment 0: paddr=0x00020020 vaddr=0x3f400020 size=0x0808c ( 32908) map - I (669) esp_image: segment 1: paddr=0x000280b4 vaddr=0x3ffb0000 size=0x01ea4 ( 7844) - I (672) esp_image: segment 2: paddr=0x00029f60 vaddr=0x40080000 size=0x00400 ( 1024) + I (669) esp_image: segment 1: paddr=0x000280b4 vaddr=0x3ffb0000 size=0x01ea4 ( 7844) + I (672) esp_image: segment 2: paddr=0x00029f60 vaddr=0x40080000 size=0x00400 ( 1024) 0x40080000: _WindowOverflow4 at esp-idf/esp-idf/components/freertos/xtensa_vectors.S:1778 - I (676) esp_image: segment 3: paddr=0x0002a368 vaddr=0x40080400 size=0x05ca8 ( 23720) + I (676) esp_image: segment 3: paddr=0x0002a368 vaddr=0x40080400 size=0x05ca8 ( 23720) I (692) esp_image: segment 4: paddr=0x00030018 vaddr=0x400d0018 size=0x126a8 ( 75432) map 0x400d0018: _flash_cache_start at ??:? - I (719) esp_image: segment 5: paddr=0x000426c8 vaddr=0x400860a8 size=0x01f4c ( 8012) + I (719) esp_image: segment 5: paddr=0x000426c8 vaddr=0x400860a8 size=0x01f4c ( 8012) 0x400860a8: prvAddNewTaskToReadyList at esp-idf/esp-idf/components/freertos/tasks.c:4561 I (722) flash_encrypt: Encrypting partition 2 at offset 0x20000... @@ -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 @@ -313,7 +313,7 @@ Flash 的加密过程 - 启用 Flash 加密将增大引导加载程序，因而可能需要更新分区表偏移。可参见 See :ref:`secure-boot-bootloader-size`。 - 保存配置并退出。 - + 构建并烧录完整的映像包括：引导加载程序、分区表和 app。这些分区最初以未加密形式写入 Flash :: @@ -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 加载器将无法加载 引导加载程序，并会显示以下错误类型： @@ -374,27 +374,27 @@ Flash 的加密过程 rst:0x3 (SW_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) flash read err, 1000 - ets_main.c 371 + ets_main.c 371 ets Jun 8 2016 00:22:57 rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) flash read err, 1000 - ets_main.c 371 + ets_main.c 371 ets Jun 8 2016 00:22:57 rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) flash read err, 1000 - ets_main.c 371 + ets_main.c 371 ets Jun 8 2016 00:22:57 rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) flash read err, 1000 - ets_main.c 371 + ets_main.c 371 ets Jun 8 2016 00:22:57 rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) flash read err, 1000 - ets_main.c 371 + ets_main.c 371 ets Jun 8 2016 00:22:57 2. 如果引导加载程序已加密，但使用明文分区表映像重新更新了分区表，则引导加载程序将无法读取分区表，并会显示以下错误类型： @@ -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 加密 `。 @@ -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 内容时需加注意。 @@ -526,14 +526,14 @@ ROM 函数 ``esp_rom_spiflash_write_encrypted`` 将在 Flash 中写入加密数 OTA 更新 ^^^^^^^^^^ -只要使用了函数 ``esp_partition_write``，则加密分区的 OTA 更新将自动以加密形式写入。 +只要使用了函数 ``esp_partition_write``，则加密分区的 OTA 更新将自动以加密形式写入。 .. _updating-encrypted-flash-serial: 关闭 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:`可再次烧录 ` 安全启动模式，且安全启动密钥已预生成并烧录至 ESP32（可参见 :ref:`安全启动 `），则 :ref:`明文串行 flash 更新 ` 可实现。在该配置下，``idf.py bootloader`` 将生成简化的引导加载程序和安全启动摘要文件，用于在偏移量 0x0 处进行烧录。当进行明文串行重新烧录步骤时，须在烧录其他明文数据前重新烧录此文件。 +- 只有当选择 :ref:`可再次烧录 ` 安全启动模式，且安全启动密钥已预生成并烧录至 {IDF_TARGET_NAME}（可参见 :ref:`安全启动 `），则 :ref:`明文串行 flash 更新 ` 可实现。在该配置下，``idf.py bootloader`` 将生成简化的引导加载程序和安全启动摘要文件，用于在偏移量 0x0 处进行烧录。当进行明文串行重新烧录步骤时，须在烧录其他明文数据前重新烧录此文件。 - 假设未重新烧录引导加载程序，:ref:`使用预生成的 Flash 加密密钥重新烧录 ` 仍可实现。重新烧录引导加载程序时，需在安全启动配置中启用相同的 :ref:`可重新烧录 ` 选项。 .. _flash-encryption-without-secure-boot: