Merge branch 'feature/docs-add-debugging-freertos-objects' into 'master'

docs: add debugging freertos objects

See merge request espressif/esp-idf!18357

docs/en/api-guides/jtag-debugging/debugging-examples.rst

@@ -245,6 +245,7 @@ Examples in this section
 5. :ref:`jtag-debugging-examples-command-line-05`
 6. :ref:`jtag-debugging-examples-command-line-06`
 7. :ref:`jtag-debugging-examples-command-line-07`
+8. :ref:`jtag-debugging-examples-command-line-08`
 
 
 .. _jtag-debugging-examples-command-line-01:
@@ -445,10 +446,6 @@ To check it delete all breakpoints and enter ``c`` to resume application. Then e
 
 In particular case above, the application has been halted in line 52 of code in file ``freertos_hooks.c``. Now you can resume it again by enter ``c`` or do some debugging as discussed below.
 
-.. note::
-
-    In MSYS2 shell Ctrl+C does not halt the target but exists debugger. To resolve this issue consider debugging with :ref:`jtag-debugging-examples-eclipse` or check a workaround under http://www.mingw.org/wiki/Workaround_for_GDB_Ctrl_C_Interrupt.
-
 
 .. _jtag-debugging-examples-command-line-04:
 
@@ -627,6 +624,34 @@ If current value of ``i`` is less than ``2`` and program is resumed, it will bli
     (gdb)
 
 
+.. _jtag-debugging-examples-command-line-08:
+
+Debugging FreeRTOS Objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This part might be interesting when you are debugging FreeRTOS tasks interactions.
+Users that need to use the FreeRTOS task interactions can use the GDB ``freertos`` command. The ``freertos`` command is not native to GDB and comes from the `freertos-gdb <https://pypi.org/project/freertos-gdb>`_ Python extension module. The ``freertos`` command contains a series of sub-commands as demonstrated in the code snippet::
+
+    (gdb) freertos
+    "freertos" must be followed by the name of a subcommand.
+    List of freertos subcommands:
+
+    freertos queue --  Generate a print out of the current queues info.
+    freertos semaphore --  Generate a print out of the current semaphores info.
+    freertos task --  Generate a print out of the current tasks and their states.
+    freertos timer --  Generate a print out of the current timers info.
+
+For a more detailed description of this extension, please refer to https://pypi.org/project/freertos-gdb.
+
+.. note::
+
+    The freertos-gdb Python module is included as a Python package requirement by ESP-IDF, thus should be automatically installed (see :ref:`get-started-set-up-tools` for more details).
+
+    The FreeRTOS extension automatically loads in case GDB is executed with command via ``idf.py gdb``. Otherwise, the module could be enabled via the ``python import freertos_gdb`` command inside GDB.
+
+    Users only need to have Python 3.6 (or above) that contains a Python shared library.
+
+
 Obtaining help on commands
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 

docs/en/api-guides/jtag-debugging/index.rst

@@ -249,6 +249,11 @@ This section is intended for users not familiar with GDB. It presents example de
 
 Similar debugging actions are provided using GDB from :ref:`jtag-debugging-examples-command-line`.
 
+.. note::
+
+    :ref:`jtag-debugging-examples-command-line-08` is currently only available for command line debugging.
+
+
 Before proceeding to examples, set up your {IDF_TARGET_NAME} target and load it with :example:`get-started/blink`.
 
 

docs/en/api-guides/jtag-debugging/tips-and-quirks.rst

