|
| 1 | + |
| 2 | +GDBSTUB |
| 3 | +======= |
| 4 | + |
| 5 | +Intro |
| 6 | +----- |
| 7 | + |
| 8 | +While the ESP8266 supports the standard Gnu set of C programming utilities, for now the choice of debuggers |
| 9 | +has been limited: there is an attempt at [OpenOCD support](https://github.com/projectgus/openocd), but at |
| 10 | +the time of writing, it doesn't support hardware watchpoints and breakpoints yet, and it needs a separate |
| 11 | +JTAG adapter connecting to the ESP8266s JTAG pins. As an alternative, [Cesanta](https://www.cesanta.com/) |
| 12 | +has implemented a barebones[GDB stub](https://blog.cesanta.com/esp8266-gdb) in their Smart.js solution - |
| 13 | +unfortunately, this only supports exception catching and needs some work before you can use it outside of |
| 14 | +the Smart.js platform. Moreover, it also does not work with FreeRTOS. |
| 15 | + |
| 16 | +For internal use, we at Espressif desired a GDB stub that works with FreeRTOS and is a bit more capable, |
| 17 | +so we designed our own implementation of it. This stub works both under FreeRTOS as well as the OS-less |
| 18 | +SDK and is able to catch exceptions and do backtraces on them, read and write memory, forward [os_]printf |
| 19 | +statements to gdb, single-step instructions and set hardware break- and watchpoints. It connects to the |
| 20 | +host machine (which runs gdb) using the standard serial connection that's also used for programming. |
| 21 | + |
| 22 | +In order to be useful the gdbstub has to be used in conjunction with an xtensa-lx106-elf-gdb, for example |
| 23 | +as generated by the [esp-open-sdk](https://github.com/pfalcon/esp-open-sdk) project. |
| 24 | + |
| 25 | +Usage |
| 26 | +----- |
| 27 | + * Grab the gdbstub project and put the files in a directory called 'gdbstub' in your project. You can do this |
| 28 | +either by checking out the Git repo, or adding the Git repo as a submodule to your project if it's already |
| 29 | +in Git. |
| 30 | + * Modify your Makefile. You'll need to include the gdbstub sources: if your Makefile is structured like the |
| 31 | +ones in the Espressif examples, you can add `gdbstub` to the `SUBDIRS` define and `gdbstub/libgdbstub.a` to the |
| 32 | +`COMPONENTS_eagle.app.v6` define. Also, you probably want to add `-ggdb` to your compiler flags (`TARGET_LDFLAGS`) |
| 33 | +and, if you are debugging, change any optimation flags (-Os, -O2 etc) into `-Og`. Finally, make sure your Makefile |
| 34 | +also compiles .S files. |
| 35 | + * Configure gdbstub by editting `gdbstub-cfg.h`. There are a bunch of options you can tweak: FreeRTOS or bare SDK, |
| 36 | +private exception/breakpoint stack, console redirection to GDB, wait till debugger attachment etc. You can also |
| 37 | +configure the options by including the proper -Dwhatever gcc flags in your Makefiles. |
| 38 | + * In your user_main.c, add an `#include <../gdbstub/gdbstub.h>` and call `gdbstub_init();` somewhere in user_main. |
| 39 | + * Compile and flash your board. |
| 40 | + * Run gdb, depending on your configuration immediately after resetting the board or after it has run into |
| 41 | +an exception. The easiest way to do it is to use the provided script: xtensa-lx106-elf-gdb -x gdbcmds -b 38400 |
| 42 | +Change the '38400' into the baud rate your code uses. You may need to change the gdbcmds script to fit the |
| 43 | +configuration of your hardware and build environment. |
| 44 | + |
| 45 | +Notes |
| 46 | +----- |
| 47 | + * Using software breakpoints ('br') only works on code that's in RAM. Code in flash can only have a hardware |
| 48 | +breakpoint ('hbr'). |
| 49 | + * Due to hardware limitations, only one hardware breakpount and one hardware watchpoint are available. |
| 50 | + * Pressing control-C to interrupt the running program depends on gdbstub hooking the UART interrupt. |
| 51 | +If some code re-hooks this afterwards, gdbstub won't be able to receive characters. If gdbstub handles |
| 52 | +the interrupt, the user code will not receive any characters. |
| 53 | + * Continuing from an exception is not (yet) supported in FreeRTOS mode. |
| 54 | + * The WiFi hardware is designed to be serviced by software periodically. It has some buffers so it |
| 55 | +will behave OK when some data comes in while the processor is busy, but these buffers are not infinite. |
| 56 | +If the WiFi hardware receives lots of data while the debugger has stopped the CPU, it is bound |
| 57 | +to crash. This will happen mostly when working with UDP and/or ICMP; TCP-connections in general will |
| 58 | +not send much more data when the other side doesn't send any ACKs. |
| 59 | + |
| 60 | +License |
| 61 | +------- |
| 62 | +This gdbstub is licensed under the Espressif MIT license, as described in the License file. |
| 63 | + |
| 64 | + |
| 65 | +Thanks |
| 66 | +------ |
| 67 | + * Cesanta, for their initial ESP8266 exception handling only gdbstub, |
| 68 | + * jcmvbkbc, for providing an incompatible but interesting gdbstub for other Xtensa CPUs, |
| 69 | + * Sysprogs (makers of VisualGDB), for their suggestions and bugreports. |
0 commit comments