[OpenSDAv2] Tutorial: Set-up the right debug interface for your IDE toolchain

bheemarao — Fri, 08 Oct 2021 07:50:44 GMT

Current Revision posted to Documents by bheemarao on 10/8/2021 7:50:44 AM

This Document was extracted from Anthony Huereca blog published at Freescale Community Forum https://community.freescale.com/docs/DOC-100720 with his agreement.

OpenSDA/OpenSDAv2 is a serial and debug adapter that is built into several Freescale evaluation boards. It provides a bridge between your computer (or other USB host) and the embedded target processor, which can be used for debugging, flash programming, and serial communication, all over a simple USB cable.

The OpenSDA hardware consists of a circuit featuring a Freescale Kinetis K20 microcontroller (MCU) with an integrated USB controller. On the software side, it implements a mass storage device, bootloader which offers a quick and easy way to load OpenSDA applications such as flash programmers, run-control debug interfaces, serial to USB converters, and more. Details on OpenSDA can be found in the OpenSDA User Guide.

The bootloader and app firmware that lay on top of the original OpenSDA circuit was proprietary. But recently ARM decided to open source their CMSIS-DAP interface, and now a truly open debug platform could be created. This new open-sourced firmware solution is known as OpenSDAv2.

OpenSDAv2:

OpenSDAv2 uses the exact same hardware circuit as the original OpenSDA solution, and out of the box it still provides a debugger, drag-and-drop flash programmer, and virtual serial port over a single USB cable.

The difference is the firmware implementation:

OpenSDA: Programmed with the proprietary P&E Micro developed bootloader. P&E Micro is the default debug interface app.
OpenSDAv2: Programmed with the open-sourced CMSIS-DAP/mbed bootloader. CMSIS-DAP is the default debug interface app.

	Firmware Developer	Kinetis K20 Based Hardware Circuit	Default Debug Interface	Drag-and-drop Target MCUFlash Programming	Virtual Serial Port	Source Code Available
OpenSDA	P&E Micro	x	P&E Micro	.srec/.s19	x
OpenSDAv2	ARM/mbed.org	x	CMSIS-DAP	.bin	x	x

The bootloader and app firmware used by OpenSDAv2 is developed by the community at mbed.org, and is known as “CMSIS-DAP Interface Firmware”. If you explore that site, you will find that this firmware was also ported to run on other hardware, but the combination of this mbed.org firmware with the Kinetis K20 MCU is known as OpenSDAv2.

It is important to understand however that it is possible to run a P&E Micro debug app on the CMSIS-DAP/mbed bootloader found on OpenSDAv2. Likewise it is possible to run a CMSIS-DAP debug app on the P&E Micro bootloader found on OpenSDA. The debug application used needs to be targeted towards a specific bootloader though, as a single binary cannot be used on both the OpenSDA and OpenSDAv2 bootloaders.

OpenSDAv2 Apps:

mbed CMSIS-DAP (default app)
P&E Micro (found in Kinetis SDK beta release)
Segger JLink

OpenSDAv2 Bootloader:

The key difference between OpenSDA and OpenSDAv2 is the bootloader.

Boards with OpenSDA use a proprietary bootloader developed by P&E Micro, and it cannot be erased or reprogrammed by an external debugger due to the security restrictions in the firmware.
Boards with OpenSDAv2 use the open-source bootloader developed by mbed.org, and it can be erased and reprogrammed with an external debugger.

Apps need to be specifically tweaked to work with either the P&E bootloader (Original OpenSDA) or the CMSIS-DAP/mbed bootloader (OpenSDAv2) as the bootloader memory map is different. Thus it’s important to know which type of bootloader is on your board to determine which version of an app to load.

You can determine this by holding reset while plugging in the USB cable. A BOOTLOADER drive will appear for both OpenSDA and OpenSDAv2 as shown below.

The OpenSDAv2 bootloader (may also be called the CMSIS-DAP/mbed bootloader) developed by mbed.org will have the following files inside. Double clicking on bootload.htm will take you to the

mbed.org website.

The OpenSDA bootloader developed by P&E Micro will have the following inside. Clicking on SDA_INFO.HTM will take you to the P&E website.

Using CMSIS-DAP:

When you connect a Freedom board that has OpenSDAv2 (such as the FRDM-K64F) to your computer with a USB cable, it will begin running the default CMSIS_DAP/mbed application.

You will see a new disk drive appear labeled “MBED”.

You can then drag-and-drop binary (.bin) files onto the virtual hard disk to program the internal flash of the target MCU.

OpenSDAv2 will also enumerate as a virtual serial port, which you can use a terminal program. such as TeraTerm (shown below), to connect to. You may need to install the mbed Windows serial port driver first before the serial port will enumerate on Windows properly. It should work without a driver for MacOS and Linux.

The CMSIS-DAP app also allows you to debug the target MCU via the CMSIS-DAP interface. Select the CMSIS-DAP interface in your IDE of choice (IAR, Keil), and inside the CMSIS-DAP options select the Single Wire Debug (SWD) option as shown below :

IAR:

Keil:

Resources

CMSIS-DAP Interface Firmwarembed.org FRDM-K64 Page

FRDM-K64 User GuideOpenSDAv2 on MCU on Eclipse blog

OpenSDA User Guide

Appendix A: Building the CMSIS-DAP Debug Application

The open source CMSIS-DAP Interface Firmware app is the default app used on boards with OpenSDAv2. It provides:

Debugging via the CMSIS-DAP interface
Drag-and-drop flash programming
Virtual Serial Port providing USB-to-Serial convertor

While binaries of this app are provided for supported boards, some developers would like to build the CMSIS-DAP debug application themselves.

