GDB

Template:ArticleBasedOnModel Template:ArticleMainWriter

1. Article purpose[edit | edit source]

This article provides the basic information needed to start using the GDB^[1] application tool.

It explains how to use this GNU debugger tool connected to your ST board target via Ethernet or via ST-LINK, and how to perform cross-debugging (IDE, gdb viewer tool or command line) on Arm^® Cortex^®-A7 side for Linux^® application, Linux^® kernel (including external modules), or Arm^® Cortext^®-M4 firmware.

2. Introduction[edit | edit source]

The following table provides a brief description of the tool, as well as its availability depending on the software packages:

Template:Y: this tool is either present (ready to use or to be activated), or can be integrated and activated on the software package.

Template:N: this tool is not present and cannot be integrated, or it is present but cannot be activated on the software package.

Tool			STM32MPU Embedded Software distribution			STM32MPU Embedded Software distribution for Android™
Name	Category	Purpose	Starter Package	Developer Package	Distribution Package	Starter Package	Developer Package	Distribution Package
GDB	Debugging tools	The GNU Project debugger, GDB^[1], allows monitoring program execution, or what the program was doing at the moment it crashed.	Template:N*	Template:Y	Template:N**	Template:UnderConstruction
GDB	Debugging tools		* Cross compile gdb binary is required and only available from Developer Package. ** It is recommended to use the Developer Package to run the gdb debug session, which provided all dependencies

The GDB can perform four main types of actions (plus other corollary actions) to help you detect bugs when running your software or application:

Start the program, specifying anything that might affect its behaviour.
Make the program stop on specific conditions.
Examine what happened when the program stopped.
Update the program in order to test a bug correction, and jump to the next one.

3. Overview of GDB setup for STM32MPU[edit | edit source]

3.1. GDB setup paths[edit | edit source]

Two paths can be used in the STM32MPU environment for GDB setup:

gdb ↔ gdbserver path through Ethernet, Template:Highlight.

In that case, two software components are required, one on the target and the other on the host PC.

gdb ↔ JTAG/SWD path through OpenOCD and ST-LINK, Template:Highlight.

In that case, only one software component is required on the host PC.

Template:ImageMap

Two components are included in OpenSTLinux Developer Package for GDB setup:

gdbserver: Template:Highlight and used as remote access for a host connection
arm-openstlinux_weston-linux-gdb: Template:Highlight, cross-compiled gdb binary that manages the connexion between the host computer and the target board

3.2. JTAG and SWD debug port[edit | edit source]

The STM32MPU features two debug ports through the embedded CoreSight™ component that implements an external access port for connecting debugging equipment:

A 5-pin standard JTAG interface (JTAG-DP)
A 2-pin (clock + data) “serial-wire debug” port (SW-DP)

These two modes are mutually exclusive since they share the same I/O pins.

Refer to STM32MP15 reference manuals for information related to JTAG and SWD.

4. Installing the GDB tool[edit | edit source]

This tool is made of two parts, one on the host PC, and a second on the target (only for debugging Linux applications).

4.1. Installing the GDB tool on your host PC[edit | edit source]

4.1.1. Using the STM32MPU Embedded Software distribution[edit | edit source]

4.1.1.1. Developer Package[edit | edit source]

Only the Developer Package can be used, since it is the only one which provides all the required components:

The cross-compiled GDB binary
The OpenOCD binary and configuration files
The symbols files of all BSP components (TF-A, U-Boot and Linux kernel), corresponding to the images of the OpenSTLinux Starter Package.

4.1.2. Using the STM32MPU Embedded Software distribution for Android™[edit | edit source]

Template:UnderConstruction

4.2. Installing the GDB on your target board[edit | edit source]

On the target board, only the gdbserver binary is required for debugging Linux applications.

It is available by default within the Starter Package, which provides images linked to the Developer Package.

5. Getting started[edit | edit source]

This chapter describes the two ways for debugging OpenSTLinux BSP components (TF-A, U-Boot and Linux kernel including external modules), Linux applications and Cortex-M4 firmware: by using GDB commands or by using a GDB user interface such as gdbgui, DDD or IDE.

5.1. Prerequisites[edit | edit source]

The target board is up and running.

5.2. Debug OpenSTLinux BSP components[edit | edit source]

5.2.1. Setting up GDB / OpenOCD debug path environment[edit | edit source]

Architecture

The figure below shows the architecture corresponding to the GDB/OpenOCD connected to Cortex-A7 and Cortex-M4 cores.
Note: The ST-LINK probes available on the STM32MP1 board can be used through a USB interface, as well as any other external probes through the Trace or JTag connector.

Prerequisites

