Live Debug
==========
.. highlight:: bash
This project is an example of how to integrate GDB debugging into your
project. It provides a basic command interface which you can use via
regular serial terminal or with the GDB application.
To use this sample application with the command-line GDB application,
simply build and flash the project as usual::
make clean
make flash
You should be presented with the GDB command prompt. Enter 'c' to
continue running the application:
.. code-block:: text
(gdb) c
Continuing.
(attached)
The ``(attached)`` prompt is displayed by the LiveDebug application.
Type ``help`` to get a list of available commands.
Note that if you run this application via serial terminal
(``make terminal``) you'll get the ``(Detached)`` prompt instead.
2. Debugging under eclipse
Interacting with the GDB console causes problems for eclipse, so compile
with the ``ENABLE_GDB_CONSOLE=0`` option::
make clean
make flash ENABLE_CONSOLE=0
Alternatively, use the ``consoleOff`` command from the GDB command
prompt, then quit the debugger and connect via eclipse.
Exception Handling
------------------
Sming comes with a built-in exception handling that takes care to
display the stack trace leading to the issue. Usually it looks like this:
.. code-block:: text
***** Fatal exception 28 (LOAD_PROHIBITED)
pc=0x40100e96 sp=0x3ffff640 excvaddr=0x000015b8
ps=0x00000033 sar=0x00000018 vpri=0x000000f0
r00: 0x40100d69=1074793833 r01: 0x3ffff640=1073739328 r02: 0x3fff3900=1073690880
r03: 0x2b265ed4= 723934932 r04: 0x3fffbff0=1073725424 r05: 0x000015b8= 5560
r06: 0x000015b8= 5560 r07: 0x14a8433b= 346571579 r08: 0x00000008= 8
r09: 0x14a842f3= 346571507 r10: 0x3fff22d0=1073685200 r11: 0x00000003= 3
r12: 0x00000048= 72 r13: 0x3fff38c0=1073690816 r14: 0x3ffe9da0=1073651104
r15: 0x3fff1138=1073680696
Stack dump:
To decode the stack dump call from command line:
make decode-stacktrace
and copy & paste the text enclosed in '===='.
================================================================
3ffff640: 40100e96 00000033 00000018 000000f0
3ffff650: 40100d69 3fff3900 2b265ed4 3fffbff0
3ffff660: 000015b8 000015b8 14a8433b 00000008
3ffff670: 14a842f3 3fff22d0 00000003 00000048
3ffff680: 3fff38c0 3ffe9da0 3fff1138 0000001c
3ffff690: 002222fb c0fb5c01 0bc10000 facfd1fb
3ffff6a0: 620020c0 6162802d 0020c004 59062c52
3ffff6b0: 0020c051 61492c48 210020c0 7c38fb50
...
================================================================
Enter ``make decode-stacktrace`` then copy & paste the text
to produce something readable like this:
.. code-block:: text
0x40100e96: pvPortRealloc at ??: ?
0x40100d69: pvPortMalloc at ??:?
0x402455f0: ax_port_malloc at C:\tools\Sming-3.1.2\Sming/third-party/axtls-8266/ replacements/mem.c:51
0x4024561a: ax_port_calloc at C:\tools\Sming-3.1.2\Sming/third-party/axtls-8266/ replacements/mem.c:63
0x40230acc: x509_new at c:\tools\Sming-3.1.2\Sming\third-party\axtls-8266/ssl/x5 09.c:81
0x4023d3e4: m_vsnprintf at C:\tools\Sming-3.1.2\Sming/system/m_printf.cpp:69
0x4023d4a6: m_vprintf at C:\tools\Sming-3.1.2\Sming/system/m_printf.cpp:83
0x40000a39: ?? ??:0
0x4021418a: pp_attach at ??:?
0x40221d60: pbuf_alloc at ??:?
0x40221f0a: pbuf_copy at ??:?
0x4023d3e4: m_vsnprintf at C:\tools\Sming-3.1.2\Sming/system/m_printf.cpp:69
Note that you can also put the stack trace into a file, for example ``dump.txt`` then enter::
make decode-stacktrace TRACE=dump.txt
Using the information about the type of the exception (ex:
``***** Fatal exception 28``) and the sequence of commands might help us
figure out the issue.
But that information might not be enough. And finding the root cause may
take quite some time.
GDB Debugging
-------------
Debugging is a powerful technique allowing you to interactively run your
code and be able to see much more information about the things that went
wrong.
To use, (Re)compile your project with the ``ENABLE_GDB`` option and
flash it to the board::
make clean
make ENABLE_GDB=1
make flash
Instead of a terminal, the GDB console will be opened automatically.
If you need to run GDB manually after resetting the board or after it
has run into an exception, use the provided script::
make gdb
Note that software breakpoints ('br') only work on code that is in RAM.
During development you can use the GDB_IRAM_ATTR attribute in your
function declarations. Code in flash can only have a hardware breakpoint
('hbr').
Read the GDB stub :component-esp8266:`Notes <gdbstub>` for more information.