This debug application can be built for either the OpenSDAv2/mbed bootloader, or for the original OpenSDA bootloader developed by P&E Micro. If you are not sure which bootloader your board has, refer to the bootloader section in this document.

Building the CMSIS-DAP debug application requires Keil MDK. You will also need to have the “Legacy Support for Cortex-M Devices” software pack installed for Keil.

You will also need Python 2.x installed. Due to the python script used, Python 3.x will not work.

You can download and get the CMSIS-DAP source code from https://github.com/mbedmicro/CMSIS-DAP using the Download ZIP link.

The source can also be downloaded via git:

“git clone https://github.com/mbedmicro/CMSIS-DAP.git”

The source code can be seen as shown below:

This repository contains the files for both the bootloader and the CMSIS-DAP debug interface application. We will concentrate on the interface application at the moment.

Open up Keil MDK, and open up the project file located at \CMSIS-DAP\interface\mdk\k20dx128\k20dx128_interface.uvproj

In the project configuration drop-down box, you will notice there are a lot of options. Since different chips may have slightly different flash programming algorithms, there is a target for each specific evaluation board. In this case, we will be building for the FRDM-K64F board. Scroll down until you get to that selection:

Notice there are three options for the K64:

k20dx128_k64f_if: Used for debugging the CMSIS-DAP application with Keil. Code starts at address 0x0000_0000
k20dx128_k64_if_openSDA_bootloader: Creates a binary to drag-and-drop on the P&E developed bootloader (Original OpenSDA)
k20dx128_k64_if_mbed_bootloader: Creates a binary to drag-and-drop onto the CMSIS-DAP/mbed developed bootloader (OpenSDAv2)

Since the FRDM-K64F comes with the OpenSDAv2 bootloader, we will use the 3^rd option. If we were building the mbed app for another Freedom board which had the original OpenSDA bootloader,

we would choose the 2^nd option instead.

Now click on the compile icon. You may get some errors

If you get an error similar to the one shown below, make sure you have installed the Legacy pack for ARM as previously described earlier:

compiling RTX_Config.c... ..\..\Common\src\RTX_Config.c(184): error: #5: cannot open source input file "RTX_lib.c": No such file or directory

and

compiling usb_config.c...

..\..\..\shared\USBStack\INC\usb_lib.c(18): error: #5: cannot open source input file "..\..\RL\USB\INC\usb.h": No such file or directory

If you get an error regarding a missing version_git.h file, make sure that Python 2.x and git are in your path. A Python build script fetches that file.
If there is a warning about “invalid syntax” when running the Python script, make sure your using Python 2.x. Python 3.x will not work with the build script.

Now recompile again, and it should successfully compile. If you look now in \CMSIS-DAP\interface\mdk\k20dx128 you will see a new k20dx128_k64f_if_mbed.bin file

If you compiled the project for the OpenSDA bootloader, there would be a new k20dx128_k64f_if_openSDA.S19 file instead.

Loading the CMSIS-DAP Debug Application:

Now take the Freedom board, press and hold the reset button as you plug in the USB cable. Then, drag-and-drop the .bin file (for OpenSDAv2) or .S19 file (for OpenSDA) into the BOOTLOADER drive that enumerated.

Perform a power cycle, and you should see a drive called “MBED” come up and you can start using the CMSIS-DAP debug interface, as well as drag-and-drop programming and virtual serial port as described earlier in this document.

Appendix B: Building the CMSIS-DAP Bootloader

All Freedom boards already come with a bootloader pre-flashed onto the K20. But for those building their own boards that would like to use CMSIS-DAP, or those who would like to tinker with the bootloader, it possible to flash it to the Kinetis K20 device. Flashing the bootloader will require an external debugger, such as the Keil ULink programmer or Segger JLink.

Also note that the OpenSDA/PE Micro Bootloader cannot be erased! Due to the proprietary nature of the P&E firmware used by the original OpenSDA, it can only be programmed at the board manufacturer and JTAG is disabled. So these instructions are applicable for boards with OpenSDAv2 only.

First, open up the bootloader project which is located at \CMSIS-DAP\bootloader\mdk\k20dx128\k20dx128_bootloader.uvproj

There is only one target available because all OpenSDAv2 boards will use the same bootloader firmware as the hardware circuitry is the same.

Click on the compile icon and it should compile successfully. If you see errors about a missing version_git.h file, note that Python 2.x must be in the path to run a pre-build script which fetches that file.

Now connect a Keil ULink to J10 and then insert a USB cable to provide power to J26. Note that if you have the 20-pin connector, you’ll want to use the first 10 pins.

Then for Keil 5 you will need to change some debug options (CMSIS-DAP is built under Keil 4.x).

Right click on the bootloader project, and go to the Debug tab and next to ULINK Pro Cortex Debugger, click on Settings:

Then under “Cortex-M Target Driver Setup”, change the “Connect” drop down box to “under Reset” and “Reset” dropdown box to “HW RESET”. Hit OK to save the settings.

Then in Keil, click on Flash->Erase.

And then on Flash->Download.

If you get an “Invalid ROM Table” error when flashing the CMSIS-DAP bootloader, make sure you made the changes to the debugger settings listed above.

After some text scrolls by, you should see:

Now power cycle while holding down the reset button, and you should see the bootloader drive come up. You’ll then need to drag and drop the mbed application built earlier onto it. And that’s all there is to it!

The binaries for the bootloader and CMSIS-DAP debug app for the FRDM-K64F board created in writing this guide are attached.

Attachments:

community.element14.com/.../k20dx128_5F00_bootloader.axf.zip
community.element14.com/.../k20dx128_5F00_k64f_5F00_if_5F00_mbed.bin.zip