The Developer Package must be installed. It provides the SDK, the debug symbol files and the source files for TF-A, U-Boot and Linux kernel (refer to STM32MP1 Developer Package).

The debug symbol files contain the symbols for the TF-A, U-Boot and Linux kernel binaries (from the Starter Package image) that have been flashed on the board.

Environment configuration files

To speed up environment setup for debugging with GDB, download two configuration files, and install them on your PC (under the home directory: $HOME/gdbscripts/). You can then Template:Highlight them:

- Setup.gdb: main configuration file in which you can define the debug context you want to use. Possible combinations are:

Debug mode	Cortex-A7-TF-A (1)	Cortex-A7-U-Boot (2)	Cortext-A7-Linux kernel (3)
Boot (0)	Template:Y	Template:Y	Template:Y
Running target (1)	Template:N	Template:Y	Template:Y

- Path_env.gdb: customization file to define all the paths to source and symbol files, which can either be directly retrieved from the Developer Package (refer to the Example of directory structure for Packages), or result from a new compilation. Template:Highlight.

Store these files locally on your host PC, Template:Highlight and update them accordingly.

5.2.2. Configuring GDB and OpenOCD for attachment on a running target[edit | edit source]

When the target board is running, you can attach the GDB only during one of following phases:

5.2.2.1. U-Boot execution phase[edit | edit source]

Select the right configuration in Setup.gdb:

# Set debug phase:
#	1: Attach at Cortex-A7-TF-A
#	2: Attach at Cortex-A7-U-Boot
#	3: Attach at Cortext-A7-Linux kernel
Template:Green = Template:Green

#	0: Attach at boot
#	1: Attach running target
Template:Green = Template:Green

When the configuration is complete, jump to Running OpenOCD and GDB.

5.2.2.2. Linux kernel execution phase[edit | edit source]

Select the right configuration in Setup.gdb:

# Set debug phase:
#	1: Attach at Cortex-A7-TF-A
#	2: Attach at Cortex-A7-U-Boot
#	3: Attach at Cortext-A7-Linux kernel
Template:Green = Template:Green

#	0: Attach at boot
#	1: Attach running target
Template:Green = Template:Green

When the configuration is complete, jump to Running OpenOCD and GDB.

5.2.3. Configuring GDB and OpenOCD for attachment on boot[edit | edit source]

You can attach the GDB during target boot only in the following cases: Template:Warning

5.2.3.1. TF-A boot case[edit | edit source]

In that case, the GDB breaks in bl2_entrypoint function.

Select the right configuration in Setup.gdb:

# Set the debug phase:
#	1: Attach at Cortex-A7-TF-A
#	2: Attach at Cortex-A7-U-Boot
#	3: Attach at Cortext-A7-Linux kernel
Template:Green = Template:Green

#	0: Attach at boot
#	1: Attach running target
Template:Green = Template:Green

When this operation is complete, jump to Running OpenOCD and GDB.

5.2.3.2. U-Boot boot case[edit | edit source]

In that case, the GDB breaks in in _start function.

Select the right configuration in Setup.gdb:

# Set the debug phase:
#	1: Attach at Cortex-A7-TF-A
#	2: Attach at Cortex-A7-U-Boot
#	3: Attach at Cortext-A7-Linux kernel
Template:Green = Template:Green

#	0: Attach at boot
#	1: Attach running target
Template:Green = Template:Green

When this operation is complete, jump to Running OpenOCD and GDB.

5.2.3.3. Linux kernel boot case[edit | edit source]

In that case, the GDB breaks in stext function.

Select the right configuration in Setup.gdb:

# Set the debug phase:
#	1: Attach at Cortex-A7-TF-A
#	2: Attach at Cortex-A7-U-Boot
#	3: Attach at Cortext-A7-Linux kernel
Template:Green = Template:Green

#	0: Attach at boot
#	1: Attach running target
Template:Green = Template:Green

When this operation is complete, jump to Running OpenOCD and GDB.

5.2.4. Running OpenOCD and GDB[edit | edit source]

Prerequisites

Before running OpenOCD and GDB, check that the target board is in the right state.

For all configurations except GDB attachment to a running SSBL (U-Boot), the board has to operate in OpenSTLinux running mode.

In case of attachment to a running SSBL (U-Boot) configuration, the board target must be in U-Boot console mode:

#Reboot the target board

#Press any key to stop at U-Boot execution when booting the board
Template:Board$ ...
Template:Board$ Hit any key to stop autoboot:  0
Template:Board$ STM32MP>

When you are in the expected configuration, two different consoles must be started: one for OpenOCD and one for GDB.
Template:Highlight

OpenOCD console

