OpenOCD notes

The OpenOCD debugger can be configured to support the on-board ST-LINK/V2-1 interface available via the USB CN14 connection. 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.stm32l476_disco.cfg is provided within the eCos platform HAL package in the source repository. This will be in the directory packages/hal/cortexm/stm32/stm32l476_disco/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.stm32l476_disco.cfg
Open On-Chip Debugger 0.10.0-dev-00371-g81631e4 (2016-09-08-17:23)
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: 480 kHz
adapter_nsrst_delay: 100
srst_only separate srst_nogate srst_open_drain connect_assert_srst
Info : clock speed 480 kHz
Info : STLINK v2 JTAG v20 API v2 SWIM v4 VID 0x0483 PID 0x374B
Info : using stlink api v2
Info : Target voltage: 3.227369
Info : stm32l4x.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)

The application can then be loaded and executed under GDB as normal. If you are using Eclipse then, if required, you can define a “preload” gdb macro to emit any necessary commands 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 then 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 }

Configuration of JTAG/SWD applications

JTAG/SWD applications can be loaded directly into SRAM or flash 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 these modes, it is recommended to use the SRAM, ROM or ROMAPP startup types 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 aformentioned startup types will just work.

With these changes, any diagnostic output will appear out of the configured diagnostic channel. An eCosCentric extension allows diagnostic output to appear in GDB. For this feature to work, you must enable the configuration option CYGSEM_HAL_DIAG_TO_GDBFILEIO_CHAN in the common HAL package. If you are using the graphical configuration tool then you should then accept any suggested solutions to the subsequent configuration conflicts. Older eCos releases also required the gdb "set hwdebug on" command to be used to enable GDB or Eclipse console output, but this is no longer required with the latest tools.