OpenOCD is an open source and free-of-charge debugging solution, which is a great option here at the University of Lucerne, as students do not need to buy an expensive debugging probe. Still, I recommend to buy professional probes like the P&E or Segger ones, as they are worth every (Euro) cent. But for a ‘zero’ budget, OpenOCD with CMSIS-DAP is something to consider. And with Kinetis Design Studio using the GNU ARM Eclipse Plugins, OpenOCD is not that hard to be used. And because both Freescale and GNU ARM Eclipse offer OpenOCD Windows binaries, that connection method is in the reach of Windows users too.

Outline

This post uses the FRDM-KL25Z to be debugged using OpenOCD with CMSIS-DAP. I’m using Eclipse Kepler and Kinetis Design Studio v2.0.0, but information should apply to different Eclipse versions too. This post is for Windows users, as Linux users probably are so familiar with re-building the kernel and building their own OpenOCD, that they very likely do not need any help ;-).

❗ I’m using the Freescale FRDM-KL25Z board. Be aware that not every microcontroller is supported by OpenOCD our of the box! I’m able to use with FRDM-KL02Z, FRDM-KL05Z, FRDM-KL25Z, FRDM-KL26Z, FRDM-KL46Z, FRDM-K22F and FRDM-K64F. But it did not work for me with the FRDM-K20D50 board.

Debugging with OpenOCD involves several components: below are the major components involved with Eclipse debugging a board through OpenOCD:

Eclipse with its debugging views is using a GDB client (arm-none-eabi-gdb executable in the case for ARM debugging). The GDB client communicates through TCP/IP with the OpenOCD GDB server. The GDB server needs some means to talk to the microcontroller, typically through a SWD/JTAG debugging probe. OpenOCD includes support for the CMSIS-DAP debugging transport protocol (see “Using the FRDM-KL25Z with CMSIS-DAP to program non-Freescale ARM Microcontrollers“). In the case of the FRDM board, there is a Kinetis K20 microcontroller on the board which acts as SWD debugging probe, running a CMSIS-DAP debugging firmware. This CMSIS-DAP firmware implements the USB HID communication protocol to the host and manages the SWD (Single Wire Debug) connection to the KL215Z128 micrcontroller:

Installation

