JTAG/SWD debugging support

JTAG/SWD debugging support
	Chapter 308. STM32F4DISCOVERY Platform HAL

Name

JTAG/SWD support — Usage

Use of JTAG/SWD for debugging

JTAG/SWD can be used to single-step and debug loaded applications, or even applications resident in ROM, including the GDB stub ROM.

Debugging of ROM applications is only possible if using hardware breakpoints. The Cortex-M4 core of the STM32F407VG only supports six such hardware breakpoints, so they may need to be used sparingly. If using a GDB front-end such as Eclipse, check it has not set unnecessary extra breakpoints such as at main(). Some JTAG/SWD devices give the option of whether to set hardware or software breakpoints by default. Be sure to configure your device appropriately.

When debugging via JTAG, you are likely to need to disable the default HAL idle thread action, otherwise there may be issues where the target fails to halt and the debugging session is unreliable. More details can be found in the Cortex-M architectural HAL. This should not be necessary when using a SWD-based hardware debugger such as the on-board ST-LINK/V2 interface.

The default eCos configuration does not enable the use of ITM stimulus ports for the output of HAL diagnostics or Kernel instrumentation. The architecture HAL package CYGPKG_HAL_CORTEXM provides options to enable such use.

For HAL diagnostic (e.g. diag_printf()) output the architecture CDL option CYGHWR_HAL_CORTEXM_DIAGNOSTICS_INTERFACE should be updated to select ITM as the output destination. Once the ITM option has been configured the option CYGHWR_HAL_CORTEXM_DIAGNOSTICS_ITM_PORT allows the actual stimulus port used for the diagnostics to be selected.

When the Kernel instrumentation option CYGPKG_KERNEL_INSTRUMENT is enabled then the CYGHWR_HAL_CORTEXM_ITM_INSTRUMENTATION option can be enabled to direct instrumentation record output via an ITM stimulus port, rather than into a local memory buffer. The stimulus port used can be configured via the CYGHWR_HAL_CORTEXM_ITM_INSTRUMENTATION_PORT_BASE option.

When using the STM32F4DISCOVERY board via the ST-LINK/V2 interface then it is recommended that the ITM stimulus port approach is used to provide access to diagnostics and instrumentation over the single USB host connection. This avoids the need for a seperate, and slower, UART connection for provision of the HAL diagnostic output, plus continuous streaming instrumentation can be output via ITM where only very small local RAM buffers would normally be available for the default “memory buffer” instrumentation support. This allows a single cable ST-LINK/V2 connection to provide board power, hardware debug support, diagnostic output and instrumentation capture features.

Normally a notable disadvantage with JTAG/SWD debugging is that it does not allow thread-aware debugging, such as the ability to inspect different eCos threads or their stack backtraces, set thread-specific breakpoints, and so on. Fortunately the Ronetix PEEDI JTAG unit does support thread-aware debugging of eCos applications, however extra configuration steps are required. Consult the PEEDI documentation for more details as usage is beyond the scope of this document.

OpenOCD notes

The OpenOCD debugger can be configured to support the on-board ST-LINK/V2 interface available via the USB CN1 connection, with the CN3 links closed to directly connect to the target STM32F407 CPU. When configuring the openocd tool build, the configure script can be given the option --enable-stlink to provide for ST-LINK support.

An example OpenOCD configuration file openocd.stm32f4dis.cfg is provided within the eCos platform HAL package in the source repository. This will be in the directory packages/hal/cortexm/stm32/stm32f4dis/current/misc relative to the root of your eCos installation.

This configuration file can be used with OpenOCD on the host as follows:

$ openocd -f openocd.stm32f4dis.cfg
Open On-Chip Debugger 0.9.0 (2015-09-18-16:19)
Licensed under GNU GPL v2
For bug reports, read
    http://openocd.org/doc/doxygen/bugs.html
Info : The selected transport took over low-level target control. The results might differ compared to plain JTAG/SWD
adapter speed: 2000 kHz
adapter_nsrst_delay: 100
none separate
Info : Unable to match requested speed 2000 kHz, using 1800 kHz
Info : Unable to match requested speed 2000 kHz, using 1800 kHz
Info : clock speed 1800 kHz
Info : STLINK v2 JTAG v17 API v2 SWIM v0 VID 0x0483 PID 0x3748
Info : using stlink api v2
Info : Target voltage: 2.886506
Info : stm32f4x.cpu: hardware has 6 breakpoints, 4 watchpoints

By default openocd provides a console on port 4444, and this can be used to interact with the target system. This console interface can be used to perform debugging, program the flash, etc.

