OpenOCD/CMSIS-DAP Debugging with Eclipse and without an IDE

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.

FRDM-KL25Z with OpenOCD Debug

FRDM-KL25Z with OpenOCD Debug

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:

OpenOCD GDB Debug Chain

OpenOCD GDB Debug Chain

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:

FRDM-KL25Z with OpenOCD Debug

FRDM-KL25Z with OpenOCD Debug

Installation

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

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

OpenOCD in KDS V2.0.0

OpenOCD in KDS V2.0.0

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:

OpenOCD version

OpenOCD version

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:

OpenSDA CMSIS-DAP

OpenSDA CMSIS-DAP

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

CMSIS-DAP as HID

CMSIS-DAP as HID

💡 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:

mbed devices

mbed devices

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:

OpenOCD with GDB in GNU ARM Eclipse

OpenOCD with GDB in GNU ARM Eclipse

  • 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:

Start OpenOCD locally

Start OpenOCD locally

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
OpenOCD launched by hand

OpenOCD launched by hand

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.

Debug with OpenOCD started manually

Debug with OpenOCD started manually

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
running openocd

running openocd

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
running gdb

running gdb

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

target remote localhost:3333
connecting gdb to OpenOCD

connecting gdb to OpenOCD

OpenOCD will acknowledge the connection:

OpenOCD connected to gdb

OpenOCD connected to gdb

with

monitor reset init

it halts and resets the target:

gdb monitor reset

gdb monitor reset

OpenOCD with monitor init reset

OpenOCD with monitor init reset

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

file <path to elf file>

💡 Use ‘/’ for the path/directory delimiter

Loading ELF File with GDB

Loading ELF File with GDB

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:

Happy OpenOCDing 🙂

Advertisements

13 thoughts on “OpenOCD/CMSIS-DAP Debugging with Eclipse and without an IDE

  1. Hello Erich! How are you?

    When I enable the security flash option, are all forms of debug disabled?

    When checking this option, the debug refuses through OpenSDA. Is it correct to think that the debug is not possible using JTAG or OpenOCD because flash is secured?

    Thanks! Have a nice spring!

    Like

    • Hi Carlos,
      sorry, I have seen your other question/forum topic, but had no time to look at it. I have not played with OpenOCD and device security, but it would be no surprise if OpenOCD would have an issue with this. In general, I know these:
      a) If you enable both the flash security and the mass erase disabled, you will brick your device.
      b) CodeWarrior and many flash programming algos will modify the binary and will save you from a). You will need either use the Segger ‘security’ flash algo, or use a direct ‘flash to file’ if you really want to brick your device.
      c) most flash algos/probes will do a mass erase before programming. So if you have your device secured (and the mass erase bit not set), it will still be able to program your part.

      Like

  2. Pingback: Command Line Programming and Debugging with GDB | MCU on Eclipse

  3. It seems that mainline OpenOCD actually does not support the cfg file, giving this:

    kinetis.cfg:11: Error: invalid subcommand “newdap kinetis cpu -irlen 4”

    Which based on this (https://community.freescale.com/thread/357363) seems to indicate that Freescale made their own patches to OpenOCD and either not shared them back upstream or OpenOCD hasn’t had a chance to merge the patches in yet.

    To confirm, could you do a openocd -v and throw it on here, and where you got your openocd from? Or did it come with the Eclipse Plugin?

    Open On-Chip Debugger 0.9.0 (2015-05-19-13:50)

    Like

    • Yes, OpenOCD mainline is different. That version of OpenOCD has been patched by Somnium (not by Freescale). My version gives this:
      Open On-Chip Debugger 0.8.0-dev (2015-01-09-16:22)
      It comes with Kinetis Design Studio V2.0.0 and V3.0.0 installed (www.freescale.com/kds). Freescale has on that site as well the source file package of it.

      Like

  4. I have the FRDM-KL26Z board.. I can’t seem to find CMSIS-DAP from mbed for this, only the 25Z. Should it be ok?

    I managed to get OpenOCD mostly working.. but it kept losing connection randomly.

    Like

    • Hi Joey,
      yes, that should be ok too. I’m using a generic CMSIS-DAP which is part of the FRDM-KL25Z package. If you want to have a more stable debug connection, I recommend to use either the P&E or Segger OpenSDA firmware.

      Like

  5. Hello

    I’m trying to debug and I’m getting the following error:

    GNU ARM Eclipse 64-bits Open On-Chip Debugger 0.10.0-dev-00141-g09aeb96-dirty (2015-10-28-11:39)
    Licensed under GNU GPL v2
    For bug reports, read
    http://openocd.org/doc/doxygen/bugs.html
    embedded:startup.tcl:60: Error: Can’t find kinetis.cfg
    in procedure ‘script’
    at file “embedded:startup.tcl”, line 60

    What am I missing?

    Thanks!!

    Like

    • so it seems that you are using openOCD 0.10.0. I think only 0.8.0 works.
      And it is looking for the kinetis.cfg (specified in the launch config)?
      That file included in Kinetis Design Studio.

      Like

      • Erich

        Thank you for the answer.

        Can I get kinetis.cfg file somewhere else? Because I don’t have KDS.

        Thanks!

        Like

      • Manuel,
        I have pasted the content of that file below.
        Erich

        # 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
        }

        Like

What do you think?

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s