Documenting how to use xtensa-lx106-elf-gdb for C library development

[TerryE]

Missing feature

Using the remote GDB tool is a very powerful aid for doing any C runtime development but with health warnings and caveats. I am not sure where to put this in or canon of HOWTOs and other resources, and I suspect that a blog post or wiki page here might be the easiest way.

Justification

This know how should be shared somehow. There isn't much out on the internet on this.

Workarounds

Do what I did and learn the hard way. _This issue is just a place holder to collaborate on this.

Key points

• The remote GDB interface works and has some strengths and some terrible weaknesses.
• It only really has a role for C development. If you only use Lua then you can ignore this.
• You need a working Xtensa toolchain including xtensa-lx106-elf-gdb. I have an Ubuntu laptop so this is tivial for me, I've also built the toolchain on an RPi so using one of these would easy as well. I leave the WinX options to WinX developers.
• If you can develop your library as a component on your host then do so, because the standard host gdb tool is far more powerful (that's why I first added the -e option to luac.cross by the way).
• Going into the debugger is a one-way trip as it takes over UART0. In practice the only exit is to reboot the ESP.
• In general all of the examining data and stack commands work well and just as they do in a host session. Great.
• You can only have 1 H/W breakpoint which you can use to debug flash-based code, so stepping up to a known point works well. However if the code goes down unexpected paths then that's it: reboot and retry time. One trick here is to create a placeholder break() function. You can then compile in calls to break() in the code you are testing and set this as a breakpoint. fr 1 will give you the calling location.
• I believe that software breakpoints work if your functions are compiled with TEXT_SECTION_ATTR, but this section is very limited and I haven't tried this.
• Stepping works so long as you stay within the scope of the function being debugged (i.e. you can't step over a function call).
• I've developed a bunch of macros that help a little with the pain.
• I add some standard Lua functions to make interactive work easier. These can go in either _init in LFS or init.lua on SPIFFS. An example is:

function b() local g=gdbstub;  g.open(); g.gdboutput(1); g.brk(); end
function t() b();  for i=1,252 do node.writercr(2, "Hello World "..i) end

• Here, I am stepping through node_writercr() and the platform code it executes. Tedious but a lot better than shotgun printfs
• I can reboot the ESP, then type t() at the interactive prompt. This compiles and execute the t() call which enters the debugger in g.brk(). The gdb stub then takes over the UART0 and issues a handshake prompt $T05#b9. Time to leave the terminal emulator and switch into the debugger. If you've got the right .gbbinitthen you will enter gdb, and you can break on your target routine and start debugging.
• Our version of the non-aligned exception handler interoperated nicely with the gdb stub. The Espressif one does not, so hitting a non-aligned flash fetch screws up during debugging. Need to think about this one.
• . . . TO BE CONTINUED

Other resources

• Arduino ESP8266 - Using GDB to Debug Applications
• Live debugging with open-source tools (Programming for ESP8266: Part 4)
• Kacang Bawang - ESP8266 SDK: how to debug with gdb

[marcelstoer]

a blog post or wiki page here might be the easiest way

Why not another whitepaper cross-linked from the GDB module documentation?

[TerryE]

I am proposing to continue the issues on #2932 specifically related to the use of remote gdb here as a way of taking both issues forward:

• The standard root Makefile on Intel 64 Linux platforms (including docker containers) import and unpacks Johny's pre_built toolchain as part of the make and the host remote gdb application. Do a find tools/toolchain -name gdb to find it. I have a elf-gdb symlink to this in my '~/bin' directory, so that using elf-gdb at the bash command prompt invokes this. (If use the elf- prefix because I also use the standard gdb for debugging host apps such as luac.cross
• Windows users using docker can access bash interactively in their nodemcu container. This is standard docker functionality. They can also map a host USB port through the VM/WSL into the docker container so that esptools, elf-gdb and other tools can directly connect to a USB-connected ESP. Again standard functionality.
• @nwf asked whether elf-gdb can use watchpoints and breakpoints. Yes, but only one watch/break point at a time. esp-gdbstub/gdbstub-entry.S contains the low level entry hooks. The way that you control the ESP hardware is through a set of special regs defined in <xtensa/config/specreg.h> (again search the tools/toolchain folder for this file. Some of you might be familiar with the CCOUNT special register.

As to the mechanics of how a developer does all this. I can go through all this if I have a volunteer willing to go through this with me.

[marcelstoer]

Hhmm, does it make sense to keep both this issue open and #1862?

[TerryE]

Yes Marcel, you are right: they are largely duplicates so I've closed the older as this largely subsumes it.

There was one point not covered here:

Marcel, one thing that I keep asking myself is: why we don't implement the standard Lua debug library? It is really quit useful in bug hunting end-user Lua apps.

And the answer is that Lua 5.3 does include a full debug library implementation less the debug.debug() method and doing this is on my TODO list.

Do you see my point? I would really like a collaborator to get up to speed and work with my on the know-how transfer and communicating to you our wider community rather than this being yet another "Terry TODO" list item.

[marcelstoer]

I would really like a collaborator to get up to speed and work with my on the know-how transfer and communicating to you our wider community rather than this being yet another "Terry TODO" list item.

Yes, I do understand that. You are referring to the earlier

As to the mechanics of how a developer does all this. I can go through all this if I have a volunteer willing to go through this with me.

I would love to do that as I feel it would be a fantastic learning experience (for me)! ATM anything that goes beyond keeping-the-lights-on activities for NodeMCU are out of reach for me. Very sorry 😢 It's a constant fight squeezing all obligations into my daily schedule.

[TerryE]

@marcelstoer, we are all constrained by our background skills and other priorities. We also make whatever contributions we make and in our own way purely pro bono, and so we shouldn't expect any more from any individual contributor who like you is making a material contribution. Nonetheless, if we want NodeMCU to succeed as a community project then somehow we need to engage and encourage the newer contributors and make them feel that their own contributions are valued. It's that new blood that we need to help the tired old blood like me!

[marcelstoer]

By coincidence I just stumbled upon https://arduino-esp8266.readthedocs.io/en/latest/gdb.html. Maybe it can serve as a source of inspiration.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.