@@ -71,6 +71,8 @@ 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`.
 
+GDB has a Python extension for FreeRTOS support. ESP-IDF automatically loads this module into GDB with the ``idf.py gdb`` command when the system requirements are met. See more details in :ref:`jtag-debugging-examples-command-line-08`.
+
 .. only:: esp32
 
     .. _jtag-debugging-tip-code-flash-voltage:

docs/zh_CN/api-guides/jtag-debugging/debugging-examples.rst

@@ -245,6 +245,7 @@
 5. :ref:`jtag-debugging-examples-command-line-05`
 6. :ref:`jtag-debugging-examples-command-line-06`
 7. :ref:`jtag-debugging-examples-command-line-07`
+8. :ref:`jtag-debugging-examples-command-line-08`
 
 
 .. _jtag-debugging-examples-command-line-01:
@@ -445,10 +446,6 @@
 
 在上图所示的情况下，应用程序已经在 ``freertos_hooks.c`` 文件的第 52 行暂停运行，现在您可以通过输入 ``c`` 再次将其恢复运行或者进行如下所述的一些调试工作。
 
-.. note::
-
-	在 MSYS2 的 shell 中输入 Ctrl+C 并不会暂停目标的运行，而是会退出调试器。解决这个问题的方法可以通过 :ref:`使用 Eclipse 来调试 <jtag-debugging-examples-eclipse>` 或者参考 http://www.mingw.org/wiki/Workaround_for_GDB_Ctrl_C_Interrupt 里的解决方案。
-
 
 .. _jtag-debugging-examples-command-line-04:
 
@@ -627,6 +624,34 @@
     (gdb)
 
 
+.. _jtag-debugging-examples-command-line-08:
+
+调试 FreeRTOS 对象
+^^^^^^^^^^^^^^^^^^
+
+该部分内容或许可以帮助您调试 FreeRTOS 任务交互。
+需要调试 FreeRTOS 任务交互的用户可使用 GDB 命令 ``freertos``。该命令并非 GDB 原生命令，而是来自于 Python 扩展模块 `freertos-gdb <https://pypi.org/project/freertos-gdb>`_，其包含一系列子命令::
+
+    (gdb) freertos
+    "freertos" 后面必须紧随子命令的名称
+    freertos 子命令如下：
+
+    freertos queue --  打印当前队列信息
+    freertos semaphore --  打印当前信号量信息
+    freertos task --  打印当前任务及其状态
+    freertos timer --  打印当前定时器信息
+
+点击 https://pypi.org/project/freertos-gdb 链接了解此扩展模块的详细信息。
+
+.. note::
+
+    ESP-IDF 在安装 Pyhton 包时会自动安装 freertos-gdb Python 模块，详情请参考 :ref:`get-started-set-up-tools`。
+
+    如果使用 ``idf.py gdb`` 命令运行 GDB，FreeRTOS 扩展会自动加载。也可以使用 GDB 内部命令 ``python import freertos_gdb`` 使能该模块。
+
+    请保证使用 Python 3.6 及以上版本，该版本具有 Python 共享库。
+
+
 获得命令的帮助信息
 ^^^^^^^^^^^^^^^^^^
 

docs/zh_CN/api-guides/jtag-debugging/index.rst

@@ -249,6 +249,11 @@ OpenOCD 安装完成后就可以配置 {IDF_TARGET_NAME} 目标（即带 JTAG
 
 此外还会提供在 :ref:`在命令行终端进行调试 <jtag-debugging-examples-command-line>` 下使用 GDB 调试的案例。
 
+.. note::
+
+    :ref:`jtag-debugging-examples-command-line-08` 目前仅适用于命令行调试。
+
+
 在演示之前，请完成 {IDF_TARGET_NAME} 目标板设置并加载 :example:`get-started/blink` 至 {IDF_TARGET_NAME} 中。
 
 

docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst

@@ -69,7 +69,9 @@ ESP-IDF 有一些针对 OpenOCD 调试功能的选项可以在编译时进行设
 支持 FreeRTOS
 ^^^^^^^^^^^^^^^^
 