# First console for starting openocd with configuration file
Template:PC$ source Template:Orange/environment-setup-cortexa7hf-neon-vfpv4-openstlinux_weston-linux-gnueabi
Template:PC$ $OECORE_NATIVE_SYSROOT/usr/bin/openocd -s $OECORE_NATIVE_SYSROOT/usr/share/openocd/scripts -f Template:Orange

Possible target configuration files for Template:Orange:

Target board	Adapter	SWD mode board.cfg	JTAG mode board.cfg
STM32MP157C-EV1	ST-LINK *	board/stm32mp15x_ev1_stlink_swd.cfg	board/stm32mp15x_ev1_stlink_jtag.cfg
STM32MP157C-EV1	U-LINK2	board/stm32mp15x_ev1_ulink2_swd.cfg	board/stm32mp15x_ev1_ulink2_jtag.cfg
STM32MP157C-EV1	J-LINK	board/stm32mp15x_ev1_jlink_swd.cfg	board/stm32mp15x_ev1_jlink_jtag.cfg
STM32MP157X-DK2	ST-LINK *	board/stm32mp15x_dk2.cfg	Template:N**

* Both v2 and v3 are supported.

** JTAG wires are not connected in DK2.

Template:Highlight

GDB console

Template:Warning

# Second console for starting the GDB
Template:PC$ Template:Highlight
Template:PC$ source Template:Orange/environment-setup-cortexa7hf-neon-vfpv4-openstlinux_weston-linux-gnueabi
Template:PC$ $OECORE_NATIVE_SYSROOT/usr/bin/arm-openstlinux_weston-linux-gnueabi/arm-openstlinux_weston-linux-gnueabi-gdb -x=Template:Highlight

5.2.5. To know more about Linux kernel debug with GDB[edit | edit source]

Please refer to Debugging the Linux kernel using the GDB.

5.2.6. Access to STM32MP registers[edit | edit source]

5.2.6.1. Using gdb command line[edit | edit source]

- The following monitoring commands can be used to read a register value:

(gdb) monitor mdb <Template:Orange> [[[:Template:Orange]]] #Display target memory as 8-bit bytes
(gdb) monitor mdh <Template:Orange> [[[:Template:Orange]]] #Display target memory as 16-bit bytes
(gdb) monitor mdw <Template:Orange> [[[:Template:Orange]]] #Display target memory as 32-bit bytes

For example: Read RCC_MP_APB1ENSETR register on STM32MP1 to check RCC APB1 peripheral enable status.

(gdb) monitor Template:Highlight phys Template:Green Template:Highlight
0x50000a00: Template:Highlight --> UART4 is enable as explained in STM32MP15 reference manuals

- The following monitoring commands can be used to set a register value:

(gdb) monitor mwb <Template:Orange> <Template:Orange> [[[:Template:Orange]]] #Write byte(s) to target memory
(gdb) monitor mwh <Template:Orange> <Template:Orange> [[[:Template:Orange]]] #Write 16-bit half-word(s) to target memory
(gdb) monitor mww <Template:Orange> <Template:Orange> [[[:Template:Orange]]] #Write 32-bit word(s) to target memory

For example: Write RCC_MP_APB1ENCLRR register on STM32MP1 to clear the UART4 RCC of APB1 peripheral, then reenable it:

(gdb) monitor Template:Highlight phys Template:Green Template:Highlight Template:Highlight

# You can then check that UART4 is disable by reading the RCC_MP_APB1ENSETR register:
(gdb) monitor mdw phys Template:Green
0x50000a00: 00000000

# You can also check that the console is disabled by going on running the GDB
(gdb) c

# When the GBD has stopped running, you can re-enable UART4 RCC:
(gdb) monitor mww phys Template:Green Template:Highlight

5.2.6.2. Using CMSIS-SVD environment[edit | edit source]

The CMSIS-SVD environment is useful to get detailed information on registers, such as name and bit descriptions.

It is based on python scripts and svd files which contain the description of all registers.

Refer to CMSIS-SVD environment and scripts for more details.

5.3. Debug Cortex-M4 firmware with GDB[edit | edit source]

The Arm Cortex-M4 core firmware can also be debugged using the GDB in command line (without IDE).

Two setups can be used:

Engineering mode (only Cortex-M4 core running)

Template:UnderConstruction

Production mode (both Cortex-M4 and Cortex-A7 cores running)

Template:UnderConstruction

5.4. Debug Linux application with gdbserver[edit | edit source]

5.4.1. Enable debug information[edit | edit source]

Once your program is built using the sdk toolchain, make sure that the -g option is enabled to debug your program and add the necessary debug information.

Note: If an issue occurs during debugging, you can also force gcc to "not optimize code" using the -O0 option.

Example of a simple test program build:

Template:PC$ $CC -g -o myappli myappli.c

Example based on Hello World: refer to "hello world" user space example