Normally arm-eabi-gdb is used to connect to the default GDB server port 3333 for debugging. For example:

(gdb) target remote localhost:3333
Remote debugging using localhost:3333
0x00000000 in ?? ()
(gdb) monitor reset halt
target state: halted
target halted due to debug-request, current mode: Thread
xPSR: 0x01000000 pc: 0x0800422c msp: 0x20000c80
(gdb)

The application can then be loaded and executed under GDB as normal. If you are using Eclipse then you will need to define a “preload” gdb macro to emit the monitor reset halt command to OpenOCD. See the “Hardware Assisted Debugging” section of the “Eclipse/CDT for eCos application development” document's “Debugging eCos applications” chapter.

If the HAL diagnostics are configured to use ITM, and stimulus port 31 is configured as the HAL diagnostic destination, then the configuration example above will direct OpenOCD to direct ITM output (and also DWT and ETM) to a file named tpiu.out in the current directory of the shell which was used to run the openocd command. A more specific filename can be used by adjusting the OpenOCD configuration file.

To extract the ITM output, the Cortex-M architecture HAL package provides a helper program parseitm in the directory packages/hal/cortexm/arch/current/host relative to the root of your eCos installation. It can be compiled simply with:

$ gcc -o parseitm parseitm.c

You simply run it with the desired ITM stimulus port and name of the file containing the ITM output, for example:

$ parseitm -p 31 -f itm.out

It will echo all ITM stimulus for that port, continuing to read from the file until interrupted with Ctrl-C. Note that limited buffer space in debug hardware such as the ST-LINK can result in occasionally missed ITM data. eCosPro provides a workaround of throttling data within the CYGHWR_HAL_CORTEXM_ITM_DIAGNOSTICS_THROTTLE CDL configuration component in order to reduce or avoid lost ITM data. For further details, see the note in OpenOCD ITM support.

Similarly, if the eCos application is built with Kernel instrumentation enabled and configured for ITM output, then the default stimulus port 24 output can be captured. For example, assuming the application cminfo is the ELF file built from an eCos configuration with ITM instrumentation enabled, and is loaded and run via openocd, then we could run parseitm to capture instrumentation whilst the program executes, and then view the gathered data using the example instdump tool provided in the Kernel package.

$ parseitm -p 24 -f tpiu.out > inst.bin
^C
$ instdump -r inst.bin cminfo
Threads:
 threadid 1 threadobj 200045D0 "idle_thread"

     0:[THREAD:CREATE][THREAD 4095][TSHAL 4][TSTICK 0][ARG1:200045D0] { ts 4 microseconds }
     1:[SCHED:LOCK][THREAD 4095][TSHAL 45][TSTICK 0][ARG1:00000002] { ts 45 microseconds }
     2:[SCHED:UNLOCK][THREAD 4095][TSHAL 195][TSTICK 0][ARG1:00000002] { ts 195 microseconds }
     3:[SCHED:LOCK][THREAD 4095][TSHAL 346][TSTICK 0][ARG1:00000002] { ts 346 microseconds }
     4:[SCHED:UNLOCK][THREAD 4095][TSHAL 495][TSTICK 0][ARG1:00000002] { ts 495 microseconds }
     5:[THREAD:RESUME][THREAD 1][TSHAL 647][TSTICK 0][ARG1:200045D0][ARG2:200045D0] { ts 647 microseconds }
     6:[SCHED:LOCK][THREAD 1][TSHAL 795][TSTICK 0][ARG1:00000002] { ts 795 microseconds }
     7:[MLQ:ADD][THREAD 1][TSHAL 945][TSTICK 0][ARG1:200045D0][ARG2:0000001F] { ts 945 microseconds }
     8:[SCHED:UNLOCK][THREAD 1][TSHAL 1096][TSTICK 0][ARG1:00000002] { ts 1096 microseconds }
     9:[INTR:ATTACH][THREAD 1][TSHAL 0][TSTICK 0][ARG1:00000000] { ts 10000 microseconds }
    10:[INTR:UNMASK][THREAD 1][TSHAL 149][TSTICK 0][ARG1:00000000] { ts 10149 microseconds }
    11:[INTR:ATTACH][THREAD 1][TSHAL 305][TSTICK 0][ARG1:00000054] { ts 10305 microseconds }
    12:[INTR:UNMASK][THREAD 1][TSHAL 449][TSTICK 0][ARG1:00000054] { ts 10449 microseconds }

Ronetix PEEDI notes