-OpenOCD 完全支持 ESP-IDF 自带的 FreeRTOS 操作系统，GDB 会将 FreeRTOS 中的任务当做线程。使用 GDB 命令 ``i threads`` 可以查看所有的线程，使用命令 ``thread n`` 可以切换到某个具体任务的堆栈，其中 ``n`` 是线程的编号。检测 FreeRTOS 的功能可以在配置目标时被禁用。更多详细信息，请参阅 :ref:`jtag-debugging-tip-openocd-configure-target`.
+OpenOCD 完全支持 ESP-IDF 自带的 FreeRTOS 操作系统，GDB 会将 FreeRTOS 中的任务当做线程。使用 GDB 命令 ``i threads`` 可以查看所有的线程，使用命令 ``thread n`` 可以切换到某个具体任务的堆栈，其中 ``n`` 是线程的编号。检测 FreeRTOS 的功能可以在配置目标时被禁用。更多详细信息，请参阅 :ref:`jtag-debugging-tip-openocd-configure-target`。
+
+GDB 具有 FreeRTOS 支持的 Python 扩展模块。在系统要求满足的情况下，通过 ``idf.py gdb`` 命令，ESP-IDF 会将该模块自动加载到 GDB 中。详细信息请参考 :ref:`jtag-debugging-examples-command-line-08`。
 
 .. only:: esp32
 
@@ -78,7 +80,7 @@ OpenOCD 完全支持 ESP-IDF 自带的 FreeRTOS 操作系统，GDB 会将 FreeRT
     在 OpenOCD 的配置文件中设置 SPI 闪存的工作电压
     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-    ESP32 的 MTDI 引脚是用于 JTAG 通信的四个引脚之一，同时也是 ESP32 的 bootstrapping 引脚。上电时，ESP32 会在 MTDI 引脚上采样二进制电平，据此来设置内部的稳压器，用于给外部的 SPI 闪存芯片供电。如果上电时 MTDI 引脚上的二进制电平为低电平，则稳压器会被设置为 3.3 V；如果 MTDI 引脚为高电平，则稳压器会被设置为 1.8 V。MTDI 引脚通常需要一个上拉电阻或者直接使能内部的弱下拉电阻（详见 `ESP32 系列芯片技术规格书 <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_cn.pdf>`_ ），具体取决于所使用的 SPI 芯片的类型。但是一旦连接上 JTAG 后，原来用于实现 bootstrapping 功能的上拉或者下拉电阻都会被覆盖掉。
+    ESP32 的 MTDI 管脚是用于 JTAG 通信的四个管脚之一，同时也是 ESP32 的 bootstrapping 管脚。上电时，ESP32 会在 MTDI 管脚上采样二进制电平，据此来设置内部的稳压器，用于给外部的 SPI 闪存芯片供电。如果上电时 MTDI 管脚上的二进制电平为低电平，则稳压器会被设置为 3.3 V；如果 MTDI 管脚为高电平，则稳压器会被设置为 1.8 V。MTDI 管脚通常需要一个上拉电阻或者直接使能内部的弱下拉电阻（详见 `ESP32 系列芯片技术规格书 <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_cn.pdf>`_ ），具体取决于所使用的 SPI 芯片的类型。但是一旦连接上 JTAG 后，原来用于实现 bootstrapping 功能的上拉或者下拉电阻都会被覆盖掉。
 
     为了解决这个问题，OpenOCD 的板级配置文件（例如 ESP-WROVER-KIT 开发板的 ``board\esp32-wrover-kit-3.3v.cfg``）提供了 ``ESP32_FLASH_VOLTAGE`` 参数来设置 ``TDO`` 信号线在空闲状态下的二进制电平，这样就可以减少由于闪存电压不正确而导致的应用程序启动不良的几率。
 
@@ -172,7 +174,7 @@ TCL 语言中为变量赋值的语法是:
     * - ``ESP_RTOS``
       - 设置成 ``none`` 可以关闭 OpenOCD 对 RTOS 的支持，这样的话，你将无法在 GDB 中查看到线程列表。这个功能在调试 FreeRTOS 本身的时候会很有用，可以单步调试调度器的代码。
     * - ``ESP_FLASH_SIZE``
-      - 设置成 ``0`` 可以关闭对 Flash 断点的支持。
+      - 设置成 ``0`` 可以关闭对 flash 断点的支持。
     * - ``ESP_SEMIHOST_BASEDIR``
       - 设置 semihosting 在主机端的默认目录。
 
@@ -190,16 +192,16 @@ TCL 语言中为变量赋值的语法是:
 
 .. _jtag-debugging-tip-jtag-pins-reconfigured:
 