Edit and update the makefile for the user space example:

...
# Add / change option in CFLAGS if needed
-# CFLAGS += <new option>
+ CFLAGS += -g
...

5.4.2. Remote debugging using gdbserver[edit | edit source]

In this setup, an Template:Highlight.

Once your program is installed on the target (using ssh or copied from an SDcard), you can start debugging it.

On target side: based on "Hello world" user space example

Template:Board$ cd /usr/local/bin
Template:Board$ ls
   hello_world_example
Template:Board$ gdbserver host:1234 hello_world_example
  Process main created; pid = 11832 (this value depends on your target)
  Listening on port 1234

Your target waits for remote PC connection, and then starts debugging.

Launch the GDB command from your source file folder (easier source loading)

Template:Highlight

Template:PC$ cd Template:Orange
Template:PC$ ls
    hello_world_example  hello_world_example.c  hello_world_example.o  kernel_install_dir  Makefile
Template:PC$ source Template:Orange/environment-setup-cortexa7hf-neon-vfpv4-openstlinux_weston-linux-gnueabi
Template:PC$ $OECORE_NATIVE_SYSROOT/usr/bin/arm-openstlinux_weston-linux-gnueabi/arm-openstlinux_weston-linux-gnueabi-gdb
   GNU gdb (GDB) X.Y.Z
   ...
   This GDB was configured as "--host=x86_64-openstlinux_weston_sdk-linux --target=arm-openstlinux_weston-linux-gnueabi".
   ...
(gdb)

Connect to the target and load the source file:

(gdb) target remote Template:Orange:1234
  Remote debugging using <IP_Addr_of_Board>:1234
  Reading /home/root/test from remote target...
  ...
(gdb) break 16 (line number in the source file)
(gdb) continue

The target program breaks on the breakpoint. Proceed until the end of the program:

(gdb) continue
  Continuing.
  [Inferior 1 (process 16204) exited normally]
(gdb) quit

5.5. User interface application[edit | edit source]

5.5.1. Text user interface (TUI) mode[edit | edit source]

This user interface mode is the first step before using the graphical UI as GDBGUI or DDD.

The TUI can be very useful to map source code with instruction.

Please go through the online documentation ^[2] ^[3].

5.5.2. Debugging with GDBGUI[edit | edit source]

Please refer to the dedicated gdbgui article.

5.5.3. Debugging with DDD[edit | edit source]

GNU DDD is a graphical front-end for command-line debuggers. Please refer to dedicated web page for details^[4].

5.5.4. Debugging with IDE[edit | edit source]

Please refer to STM32-CoPro-MPU plugin for SW4STM32.

6. To go further[edit | edit source]

6.1. Useful GDB commands[edit | edit source]

When using the GDB in command line mode, it is important to know some basic GDB commands, such as run software, set breakpoints, execute step by step, print variables and display information.

Please refer to GDB commands article.

6.2. Core dump analysis using GDB[edit | edit source]

The core dump generated for an application crash can be analysed by using the GDB.

Developer Package components, such as SDK and symbol files, must installed. Please refer to STM32MP1 Developer Package.

The symbol file containing the debug symbol of the application in which the crash occurred must also be available.

First enable the SDK environment:

Template:PC$ source Template:Orange/environment-setup-cortexa7hf-neon-vfpv4-openstlinux_weston-linux-gnueabi

Then play the core dump with GDB:

Template:PC$ $OECORE_NATIVE_SYSROOT/usr/bin/arm-openstlinux_weston-linux-gnueabi/arm-openstlinux_weston-linux-gnueabi-gdb Template:Orange

6.3. Tips[edit | edit source]

Managing multiple debug setups

To manage multiple debug setups for different software versions, create different Path_env.gdb files with different names, and call the expected file in the Setup.gdb file:

...
####################################################################

# Set environment configuration
#Path_env.gdb
source Path_env_dk2_18_12_14.gdb

####################################################################
...

7. References[edit | edit source]

Useful external links

Document link	Document Type	Description
Using kgdb, kdb and the kernel debugger internals	User Guide	KGDB documentation guide
Welcome to the GDB Wiki	User guide	GDB Wiki
Building GDB and GDBserver for cross debugging	User Guide	Explain how to build gdb for target and host
A GDB Tutorial with Examples	Training	Debugging a simple application

[gdbgnudotorg-1] 1.0 ^1.1 https://www.gnu.org/software/gdb

[2] ttps://sourceware.org/gdb/onlinedocs/gdb/TUI.html#TUI

[3] ttps://ftp.gnu.org/old-gnu/Manuals/gdb/html_chapter/gdb_19.html

[4] ttps://www.gnu.org/software/ddd

[1]

[2]

[3]

[4]