From 9b56892bfe9e9109567e5f33d28bc1d726e61519 Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Tue, 3 Mar 2020 11:10:23 +0800 Subject: [PATCH] doc: fix broken .. only:: in JTAG guide Added note about .. only:: limitations to guide --- .../jtag-debugging/tips-and-quirks.rst | 32 ++++++++------- docs/en/contribute/documenting-code.rst | 27 +++++++++++- .../zh_CN/api-guides/jtag-debugging/index.rst | 17 ++------ .../jtag-debugging/tips-and-quirks.rst | 41 ++++++++++--------- 4 files changed, 68 insertions(+), 49 deletions(-) diff --git a/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst b/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst index c95ad6e2df..bb47fc1a5e 100644 --- a/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst +++ b/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst @@ -69,9 +69,10 @@ FreeRTOS support OpenOCD has explicit support for the ESP-IDF FreeRTOS. GDB can see FreeRTOS tasks as threads. Viewing them all can be done using the GDB ``i threads`` command, changing to a certain task is done with ``thread n``, with ``n`` being the number of the thread. FreeRTOS detection can be disabled in target's configuration. For more details see :ref:`jtag-debugging-tip-openocd-configure-target`. -.. _jtag-debugging-tip-code-flash-voltage: -.. only:: esp33 +.. only:: esp32 + + .. _jtag-debugging-tip-code-flash-voltage: Why to set SPI flash voltage in OpenOCD configuration? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -83,7 +84,11 @@ OpenOCD has explicit support for the ESP-IDF FreeRTOS. GDB can see FreeRTOS task Check specification of ESP32 module connected to JTAG, what is the power supply voltage of SPI flash chip. Then set ``ESP32_FLASH_VOLTAGE`` accordingly. Most WROOM modules use 3.3 V flash, while WROVER modules use 1.8 V flash. -.. _jtag-debugging-tip-optimize-jtag-speed: + .. _jtag-debugging-tip-optimize-jtag-speed: + +.. only:: esp32s2 + + .. _jtag-debugging-tip-optimize-jtag-speed: Optimize JTAG speed ^^^^^^^^^^^^^^^^^^^ @@ -156,19 +161,18 @@ Disable RTOS support Comment out this line to have RTOS support. - -Power supply voltage of ESP32's SPI flash chip -"""""""""""""""""""""""""""""""""""""""""""""" - -:: - - set ESP32_FLASH_VOLTAGE 1.8 - -Comment out this line to set 3.3 V, ref: :ref:`jtag-debugging-tip-code-flash-voltage` - - .. only:: esp32 + Power supply voltage of ESP32's SPI flash chip + """""""""""""""""""""""""""""""""""""""""""""" + + :: + + set ESP32_FLASH_VOLTAGE 1.8 + + Comment out this line to set 3.3 V, ref: :ref:`jtag-debugging-tip-code-flash-voltage` + + Configuration file for ESP32 targets """""""""""""""""""""""""""""""""""" diff --git a/docs/en/contribute/documenting-code.rst b/docs/en/contribute/documenting-code.rst index 13b5c1974c..2f6e2ee551 100644 --- a/docs/en/contribute/documenting-code.rst +++ b/docs/en/contribute/documenting-code.rst @@ -255,7 +255,7 @@ Exclusion of content based on chip-target Occasionally there will be content that is only relevant for one of targets. When this is the case, you can exclude that content by using the ''.. only:: TARGET'' directive, where you replace 'TARGET' with one of the chip names. As of now the following targets are available: * esp32 -* esp32s2 +* esp32s2 Example: @@ -267,7 +267,30 @@ Example: This functionality is provided by the `Sphinx selective exclude `_ extension. -The '':TARGET:'' role is used for excluding content from a table of content tree. For example: +A weakness in this extension is that it does not correctly handle the case were you exclude a section, and that is directly followed by a labeled new section. In these cases everything will render correctly, but the label will not correctly link to the section that follows. A temporary work-around for the cases were this can't be avoided is the following: + +.. code-block:: none + + .. only:: esp32 + + .. _section_1_label: + + Section 1 + ^^^^^^^^^ + + Section one content + + .. _section_2_label: + + .. only:: esp32s2 + + _section_2_label: + + Section 2 + ^^^^^^^^^ + Section 2 content + +The :TARGET: role is used for excluding content from a table of content tree. For example: .. code-block:: none diff --git a/docs/zh_CN/api-guides/jtag-debugging/index.rst b/docs/zh_CN/api-guides/jtag-debugging/index.rst index 3456396939..dd18dbfd23 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/index.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/index.rst @@ -276,19 +276,10 @@ Windows 用户:: 本节列出了本指南中提到的所有注意事项和补充内容的链接。 -* :ref:`jtag-debugging-tip-breakpoints` -* :ref:`jtag-debugging-tip-where-breakpoints` -* :ref:`jtag-debugging-tip-flash-mappings` -* :ref:`jtag-debugging-tip-why-next-works-as-step` -* :ref:`jtag-debugging-tip-code-options` -* :ref:`jtag-debugging-tip-freertos-support` -* :ref:`jtag-debugging-tip-code-flash-voltage` -* :ref:`jtag-debugging-tip-optimize-jtag-speed` -* :ref:`jtag-debugging-tip-debugger-startup-commands` -* :ref:`jtag-debugging-tip-openocd-configure-target` -* :ref:`jtag-debugging-tip-reset-by-debugger` -* :ref:`jtag-debugging-tip-jtag-pins-reconfigured` -* :ref:`jtag-debugging-tip-reporting-issues` +.. toctree:: + :maxdepth: 2 + + tips-and-quirks 相关文档 diff --git a/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst b/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst index e73ccf83f7..898bbd5380 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst @@ -67,10 +67,9 @@ ESP-IDF 有一些针对 OpenOCD 调试功能的选项可以在编译时进行设 OpenOCD 完全支持 ESP-IDF 自带的 FreeRTOS 操作系统，GDB 会将 FreeRTOS 中的任务当做线程。使用 GDB 命令 ``i threads`` 可以查看所有的线程，使用命令 ``thread n`` 可以切换到某个具体任务的堆栈，其中 ``n`` 是线程的编号。检测 FreeRTOS 的功能可以在配置目标时被禁用。更多详细信息，请参阅 :ref:`jtag-debugging-tip-openocd-configure-target`. +.. only:: esp32 -.. _jtag-debugging-tip-code-flash-voltage: - -.. only:: esp33 + .. _jtag-debugging-tip-code-flash-voltage: 在 OpenOCD 的配置文件中设置 SPI 闪存的工作电压 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -81,8 +80,11 @@ OpenOCD 完全支持 ESP-IDF 自带的 FreeRTOS 操作系统，GDB 会将 FreeRT 查看 JTAG 连接的 ESP32 模组的规格书，检查其 SPI 闪存芯片的供电电压值，然后再相应的设置 ``ESP32_FLASH_VOLTAGE``。大多数的 WROOM 模组使用 3.3 V 的闪存芯片，但是 WROVER 模组使用 1.8 V 的闪存芯片。 + .. _jtag-debugging-tip-optimize-jtag-speed: -.. _jtag-debugging-tip-optimize-jtag-speed: +.. only:: esp32s2 + + .. _jtag-debugging-tip-optimize-jtag-speed: 优化 JTAG 的速度 ^^^^^^^^^^^^^^^^ @@ -156,24 +158,23 @@ OpenOCD 需要知道当前使用的 JTAG 适配器的类型，以及其连接的 如果要支持 RTOS， 请注释掉这一行。 - -ESP32 的 SPI 闪存芯片的电源电压 -""""""""""""""""""""""""""""""" - -:: - - set ESP32_FLASH_VOLTAGE 1.8 - -如果 SPI 闪存芯片的电源电压为 3.3 V， 请注释掉这一行，更多信息请参阅： :ref:`jtag-debugging-tip-code-flash-voltage`。 - - - - -ESP32 的目标配置文件 -"""""""""""""""""""" - .. only:: esp32 + ESP32 的 SPI 闪存芯片的电源电压 + """""""""""""""""""""""""""""""""" + + :: + + set ESP32_FLASH_VOLTAGE 1.8 + + 如果 SPI 闪存芯片的电源电压为 3.3 V， 请注释掉这一行，更多信息请参阅： :ref:`jtag-debugging-tip-code-flash-voltage`。 + + + + + ESP32 的目标配置文件 + """""""""""""""""""" + :: source [find target/esp32.cfg]