From a421ea8d429b2bb08c16ff651b8c9c98b056577f Mon Sep 17 00:00:00 2001 From: Ivan Grokhotkov Date: Fri, 3 Jul 2020 18:00:36 +0200 Subject: [PATCH] docs: formatting fix in idf.py debugging section --- .../jtag-debugging/using-debugger.rst | 65 ++++++++++--------- 1 file changed, 36 insertions(+), 29 deletions(-) diff --git a/docs/en/api-guides/jtag-debugging/using-debugger.rst b/docs/en/api-guides/jtag-debugging/using-debugger.rst index c2f70d97fc..2af126e7d2 100644 --- a/docs/en/api-guides/jtag-debugging/using-debugger.rst +++ b/docs/en/api-guides/jtag-debugging/using-debugger.rst @@ -2,9 +2,11 @@ Using Debugger -------------- :link_to_translation:`zh_CN:[中文]` -This section covers configuration and running debugger from :ref:`jtag-debugging-using-debugger-eclipse` -or from :ref:`jtag-debugging-using-debugger-command-line` or using :ref:`jtag-debugging-with-idf-py`. -It is recommended to first check if debugger works from :ref:`jtag-debugging-using-debugger-command-line` and then move to using Eclipse. +This section covers configuration and running debugger using several methods: + +* from :ref:`jtag-debugging-using-debugger-eclipse` +* from :ref:`jtag-debugging-using-debugger-command-line` +* using :ref:`jtag-debugging-with-idf-py`. .. _jtag-debugging-using-debugger-eclipse: @@ -12,6 +14,10 @@ It is recommended to first check if debugger works from :ref:`jtag-debugging-usi Eclipse ^^^^^^^ +.. note:: + + 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. To begin with, install "GDB Hardware Debugging" plugin by opening Eclipse and going to `Help` > `Install` New Software. @@ -193,50 +199,51 @@ If you are not quite sure how to use GDB, check :ref:`jtag-debugging-examples-co .. _jtag-debugging-with-idf-py: -Using idf.py debug targets -^^^^^^^^^^^^^^^^^^^^^^^^^^ +idf.py debug targets +^^^^^^^^^^^^^^^^^^^^ It is also possible to execute the described debugging tools conveniently from ``idf.py``. These commands are supported: -1. ``idf.py openocd`` +1. ``idf.py openocd`` -Runs OpenOCD in a console with configuration defined in the environment or via command line. -It uses default script directory defined as ``OPENOCD_SCRIPTS`` environmental variable, which is automatically added -from an Export script (``export.sh`` or ``export.bat``). It is possible to override the script location -using command line argument ``--openocd-scripts``. + Runs OpenOCD in a console with configuration defined in the environment or via command line. + It uses default script directory defined as ``OPENOCD_SCRIPTS`` environmental variable, which is automatically added + from an Export script (``export.sh`` or ``export.bat``). It is possible to override the script location + using command line argument ``--openocd-scripts``. -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 ``-f board/esp32-wrover-kit-3.3v.cfg`` board definition. + .. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc + :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. -2. ``idf.py gdb`` +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`` +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 very simple source code view. -4. ``idf.py gdbgui`` +4. ``idf.py gdbgui`` -Starts `gdbgui `_ debugger frontend enabling out-of-the-box debugging in a browser window. + Starts `gdbgui `_ debugger frontend enabling out-of-the-box debugging in a browser window. -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. + 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. -An example of a very useful combination is - - :: + An example of a very useful combination is:: idf.py openocd gdbgui monitor -.. highlight:: none -The above command runs OpenOCD in the background, starts `gdbgui `_ to open a browser window -with active debugger frontend and opens a serial monitor in the active console. + The above command runs OpenOCD in the background, starts `gdbgui `_ to open a browser window + with active debugger frontend and opens a serial monitor in the active console.