Command Line Programming and Debugging with GDB

Eclipse with GDB is great: it comes with a graphical front end for debugging. But sometimes it is all about to download a program. Is it really necessary to launch an IDE like Eclipse to program or quickly debug a board? With the GNU Debugger (GDB), the answer is ‘no’: GDB comes with a command line debugger which is designed exactly for this: providing a command line interface for programming/downloading and debugging, bypassing any GUI (Graphical User Interface).

Combination of GDB Debugging Probes and Boards

Combination of GDB Debugging Probes and Boards (P&E, Segger and FRDM-KL25Z)

Outline

In “OpenOCD/CMSIS-DAP Debugging with Eclipse and without an IDE” I have documented how this works with the combination of GDB+OpenOCD+CMSIS-DAP, but this works in a similar way with Segger J-Link and P&E Multilink, as both come with a GDB server implementation too (e.g. if I use the Freescale Kinetis Design Studio or a DIY Eclipse IDE).

What I need is:

  • The GDB client: this comes with the GNU tools, e.g. the GNU ARM Embedded (launchpad).
  • The GDB server (e.g. from P&E or Segger). Both come installed with the Kinetis Design Studio.
  • And a board :-). I use here the FRDM-KL25Z board as it works with P&E, Segger, and OpenOCD/CMSIS-DAP GDB servers.

GDB Debugging Chain

To debug with GDB, I need a client, a server, a probe and of course a board:

GDB Debugging Chain

GDB Debugging Chain

The client is the gdb executable (arm-none-eabi-gdb.exe) on the host. It talks over a TCP/IP connection/port to the GDB server. The server is usually an executable running on the same machine, but it can run anywhere in the network too on a remote machine. Popular GDB servers are available from Segger, P&E or as well as open source (e.g. OpenOCD, see “OpenOCD/CMSIS-DAP Debugging with Eclipse and without an IDE“). Kinetis Design Studio v2.0.0 comes with all these three servers. The server needs to talk to the microcontroller/device/board using a JTAG/SWD connection: this can be a probe from vendors like Segger (J-Link, for example), P&E (USB Multilink, for example) or with CMSIS-DAP (e.g. on the FRDM-KL25Z board, see https:\\www.freescale.com\opensda). Both Segger and P&E provide firmware files for the FRDM boards to behave like a hardware probe, see “Segger J-Link Firmware for OpenSDAv2” and “New P&E OpenSDA Firmware v114“.

GDB Client

The GDB client for ARM is named arm-none-eabi-gdb.exe, and in the case of KDS V2.0.0 it is located inside the toolchain\bin folder:

GDB Client

GDB Client

start the GDB client with

arm-none-eabi-gdb.exe

The GDB client can be used with many GDB servers. The Segger and P&E specifics will be handled after this section.

P&E GDB Server

There is a GDB server from P&E available from http://www.pemicro.com/products/product_viewDetails.cfm?product_id=15320151. Alternatively, a P&E GDB server is included in the Freescale Kinetis Design Studio (KDS) (https://www.freescale.com/kds).

In case of KDS V2.0.0, the P&E GDB server is inside the eclipse\plugins\com.pemicro.debug.gdbjtag.pne folder. The folder name depends on the version, and there is a sub folder depending on Windows or Linux (win32 on Windows). The GDB server is named ‘pegdbserver_console.exe’:

PnE GDB Server

PnE GDB Server

The most important command line arguments are:

  • -startserver: starts the server
  • -device: specifies the device
  • -devicelist: lists the supported devices

These and other command line options are documented in
<KDS_2.0.0>\pemicro\Kinetis_Design_Studio_Debug_Configuration_User_Guide.pdf

To find out the list of supported devices, use the -devicelist command:

πŸ’‘ the real path to the P&E gdb server depends on your version installed. I’m using KDS v2.0.0

pegdbserver_console.exe -devicelist
Pemicro GDB Device List

Pemicro GDB Device List

I start the server for the device on the FRDM-KL25Z on a cmd/DOS prompt with

pegdbserver_console.exe -startserver -device=KL25Z128M4

and it will report something like this:

P&E GDB Server, Version 5.13.02.00
Copyright 2014, P&E Microcomputer Systems Inc, All rights reserved

Loading library C:\Freescale\KDS_2.0.0\eclipse\plugins\com.pemicro.debug.gdbjtag
.pne_1.1.8.201411191655\win32\gdi\unit_ngs_arm_internal.dll ... Done.