-不要将 JTAG 引脚用于其他功能
+不要将 JTAG 管脚用于其他功能
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-如果除了 {IDF_TARGET_NAME} 模组和 JTAG 适配器之外的其他硬件也连接到了 JTAG 引脚，那么 JTAG 的操作可能会受到干扰。{IDF_TARGET_NAME} JTAG 使用以下引脚：
+如果除了 {IDF_TARGET_NAME} 模组和 JTAG 适配器之外的其他硬件也连接到了 JTAG 管脚，那么 JTAG 的操作可能会受到干扰。{IDF_TARGET_NAME} JTAG 使用以下管脚：
 
 .. include:: {IDF_TARGET_PATH_NAME}.inc
     :start-after: jtag-pins
     :end-before: ---
 
-如果用户应用程序更改了 JTAG 引脚的配置，JTAG 通信可能会失败。如果 OpenOCD 正确初始化（检测到两个 Tensilica 内核），但在程序运行期间失去了同步并报出大量 DTR/DIR 错误，则应用程序可能将 JTAG 引脚重新配置为其他功能或者用户忘记将 Vtar 连接到 JTAG 适配器。
+如果用户应用程序更改了 JTAG 管脚的配置，JTAG 通信可能会失败。如果 OpenOCD 正确初始化（检测到两个 Tensilica 内核），但在程序运行期间失去了同步并报出大量 DTR/DIR 错误，则应用程序可能将 JTAG 管脚重新配置为其他功能或者用户忘记将 Vtar 连接到 JTAG 适配器。
 
 .. highlight:: none
 
@@ -221,16 +223,16 @@ JTAG 与闪存加密和安全引导
 
 Kconfig 配置项 :ref:`CONFIG_SECURE_BOOT_ALLOW_JTAG` 可以改变这个默认行为，使得用户即使开启了安全引导或者闪存加密，仍会保留 JTAG 的功能。
 
-然而，因为设置 :ref:`软件断点 <jtag-debugging-tip-where-breakpoints>` 的需要，OpenOCD 会尝试自动读写 Flash 中的内容，这会带来两个问题：
+然而，因为设置 :ref:`软件断点 <jtag-debugging-tip-where-breakpoints>` 的需要，OpenOCD 会尝试自动读写 flash 中的内容，这会带来两个问题：
 
-- 软件断点和闪存加密是不兼容的，目前 OpenOCD 尚不支持对 Flash 中的内容进行加密和解密。
+- 软件断点和闪存加密是不兼容的，目前 OpenOCD 尚不支持对 flash 中的内容进行加密和解密。
 - 如果开启了安全引导功能，设置软件断点会改变被签名的程序的摘要，从而使得签名失效。这也意味着，如果设置了软件断点，系统会在下次重启时的签名验证阶段失败，导致无法启动。
 
 关闭 JTAG 的软件断点功能，可以在启动 OpenOCD 时在命令行额外加一项配置参数 ``-c 'set ESP_FLASH_SIZE 0'``，请参考 :ref:`jtag-debugging-tip-openocd-config-vars`。
 
 .. note::
 
-   同样地，当启用该选项，并且调试过程中打了软件断点，之后引导程序将无法校验通过应用程序的签名。
+   同样地，当启用该选项，并且在调试过程中设置了软件断点，引导程序将无法校验通过应用程序的签名。
 
 .. only:: esp32
 
@@ -255,7 +257,7 @@ Kconfig 配置项 :ref:`CONFIG_SECURE_BOOT_ALLOW_JTAG` 可以改变这个默认
     c. 用于调试的操作系统的详细信息。
     d. 操作系统是在本地计算机运行还是在虚拟机上运行？
 
-2.  创建一个能够演示问题的简单示例工程，描述复现该问题的步骤。且这个调试示例不能受到 Wi-Fi 协议栈引入的非确定性行为的影响，因而再次遇到同样问题时，更容易复现。
+2.  创建一个能够演示问题的简单示例工程，描述复现该问题的步骤。且这个调试示例不能受到 Wi-Fi 协议栈引入的非确定性行为的影响，这样再次遇到同样问题时，更容易复现。
 
 .. highlight:: bash