1# GDBstub example
2
3This example shows how to use gdbstub and it's functionality at runtime to debug an application with GDB.
4With the gdbstub component it is possible to run GDB from IDF Monitor by pressing Ctrl+C and debug
5the application using GDB. It is also possible to read/modify memory values, interrupt and continue the application.
6Upon exit from GDB, the application will continue to work in IDF Monitor as before.
7
8## How to use example
9### Hardware Required
10
11he example can run on any commonly available ESP32 development board.
12There are two possible ways to execute gdbstub with GDB: from IDF Monitor and as standalone application.
13gdbstub support ESP32, ESP32-S2 and ESP32-S3 chips.
14
15### Configure the project
16
17By default, the example is already pre-configured, but the user can change configuration options with the following command:
18```
19idf.py menuconfig
20```
21Current example is pre-configured. The user can scroll through the system parameters and see the settings.
22Most important one is:
23-> Component Config -> ESP System Settings -> Panic handler behaviour -> GDBStub on runtime
24This selection switches gdbstub to runtime mode.
25Depending on the project, following settings could be used:
26-> Component Config -> GDB Stub -> ...
27The user can enable or disable task list handling and define a maximum amount of tasks.
28Note that gdbstub can now only be used when FreeRTOS is run on the first core only.
29This setting is located here:
30-> Component Config -> FreeRTOS -> Run FreeRTOS only on first core.
31
32### Build and Flash
33
34Build the project and flash it to the board, then run IDF Monitor to view the serial output:
35
36```
37idf.py -p PORT flash monitor
38```
39Replace PORT with the name of the serial port to use, for example COM4 for Windows or /dev/ttyUSB0 for Linux.
40To exit the serial monitor, type ``Ctrl-]``.
41See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
42
43In addition, it is also possible to run GDB and connect to the Esp32 directly, without IDF Monitor.
44```
45xtensa-esp32-elf-gdb ./build/gdbstub.elf -ex "set serial baud 115200" -ex "target remote \\.\COM10"
46```
47This will execute GDB and GDB will connect to your Esp32 by serial port COM10 with baudrate 115200.
48
49## Example Output
50
51The example demonstrates how to switch to GDB, watch values, change values, continue to run, and exit from GDB to the application.
52To switch to GDB, the user presses Ctrl+C. This will stop the application and run the GDB.
53In GDB, the user can print values "print call_count" and "print update_log_level" and then
54change them  "set call_count 100" and "set update_log_level = ESP_LOG_WARN".
55The user can continue running the application in GDB by entering "continue" and then interrupt the application by pressing Ctrl+C.
56The user can check again that the application has worked by checking variable "print call_count".
57The user can exit from GDB to continue seeing the trace from IDF Monitor by pressing "quit" and then "y".
58The user will see in IDF Monitor that call_count and logging level have changed.
59A typical console output for such a scenario is shown below:
60```
61I (300) cpu_start: Starting scheduler on PRO CPU.
62Hello GDB example!
63I (307) gdbstub_example: INFO  mode enabled. Call - 0. To enter GDB please press "Ctrl+C"
64W (317) gdbstub_example: WARN  mode enabled. Call - 0. To enter GDB please press "Ctrl+C"
65I (1317) gdbstub_example: INFO  mode enabled. Call - 1. To enter GDB please press "Ctrl+C"
66W (1317) gdbstub_example: WARN  mode enabled. Call - 1. To enter GDB please press "Ctrl+C"
67To exit from the idf.py please use "Ctrl+]"
68$T02#b6GNU gdb (crosstool-NG esp-2020r3) 8.1.0.20180627-git
69Copyright (C) 2018 Free Software Foundation, Inc.
70License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
71This is free software: you are free to change and redistribute it.
72There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
73and "show warranty" for details.
74This GDB was configured as "--host=x86_64-host_w64-mingw32 --target=xtensa-esp32-elf".
75Type "show configuration" for configuration details.
76For bug reporting instructions, please see:
77<http://www.gnu.org/software/gdb/bugs/>.
78Find the GDB manual and other documentation resources online at:
79<http://www.gnu.org/software/gdb/documentation/>.
80For help, type "help".
81Type "apropos word" to search for commands related to "word"...
82Reading symbols from c:\esp-idf\examples\system\gdbstub\build\gdbstub.elf...done.
83Remote debugging using \\.\COM15
840x400dff0a in esp_pm_impl_waiti () at C:/esp-idf/components/esp_pm/pm_impl.c:533
85533         asm("waiti 0");
86(gdb) print call_count
87$1 = 2
88(gdb) set call_count = 100
89(gdb) print call_count
90$2 = 100
91(gdb) print update_log_level
92$3 = ESP_LOG_DEBUG
93(gdb) set update_log_level = ESP_LOG_WARN
94(gdb) print update_log_level
95$4 = ESP_LOG_WARN
96(gdb) c
97Continuing.
98
99Thread 1 received signal SIGINT, Interrupt.
1000x400dff0a in esp_pm_impl_waiti () at C:/esp-idf/components/esp_pm/pm_impl.c:533
101533         asm("waiti 0");
102(gdb) print call_count
103$6 = 108
104(gdb) quit
105A debugging session is active.
106
107        Inferior 1 [Remote target] will be killed.
108
109Quit anyway? (y or n) y
110W (13977) gdbstub_example: WARN  mode enabled. Call - 108. To enter GDB please press "Ctrl+C"
111W (14977) gdbstub_example: WARN  mode enabled. Call - 109. To enter GDB please press "Ctrl+C"
112W (15977) gdbstub_example: WARN  mode enabled. Call - 110. To enter GDB please press "Ctrl+C"
113W (16977) gdbstub_example: WARN  mode enabled. Call - 111. To enter GDB please press "Ctrl+C"
114```
115
116To reproduce this scenario run the application by: idf.py -P PORT flash monitor
117Then:
1181. Interrupt the application by pressing Ctrl+C
1192. In GDB, print the application values by typing in GDB command line "print call_count" or "print update_log_level"
1203. Modify the application values by typing in GDB command line "set call_count = 100" or "set update_log_level = ESP_LOG_WARN"
1214. Continue the application by typing in GDB command line "continue"
1225. Interrupt application by pressing Ctrl+C
1236. Check the value by typing in GDB command line "print call_count" or "print update_log_level"
1247. Exit GDB by typing "quit" and then "y"
125
126To exit from monitor please use Ctrl+]
127
128