Cortex-M Hardware Debug

Cortex-M Hardware Debug
	Chapter 289. Cortex-M Architectural Support

Name

Cortex-M Hardware Debug — Overview of hardware debug features

Introduction

Some Cortex-M designs may include the Instrumentation Trace Macrocell (ITM) and Data Watchpoint and Trace (DWT) features. The ITM allows for software generated “instrumentation” to be output via the Single Wire Debug (SWD) hardware interface in a relatively non-intrusive fashion. The SWD ITM support provides for much higher data rates than can normally be achieved via a UART, so they can provide for software controlled debug I/O support with a significantly reduced system overhead, which may be important for some eCos applications.

There is no explicit eCos support for making use of the DWT features, since the hardware debug tools being used can control the feature use independently of the eCos application. The specific hardware debug tools being used may provide support as required. For example the Ronetix PEEDI has built-in support for tracking DWT PC sample events for profiling.

Instrumentation Trace Macrocell (ITM)

If the Cortex-M ITM support is enabled in the CDL configuration then HAL diagnostics can be directed to a ITM stimulus port, and if instrumentation is enabled then event records directed to a different stimulus port. How the output data is processed or captured is dependent on the hardware tool being used to drive the SWD interface.

The following sections give a brief overview of using the Ronetix PEEDI hardware debugger, and the OpenOCD tool in conjunction with the STMicroelectronics ST-LINKv2 adapter. This is by no means an exhaustive list since many 3rd-party hardware tools exist, and any tool capable of handling ITM stimulus port output can normally be configured to accept console (HAL diagnostic) input or record captured data (instrumentation). More detail of specific variant or target SWD/JTAG setup and ITM stimulus port support may be found in the relevant eCos platform specific documentation.

Ronetix PEEDI

The documentation supplied with the Ronetix PEEDI provides an overview of using the Cortex-M ITM features. However, the example PEEDI configuration file BASE_DIR/packages/hal/cortexm/arch/current/misc/peedi.cortexm3.swd.cfg provided with eCos has comments on how the PEEDI can be configured to provide access to the data written to ITM stimulus ports on specific TCP network ports. It also provides an example of using the DWT PC sampling feature to gather non-intrusive application execution profiling.

The simplest use would be to use the telnet command to connect to the stimulus port connection being used for HAL diagnostics. When an application configured for ITM diagnostics is executed then the output will appear on the configured network port:

$ telnet peedi-0 2001
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
INFO:<code from 0x20000290 -> 0x2000e254, CRC 2a20>
…

Similarly the Linux nc command could be used to save data from an instrumentation port to a file for post-processing. For example, if the eCos application is built with Kernel instrumentation enabled and configured for ITM output, then the stimulus port output can be captured and processed using the example instdump tool provided in the Kernel package.

$ nc peedi-0 2003 > inst.bin
^C
$ instdump -r inst.bin elfapp
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 }
     …

OpenOCD

The OpenOCD ITM support is limited to using the ST-LINKv2 hardware interface to the target board. For example, as built-in to the STM32F4DISCOVERY and STM32x0G-EVAL platforms. The ST-LINKv2 firmware on the boards should be at least JTAG v17, so older boards may need to have their ST-LINK firmware updated via the relevant STMicroelectronics tool prior to being used for ITM stimulus port support.

The BASE_DIR/packages/hal/cortexm/stm32/stm32f4dis/current/misc/openocd.stm32f4dis.cfg file provides an example OpenOCD configuration file that captures ITM stimulus port data and directs it to a file named tpiu.out in the current directory at the time openocd was invoked. This file can then be interpreted by a program parseitm which can be found in this package in the directory packages/hal/cortexm/arch/VERSION/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, and it will echo all ITM stimulus for that port, continuing to read from the file until interrupted with Ctrl-C for example:

$ parseitm -p 31 -f tpiu.out

Note

	Note
Note that limited buffer space in debug hardware such as the ST-LINK can result in some ITM data becoming lost due to buffer overruns. eCosPro provides a workaround of throttling data within the `CYGHWR_HAL_CORTEXM_ITM_DIAGNOSTICS_THROTTLE` CDL configuration component of this package in order to reduce or avoid lost ITM data. Two approaches are available: "Chunk" or "Per-Character" throttling. In the case of Chunk throttling, a configurable number of characters are output before a delay is applied to allow the buffer to be emptied. However this can result in a longer delay while waiting for the buffer to empty. Alternatively, Per-Character throttling imposes a small delay after every character, whether it is needed or not. More detail on the behaviour of these configuration options can be found in the description of the "ITM Throttling" component (`CYGHWR_HAL_CORTEXM_ITM_DIAGNOSTICS_THROTTLE`) and its sub-options within the eCos Configuration Tool.

Note that limited buffer space in debug hardware such as the ST-LINK can result in some ITM data becoming lost due to buffer overruns. eCosPro provides a workaround of throttling data within the CYGHWR_HAL_CORTEXM_ITM_DIAGNOSTICS_THROTTLE CDL configuration component of this package in order to reduce or avoid lost ITM data.

Two approaches are available: "Chunk" or "Per-Character" throttling. In the case of Chunk throttling, a configurable number of characters are output before a delay is applied to allow the buffer to be emptied. However this can result in a longer delay while waiting for the buffer to empty. Alternatively, Per-Character throttling imposes a small delay after every character, whether it is needed or not.

More detail on the behaviour of these configuration options can be found in the description of the "ITM Throttling" component (CYGHWR_HAL_CORTEXM_ITM_DIAGNOSTICS_THROTTLE) and its sub-options within the eCos Configuration Tool.

These are just default examples; it is also possible to configure the eCos kernel to send its instrumentation output via ITM, and applications may make use of other stimulus ports for application-specific functionality.


The HAL Port		Chapter 290. Kinetis Variant HAL

2024-12-10

eCosPro Non-Commercial Public License