The esp8266 portion of the project
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

69 lines
4.3 KiB

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