alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2025-09-25 01:37:22 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: Add ESP-IDF GDB OpenOCD debugging plugin support

Browse Source
This commit is contained in:
Kondal Kolipaka
2023-05-09 19:31:56 +08:00
parent 38e84bdd4f
commit 62ef1a5b86
2 changed files with 93 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files

89
docs/en/api-guides/jtag-debugging/using-debugger.rst
View File

@@ -2,13 +2,13 @@ Using Debugger
--------------
:link_to_translation:`zh_CN:[中文]`
This section covers configuration and running debugger using several methods:
This section covers the steps to configure and run a debugger using various methods, including:
* from :ref:`jtag-debugging-using-debugger-eclipse`
* from :ref:`jtag-debugging-using-debugger-command-line`
* using :ref:`jtag-debugging-with-idf-py`
* :ref:`jtag-debugging-using-debugger-eclipse`
* :ref:`jtag-debugging-using-debugger-command-line`
* :ref:`jtag-debugging-with-idf-py`
See also a separate document `Configuration for Visual Studio Code Debug <https://github.com/espressif/vscode-esp-idf-extension/blob/master/docs/DEBUGGING.md>`__ describing how to run a debugger from VS Code.
For how to run a debugger from VS Code, see `Configuration for Visual Studio Code Debug <https://github.com/espressif/vscode-esp-idf-extension/blob/master/docs/DEBUGGING.md>`__.
.. _jtag-debugging-using-debugger-eclipse:
@@ -20,21 +20,35 @@ Eclipse
It is recommended to first check if debugger works using :ref:`jtag-debugging-with-idf-py` or from :ref:`jtag-debugging-using-debugger-command-line` and then move to using Eclipse.
Debugging functionality is provided out of box in standard Eclipse installation. Another option is to use pluggins like "GDB Hardware Debugging" plugin. We have found this plugin quite convenient and decided to use throughout this guide.
Eclipse is an integrated development environment (IDE) that provides a powerful set of tools for developing and debugging software applications. For ESP-IDF applications, `IDF Eclipse plugin <https://github.com/espressif/idf-eclipse-plugin>`_ provides two ways of debugging:
To begin with, install "GDB Hardware Debugging" plugin by opening Eclipse and going to `Help` > `Install` New Software.
1. `ESP-IDF GDB OpenOCD Debugging <https://github.com/espressif/idf-eclipse-plugin/blob/master/docs/OpenOCD%20Debugging.md#esp-idf-gdb-openocd-debugging>`_
2. GDB Hardware Debugging
Once installation is complete, configure debugging session following steps below. Please note that some of configuration parameters are generic and some are project specific. This will be shown below by configuring debugging for "blink" example project. If not done already, add this project to Eclipse workspace following guidance in `Eclipse Plugin <https://github.com/espressif/idf-eclipse-plugin/blob/master/README.md>`_. The source of :example:`get-started/blink` application is available in :idf:`examples` directory of ESP-IDF repository.
By default, Eclipse supports OpenOCD Debugging via the GDB Hardware Debugging plugin, which requires starting the OpenOCD server from the command line and configuring the GDB client from Eclipse to start with the debugging. This approach can be time-consuming and error-prone.
1. In Eclipse go to `Run` > `Debug Configuration`. A new window will open. In the window's left pane double click "GDB Hardware Debugging" (or select "GDB Hardware Debugging" and press the "New" button) to create a new configuration.
To make the debugging process easier, the IDF Eclipse plugin has a customized ESP-IDF GDB OpenOCD Debugging functionality. This functionality supports configuring the OpenOCD server and GDB client from within Eclipse. All the required configuration parameters will be pre-filled by the plugin, and you can start debugging with just a click of a button.
2. In a form that will show up on the right, enter the "Name:" of this configuration, e.g. "Blink checking".
Therefore, it is recommended to use the `ESP-IDF GDB OpenOCD Debugging <https://github.com/espressif/idf-eclipse-plugin/blob/master/docs/OpenOCD%20Debugging.md#esp-idf-gdb-openocd-debugging>`_ via the IDF Eclipse plugin.
3. On the "Main" tab below, under "Project:", press "Browse" button and select the "blink" project.
**GDB Hardware Debugging**
4. In next line "C/C++ Application:" press "Browse" button and select "blink.elf" file. If "blink.elf" is not there, then likely this project has not been build yet. See `Eclipse Plugin <https://github.com/espressif/idf-eclipse-plugin/blob/master/README.md>`_ how to do it.
.. note::
This approach is recommended only if you are unable to debug using `ESP-IDF GDB OpenOCD Debugging <https://github.com/espressif/idf-eclipse-plugin/blob/master/docs/OpenOCD%20Debugging.md#esp-idf-gdb-openocd-debugging>`_ for some reason.
5. Finally, under "Build (if required) before launching" click "Disable auto build".
To install the ``GDB Hardware Debugging`` plugin, open Eclipse and select ``Help`` > ``Install`` New Software.
After installation is complete, follow these steps to configure the debugging session. Please note that some configuration parameters are generic, while others are project-specific. This will be shown below by configuring debugging for "blink" example project. If not done already, add this project to Eclipse workspace following `Eclipse Plugin <https://github.com/espressif/idf-eclipse-plugin/blob/master/README.md>`_. The source of :example:`get-started/blink` application is available in :idf:`examples` directory of ESP-IDF repository.
1. In Eclipse, go to ``Run`` > ``Debug Configuration``. A new window will open. In the left pane of the window, double-click ``GDB Hardware Debugging`` (or select ``GDB Hardware Debugging`` and press the ``New`` button) to create a new configuration.
2. In a form that will show up on the right, enter the ``Name:`` of this configuration, e.g. "Blink checking".
3. On the ``Main`` tab below, under ``Project:``, press the ``Browse`` button and select the ``blink`` project.
4. In the next line under ``C/C++ Application:``, press the ``Browse`` button and select the ``blink.elf`` file. If ``blink.elf`` is not there, it is likely that this project has not been built yet. Refer to the `Eclipse Plugin <https://github.com/espressif/idf-eclipse-plugin/blob/master/README.md>`_ for instructions.
5. Finally, under ``Build (if required) before launching`` click ``Disable auto build``.
A sample window with settings entered in points 1 - 5 is shown below.
@@ -45,9 +59,9 @@ Once installation is complete, configure debugging session following steps below
Configuration of GDB Hardware Debugging - Main tab
6. Click "Debugger" tab. In field "GDB Command" enter ``{IDF_TARGET_TOOLCHAIN_PREFIX}-gdb`` to invoke debugger.
6. Click the ``Debugger`` tab. In field ``GDB Command``, enter ``{IDF_TARGET_TOOLCHAIN_PREFIX}-gdb`` to invoke the debugger.
7. Change default configuration of "Remote host" by entering ``3333`` under the "Port number".
7. Change the default configuration of the ``Remote host`` by entering ``3333`` under the ``Port number``.
Configuration entered in points 6 and 7 is shown on the following picture.
@@ -58,7 +72,7 @@ Once installation is complete, configure debugging session following steps below
Configuration of GDB Hardware Debugging - Debugger tab
8. The last tab to that requires changing of default configuration is "Startup". Under "Initialization Commands" uncheck "Reset and Delay (seconds)" and "Halt"". Then, in entry field below, enter the following lines:
8. The last tab that requires changing the default configuration is ``Startup``. Under ``Initialization Commands`` uncheck ``Reset and Delay (seconds)`` and ``Halt``. Then, in the entry field below, enter the following lines:
::
@@ -67,18 +81,18 @@ Once installation is complete, configure debugging session following steps below
set remote hardware-watchpoint-limit 2
.. note::
If you want to update image in the flash automatically before starting new debug session add the following lines of commands at the beginning of "Initialization Commands" textbox::
To automatically update the image in the flash before starting a new debug session, add the following command lines to the beginning of the ``Initialization Commands`` textbox::
mon reset halt
mon program_esp ${workspace_loc:blink/build/blink.bin} 0x10000 verify
For description of ``program_esp`` command see :ref:`jtag-upload-app-debug`.
For description of ``program_esp`` command, see :ref:`jtag-upload-app-debug`.
9. Under "Load Image and Symbols" uncheck "Load image" option.
9. Uncheck the ``Load image`` option under ``Load Image and Symbols``.
10. Further down on the same tab, establish an initial breakpoint to halt CPUs after they are reset by debugger. The plugin will set this breakpoint at the beginning of the function entered under "Set break point at:". Checkout this option and enter ``app_main`` in provided field.
10. Further down on the same tab, establish an initial breakpoint to halt CPUs after they are reset by debugger. The plugin will set this breakpoint at the beginning of the function entered under ``Set break point at:``. Checkout this option and enter ``app_main`` in provided field.
11. Checkout "Resume" option. This will make the program to resume after ``mon reset halt`` is invoked per point 8. The program will then stop at breakpoint inserted at ``app_main``.
11. Checkout ``Resume`` option. This will make the program to resume after ``mon reset halt`` is invoked per point 8. The program will then stop at breakpoint inserted at ``app_main``.
Configuration described in points 8 - 11 is shown below.
@@ -89,11 +103,11 @@ Once installation is complete, configure debugging session following steps below
Configuration of GDB Hardware Debugging - Startup tab
If the "Startup" sequence looks convoluted and respective "Initialization Commands" are not clear to you, check :ref:`jtag-debugging-tip-debugger-startup-commands` for additional explanation.
If the ``Startup`` sequence looks convoluted and respective ``Initialization Commands`` are unclear, check :ref:`jtag-debugging-tip-debugger-startup-commands` for additional explanation.
12. If you previously completed :ref:`jtag-debugging-configuring-target` steps described above, so the target is running and ready to talk to debugger, go right to debugging by pressing "Debug" button. Otherwise press "Apply" to save changes, go back to :ref:`jtag-debugging-configuring-target` and return here to start debugging.
12. If you have completed the :ref:`jtag-debugging-configuring-target` steps described above, so the target is running and ready to talk to debugger, go right to debugging by pressing ``Debug`` button. Otherwise press ``Apply`` to save changes, go back to :ref:`jtag-debugging-configuring-target` and return here to start debugging.
Once all 1 - 12 configuration steps are satisfied, the new Eclipse perspective called "Debug" will open as shown on example picture below.
Once all configuration steps 1-12 are satisfied, the new Eclipse perspective called "Debug" will open, as shown in the example picture below.
.. figure:: ../../../_static/debug-perspective.jpg
:align: center
@@ -110,11 +124,11 @@ If you are not quite sure how to use GDB, check :ref:`jtag-debugging-examples-ec
Command Line
^^^^^^^^^^^^
1. Begin with completing steps described under :ref:`jtag-debugging-configuring-target`. This is prerequisite to start a debugging session.
1. Begin by completing the steps described under :ref:`jtag-debugging-configuring-target`. This is prerequisite to start a debugging session.
.. highlight:: bash
2. Open a new terminal session and go to directory that contains project for debugging, e.g.
2. Open a new terminal session and go to the directory that contains the project for debugging, e.g.
::
@@ -122,7 +136,7 @@ Command Line
.. highlight:: none
3. When launching a debugger, you will need to provide couple of configuration parameters and commands. Instead of entering them one by one in command line, create a configuration file and name it ``gdbinit``:
3. When launching a debugger, you will need to provide a couple of configuration parameters and commands. Instead of entering them one by one in the command line, create a configuration file and name it ``gdbinit``:
::
@@ -133,9 +147,9 @@ Command Line
thb app_main
c
Save this file in current directory.
Save this file in the current directory.
For more details what's inside ``gdbinit`` file, see :ref:`jtag-debugging-tip-debugger-startup-commands`
For more details on what's inside ``gdbinit`` file, see :ref:`jtag-debugging-tip-debugger-startup-commands`
.. highlight:: bash
@@ -147,7 +161,7 @@ Command Line
.. highlight:: none
5. If previous steps have been done correctly, you will see a similar log concluded with ``(gdb)`` prompt:
5. If the previous steps have been done correctly, you will see a similar log concluded with the ``(gdb)`` prompt:
::
@@ -194,9 +208,10 @@ Command Line
43 xTaskCreate(&blink_task, "blink_task", 512, NULL, 5, NULL);
(gdb)
Note the third line from bottom that shows debugger halting at breakpoint established in ``gdbinit`` file at function ``app_main()``. Since the processor is halted, the LED should not be blinking. If this is what you see as well, you are ready to start debugging.
If you are not quite sure how to use GDB, check :ref:`jtag-debugging-examples-command-line` example debugging session in section :ref:`jtag-debugging-examples`.
Note the third-to-last line, which shows debugger halting at breakpoint established in ``gdbinit`` file at function ``app_main()``. Since the processor is halted, the LED should not be blinking. If this is what you see as well, you are ready to start debugging.
If you are not sure how to use GDB, check :ref:`jtag-debugging-examples-command-line` example debugging session in section :ref:`jtag-debugging-examples`.
.. _jtag-debugging-with-idf-py:
@@ -215,25 +230,25 @@ It is also possible to execute the described debugging tools conveniently from `
:start-after: idf-py-openocd-default-cfg
:end-before: ---
As for the JTAG configuration of the current board, please use the environmental variable ``OPENOCD_COMMANDS`` or ``--openocd-commands`` command line argument. If none of the above is defined, OpenOCD is started with |idf-py-def-cfg| board definition.
To configure the JTAG configuration for the current board, please use the environmental variable ``OPENOCD_COMMANDS`` or ``--openocd-commands`` command line argument. If none of the above is defined, OpenOCD is started with |idf-py-def-cfg| board definition.
2. ``idf.py gdb``
Starts the gdb the same way as the :ref:`jtag-debugging-using-debugger-command-line`, but generates the initial gdb scripts referring to the current project elf file.
Starts the GDB the same way as the :ref:`jtag-debugging-using-debugger-command-line`, but generates the initial GDB scripts referring to the current project elf file.
3. ``idf.py gdbtui``
The same as `2`, but starts the gdb with ``tui`` argument allowing very simple source code view.
The same as `2`, but starts the gdb with ``tui`` argument, allowing for a simple source code view.
4. ``idf.py gdbgui``
Starts `gdbgui <https://www.gdbgui.com>`_ debugger frontend enabling out-of-the-box debugging in a browser window. Please run the install script with the "--enable-gdbgui" argument in order to make this option supported, e.g. ``install.sh --enable-gdbgui``.
Starts `gdbgui <https://www.gdbgui.com>`_ debugger frontend enabling out-of-the-box debugging in a browser window. To enable this option, run the install script with the "--enable-gdbgui" argument, e.g. ``install.sh --enable-gdbgui``.
It is possible to combine these debugging actions on a single command line allowing convenient setup of blocking and non-blocking actions in one step. ``idf.py`` implements a simple logic to move the background actions (such as openocd) to the beginning and the interactive ones (such as gdb, monitor) to the end of the action list.
You can combine these debugging actions on a single command line, allowing for convenient setup of blocking and non-blocking actions in one step. ``idf.py`` implements a simple logic to move the background actions (such as openocd) to the beginning and the interactive ones (such as gdb, monitor) to the end of the action list.
An example of a very useful combination is::