Add a "How To Debug" chapter to Extension Developer FAQ

[marcelstoer]

We currently have module documentation for gdbstub. It's quite a bit more than a simple API documentation but not enough to qualify as a real "How to". IMO it would be helpful to have recipe-style instructions in the extension developer FAQs for people who have never worked with GDB. Such a chapter would also prove to be useful in bug processing. We could send people there with a clear conscience and ask them to do some of the debugging themselves.

[TerryE]

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.

As to the gdb stub, I personally feel that we should assume that C developers will already be familiar with gdb (and if they aren't, then there are already a lot of useful tutorials out there). What we could do with is a more focused explanation of how to do host / target debugging using the gddbstub and its strengths and limitations. This will be a lot shorter and easier to resource from the collaborators.

[marcelstoer]

Nice feedback Terry, thanks.

why we don't implement the standard Lua debug library? It is really quit useful in bug hunting end-user Lua apps.

I'm sure we wouldn't reject a PR if someone provided an implementation, would we?

As to the gdb stub, I personally feel that we should assume that C developers will already be familiar with gdb

I couldn't tell. What I do know though is that in 17+ years of Java development I never interacted with the Java debugger directly - the complexity is all nicely tucked away in the IDEs.

and if they aren't, then there are already a lot of useful tutorials out there

That must be true but nothing stops us from adding a reference to your favourite tutorial.

What we could do with is a more focused explanation of how to do host / target debugging using the gddbstub and its strengths and limitations.

That's essentially what I had in mind. Philip's documentation contains aspects of that already.

I created this isssue here because I personally would profit from such an FAQ chapter. Reading and debugging someone else's code in a language that you are not/no longer/not yet familiar with is the first step into understanding. That's my status with this firmware code.

[TerryE]

@marcelstoer @jmattsson @pjsg after my experiences on debugging this #2068, I have decided that we definitely need this. We also need a more developer friendly way of debugging and testing C library code.

I've got the GDB stub working well -- albeit with nasty quirks -- but to do this I've had to patch the Espressif library, the UART driver, and various Lua modules. The main catch-22 is that if you want to debug at a C statement level then you've got to allow the GDB stub to take control of UART0. And this means that you must lose access to the interactive Lua prompt -- which is a total pain. So I have two approaches for doing adhoc Lua testing to exercise a C library that I am debugging:

• Rapid file system replacement. I have a script which allows me to update a 32Kb filesystem at a fixed location and then inject it into the test 8266. So I can make a quick change to init.lua save it and download to the ESP module and reboot into it within ~ 3 sec. This allows me to do my Lua tests by quick replacement of the startup init file.

• Telnet Server. This just boots into my variant of the Telnet server so I can connect to it using screen and issue Lua commands that way, but one slight hassle is that this only redirects stdout and not stderr so output comes back to the Telnet session, but errors are reported elsewhere.

I've also had to tweak the debug and error routines so that you can redirect error messages / stderr to UART1. So now my "on holiday" mobile rig consists of my laptop, a Wemos D1 chip with UART1 connected through a USB serial UART chip so I have 2 USB serial connections: one at 115,200 baud for the GDB session and one at 460,800 baud for logging debug and other diagnostics. It's a total pain doing all of this on a single laptop screen and for the first time I am seriously considering using two decent auxiliary monitors in my office for doing this work.

The other thing is that you can use the remote GDB usefully and step through the code -- so long as you can work with a single breakpoint pending, and so lots of hdr mod:XXX, del 1, hdr YYY, del 2, ... The single step feature is of limited use and the storage walk / set works well, through it would be really nice to have a simple way of forcing a single module into RAM so that you can use normal b instructions. Any feedback gratefully received.

So I am quite a seasoned crusty old hacker and with a couple of days perseverance got a development model that works for me. My issue is how we share this know-how. It ain't easy and there's a big learnng curve for beginners.

[TerryE]

Sorry about the close and open -- finger trouble. If I am honest, then I would never have got this flash stuff working without a usable remote debugger. Goodness knows how @zeroday got the first version of the Lua system bootstrapped. I am just in awe.

I did the LCD patch by getting it working under a standard Linux environment using the patch on std Lua then moving onto NodeMCU, but for stuff like this Flash mod, Lua 5.3 or any complex H/W related libraary, then IMO you really need decent gdb access to develop this sort of stuff, and because of the UART0 conflict, this isn't easy.

[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.