mirror of
https://github.com/espressif/esp-idf.git
synced 2025-08-01 03:34:32 +02:00
doc(esp-idf) | JTAG debugging EN update
This commit is contained in:
zhuying
morris
@@ -1,8 +1,9 @@
|
||||
***************************************
|
||||
Building OpenOCD from Sources for Linux
|
||||
***************************************
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
The following instructions are alternative to downloading binary OpenOCD from Espressif website. To quickly setup the binary OpenOCD, instead of compiling it yourself, backup and proceed to section :doc:`setup-openocd-linux`.
|
||||
The following instructions are alternative to downloading binary OpenOCD from `Espressif GitHub <https://github.com/espressif/openocd-esp32/releases>`_. To quickly setup the binary OpenOCD, instead of compiling it yourself, backup and proceed to section :doc:`setup-openocd-linux`.
|
||||
|
||||
|
||||
.. highlight:: bash
|
||||
|
||||
@@ -1,8 +1,9 @@
|
||||
***************************************
|
||||
Building OpenOCD from Sources for MacOS
|
||||
***************************************
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
The following instructions are alternative to downloading binary OpenOCD from Espressif website. To quickly setup the binary OpenOCD, instead of compiling it yourself, backup and proceed to section :doc:`setup-openocd-macos`.
|
||||
The following instructions are alternative to downloading binary OpenOCD from `Espressif GitHub <https://github.com/espressif/openocd-esp32/releases>`_. To quickly setup the binary OpenOCD, instead of compiling it yourself, backup and proceed to section :doc:`setup-openocd-macos`.
|
||||
|
||||
.. highlight:: bash
|
||||
|
||||
@@ -22,7 +23,7 @@ Install Dependencies
|
||||
|
||||
Install packages that are required to compile OpenOCD using Homebrew::
|
||||
|
||||
brew install automake libtool libusb wget gcc@4.9 pkg-config
|
||||
brew install automake libtool libusb wget gcc@4.9 pkg-config
|
||||
|
||||
Build OpenOCD
|
||||
=============
|
||||
@@ -51,4 +52,4 @@ Next Steps
|
||||
|
||||
To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-esp32-target`.
|
||||
|
||||
|
||||
|
||||
@@ -1,8 +1,9 @@
|
||||
*****************************************
|
||||
Building OpenOCD from Sources for Windows
|
||||
*****************************************
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
The following instructions are alternative to downloading binary OpenOCD from Espressif website. To quickly setup the binary OpenOCD, instead of compiling it yourself, backup and proceed to section :doc:`setup-openocd-windows`.
|
||||
The following instructions are alternative to downloading binary OpenOCD from `Espressif GitHub <https://github.com/espressif/openocd-esp32/releases>`_. To quickly setup the binary OpenOCD, instead of compiling it yourself, backup and proceed to section :doc:`setup-openocd-windows`.
|
||||
|
||||
|
||||
.. highlight:: bash
|
||||
@@ -29,16 +30,16 @@ Install packages that are required to compile OpenOCD:
|
||||
|
||||
::
|
||||
|
||||
pacman -S libtool
|
||||
pacman -S autoconf
|
||||
pacman -S automake
|
||||
pacman -S texinfo
|
||||
pacman -S mingw-w64-i686-libusb-compat-git
|
||||
pacman -S pkg-config
|
||||
pacman -S libtool
|
||||
pacman -S autoconf
|
||||
pacman -S automake
|
||||
pacman -S texinfo
|
||||
pacman -S mingw-w64-i686-libusb-compat-git
|
||||
pacman -S pkg-config
|
||||
|
||||
.. note::
|
||||
|
||||
Installation of ``pkg-config`` is breaking operation of esp-idf toolchain. After building of OpenOCD it should be uninstalled. It be covered at the end of this instruction. To build OpenOCD again, you will need to run ``pacman -S pkg-config`` once more. This issue does not concern other packages installed in this step (before ``pkg-config``).
|
||||
Installation of ``pkg-config`` is breaking operation of esp-idf toolchain. After building of OpenOCD it should be uninstalled. It be covered at the end of this instruction. To build OpenOCD again, you will need to run ``pacman -S pkg-config`` once more. This issue does not concern other packages installed in this step (before ``pkg-config``).
|
||||
|
||||
|
||||
Build OpenOCD
|
||||
@@ -65,7 +66,7 @@ Once ``make`` process is successfully completed, the executable of OpenOCD will
|
||||
|
||||
Remove ``pkg-config``, as discussed during installation of dependencies::
|
||||
|
||||
pacman -Rs pkg-config
|
||||
pacman -Rs pkg-config
|
||||
|
||||
|
||||
Next Steps
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
Configure Other JTAG Interface
|
||||
==============================
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Refer to section :ref:`jtag-debugging-selecting-jtag-adapter` for guidance what JTAG interface to select, so it is able to operate with OpenOCD and ESP32. Then follow three configuration steps below to get it working.
|
||||
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
Configure WROVER JTAG Interface
|
||||
===============================
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
All versions of ESP32 WROVER KIT boards have JTAG functionality build in. Putting it to work requires setting jumpers to enable JTAG functionality, setting SPI flash voltage and configuring USB drivers. Please refer to step by step instructions below.
|
||||
All versions of ESP-WROVER-KIT boards have JTAG functionality build in. Putting it to work requires setting jumpers to enable JTAG functionality, setting SPI flash voltage and configuring USB drivers. Please refer to step by step instructions below.
|
||||
|
||||
|
||||
Configure Hardware
|
||||
@@ -29,17 +30,17 @@ Configure Hardware
|
||||
Configure USB Drivers
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Install and configure USB drivers, so OpenOCD is able to communicate with JTAG interface on ESP32 WROVER KIT board as well as with UART interface used to upload application for flash. Follow steps below specific to your operating system.
|
||||
Install and configure USB drivers, so OpenOCD is able to communicate with JTAG interface on ESP-WROVER-KIT board as well as with UART interface used to upload application for flash. Follow steps below specific to your operating system.
|
||||
|
||||
.. note:: ESP32 WROVER KIT uses an FT2232 adapter. The following instructions can also be used for other FT2232 based JTAG adapters.
|
||||
.. note:: ESP-WROVER-KIT uses an FT2232 adapter. The following instructions can also be used for other FT2232 based JTAG adapters.
|
||||
|
||||
|
||||
Windows
|
||||
"""""""
|
||||
|
||||
1. Using standard USB A / micro USB B cable connect ESP32 WROVER KIT to the computer. Switch the WROVER KIT on.
|
||||
1. Using standard USB A / micro USB B cable connect ESP-WROVER-KIT to the computer. Switch the WROVER KIT on.
|
||||
|
||||
2. Wait until USB ports of WROVER KIT are recognized by Windows and drives are installed. If they do not install automatically, then then download them from http://www.ftdichip.com/Drivers/D2XX.htm and install manually.
|
||||
2. Wait until USB ports of WROVER KIT are recognized by Windows and drives are installed. If they do not install automatically, then download them from http://www.ftdichip.com/Drivers/D2XX.htm and install manually.
|
||||
|
||||
3. Download Zadig tool (Zadig_X.X.exe) from http://zadig.akeo.ie/ and run it.
|
||||
|
||||
@@ -60,13 +61,13 @@ Windows
|
||||
|
||||
Do not change the second device "Dual RS232-HS (Interface 1)". It is routed to ESP32's serial port (UART) used for upload of application to ESP32's flash.
|
||||
|
||||
Now ESP32 WROVER KIT's JTAG interface should be available to the OpenOCD. To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-run-openocd`.
|
||||
Now ESP-WROVER-KIT's JTAG interface should be available to the OpenOCD. To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-run-openocd`.
|
||||
|
||||
|
||||
Linux
|
||||
"""""
|
||||
|
||||
1. Using standard USB A / micro USB B cable connect ESP32 WROVER KIT board to the computer. Power on the board.
|
||||
1. Using standard USB A / micro USB B cable connect ESP-WROVER-KIT board to the computer. Power on the board.
|
||||
|
||||
.. highlight:: none
|
||||
|
||||
@@ -79,7 +80,7 @@ Linux
|
||||
crw-rw---- 1 root dialout 188, 1 Jul 10 19:04 /dev/ttyUSB1
|
||||
|
||||
|
||||
3. Following section "Permissions delegation" in OpenOCD's README, set up the access permissions to both USB ports.
|
||||
3. Following section "Permissions delegation" in `OpenOCD's README <https://sourceforge.net/p/openocd/code/ci/master/tree/README>`_, set up the access permissions to both USB ports.
|
||||
|
||||
4. Log off and login, then cycle the power to the board to make the changes effective. In terminal enter again ``ls -l /dev/ttyUSB*`` command to verify, if group-owner has changed from ``dialout`` to ``plugdev``:
|
||||
|
||||
@@ -93,13 +94,13 @@ Linux
|
||||
|
||||
The ``/dev/ttyUSBn`` interface with lower number is used for JTAG communication. The other interface is routed to ESP32's serial port (UART) used for upload of application to ESP32's flash.
|
||||
|
||||
Now ESP32 WROVER KIT's JTAG interface should be available to the OpenOCD. To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-run-openocd`.
|
||||
Now ESP-WROVER-KIT's JTAG interface should be available to the OpenOCD. To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-run-openocd`.
|
||||
|
||||
|
||||
MacOS
|
||||
"""""
|
||||
|
||||
On macOS, using FT2232 for JTAG and serial port at the same time needs some additional steps. When the OS loads FTDI serial port driver, it does so for both channels of FT2232 chip. However only one of these channels is used as a serial port, while the other is used as JTAG. If the OS has loaded FTDI serial port driver for the channel used for JTAG, OpenOCD will not be able to connect to to the chip. There are two ways around this:
|
||||
On macOS, using FT2232 for JTAG and serial port at the same time needs some additional steps. When the OS loads FTDI serial port driver, it does so for both channels of FT2232 chip. However only one of these channels is used as a serial port, while the other is used as JTAG. If the OS has loaded FTDI serial port driver for the channel used for JTAG, OpenOCD will not be able to connect to the chip. There are two ways around this:
|
||||
|
||||
1. Manually unload the FTDI serial port driver before starting OpenOCD, start OpenOCD, then load the serial port driver.
|
||||
|
||||
@@ -195,4 +196,3 @@ In a nutshell, this approach requires modification to FTDI driver configuration
|
||||
After these steps, serial port and JTAG can be used at the same time.
|
||||
|
||||
To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-run-openocd`.
|
||||
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
Debugging Examples
|
||||
==================
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
This section describes debugging with GDB from :ref:`jtag-debugging-examples-eclipse` as well as from :ref:`jtag-debugging-examples-command-line`.
|
||||
|
||||
@@ -34,8 +35,8 @@ Examples in this section
|
||||
|
||||
.. _jtag-debugging-examples-eclipse-01:
|
||||
|
||||
Navigating though the code, call stack and threads
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Navigating through the code, call stack and threads
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
When the target is halted, debugger shows the list of threads in "Debug" window. The line of code where program halted is highlighted in another window below, as shown on the following picture. The LED stops blinking.
|
||||
|
||||
@@ -59,7 +60,7 @@ By expanding threads you can navigate throughout the application. Expand Thread
|
||||
|
||||
In another window on right, you can see the disassembled machine code no matter if your project provides it in source or only the binary form.
|
||||
|
||||
Go back to the ``app_main()`` in Thread #1 to familiar code of ``blink.c`` file that will be examined in more details in the following examples. Debugger makes it easy to navigate through the code of entire application. This comes handy when stepping though the code and working with breakpoints and will be discussed below.
|
||||
Go back to the ``app_main()`` in Thread #1 to familiar code of ``blink.c`` file that will be examined in more details in the following examples. Debugger makes it easy to navigate through the code of entire application. This comes handy when stepping through the code and working with breakpoints and will be discussed below.
|
||||
|
||||
|
||||
.. _jtag-debugging-examples-eclipse-02:
|
||||
@@ -163,7 +164,7 @@ Now resume program by pressing F8 and observe "Monitor" tab.
|
||||
:alt: Observing memory location 0x3FF44004 changing one bit to ON"
|
||||
:figclass: align-center
|
||||
|
||||
Observing memory location 0x3FF44004 changing one bit to ON"
|
||||
Observing memory location 0x3FF44004 changing one bit to "ON"
|
||||
|
||||
You should see one bit being flipped over at memory location ``0x3FF44004`` (and LED changing the state) each time F8 is pressed.
|
||||
|
||||
@@ -172,7 +173,7 @@ You should see one bit being flipped over at memory location ``0x3FF44004`` (and
|
||||
:alt: Observing memory location 0x3FF44004 changing one bit to ON"
|
||||
:figclass: align-center
|
||||
|
||||
Observing memory location 0x3FF44004 changing one bit to ON"
|
||||
Observing memory location 0x3FF44004 changing one bit to "OFF"
|
||||
|
||||
To set memory use the same "Monitor" tab and the same memory location. Type in alternate bit pattern as previously observed. Immediately after pressing enter you will see LED changing the state.
|
||||
|
||||
@@ -182,7 +183,7 @@ To set memory use the same "Monitor" tab and the same memory location. Type in a
|
||||
Watching and setting program variables
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
A common debugging tasks is checking the value of a program variable as the program runs. To be able to demonstrate this functionality, update file ``blink.c`` by adding a declaration of a global variable ``int i`` above definition of function ``blink_task``. Then add ``i++`` inside ``loop(1)`` of this function to get ``i`` incremented on each blink.
|
||||
A common debugging tasks is checking the value of a program variable as the program runs. To be able to demonstrate this functionality, update file ``blink.c`` by adding a declaration of a global variable ``int i`` above definition of function ``blink_task``. Then add ``i++`` inside ``while(1)`` of this function to get ``i`` incremented on each blink.
|
||||
|
||||
Exit debugger, so it is not confused with new code, build and flash the code to the ESP and restart debugger. There is no need to restart OpenOCD.
|
||||
|
||||
@@ -227,9 +228,9 @@ Command Line
|
||||
|
||||
Verify if your target is ready and loaded with :example:`get-started/blink` example. Configure and start debugger following steps in section :ref:`jtag-debugging-using-debugger-command-line`. Pick up where target was left by debugger, i.e. having the application halted at breakpoint established at ``app_main()``::
|
||||
|
||||
Temporary breakpoint 1, app_main () at /home/user-name/esp/blink/main/./blink.c:43
|
||||
43 xTaskCreate(&blink_task, "blink_task", configMINIMAL_STACK_SIZE, NULL, 5, NULL);
|
||||
(gdb)
|
||||
Temporary breakpoint 1, app_main () at /home/user-name/esp/blink/main/./blink.c:43
|
||||
43 xTaskCreate(&blink_task, "blink_task", configMINIMAL_STACK_SIZE, NULL, 5, NULL);
|
||||
(gdb)
|
||||
|
||||
|
||||
|
||||
@@ -247,123 +248,123 @@ Examples in this section
|
||||
|
||||
.. _jtag-debugging-examples-command-line-01:
|
||||
|
||||
Navigating though the code, call stack and threads
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Navigating through the code, call stack and threads
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
When you see the ``(gdb)`` prompt, the application is halted. LED should not be blinking.
|
||||
|
||||
To find out where exactly the code is halted, enter ``l`` or ``list``, and debugger will show couple of lines of code around the halt point (line 43 of code in file ``blink.c``) ::
|
||||
|
||||
(gdb) l
|
||||
38 }
|
||||
39 }
|
||||
40
|
||||
41 void app_main()
|
||||
42 {
|
||||
43 xTaskCreate(&blink_task, "blink_task", configMINIMAL_STACK_SIZE, NULL, 5, NULL);
|
||||
44 }
|
||||
(gdb)
|
||||
(gdb) l
|
||||
38 }
|
||||
39 }
|
||||
40
|
||||
41 void app_main()
|
||||
42 {
|
||||
43 xTaskCreate(&blink_task, "blink_task", configMINIMAL_STACK_SIZE, NULL, 5, NULL);
|
||||
44 }
|
||||
(gdb)
|
||||
|
||||
|
||||
Check how code listing works by entering, e.g. ``l 30, 40`` to see particular range of lines of code.
|
||||
|
||||
You can use ``bt`` or ``backtrace`` to see what function calls lead up to this code::
|
||||
|
||||
(gdb) bt
|
||||
#0 app_main () at /home/user-name/esp/blink/main/./blink.c:43
|
||||
#1 0x400d057e in main_task (args=0x0) at /home/user-name/esp/esp-idf/components/esp32/./cpu_start.c:339
|
||||
(gdb)
|
||||
(gdb) bt
|
||||
#0 app_main () at /home/user-name/esp/blink/main/./blink.c:43
|
||||
#1 0x400d057e in main_task (args=0x0) at /home/user-name/esp/esp-idf/components/esp32/./cpu_start.c:339
|
||||
(gdb)
|
||||
|
||||
Line #0 of output provides the last function call before the application halted, i.e. ``app_main ()`` we have listed previously. The ``app_main ()`` was in turn called by function ``main_task`` from line 339 of code located in file ``cpu_start.c``.
|
||||
|
||||
To get to the context of ``main_task`` in file ``cpu_start.c``, enter ``frame N``, where N = 1, because the ``main_task`` is listed under #1)::
|
||||
|
||||
(gdb) frame 1
|
||||
#1 0x400d057e in main_task (args=0x0) at /home/user-name/esp/esp-idf/components/esp32/./cpu_start.c:339
|
||||
339 app_main();
|
||||
(gdb)
|
||||
(gdb) frame 1
|
||||
#1 0x400d057e in main_task (args=0x0) at /home/user-name/esp/esp-idf/components/esp32/./cpu_start.c:339
|
||||
339 app_main();
|
||||
(gdb)
|
||||
|
||||
Enter ``l`` and this will reveal the piece of code that called ``app_main()`` (in line 339)::
|
||||
|
||||
(gdb) l
|
||||
334 ;
|
||||
335 }
|
||||
336 #endif
|
||||
337 //Enable allocation in region where the startup stacks were located.
|
||||
338 heap_caps_enable_nonos_stack_heaps();
|
||||
339 app_main();
|
||||
340 vTaskDelete(NULL);
|
||||
341 }
|
||||
342
|
||||
(gdb)
|
||||
(gdb) l
|
||||
334 ;
|
||||
335 }
|
||||
336 #endif
|
||||
337 //Enable allocation in region where the startup stacks were located.
|
||||
338 heap_caps_enable_nonos_stack_heaps();
|
||||
339 app_main();
|
||||
340 vTaskDelete(NULL);
|
||||
341 }
|
||||
342
|
||||
(gdb)
|
||||
|
||||
By listing some lines before, you will see the function name ``main_task`` we have been looking for::
|
||||
|
||||
(gdb) l 326, 341
|
||||
326 static void main_task(void* args)
|
||||
327 {
|
||||
328 // Now that the application is about to start, disable boot watchdogs
|
||||
329 REG_CLR_BIT(TIMG_WDTCONFIG0_REG(0), TIMG_WDT_FLASHBOOT_MOD_EN_S);
|
||||
330 REG_CLR_BIT(RTC_CNTL_WDTCONFIG0_REG, RTC_CNTL_WDT_FLASHBOOT_MOD_EN);
|
||||
331 #if !CONFIG_FREERTOS_UNICORE
|
||||
332 // Wait for FreeRTOS initialization to finish on APP CPU, before replacing its startup stack
|
||||
333 while (port_xSchedulerRunning[1] == 0) {
|
||||
334 ;
|
||||
335 }
|
||||
336 #endif
|
||||
337 //Enable allocation in region where the startup stacks were located.
|
||||
338 heap_caps_enable_nonos_stack_heaps();
|
||||
339 app_main();
|
||||
340 vTaskDelete(NULL);
|
||||
341 }
|
||||
(gdb)
|
||||
(gdb) l 326, 341
|
||||
326 static void main_task(void* args)
|
||||
327 {
|
||||
328 // Now that the application is about to start, disable boot watchdogs
|
||||
329 REG_CLR_BIT(TIMG_WDTCONFIG0_REG(0), TIMG_WDT_FLASHBOOT_MOD_EN_S);
|
||||
330 REG_CLR_BIT(RTC_CNTL_WDTCONFIG0_REG, RTC_CNTL_WDT_FLASHBOOT_MOD_EN);
|
||||
331 #if !CONFIG_FREERTOS_UNICORE
|
||||
332 // Wait for FreeRTOS initialization to finish on APP CPU, before replacing its startup stack
|
||||
333 while (port_xSchedulerRunning[1] == 0) {
|
||||
334 ;
|
||||
335 }
|
||||
336 #endif
|
||||
337 //Enable allocation in region where the startup stacks were located.
|
||||
338 heap_caps_enable_nonos_stack_heaps();
|
||||
339 app_main();
|
||||
340 vTaskDelete(NULL);
|
||||
341 }
|
||||
(gdb)
|
||||
|
||||
To see the other code, enter ``i threads``. This will show the list of threads running on target::
|
||||
|
||||
(gdb) i threads
|
||||
Id Target Id Frame
|
||||
8 Thread 1073411336 (dport) 0x400d0848 in dport_access_init_core (arg=<optimized out>)
|
||||
at /home/user-name/esp/esp-idf/components/esp32/./dport_access.c:170
|
||||
7 Thread 1073408744 (ipc0) xQueueGenericReceive (xQueue=0x3ffae694, pvBuffer=0x0, xTicksToWait=1644638200,
|
||||
xJustPeeking=0) at /home/user-name/esp/esp-idf/components/freertos/./queue.c:1452
|
||||
6 Thread 1073431096 (Tmr Svc) prvTimerTask (pvParameters=0x0)
|
||||
at /home/user-name/esp/esp-idf/components/freertos/./timers.c:445
|
||||
5 Thread 1073410208 (ipc1 : Running) 0x4000bfea in ?? ()
|
||||
4 Thread 1073432224 (dport) dport_access_init_core (arg=0x0)
|
||||
at /home/user-name/esp/esp-idf/components/esp32/./dport_access.c:150
|
||||
3 Thread 1073413156 (IDLE) prvIdleTask (pvParameters=0x0)
|
||||
at /home/user-name/esp/esp-idf/components/freertos/./tasks.c:3282
|
||||
2 Thread 1073413512 (IDLE) prvIdleTask (pvParameters=0x0)
|
||||
at /home/user-name/esp/esp-idf/components/freertos/./tasks.c:3282
|
||||
* 1 Thread 1073411772 (main : Running) app_main () at /home/user-name/esp/blink/main/./blink.c:43
|
||||
(gdb)
|
||||
(gdb) i threads
|
||||
Id Target Id Frame
|
||||
8 Thread 1073411336 (dport) 0x400d0848 in dport_access_init_core (arg=<optimized out>)
|
||||
at /home/user-name/esp/esp-idf/components/esp32/./dport_access.c:170
|
||||
7 Thread 1073408744 (ipc0) xQueueGenericReceive (xQueue=0x3ffae694, pvBuffer=0x0, xTicksToWait=1644638200,
|
||||
xJustPeeking=0) at /home/user-name/esp/esp-idf/components/freertos/./queue.c:1452
|
||||
6 Thread 1073431096 (Tmr Svc) prvTimerTask (pvParameters=0x0)
|
||||
at /home/user-name/esp/esp-idf/components/freertos/./timers.c:445
|
||||
5 Thread 1073410208 (ipc1 : Running) 0x4000bfea in ?? ()
|
||||
4 Thread 1073432224 (dport) dport_access_init_core (arg=0x0)
|
||||
at /home/user-name/esp/esp-idf/components/esp32/./dport_access.c:150
|
||||
3 Thread 1073413156 (IDLE) prvIdleTask (pvParameters=0x0)
|
||||
at /home/user-name/esp/esp-idf/components/freertos/./tasks.c:3282
|
||||
2 Thread 1073413512 (IDLE) prvIdleTask (pvParameters=0x0)
|
||||
at /home/user-name/esp/esp-idf/components/freertos/./tasks.c:3282
|
||||
* 1 Thread 1073411772 (main : Running) app_main () at /home/user-name/esp/blink/main/./blink.c:43
|
||||
(gdb)
|
||||
|
||||
The thread list shows the last function calls per each thread together with the name of C source file if available.
|
||||
|
||||
You can navigate to specific thread by entering ``thread N``, where ``N`` is the thread Id. To see how it works go to thread thread 5::
|
||||
|
||||
(gdb) thread 5
|
||||
[Switching to thread 5 (Thread 1073410208)]
|
||||
#0 0x4000bfea in ?? ()
|
||||
(gdb)
|
||||
(gdb) thread 5
|
||||
[Switching to thread 5 (Thread 1073410208)]
|
||||
#0 0x4000bfea in ?? ()
|
||||
(gdb)
|
||||
|
||||
Then check the backtrace::
|
||||
|
||||
(gdb) bt
|
||||
#0 0x4000bfea in ?? ()
|
||||
#1 0x40083a85 in vPortCPUReleaseMutex (mux=<optimized out>) at /home/user-name/esp/esp-idf/components/freertos/./port.c:415
|
||||
#2 0x40083fc8 in vTaskSwitchContext () at /home/user-name/esp/esp-idf/components/freertos/./tasks.c:2846
|
||||
#3 0x4008532b in _frxt_dispatch ()
|
||||
#4 0x4008395c in xPortStartScheduler () at /home/user-name/esp/esp-idf/components/freertos/./port.c:222
|
||||
#5 0x4000000c in ?? ()
|
||||
#6 0x4000000c in ?? ()
|
||||
#7 0x4000000c in ?? ()
|
||||
#8 0x4000000c in ?? ()
|
||||
(gdb)
|
||||
(gdb) bt
|
||||
#0 0x4000bfea in ?? ()
|
||||
#1 0x40083a85 in vPortCPUReleaseMutex (mux=<optimized out>) at /home/user-name/esp/esp-idf/components/freertos/./port.c:415
|
||||
#2 0x40083fc8 in vTaskSwitchContext () at /home/user-name/esp/esp-idf/components/freertos/./tasks.c:2846
|
||||
#3 0x4008532b in _frxt_dispatch ()
|
||||
#4 0x4008395c in xPortStartScheduler () at /home/user-name/esp/esp-idf/components/freertos/./port.c:222
|
||||
#5 0x4000000c in ?? ()
|
||||
#6 0x4000000c in ?? ()
|
||||
#7 0x4000000c in ?? ()
|
||||
#8 0x4000000c in ?? ()
|
||||
(gdb)
|
||||
|
||||
As you see, the backtrace may contain several entries. This will let you check what exact sequence of function calls lead to the code where the target halted. Question marks ``??`` instead of a function name indicate that application is available only in binary format, without any source file in C language. The value like ``0x4000bfea`` is the memory address of the function call.
|
||||
|
||||
Using ``bt``, ``i threads``, ``thread N`` and ``list`` commands we are now able to navigate through the code of entire application. This comes handy when stepping though the code and working with breakpoints and will be discussed below.
|
||||
Using ``bt``, ``i threads``, ``thread N`` and ``list`` commands we are now able to navigate through the code of entire application. This comes handy when stepping through the code and working with breakpoints and will be discussed below.
|
||||
|
||||
|
||||
.. _jtag-debugging-examples-command-line-02:
|
||||
@@ -430,22 +431,22 @@ When debugging, you may resume application and enter code waiting for some event
|
||||
|
||||
To check it delete all breakpoints and enter ``c`` to resume application. Then enter Ctrl+C. Application will be halted at some random point and LED will stop blinking. Debugger will print the following::
|
||||
|
||||
(gdb) c
|
||||
Continuing.
|
||||
^CTarget halted. PRO_CPU: PC=0x400D0C00 APP_CPU: PC=0x400D0C00 (active)
|
||||
[New Thread 1073433352]
|
||||
(gdb) c
|
||||
Continuing.
|
||||
^CTarget halted. PRO_CPU: PC=0x400D0C00 APP_CPU: PC=0x400D0C00 (active)
|
||||
[New Thread 1073433352]
|
||||
|
||||
Program received signal SIGINT, Interrupt.
|
||||
[Switching to Thread 1073413512]
|
||||
0x400d0c00 in esp_vApplicationIdleHook () at /home/user-name/esp/esp-idf/components/esp32/./freertos_hooks.c:52
|
||||
52 asm("waiti 0");
|
||||
(gdb)
|
||||
Program received signal SIGINT, Interrupt.
|
||||
[Switching to Thread 1073413512]
|
||||
0x400d0c00 in esp_vApplicationIdleHook () at /home/user-name/esp/esp-idf/components/esp32/./freertos_hooks.c:52
|
||||
52 asm("waiti 0");
|
||||
(gdb)
|
||||
|
||||
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.
|
||||
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:
|
||||
@@ -556,7 +557,7 @@ You should see the LED to turn on immediately after entering ``set {unsigned int
|
||||
Watching and setting program variables
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
A common debugging tasks is checking the value of a program variable as the program runs. To be able to demonstrate this functionality, update file ``blink.c`` by adding a declaration of a global variable ``int i`` above definition of function ``blink_task``. Then add ``i++`` inside ``loop(1)`` of this function to get ``i`` incremented on each blink.
|
||||
A common debugging tasks is checking the value of a program variable as the program runs. To be able to demonstrate this functionality, update file ``blink.c`` by adding a declaration of a global variable ``int i`` above definition of function ``blink_task``. Then add ``i++`` inside ``while(1)`` of this function to get ``i`` incremented on each blink.
|
||||
|
||||
Exit debugger, so it is not confused with new code, build and flash the code to the ESP and restart debugger. There is no need to restart OpenOCD.
|
||||
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
JTAG Debugging
|
||||
==============
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
This document provides a guide to installing OpenOCD for ESP32 and debugging using
|
||||
GDB. The document is structured as follows:
|
||||
@@ -59,7 +60,7 @@ Under "Application Loading and Monitoring" there is another software and hardwar
|
||||
|
||||
Debugging using JTAG and application loading / monitoring is integrated under the `Eclipse <https://www.eclipse.org/>`_ environment, to provide quick and easy transition from writing, compiling and loading the code to debugging, back to writing the code, and so on. All the software is available for Windows, Linux and MacOS platforms.
|
||||
|
||||
If the :doc:`ESP32 WROVER KIT <../../hw-reference/modules-and-boards>` is used, then connection from PC to ESP32 is done effectively with a single USB cable thanks to FT2232H chip installed on WROVER, which provides two USB channels, one for JTAG and the second for UART connection.
|
||||
If the :doc:`ESP-WROVER-KIT <../../hw-reference/modules-and-boards>` is used, then connection from PC to ESP32 is done effectively with a single USB cable thanks to FT2232H chip installed on WROVER, which provides two USB channels, one for JTAG and the second for UART connection.
|
||||
|
||||
Depending on user preferences, both `debugger` and `make` can be operated directly from terminal / command line, instead from Eclipse.
|
||||
|
||||
@@ -69,11 +70,11 @@ Depending on user preferences, both `debugger` and `make` can be operated direct
|
||||
Selecting JTAG Adapter
|
||||
----------------------
|
||||
|
||||
The quickest and most convenient way to start with JTAG debugging is by using :doc:`ESP32 WROVER KIT <../../hw-reference/modules-and-boards>`. Each version of this development board has JTAG interface already build in. No need for an external JTAG adapter and extra wiring / cable to connect JTAG to ESP32. WROVER KIT is using FT2232H JTAG interface operating at 20 MHz clock speed, which is difficult to achieve with an external adapter.
|
||||
The quickest and most convenient way to start with JTAG debugging is by using :doc:`ESP-WROVER-KIT <../../hw-reference/modules-and-boards>`. Each version of this development board has JTAG interface already build in. No need for an external JTAG adapter and extra wiring / cable to connect JTAG to ESP32. WROVER KIT is using FT2232H JTAG interface operating at 20 MHz clock speed, which is difficult to achieve with an external adapter.
|
||||
|
||||
If you decide to use separate JTAG adapter, look for one that is compatible with both the voltage levels on the ESP32 as well as with the OpenOCD software. The JTAG port on the ESP32 is an industry-standard JTAG port which lacks (and does not need) the TRST pin. The JTAG I/O pins all are powered from the VDD_3P3_RTC pin (which normally would be powered by a 3.3V rail) so the JTAG adapter needs to be able to work with JTAG pins in that voltage range.
|
||||
If you decide to use separate JTAG adapter, look for one that is compatible with both the voltage levels on the ESP32 as well as with the OpenOCD software. The JTAG port on the ESP32 is an industry-standard JTAG port which lacks (and does not need) the TRST pin. The JTAG I/O pins all are powered from the VDD_3P3_RTC pin (which normally would be powered by a 3.3 V rail) so the JTAG adapter needs to be able to work with JTAG pins in that voltage range.
|
||||
|
||||
On the software side, OpenOCD supports a fair amount of JTAG adapters. See http://openocd.org/doc/html/Debug-Adapter-Hardware.html for an (unfortunately slightly incomplete) list of the adapters OpenOCD works with. This page lists SWD-compatible adapters as well; take note that the ESP32 does not support SWD. JTAG adapters that are hardcoded to a specific product line, e.g. STM32 debugging adapters, will not work.
|
||||
On the software side, OpenOCD supports a fair amount of JTAG adapters. See http://openocd.org/doc/html/Debug-Adapter-Hardware.html for an (unfortunately slightly incomplete) list of the adapters OpenOCD works with. This page lists SWD-compatible adapters as well; take note that the ESP32 does not support SWD. JTAG adapters that are hardcoded to a specific product line, e.g. ST-LINK debugging adapters for STM32 families, will not work.
|
||||
|
||||
The minimal signalling to get a working JTAG connection are TDI, TDO, TCK, TMS and GND. Some JTAG debuggers also need a connection from the ESP32 power line to a line called e.g. Vtar to set the working voltage. SRST can optionally be connected to the CH_PD of the ESP32, although for now, support in OpenOCD for that line is pretty minimal.
|
||||
|
||||
@@ -169,7 +170,7 @@ Open terminal, go to directory where OpenOCD is installed and start it up::
|
||||
|
||||
.. highlight:: none
|
||||
|
||||
You should now see similar output (this log is for ESP32 WROVER KIT)::
|
||||
You should now see similar output (this log is for ESP-WROVER-KIT)::
|
||||
|
||||
user-name@computer-name:~/esp/openocd-esp32$ bin/openocd -s share/openocd/scripts -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg
|
||||
Open On-Chip Debugger 0.10.0-dev-ged7b1a9 (2017-07-10-07:16)
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
************************
|
||||
Set up OpenOCD for Linux
|
||||
************************
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Set up OpenOCD
|
||||
==============
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
************************
|
||||
Set up OpenOCD for MacOS
|
||||
************************
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Install libusb
|
||||
==============
|
||||
|
||||
@@ -1,13 +1,14 @@
|
||||
**************************
|
||||
Set up OpenOCD for Windows
|
||||
**************************
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
IDF Tools Installer
|
||||
===================
|
||||
|
||||
If you are using CMake build system and followed the :doc:`/get-started-cmake/windows-setup` with the ``ESP-IDF Tools Installer`` V1.2 or newer, then by default you will already have ``openocd`` installed.
|
||||
|
||||
``ESP-IDF Tools Installer`` adds ``openocd` to the ``PATH`` so that it can be run from any directory.
|
||||
``ESP-IDF Tools Installer`` adds ``openocd`` to the ``PATH`` so that it can be run from any directory.
|
||||
|
||||
Set up OpenOCD
|
||||
==============
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
Tips and Quirks
|
||||
---------------
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
This section provides collection of all tips and quirks referred to from various parts of this guide.
|
||||
|
||||
@@ -54,7 +55,7 @@ Support options for OpenOCD at compile time
|
||||
|
||||
ESP-IDF has some support options for OpenOCD debugging which can be set at compile time:
|
||||
|
||||
* :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` is enabled by default. If a panic or unhandled exception is thrown and a JTAG debugger is connected (ie openocd is running), ESP-IDF will break into the debugger.
|
||||
* :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` is enabled by default. If a panic or unhandled exception is thrown and a JTAG debugger is connected (ie OpenOCD is running), ESP-IDF will break into the debugger.
|
||||
* :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` (disabled by default) sets watchpoint index 1 (the second of two) at the end of any task stack. This is the most accurate way to debug task stack overflows. Click the link for more details.
|
||||
|
||||
Please see the :ref:`make menuconfig <get-started-configure>` menu for more details on setting compile-time options.
|
||||
@@ -72,11 +73,11 @@ OpenOCD has explicit support for the ESP-IDF FreeRTOS. GDB can see FreeRTOS task
|
||||
Why to set SPI flash voltage in OpenOCD configuration?
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The MTDI pin of ESP32, being among four pins used for JTAG communication, is also one of ESP32's bootstrapping pins. On power up ESP32 is sampling binary level on MTDI to set it's internal voltage regulator used to supply power to external SPI flash chip. If binary level on MDTI pin on power up is low, the voltage regulator is set to deliver 3.3V, if it is high, then the voltage is set to 1.8V. The MTDI pin should have a pull-up or may rely on internal weak pull down resistor (see ESP32 Datasheet for details), depending on the type of SPI chip used. Once JTAG is connected, it overrides the pull-up or pull-down resistor that is supposed to do the bootstrapping.
|
||||
The MTDI pin of ESP32, being among four pins used for JTAG communication, is also one of ESP32's bootstrapping pins. On power up ESP32 is sampling binary level on MTDI to set it's internal voltage regulator used to supply power to external SPI flash chip. If binary level on MDTI pin on power up is low, the voltage regulator is set to deliver 3.3 V, if it is high, then the voltage is set to 1.8 V. The MTDI pin should have a pull-up or may rely on internal weak pull down resistor (see `ESP32 Series Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ for details), depending on the type of SPI chip used. Once JTAG is connected, it overrides the pull-up or pull-down resistor that is supposed to do the bootstrapping.
|
||||
|
||||
To handle this issue OpenOCD's board configuration file (e.g. ``boards\esp-wroom-32.cfg`` for ESP32-WROOM-32 module) provides ``ESP32_FLASH_VOLTAGE`` parameter to set the idle state of the ``TDO`` line to a specified binary level, therefore reducing the chance of a bad bootup of application due to incorrect flash voltage.
|
||||
|
||||
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.3V flash, while WROVER modules use 1.8V flash.
|
||||
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:
|
||||
@@ -160,7 +161,7 @@ Power supply voltage of ESP32's SPI flash chip
|
||||
|
||||
set ESP32_FLASH_VOLTAGE 1.8
|
||||
|
||||
Comment out this line to set 3.3V, ref: :ref:`jtag-debugging-tip-code-flash-voltage`
|
||||
Comment out this line to set 3.3 V, ref: :ref:`jtag-debugging-tip-code-flash-voltage`
|
||||
|
||||
|
||||
Configuration file for ESP32 targets
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
Using Debugger
|
||||
--------------
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
This section covers configuration and running debugger either from :ref:`jtag-debugging-using-debugger-eclipse`
|
||||
or :ref:`jtag-debugging-using-debugger-command-line`. It is recommended to first check if debugger works from :ref:`jtag-debugging-using-debugger-command-line` and then move to using Eclipse.
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
******************************
|
||||
Linux 环境下从源码编译 OpenOCD
|
||||
******************************
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
除了从 `Espressif 官方 <https://github.com/espressif/openocd-esp32/releases>`_ 直接下载 OpenOCD 可执行文件，你还可以选择从源码编译得到 OpenOCD。如果想要快速设置 OpenOCD 而不是自行编译，请备份好当前文件，前往 :doc:`setup-openocd-linux` 章节查阅。
|
||||
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
******************************
|
||||
MacOS 环境下从源码编译 OpenOCD
|
||||
******************************
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
除了从 `Espressif 官方 <https://github.com/espressif/openocd-esp32/releases>`_ 直接下载 OpenOCD 可执行文件，你还可以选择从源码编译得到 OpenOCD。如果想要快速设置 OpenOCD 而不是自行编译，请备份好当前文件，前往 :doc:`setup-openocd-macos` 章节查阅。
|
||||
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
********************************
|
||||
Windows 环境下从源码编译 OpenOCD
|
||||
********************************
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
除了从 `Espressif 官方 <https://github.com/espressif/openocd-esp32/releases>`_ 直接下载 OpenOCD 可执行文件，你还可以选择从源码编译得到 OpenOCD。如果想要快速设置 OpenOCD 而不是自行编译，请备份好当前文件，前往 :doc:`setup-openocd-windows` 章节查阅。
|
||||
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
配置其它 JTAG 接口
|
||||
==================
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
关于适配 OpenOCD 和 ESP32 的 JTAG 接口选择问题，请参考 :ref:`jtag-debugging-selecting-jtag-adapter` 章节，确保 JTAG 适配器能够与 OpenOCD 和 ESP32 一同工作。然后按照以下三个步骤进行设置，使其正常工作。
|
||||
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
配置 WROVER 上的 JTAG 接口
|
||||
==========================
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
所有版本的 ESP-WROVER-KIT 板子都内置了 JTAG 调试功能，要使其正常工作，还需要设置相关跳帽来启用 JTAG 功能，设置 SPI 闪存电压和配置 USB 驱动程序。具体步骤请参考以下说明。
|
||||
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
调试示例
|
||||
========
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
本节将介绍如何在 :ref:`Eclipse <jtag-debugging-examples-eclipse>` 和 :ref:`命令行 <jtag-debugging-examples-command-line>` 中使用 GDB 进行调试的示例。
|
||||
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
JTAG 调试
|
||||
=========
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
本文将指导安装 ESP32 的 OpenOCD 调试环境，并介绍如何使用 GDB 来调试 ESP32 的应用程序。本文的组织结构如下：
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
***************************
|
||||
在 Linux 环境下安装 OpenOCD
|
||||
***************************
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
安装 OpenOCD
|
||||
============
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
***************************
|
||||
在 MacOS 环境下安装 OpenOCD
|
||||
***************************
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
安装 libusb
|
||||
===========
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
*****************************
|
||||
在 Windows 环境下安装 OpenOCD
|
||||
*****************************
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
IDF 工具安装程序
|
||||
================
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
注意事项和补充内容
|
||||
------------------
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
本节提供了本指南中各部分提到的一些注意事项和补充内容。
|
||||
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
使用调试器
|
||||
----------
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
本节会在 :ref:`Eclipse <jtag-debugging-using-debugger-eclipse>` 和 :ref:`命令行 <jtag-debugging-using-debugger-command-line>` 中分别介绍配置和运行调试器的方法。我们建议你首先通过 :ref:`命令行 <jtag-debugging-using-debugger-command-line>` 检查调试器是否正常工作，然后再转到使用 :ref:`Eclipse <jtag-debugging-using-debugger-eclipse>` 平台。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user