You can get OpenOCD pre-built either with Kinetis Design Studio (http://www.freescale.com/kds) or from gnuarmeclipse.livius.net/blog/openocd/.

If installing Kinetis Design Studio, OpenOCD is present in the OpenOCD folder:

OpenOCD GDB Server

The GDB debugger (e.g. in Eclipse) does not directly talk to the board, it is talking to a server instead. The OpenOCD GDB server is located in openocd\bin as openocd.exe.

You can pass the option –version to find out the version of it:

The option –help shows this:

Open On-Chip Debugger 0.8.0-dev (2014-10-31-11:10)
Licensed under GNU GPL v2
For bug reports, read
        http://openocd.sourceforge.net/doc/doxygen/bugs.html
Open On-Chip Debugger
Licensed under GNU GPL v2
--help       | -h       display this help
--version    | -v       display OpenOCD version
--file       | -f       use configuration file 
--search     | -s       dir to search for config files and scripts
--debug      | -d       set debug level <0-4>
--log_output | -l       redirect log output to file 
--command    | -c       run

An important option is the –file one which tells OpenOCD the details about the hardware. The folder openocd\scripts contains configurations files which are device/board specific. For Freescale Kinetis devices the following kinetis.cfg file is installed with Kinetis Design Studio:

# Config Freescale Kinetis devices providing a CMSIS-DAP interface.

interface cmsis-dap

if { [info exists CHIPNAME] } {
    set _CHIPNAME $CHIPNAME
} else {
    set _CHIPNAME kinetis 
}

cmsis-dap newdap $_CHIPNAME cpu -irlen 4
global using_jtag
set using_jtag 0

set _TARGETNAME $_CHIPNAME.cpu
target create $_TARGETNAME cortex_m -chain-position $_CHIPNAME.cpu

$_TARGETNAME configure -work-area-phys 0x20000000 -work-area-size 0x1000 -work-area-backup 0

# Flash size is detected automatically.
flash bank $_CHIPNAME.flash kinetis 0 0 0 0 $_TARGETNAME

cortex_m reset_config sysresetreq

adapter_khz 1000

$_TARGETNAME configure -event gdb-attach {
  halt
}

What it does on a high level is configuring the connection to use the CMSIS-DAP interface and configures the CMSIS-DAP firmware/probe.

CMSIS-DAP Debug Firmware

The OpenOCD debug server needs a debugging probe it can talk to. For the FRDM boards there are several different firmware files available, see http://www.freescale.com/opensda. This site includes as well a download for a CMSIS-DAP firmware for the FRDM-KL25Z:

1. download and unzip “OpenSDAv1 CMSIS-DAP Debug Application”
2. Power the FRDM-KL25Z board with reset button pressed.
3. Copy the CMSIS-DAP_OpenSDA.S19 file to the BOOTLOADER:\ drive of your board.
4. Repower the board normally.

💡 See “Illustrated Step-by-Step Instructions: Updating the Freescale Freedom Board Firmware” for more details.

Now the board runs the CMSIS-DAP debug firmware which can be used with OpenOCD.

USB Drivers

The Achilles heel of any debug probe are the USB drivers, and this is not different for OpenOCD/CMSIS-DAP. With the FRDM-KL25Z board loaded with the CMSIS-DAP firmware loaded, it should show up in Windows as OpenSDA CMSIS-DAP device:

In the Windows Device manager, the CMSIS-DAP device shows up as ‘HID-compliant device’ and ‘USB Input Device’:

💡 So the CMSIS-DAP really is a HID like a keyboard or mouse device. The advantage is that no special drivers are needed. But on the other side I think this explains why CMSIS-DAP with OpenOCD is so slow (~1.8 kByte download speed per second compare to more than 40 kByte with Segger/P&E).

If you are using the mbed CMSIS-DAP (e.g. for FRDM-K22F and FRDM-K64F), then you should see three devices under ‘Devices and Printers’. You need to have the mbed special serial driver installed too:

GNU ARM Eclipse Debugger Plugin

The GNU ARM Eclipse Debugger plugins make it easy to use OpenOCD, as it offers all the important settings with panels:

• Executable: this is the path to the OpenOCD.exe (inside the bin folder of that folder)
• Config options: here the command line options and especially the configuration file passed to OpenOCD is specified. The -f option specifies the config file.
• GDB Client executable: this is the path to the gdb executable which then will talk to the OpenOCD executable.

If I launch the debug configuration, it will write something like this into the Console view:

Open On-Chip Debugger 0.8.0-dev (2014-10-31-11:10)
Licensed under GNU GPL v2
For bug reports, read
    http://openocd.sourceforge.net/doc/doxygen/bugs.html
Info : only one transport option; autoselect 'cmsis-dap'
Info : CMSIS-DAP: SWD  Supported
Info : CMSIS-DAP: Interface Initialised (SWD)
Info : add flash_bank kinetis kinetis.flash
cortex_m reset_config sysresetreq
adapter speed: 1000 kHz
Started by GNU ARM Eclipse
Info : CMSIS-DAP: FW Version = 1.0
Info : SWCLK/TCK = 0 SWDIO/TMS = 1 TDI = 0 TDO = 0 nTRST = 0 nRESET = 1
Info : DAP_SWJ Sequence (reset: 50+ '1' followed by 0)
Info : CMSIS-DAP: Interface ready
Info : clock speed 1000 kHz
Info : IDCODE 0x0bc11477
Info : kinetis.cpu: hardware has 2 breakpoints, 2 watchpoints
Info : accepting 'gdb' connection from 3333
target state: halted
target halted due to debug-request, current mode: Thread 
xPSR: 0x61000000 pc: 0x0000725c psp: 0x20000898
Info : Probing flash info for bank 0
Warn : acknowledgment received, but no packet pending
target state: halted
target halted due to debug-request, current mode: Thread 
xPSR: 0x61000000 pc: 0x00001b80 msp: 0x20003000
Warn : Any changes to flash configuration field will not take effect until next reset
Info : Padding image section 0 with 832 bytes
Warn : Requested write to flash configuration field 0xffffffff 0xffffffff 0xffffffff 0xfffffb7e transformed to 0xffffffff 0xffffffff 0xffffffff 0xfffffffe
Warn : Kinetis L Series supports Program Longword execution only.
Info : Kinetis: FLASH Write ...
target state: halted
target halted due to debug-request, current mode: Thread 
xPSR: 0x61000000 pc: 0x00001b80 msp: 0x20003000
===== arm v7m registers
(0) r0 (/32): 0x2000004C
(1) r1 (/32): 0x0000F800
(2) r2 (/32): 0x00000087
(3) r3 (/32): 0x00000087
(4) r4 (/32): 0x20000268
(5) r5 (/32): 0x40020000
(6) r6 (/32): 0x0000FA1C
(7) r7 (/32): 0xFFFFFF80
(8) r8 (/32): 0xA5A5A5A5
(9) r9 (/32): 0xA5A5A5A5
(10) r10 (/32): 0xA5A5A5A5
(11) r11 (/32): 0xA5A5A5A5
(12) r12 (/32): 0xA5A5A5A5
(13) sp (/32): 0x20003000
(14) lr (/32): 0x00007119
(15) pc (/32): 0x00001B80
(16) xPSR (/32): 0x61000000
(17) msp (/32): 0x20003000
(18) psp (/32): 0x20000898
(19) primask (/1): 0x00
(20) basepri (/8): 0x00
(21) faultmask (/1): 0x00
(22) control (/2): 0x00
===== Cortex-M DWT registers
(23) dwt_ctrl (/32)
(24) dwt_cyccnt (/32)
(25) dwt_0_comp (/32)
(26) dwt_0_mask (/4)
(27) dwt_0_function (/32)
(28) dwt_1_comp (/32)
(29) dwt_1_mask (/4)
(30) dwt_1_function (/32)

Starting OpenOCD

By default, OpenOCD is started locally when I press the debug button. There is a setting for this in the debug/launch configuration:

In case there are troubles starting OpenOCD (e.g. because of a firewall), it is possible to uncheck that option. In that case, I need to launch OpenOCD by hand:

bin\openocd.exe -f kinetis.cfg

Now the OpenOCD server is running, and I can connect to it from the debugger, with ‘Start OpenOCD locally’ unchecked. It will report the messages to the command prompt like it would do in the Eclipse console view.

Use CTRL+C in the cmd.exe to stop the OpenOCD executable.

Command Line Debugging without IDE

Because OpenOCD is independent of Eclipse or any IDE, it can be used to do command line debugging without an IDE :-).

