Docs for custom gdb debugger?

FAQ
1

Is there documentation on configuring a custom debug tool in a board’s json file in the platform? (i.e. platform-espressif8266/boards/d1_mini.json)

This is what I have so far:

"debug": {
  "tools": {
    "custom": {
      "server": {
        "package": "toolchain-xtensa",
        "executable": "bin/xtensa-lx106-elf-gdb"
      },
      "init_cmds": [
        "set remote hardware-breakpoint-limit 1",
        "set remote hardware-watchpoint-limit 1",
        "set remotebaud 115200",
        "file \"$PROG_PATH\"",
        "target remote $DEBUG_PORT",
        "$INIT_BREAK"
      ],
      "init_break": "",
      "extra_cmds": [
      ],
      "load_mode": "manual",
      "default": true
    }
  }
}

It seems to mostly work, but I have a few questions:

  • I have to specify debug_port in my platformio.ini. Is there a way to make this automatic in the same way that uploading automatically chooses the port?
  • Is there a variable for baudrate?
  • init_break seems to default to trying to break on main, so I have set this to an empty string. Is this correct?
  • Uploading firmware via gdb isn’t a good idea, so I’ve set load_mode to manual. Is there a more official way to disable uploading via this debug tool?
  • Is there a more official way to configure gdb as a debug tool for this board?
  • Is there any documentation on all the available options?

The above example was added to d1_min.json in platform-espressif8266 using a fork of esp8266-Arduino found here: [Needs testing] Add full gdb support with uart/Serial integration by kylefleming · Pull Request #4386 · esp8266/Arduino · GitHub

2 Likes
2

Sorry, currently we don’t have docs but will add later. Nevertheless, I’ll help you.

"require_debug_port": true

Currently, we don’t have it. We will add if you need it. Maybe, debug_speed.

Yes, that is right.

Please use

"load_cmd": "preload"

We will load firmware using “upload” target.

Could you explain a little bit how do you do that from CLI?

3

This forces the user to add a debug_port variable to their platformio.ini correct? Is there a way to specify that platformio should automatically choose a port? Right now I have to constantly change that variable depending on which board I’m debugging.

To use gdb from the cmd line, I create a file called gdbcmds, with something similar to following:

set remote hardware-breakpoint-limit 1
set remote hardware-watchpoint-limit 1
file </Path/to/.pioenvs/d1_mini/firmware.elf>
mem 0x20000000 0x3fefffff ro cache
mem 0x3ff00000 0x3fffffff rw
mem 0x40000000 0x400fffff ro cache
mem 0x40100000 0x4013ffff rw cache
mem 0x40140000 0x5fffffff ro cache
mem 0x60000000 0x60001fff rw
set remotebaud 115200
target remote /dev/cu.SLAB_USBtoUART

Then call

~/.platformio/packages/toolchain-xtensa/bin/xtensa-lx106-elf-gdb -x </path/to/gdbcmds>
4

Could you prepare a simple project which is ready for debugging? It seems that I need special firmware with GDBStub. Thanks!

5

Sure thing. I added a gdb.sh file which runs gdb from the command line and I also added my attempt at a platformio debug configuration to the d1_mini.json in the corresponding platform-espressif8266 fork.

Here’s the repo:

You will need to change the port in the last line of gdbcmds and in the last line of platformio.ini.

6

Could you help me? I can make it work.

pio debug -d /tmp/111 --interface gdb
PlatformIO Plus (https://pioplus.com) v1.1.6
GNU gdb (crosstool-NG 1.20.0) 7.5.1
Copyright (C) 2012 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
and "show warranty" for details.
This GDB was configured as "--host=x86_64-build_apple-darwin14.1.0 --target=xtensa-lx106-elf".
For bug reporting instructions, please see:
<http://www.gnu.org/software/gdb/bugs/>.
(gdb) (gdb)
(gdb)
(gdb) source .pioinit
0x40000f68 in ?? ()
(gdb) i threads
  Id   Target Id         Frame
* 1    Thread <main>     0x40000f68 in ?? ()
(gdb) b setup
Breakpoint 1 at 0x402022d6: file src/main.cpp, line 15.
(gdb) c
Continuing.
Note: automatically using hardware breakpoints for read-only addresses.

main.cpp

#include "Arduino.h"
#include <GDBStub.h>

// Set LED_BUILTIN if it is not defined by Arduino framework
// #define LED_BUILTIN 13

void setup()
{
  Serial.begin(115200);
  // initialize LED digital pin as an output.
  pinMode(LED_BUILTIN, OUTPUT);
}

void loop()
{
  // turn the LED on (HIGH is the voltage level)
  digitalWrite(LED_BUILTIN, HIGH);
  // wait for a second
  delay(1000);
  // turn the LED off by making the voltage LOW
  digitalWrite(LED_BUILTIN, LOW);
   // wait for a second
  delay(1000);
}

platformio.ini

[env:nodemcuv2]
platform = https://github.com/kylefleming/platform-espressif8266.git
board = nodemcuv2
framework = arduino
debug_port = /dev/cu.SLAB_USBtoUART

P.S: NodeMCU v2 manifest was updated with the same debug section from d1_mini.