Command line arguments: -startserver -device=KL25Z128M4
Device selected is kl25z128m4
PE-ERROR: Unable to auto-detect debug hardware. Please specify on the command-line. Halting.

C:\Freescale\KDS_2.0.0>eclipse\plugins\com.pemicro.debug.gdbjtag.pne_1.1.8.20141
1191655\win32\pegdbserver_console.exe -startserver -device=KL25Z128M4

P&E GDB Server, Version 5.13.02.00
Copyright 2014, P&E Microcomputer Systems Inc, All rights reserved

Loading library C:\Freescale\KDS_2.0.0\eclipse\plugins\com.pemicro.debug.gdbjtag
.pne_1.1.8.201411191655\win32\gdi\unit_ngs_arm_internal.dll ... Done.

Command line arguments: -startserver -device=KL25Z128M4
Device selected is kl25z128m4
HW Auto-Selected : Interface=OPENSDA Port=DBA07E44Β Β  ; USB1 : OpenSDA (DBA07E44)

Connecting to target.
OpenSDA detected - Flash Version 1.14

Device is KL25Z128M4.

Mode is In-Circuit Debug.

'Kinetis' is a registered trademark of Freescale.

(C)opyright 2012, P&E Microcomputer Systems, Inc. (www.pemicro.com)
API version is 101

Server running on 127.0.0.1:7224

With this the server is running and waiting on port 7224 for a connection from the GDB client.

To connect to the P&E GDB server, use this in the gdb client:

target remote localhost:7224

Some monitor commands are documented here: http://www.pemicro.com/forums/forum.cfm?forum_topic_id=3990

πŸ’‘ I have not found a formal document (yet?) about the P&E monitor commands supported. A tip is to look in the Eclipse debug console view for hints πŸ™‚

_reset           ; Reset the MCU
_r0   ...  _r15  ; Change CPU register Value (param : longvalue)
_fill.w          ;Fill memory words (params : startaddr endaddr wordvalue)
_fill.l          ;Fill memory longwords (params : startaddr endaddr longwordvalue)
_pc              ;Set program counter (param: longvalue)

So to reset the microcontroller, use

monitor _reset

Then I can use the load and file commands to load my application for debug:

Below is the log of a debug session with P&E GDB Server using the ARM GDB client:

P&E GDB Client Debug Session

P&E GDB Client Debug Session

Segger GDB Server

There is a GDB server from Segger available from https://www.segger.com/jlink-gdb-server.html. Alternatively, a Segger GDB server is included in the Freescale Kinetis Design Studio (KDS) (https://www.freescale.com/kds). Segger has a GUI version (on Windows only, as far as I know) and a console/command line version. I’m using the command line version here.

The Segger GDB server is named JLinkGDBServerCL.exe and located in the C:\Freescale\KDS_2.0.0\segger folder.

Start it with

JLinkGDBServerCL.exe
Segger GDB Server Running

Segger GDB Server Running

The Segger GDB server expects a connection on port 2331. In the GDB client, I use

target remote localhost:2331

With

monitor reset

I can reset the target from the GDB client.

πŸ’‘ Documentation will commands can be found here: https://www.segger.com/admin/uploads/productDocs/UM08005_JLinkGDBServer.pdf

Next, I select the device to be used:

monitor device = MKL25Z128xxx4

Then I can use the load and file commands to load my application for debug:

Below is the log of a debug session with Segger GDB Server using the ARM GDB client:

GDB Client Session with Segger GDB

GDB Client Session with Segger GDB

GDB Client Commands to Load/Program the Device

The following commands in the gdb client are generic for both P&E and Segger.

Load the application code with the load command:

load c:/tmp/KL25Z_blue.elf

Use the file command to load debug symbols in gdb:

file c:/tmp/KL25Z_blue.elf

Use the continue command to start/continue execution:

continue

With CTRL+C I can stop execution.

With the quit command I terminate the gdb session:

quit

πŸ’‘ There are plenty of tips and trick for GDB available, see as wellΒ http://haifux.org/lectures/222/GDB_haifux_David_Khosid.pdf. For example you can put default commands into a .gdbinit file. Have as well a look https://sourceware.org/gdb/current/onlinedocs/gdb/ for a list of gdb commands.

Automation

Now if it is about to flash/program a bunch of boards, it is much easier to do this from a script, batch or command file. For example I create a text file with the following content:

# Segger: listen on port
target remote localhost:2331

# Segger: reset device
monitor reset

# Segger: specify flash of device
monitor device = MKL25Z128xxx4 

# load/flash application file
load c:/tmp/KL25Z_green.elf

# exit gdb
quit

Now with the GDB server running, I can launch the gdb client with the -x option, passing that command file to it:

πŸ’‘ GDB uses a similar file named .gdbinit (if it exists) to be executed at gdb startup. So that would be a good place for common settings.

arm-none-eabi-gdb.exe -x gdb_flash.txt

That way it will flash my binary file to the board:

Batch Flashing a File

Batch Flashing a File

Be free to write your own script: that way you can add the download to your make file or anything else which uses a command line interface.

Summary

GDB comes with a nice command line interface, so no GUI or IDE is needed for debugging or just downloading/flashing an image to a device. The GNU tools come with a generic GDB client which needs to talk to a GDB server, which can be from P&E, Segger or something else like OpenOCD. The commands supported in the server differ from one GDB server to another. With little work, it is possible to setup a command line environment for programming and debugging which is very useful for automated testing or automation in general.

Happy Serving πŸ™‚

Links:

Advertisements

30 thoughts on “Command Line Programming and Debugging with GDB

  1. Any idea how to start excuting and then exit? Looking to use this for production and want to put this in a batch file. Currently when we execute “continue” we are stuck.

    Like

  2. Pingback: Batch Programming with GDB: Segger J-Link and P&E Multilink | MCU on Eclipse

  3. Pingback: Updating Segger Tools in Eclipse Kinetis Design Studio | MCU on Eclipse

  4. Hi,
    Great article.
    Do you know if there is any way to use the eclipse variables in the GDB commands?
    I want to do something like this:
    load “${project_loc}\..\..\..\\\\bootloader.elf”

    Like

  5. Pingback: Debug Multiple Boards with GDB at the Same Time | MCU on Eclipse

  6. Pingback: Flashing many ARM Boards without a Host PC | MCU on Eclipse

  7. Hi Erich,

    Thanks for your blog.

    With ARM GNU Eclipse plugin and simply by putting GDB server commands in Startup tab in debug configuration, the GDB Server do the download job for you.

    Only you need to put these commands:
    monitor flash device
    monitor flash download = 1

    and to enable flash breakpoint add:
    monitor flash breakpoints = 1

    I have tested this, and it works fine,

    Like

  8. Wow, very nice documentation. I was able to program MKE04Z8xxx4 MCU, using segger J-LInk and Linux, in less than 5 minutes. Very very clear explain.
    This is the bash script I’ve used to run JLinkGDBServer and gdb client, permitting to program many MCU just pressing ENTER , or q to exit from the programming loop:
    #!/bin/bash
    #bash script program.sh
    #if JLinkGDBServer not running, run it (specify the right MCU device)
    if [ -z `pidof JLinkGDBServer` ]; then
    JLinkGDBServer -device MKE04Z8xxx4 -if SWD &
    fi
    # programming loop
    while [ 1 ]; do
    echo “Press a key to start programming, q to end”
    read x
    if [ “a$x” = “aq” ]; then
    break
    fi
    arm-none-eabi-gdb -x program.gdb
    if [ $? -eq 0 ]; then
    beep
    else
    beep -l 100 -r 3
    fi
    done
    #kill JLinkGDB server when exiting
    killall JLinkGDBServer

    ===================================================================
    And this is the program.gdb script:
    # program.gdb script
    target remote localhost:2331
    monitor device MKE04Z8xxx4
    monitor reset
    # replace the elf file with yours
    load ./tenda_buttons.elf
    monitor go
    disconnect
    quit

    Like

  9. Pingback: What is “Realtime Debugging”? | MCU on Eclipse

  10. Hi, Erich,
    Im having issues trying to debug with PE Micro Multilink universal and KDS. After configuring, exactly like described on: “https://mcuoneclipse.com/2015/05/11/debugging-the-frdm-k64f-with-pe-multilink/ ”
    So, when i start to debug, it launches an error related to the selected remote port: “target-select remote localhost:7224”. What would it be?
    Thank you.

    Like

    • Problem solved updating kds pe micro plugin, as described on: “https://mcuoneclipse.com/2015/04/16/updated-pe-gdb-server-for-eclipse-connectattach-and-advanced-flash-programming/”.
      Thank you again!

      Like

What do you think?

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s