First, have the OpenOCD server running. In a DOS/cmd prompt cd to the OpenOCD installation folder (e.g. in C:\Freescale\KDS_2.0.0\openocd), then launch OpenOCD with the config file:

bin\openocd -f kinetis.cfg

In a separate DOS/cmd console, launch the gdb client executable (e.g. in KDS the gdb executable is in c:\freescale\kds_2.0.0\toolchain\bin):

bin\arm-none-eabi-gdb.exe

Next, connect to the OpenOCD server on the default port 3333:

target remote localhost:3333

OpenOCD will acknowledge the connection:

with

monitor reset init

it halts and resets the target:

Then use the file command to specify the binary to load:

file <path to elf file>

💡 Use ‘/’ for the path/directory delimiter

GDB will ask you to confirm loading the binary and/or symbol file.

Then I can debug the program. Here are a few commands in gdb:

• continue: continues exectution. Use CTRL-C to break/stop
• step: perform a source line step.
• nexti: perform assembly stepping

use the ‘help’ or ‘help running’ command in gdb to find out more about stepping/running the program.

Use

quit

to detach from the program.

There are many things you can do and automate with gdb command line debugging. I recommend you try things out and explore the online help. See as well the links at the end of this post, or at http://users.ece.utexas.edu/~adnan/gdb-refcard.pdf.

Trouble Shooting

I faced several times problems with OpenOCD not being able to take control over the target microcontroller. Programming it with a Segger J-Link or P&E Multilink helped. Or use the MSD (Mass Storage Device) bootloader on the FRDM board to program a ‘well known and good LED blinking program’. Another good tip is to extend the configuration file (kinetis.cfg) with what Karibe has commented here: https://mcuoneclipse.com/2013/08/05/diy-free-toolchain-for-kinetis-part-5-linux-host-with-openocd-and-cmsis-dap/#comment-52384.

Using the command line debugging mode as shown above is a good way to do things step-by-step to find out what could be wrong.

Summary

Using OpenOCD is now easier than ever with two binary Windows distributions available: one from Freescale and one from GNU ARM Eclipse. While OpenOCD with CMSIS-DAP works quite good, I still feel it is not as robust as e.g. Segger or P&E solutions, especially with connecting to a running device, or if the program on the device is somehow not working ‘normally’. Using solely OpenOCD with CMSIS-DAP is not something I recommend: better to have Segger J-Link and/or P&E Universal Multilink at hand, because both of them were able to recover/regain access to devices where OpenOCD failed. But if you are looking for a ‘zero cost’ solution, then OpenOCD is the way to go, if you are ok with the slow speed of OpenOCD with CMSIS-DAP.

Because GDB is working with OpenOCD, the GDB command line debugging capabilities are great for anyone who does not want to use an IDE (at least not all the time ;-).

Links:

• OpenOCD: http://openocd.sourceforge.net/
• Installing GNU ARM Eclipse Plugins: DIY Free Toolchain for Kinetis: Part 7 – GNU ARM Eclipse Plugins
• Liviu’s GNU ARM Eclipse Plugins
• Liviu’s OpenOCD package
• Freescale Kinetis Design Studio: http://www.freescale.com/kds
• Freescale OpenSDA web site: http://www.freescale.com/opensda
• OpenOCD on Linux: karibe.ch/2013/08/setting-up-linux-opensource-build-and-debug-tools-for-freescale-freedom-board-frdm-kl25z/
• OpenOCD with CMSIS-DAP implementation: https://github.com/TheShed/OpenOCD-CMSIS-DAP

Happy OpenOCDing 🙂