External gdb server configuration - Marus/cortex-debug GitHub Wiki

How to use "servertype": "external" and how it relates to "gdbTarget"

This type of gdb-server is run by the user manually and all options are controlled by the user. Normally, with gdb-servers we know about, we know which commands to send (via) gdb to do a reset and halt. But when the servertype is external, we have no idea and the default commands mimic what we do for openocd since it is most widely used. But this is frequently wrong since there are so many other gdb-servers including custom ones that we do not know about.

Another use case for "external" is that the server is going to run on another computer

With a rare exception, a gdb-server opens a TCP port for GDB to connect to. For example port 3333. So, you must let cortex-debug know which port it is. This is done by setting "gdbTarget": "host:port". For example "gdbTarget": "localhost:3333"

Overriding default behavior for launch, reset, and restart.

There is a set of override... settings that you can use in your launch.json. See https://github.com/Marus/cortex-debug/blob/master/debug_attributes.md At the end of the overrideLaunchCommands, we expect the device to be programmed and a reset be performed in a way that it is stopped at the reset vector. Do not go past the reset rector or many things (especially breakpoints) may not work. In your postLaunchCommands, you may do other things, but generally not needed or recommended.

Note: Do not forget to use the "showDevDebugOutput" setting to debug your launch.json (recommend setting it to "raw"). You can also use this to run a non-external server to see what we normally do for that server.

Caveats

  • There are a few things that do not work because they require additional TCP ports. Examples are RTT and SWO. For SWO, you can specify its own TCP/serial port in the seoConfig. For RTT such an option does not exist.
  • Normally, when we start a gdb-server we make sure that all the required TCP ports are available. Now, that is your responsibility to avoid port conflicts.
  • Multi-core debugging requires even more care as you need to allocate ports for all the cores. This mechanism depends on the exact gdb-server you are using.

Recommended reading

It is helpful to read how this debugger works and how all the settings in launch.json are used. Since you are controlling the entire lifecycle of the gdb-server, you are responsible for understanding the mechanics. See https://github.com/Marus/cortex-debug/wiki/Cortex-Debug-Under-the-hood

Other aspects

Some users have used the VSCode settings for preLaunchTask and postDebugTask to start and stop the gdb-server in the way they wanted. We have no control over these settings and what they do.