On the Ronetix PEEDI, the peedi.stm32f4dis.cfg file supplied in the platform HAL package should be used to setup and configure the hardware to an appropriate state to load programs.

The peedi.stm32f4dis.cfg file also contains an option to define whether hardware or software breakpoints are used by default, using the CORE0_BREAKMODE directive in the [TARGET] section. The supplied version of the file defaults to software breakpoints. With this default, hardware breakpoints can still be set from GDB using the hbreak command, or in the eCosPro version of Eclipse by setting the Breakpoint Type - consult the "Eclipse/CDT for eCos application development" manual for details. The default can be changed to hardware breakpoints, and remember to use the reboot command on the PEEDI command line interface, or press the reset button to make the changes take effect.

On the PEEDI, debugging can be performed either via the telnet interface or using arm-eabi-gdb. In the case of the latter, arm-eabi-gdb needs to connect to TCP port 2000 on the PEEDI's IP address. For example:

(gdb) target remote 111.222.333.444:2000

By default when the PEEDI is powered up, the target will always run the initialization section of the peedi.stm32f4dis.cfg file, and halts the target. This behaviour is repeated with the reset command.

If the board is reset with the 'reset' command, and then the 'go' command is given, the board will boot from ROM as normal. A similar effect can be achieved in GDB by connecting with target remote and immediately typing continue or c.

It is also possible for the target to always run, without initialization, after reset. This mode is selected with the CORE0_STARTUP_MODE directive in the [TARGET] section of the peedi.stm32f4dis.cfg file. This conveniently allows the target to be connected to the PEEDI JTAG debugger, and be able to reset and run the resident Flash program without being required to always type 'go' every time. Finally, it is also possible to set a temporary default (unless the PEEDI is reset) by giving an argument to the reset command, for example reset run. Use the command help reset at the PEEDI command prompt for more options.

Suitably configured applications can be loaded either via GDB, or directly via the telnet CLI into RAM for execution. For example:

stm32f4discovery> memory load tftp://192.168.7.9/test.bin bin 0x20000000
++ info: Loading image file:  tftp://192.168.7.9/test.bin
++ info: At absolute address: 0x20000000
loading at 0x20000000
loading at 0x20004000

Successfully loaded 28KB (29064 bytes) in 0.1s
stm32f4discovery> go 0x20000000

Consult the PEEDI documentation for information on other formats and loading mechanisms.

For Eclipse users wishing to debug ROM startup programs resident in Flash, it is worth highlighting that it is possible to use the eCosCentric Eclipse plugin to automatically reprogram Flash as the load sequence. To do so, you will need to install and use a TFTP server so that your application can be accessed from the PEEDI from there. You may then use a GDB command file, as described in more detail in the "Eclipse/CDT for eCos application development" manual. This file can then contain contents similar to the following example:

define doload
  shell arm-eabi-objcopy -O binary /path/to/eclipse/workspace/projectname/Debug/myapp /path/to/tftp/server/area/myapp.bin
  monitor flash program tftp://10.1.1.1/myapp.bin bin 0x08000000 erase
  set $pc=0x08000000
end

Obviously you will need to adjust the paths and names for your system and TFTP server requirements.

Configuration of JTAG/SWD applications

JTAG/SWD applications can be loaded directly into RAM without requiring a ROM monitor. Loading can be done directly through the JTAG/SWD device, or through GDB where supported by the JTAG/SWD device.

In order to configure the application to support this mode, it is recommended to use the JTAG startup type which will implicitly cause two important settings to change. Firstly, CYGSEM_HAL_USE_ROM_MONITOR must be disabled. Secondly the CYGDBG_HAL_DIAG_TO_DEBUG_CHAN option should be enabled in order to prevent HAL diagnostic output being encoded into GDB ($O) packets. These configuration changes could be made by hand, but use of the JTAG startup type will just work.

With these changes, any diagnostic output will appear out of the configured diagnostic channel, usually a serial port. An eCosCentric extension allows diagnostic output to appear in GDB instead. For this to work, you must enable the configuration option CYGSEM_HAL_DIAG_TO_GDBFILEIO_CHAN in the common HAL package. Then, after you load your application but before running it, you must give GDB the command:

(gdb) set hwdebug on

Eclipse users can do this by creating a GDB command file with the contents:

define postload
  set hwdebug on
end

Thay may then reference it from their Eclipse debug launch configuration. Using GDB command files is described in more detail in the "Eclipse/CDT for eCos application development" manual.


Configuration		The HAL Port

2024-12-10

eCosPro Non-Commercial Public License