CMSIS-DAP Debugger User's Guide: CMSIS-DAP Debugger User's Guide

Keil, An ARM® Company CMSIS-DAP Debugger User's Guide

The CMSIS-DAP Debugger User's Guide describes the configuration options of the CMSIS-DAP Debugger driver implemented in µVision. The driver can be used to flash and debug applications on Cortex-M processor-based devices. The CMSIS-DAP Debugger is a software component that executes on a host computer and connects to the Debug Unit of the target hardware via USB.

This manual contains the following chapters:

  • About CMSIS-DAP describes the concept, benefits, and requirements.
  • Configure Debugger Driver in µVision and setup the options for downloading and debugging applications.
  • Using the Debugger describes the steps for downloading an application to Flash and starting a debugging session.
  • Configure Cortex-M Devices for Tracing explains the settings needed for enabling trace by means of certain devices.

Copyright © Keil, An ARM Company. All rights reserved.


CMSIS-DAP Debugger User's Guide: Configure Cortex-M Devices for Tracing

Configure Cortex-M Devices for Tracing

The examples below show trace configuration settings for selected device families using a Debug Initialization File.

  • Cortex-M0+ and Cortex-M23 MTB Devices
  • Freescale MKL25Z Devices


CMSIS-DAP Debugger User's Guide: Known Limitations

Known Limitations

Connect & Reset Options

The following known issues might arise for the listed Connect & Reset Options types:

without Stop

  • Toolbar buttons will falsely indicate that the CPU enters debug halt before disconnecting from a running target.
  • The debugger cannot find an exact synchronization point for starting trace capture and for initializing the CPU States (cycle count) mechanism. Hence, trace timestamps can diverge from the States variable in the Register window after connecting to a running target. This persists until the CPU is stopped for the first time.


CMSIS-DAP Debugger User's Guide: Cortex-M0+/M23 MTB Devices

Cortex-M0+/M23 MTB Devices

Many Cortex-M0+ and Cortex-M23-based devices provide simple instruction trace support by integrating Arm© CoreSightTM Micro Trace Buffer (MTB) technology.

When MTB is enabled, the trace data is stored in a user-configurable circular on-chip trace buffer that is located in device RAM and shares it with the executed application. It is crucial to ensure that MTB area in RAM is not used for the application variables, stack, and heap. Once the program is stopped, the debugger transfers the trace frames currently in the RAM to the Trace Instruction window on the host computer.

The device, the debugger adapter, and µVision have to be configured properly to capture MTB trace on such targets:

  • Enable MTB Trace


CMSIS-DAP Debugger User's Guide: Enable MTB Trace

Enable MTB Trace

To enable Micro Trace Buffer (MTB) instruction tracing for Cortex-M0+/M23 processor-based devices:

  • Configure µVision project to capture MTB trace data as described below.
  • Make sure that CMSIS-DAP is properly configured in µVision and debug connection to the target is present.
  • Restart the debug session and observe the captured trace in µVision Trace Data Window.

Note:

  • Due to its intrinsic simplicity, MTB doesn't support advanced, trace-based features available in µVision, such as Performance Analyzer, Execution Profiler, Code Coverage, Logic Analyzer.
  • MTB tracing works on all supported debug probes in Serial Wire Debug (SWD) as well as in JTAG Debug modes.

Configure µVision project to capture MTB trace data

µVision uses a debug initialization file that configures and enables the MTB in application projects before the debug session starts. MTB configuration steps described below apply to all supported debug probes.

  1. Create a text *.ini file and enter the code that configures the MTB on the target device.

    Many MDK example applications already contain in the root folder a pre-configured initialization file for MTB setup (DBG_MTB.ini).

    The initialization code is typically annotated for µVision Configuration Wizard support and looks like below:

    /******************************************************************************/
/* DBG_MTB.ini: Initialization Script for Cortex-M0+ MTB(Micro Trace Buffer)  */
/******************************************************************************/
// <<< Use Configuration Wizard in Context Menu >>>                           //
/******************************************************************************/

/*-------------------------------------------------------------------
** Define the function to enable the trace port
**-----------------------------------------------------------------*/
FUNC void MTB_Setup (void) {
  unsigned long position;
  unsigned long master;
  unsigned long watermark;
  unsigned long _flow;
  unsigned long positionRegAddr;

// <e0.31> Trace: MTB (Micro Trace Buffer)
//    <o0.0..4> Buffer Size
//      <4=> 256B
//      <5=> 512B
//      <6=> 1kB
//      <7=> 2kB
//      <8=> 4kB
//      <9=> 8kB
//      <i> Trace buffer size in device RAM. MTB memory shall not be used by application.
//   <o1> Buffer Position
//     <i> Starting address of the trace buffer in RAM. MTB memory shall not be used by application.
//   <o2.0> Stop Trace when buffer is full
//   <o2.1> Stop Target when buffer is full
//   <o3> MTB register address
//     <i> Device-specific address of the MTB position register.
// </e>

/* Parameters linked to the Configuration Wizard */
  master     = 0x80000006;
  position   = 0x20000000;
  _flow      = 0x00000000;
  positionRegAddr = 0x41006000;

/* Preparing values for MTB register */
  position  &= 0xFFFFFFF8; // Mask POSITION.POINTER field
  watermark  = position + ((16 << (master & 0x1F)) - 32);
  _flow     |= watermark;

/* Writing values to the MTB registers on the device */
  _WDWORD(positionRegAddr+4, 0x00000000); // Clear MTB MASTER register
  _WDWORD(positionRegAddr, position);     // Write to MTB POSITION register
  _WDWORD(positionRegAddr+8, _flow);      // Write to MTB FLOW register
  _WDWORD(positionRegAddr+4, master);     // Write to MTB MASTER register to enable MTB
}

/*-------------------------------------------------------------------
** Invoke the function at debugger startup
**-----------------------------------------------------------------*/
MTB_Setup();

    To adapt this code to a custom application project, open the .ini file in µVision and specify following parameters using Configuration Wizard as shown on the figure below:

    • Trace buffer position and size in device RAM. For proper operation, it is critical to ensure that MTB is located in the RAM area that is not used by the executed firmware.

    • Stop Trace and Stop Target flags when trace buffer is full. As MTB is a circular buffer that gets read only when debug is paused, these flags help to ensure that trace data can be read before it gets overwritten.

    • Device-specific address of the MTB position register according to the device datasheet.

  2. Open the dialog Options for Target, go to the Debug tab and provide the path to the DBG_MTB.ini file in the Initialization File field.

  3. Enable MTB trace

After restarting the debug session the captured trace data can be now observed in µVision Trace Data Window.

Note:

  • See MTB configuration for Cortex-M0+ based NXP MKL25Z devices for platform-specific example.
  • Application Note 237 further explores MTB configuration and operation on Cortex-M0+ NXP LPC800 devices.


CMSIS-DAP Debugger User's Guide: Pack Options

Pack Options

Pack options are available for devices that have been delivered with a CMSIS Pack debug description. Software Pack vendors can define debug descriptions for development tools to connect the debugger to a device for debugging, tracing, or flash programming. Default values defined in the debug description are applied to the options in Debug Driver and Flash Download. Options in the screens mentioned above can be changed manually.

To configure CMSIS-DAP Debugger for using the debug description:

  1. Target Options Open the dialog Options for Target ... — Debug.
  2. Enable Use and select CMSIS-DAP Debugger.

  3. Click Settings to open the Target Driver Setup dialog. Next click on Pack (only for some devices).

    Target Driver Setup - Trace

    Pack | Displays the Software Pack that contains the debug description.
    Enable | Enable the debug description.
    Log Sequence | Enable logging of the Debug Access Sequence execution. The next box shows the base name for the generated files. The '*'-wildcard at the end is replaced by a four digit decimal index when generating the files. Each file has a size limit of 100 MByte. New indexes are started if the device changes, if the build target changes, or if a new project is loaded. Otherwise, logs are appended to the currently opened file.
    Configuration | Path to the Debug Configuration (dbgconf) file. The project folder is the root folder. This file is an optional part of the debug description and might not exist.
    Edit | Open the debug configuration file to modify device specific debug settings for this target.

Configuring debug settings

The dbgconf file usually contains Configuration Wizard annotations that make it easy to change the debug configuration:

Target Driver Setup - Trace

Notes

While configuring debug settings is optional in most cases, it is essential for complex devices with Arm Cortex-M23 or M33 cores that require correct setup before Flash downloading. Consult the device user manual for more information.


CMSIS-DAP Debugger User's Guide: Configure for Tracing

Configure for Tracing

Trace Configuration options are set in the dialog Target Driver Setup - Trace and define the way trace events are generated and captured.

To configure CMSIS-DAP Debugger for tracing:

  1. Target Options Open the Options for Target ... - Debug dialog of µVision.
  2. Enable Use and select CMSIS-DAP Debugger.

  3. Click Settings to open the Target Driver Setup dialog, and choose the Trace tab.

    Target Driver Setup - Trace

The following configuration options determine the communication type, speed, and ports used while tracing data:

  • General Settings determine the over all behavior while tracing data.
  • Trace Port defines the trace channel and tracing speed.
  • ITM Stimulus Ports can steer debugging or program-specific information that are obtained from the target device.

These following configuration options determine the captured trace data and trace events:

  • Timestamps allows time information to be sent along with trace events.
  • PC Sampling enables Program Counter information, which indicate the program location that triggered the event.
  • Trace Events obtains information on specific CPU events.

Note

  • CMSIS-DAP firmware needs to be version V1.10 or newer to support SWO trace. Verify the firmware in CMSIS-DAP JTAG/SW Adapter.
  • If the screen shows the Pack tab, then go to Pack Options to modify CMSIS Pack debug description settings.
  • Use an Initialization File to Configure Cortex-M Devices for Tracing or debugging. Commands of an initialization file are executed prior to downloading the application to Flash. Refer to Pre-Download Scripts for information about initialization files.


CMSIS-DAP Debugger User's Guide: Component Viewer

Component Viewer

The Component Viewer shows information about:

  • Software components that are provided in static memory variables or structures.
  • Objects that are addressed by an object handle.
  • Events and time information generated by event annotations in a software component using the Event Recorder.

The picture below is an example showing debug information for an USB Device object:

Refer to Component Viewer documentation for more information.


CMSIS-DAP Debugger User's Guide: Configure for Debugging

Configure for Debugging

Configure the CMSIS-DAP Debugger for debugging applications with µVision:

  1. Options for Target Button Open the dialog Options for Target - Debug to select the driver:

    Set Use: and select CMSISI-DAP Debugger from the drop-down list.

    Select Target Driver

  2. Click the button Settings for fine-tuning the debugging behavior. The button opens the dialog Cortex-M Target Driver Setup.

    Target Driver Setup

    The dialog consists of three groups of information and configuration settings:
    • CMSIS-DAP JTAG/SW Adapter
    • JTAG/SW Device
    • Debug


CMSIS-DAP Debugger User's Guide: Configure Debugger Driver

Configure Debugger Driver

Just a few steps are needed in µVision to setup the CMSIS-DAP Debugger driver:

  • Configure for Flash Programming explains how to define the behavior when downloading applications to target hardware.
  • Configure for Debugging describes configuration options for debugging applications that run on target hardware.
  • Pack Options shows how to enable debug descriptions delivered with Software Packs.
  • Configure Cortex-M Devices for Tracing explains the options for capturing MTB trace data from applications that run on target hardware.


CMSIS-DAP Debugger User's Guide: CMSIS-DAP JTAG/SW Adapter

CMSIS-DAP JTAG/SW Adapter

Target Driver Setup - CMSIS-DAP Adapter The section CMSIS-DAP JTAG/SWD Adapter displays driver, device, and firmware information.

Serial No displays the identifier of the debugger adapter in use. When more adapaters are connected, use the drop-down list to specify the adapter or driver. The field can stay empty for the CMSIS-DAP driver.

Firmware Version displays the firmware version detected on the device.

SWJ enables the driver to switch between JTAG and Serial Wire (SW) mode. Enable SWJ on devices with a combined Serial Wire/JTAG interface. Disable SWJ on devices that only have the Serial Wire interface mode.

Port sets the internal debugging interface: SW (default) or JTAG. In case a port type is not supported, the dialog shows corresponding error messages. In addition, the fields displaying driver characterisitics are grayed out.

Max Clock sets the debugging clock rate for communicating to the target board.


CMSIS-DAP Debugger User's Guide: JTAG/SW Device

JTAG/SW Device

This section of the dialog displays information about the connected target device. Depending on the selected Port, this section shows the credentials of the SW Device or the JTAG Device Chain.

SW Device shows one or more debug targets connected through the Serial Wire interface. The IDCODE and Device Name are displayed automatically for each device.

Target Driver Setup - SW Device

JTAG Device Chain shows one or more debug targets connected through the JTAG interface. The IDCODE, Device Name, and IR Length are displayed automatically for each device. Manual Configuration allows identifying undetected JTAG devices. Specify the instruction register length (IR len) of each device in the JTAG device chain.

Target Driver Setup - JTAG Device Chain

AP field specifies the identifier of the Access Port in multi-core devices with a single Debug Port (DP). The Access Port specification depends on the Arm Debug Interface (ADI) supported in the device.

  • For APv1 (ADIv5):
    • The AP value range is 0 to 255.
    • For single core devices, set AP to 0 (default).
    • For a multi-core device, core 0 is expected to have AP=0 and core 1 AP=1. However, the port identifiers are specified by the device manufacturer.
  • For APv2 (ADIv6):
    • Only SWD connection to ADIv6 target systems is currently supported.
    • The AP value range is 0x00000000 to 0xFFFFFFFF. The value needs to be set by a user for a target sub-system based on the information provided by the device vendor in documentation.
    • If AP value is set to 0xFFFFFFFF then µVision debugger will automatically connect to the AP of the first auto-detected CPU.
    • Debugger automatically requests power using Granular Power Requester (GPR) from Class 0x9 ROM Tables.
    • Only top-level APs are supported, not "nested APs" (AP exposing its registers via target memory accesses of a higher-level AP).

If AP contains an invalid identifier, the error message Invalid ROM Table is shown whenever a debugging session is started.

  • In case of an error, change the settings of the field Port or select another JTAG/SW Adapter.
  • Refer to Chaining Multiple Targets, if you have more than one target system connected to a single JTAG bus.


CMSIS-DAP Debugger User's Guide: Debug

Debug

The Debug section provides controls for connecting and reseting the device, and caching and downloading the code. The settings are applied each time a debugging session is started.

Target Driver Setup - Connect and Reset Options

Connect & Reset Options

Connect & Reset Options control the instructions executed while connecting to target.

Connect and Reset Options

Connect - controls the operations that are executed when the µVision debugger connects to the target device. The drop-down has the following options:

  • Normal just stops the CPU at the currently executed instruction after connecting.
  • with Pre-reset applies a hardware reset(HW RESET) before connecting to the device.
  • under Reset holds the hardware reset(HW RESET) signal active while connecting to the device. Use this option when the user program disables the JTAG/SW interface by mistake.
  • without Stop connects to and disconnects from the target device without explicitly stopping the CPU. Use this option, for example, to inspect memory or peripheral SFRs.

    To use this Connect type properly, set all the following options:

    • Disable Reset after Connect
    • Disable Options for Target - Debug - Load Application at Startup. Use the following command in an initialization script (refer to Creating Functions) or in the Command window to manually load debug information:
      LOAD %L INCREMENTAL. Refer to LOAD command.
    Refer to Known Limitations - without Stop for further details.

Reset after Connect (if enabled) performs a reset operation as defined in the Reset drop-down list (see below) after connecting to the target. When disabled, the debugger just stops the CPU at the currently executed instruction after connecting.

Reset controls the reset operations performed by the target device. The available options vary with the selected device and supported debug description that can be enabled in Pack Options.

  • Custom selects a reset method provided by the debug description that is different from the standard reset methods.
  • Autodetect selects the best suitable reset method for the target device. This can be a specialized reset or standard method. If Autodetect finds an unknown device, it uses the SYSRESETREQ method.
  • HW RESET performs a hardware reset by asserting the hardware reset (HW RESET) signal.
  • SYSRESETREQ performs a software reset by setting the SYSRESETREQ bit. The Cortex-M core and on-chip peripherals are reset.
  • VECTRESET performs a software reset by setting the VECTRESET bit. Only the Cortex-M core is reset. On-chip peripherals are not reset. For some Cortex-M devices, VECTRESET is the only way they may be reset. However, VECTRESET is not supported on Cortex-M0, Cortex-M0+, Cortex-M1, and ARMv8-M cores.

Stop after Reset permanently enables the Cortex-M Reset Vector Catch. This stops the CPU when running through the reset vector (e.g. because of pressing the reset button on the board, issuing a reset from uVision while the target is running; reset caused by a watchdog timer).

Stop after Bootloader stops the CPU after executing the bootloader instructions and is available only for some devices.

Log Debug Accesses writes target debug accesses and information about debug components detected in the device ROM table into a text file. The following accesses are logged:

  • MEM: Target Memory Access
  • AP: Access Port Register Access
  • DP: Debug Port Register Access

Note

  • Logging of memory block accesses are indicated as such, all read or written items of such a block access are logged.
  • Not all debug accesses are logged in detail to keep the output readable. For example, DP and AP register accesses that form a target memory access are not logged, but abstracted as a memory access.

The text file CMSIS-DAP_DebugLog_xxxx.log is created in the current project folder, where xxxx is a sequential number. The file limit is 100MB. If this limit is reached during a single debug session, then a new file is created.

Cache Options

Cache Options improve the µVision debugger performance during target debugging by caching target memory areas into the PC memory. By default, caching options are enabled to get maximum performance.

Cache Code informs the debugger that the downloaded program code will not change. When this option is set, µVision never reads the program code from the target system. Disable this option when the application includes self-modifying code or the program code might get overwritten.

Cache Memory determines whether memory displays are updated during a program stop. When this option is set, the debugger does not update memory displays until the execution of the next single step, procedure step, or go command. Disable this option to display the actual memory content (for example, the content of memory mapped peripherals) when the debugger is halted.

Download Options

Download Options control the downloading of code to the target system when starting a debugging session.

Verify Code Download compares the content of the target memory with the application program loaded in the debugger for each new debug session. Enable this option to ensure program correlation between the image loaded in target system and the image loaded in the µVision debugger. This prevents debugging the wrong code when working with various targets or more instances of µVision.

Download to Flash downloads code to all memory regions. When disabled, the debugger does not download code to the memory Address Range defined in the dialog Target Driver Settings - Programming Algorithms. Enable the option if the application is loaded into RAM and the Flash algorithm is defined for the same address range. By default, this option is disabled. Refer to the knowledgebase article µVision Debugger: Error 57: Illegal Address in Debugger Output Window.


CMSIS-DAP Debugger User's Guide: Event Recorder

Event Recorder

The Event Recorder shows execution status and event information, and helps to analyze the operation of software components.

The Event Recorder:

  • Increases the visibility to the dynamic execution of application program.
  • Provides filter capabilities for event types (Errors, API Calls, Operation, Details).
  • Allows unrestricted calls to Event Recorder functions from Threads, RTOS kernel, and ISRs.
  • Implements recording functions that do not disable ISR on ARMv7M (Cortex-M3, Cortex-M4, Cortex-M7).
  • Supplies fast time-deterministic execution of Event Recorder functions with minimal code and timing overhead. Thus, event annotations can remain in production code without the need to create a debug or release build.

Analysis Window Button Open the Event Recorder from View – Analysis Windows - Event Recorder.

Event Recorder Window

For more information, refer to the Event Recorder documentation.


CMSIS-DAP Debugger User's Guide: Freescale MKL25Z Devices

Freescale MKL25Z Devices

To enable CoreSight MTB tracing on Freescale MKL25Z devices:

  • Connect the target board and the host computer through a USB cable.
  • Configure µVision to capture MTB trace data.

Configure µVision to capture MTB trace data.

  1. Create a text file, for example DBG_MTB.ini, and enter the following code:
    /*-------------------------------------------------------------------
** Define the function to enable the trace port
**-----------------------------------------------------------------*/
FUNC void MTB_Setup (void) {
  unsigned long position;
  unsigned long master;
  unsigned long watermark;
  unsigned long _flow;

  master     = 0x80000008;
  position   = 0x20000000;
  _flow      = 0x00000000;

  position  &= 0xFFFFFFF8;              // Mask POSITION.POINTER field
  watermark  = position + ((16 << (master & 0x1F)) - 32);
  _flow     |= watermark;

  _WDWORD(0xF0000004, 0x00000000);      // MASTER
  _WDWORD(0xF0000000, position);        // POSITION
  _WDWORD(0xF0000008, _flow);           // FLOW
  _WDWORD(0xF0000004, master);          // MASTER
}

/*-------------------------------------------------------------------
** Invoke the function at debugger startup
**-----------------------------------------------------------------*/
MTB_Setup();

    Use the _WDWORD command to configure the device.

  2. Open the dialog Options for Target — Debug and insert DBG_MTB.ini into the field Initialization File.

    Configure the device for tracing

Start the debugging session and verify the captured trace data with a µVision window.

Note

  • Use the examples delivered with the Freescale board FRDM-KL25Z as a reference.
  • MTB tracing works in Serial Wire Debug as well as in JTAG Debug mode.


CMSIS-DAP Debugger User's Guide: About CMSIS-DAP

About CMSIS-DAP

CMSIS-DAP is the interface firmware for a Debug Unit that connects the Debug Port to USB. Debuggers, which execute on a host computer, connect via USB to the Debug Unit and to the Device that runs the application software. The Debug Unit connects via JTAG or SW to the target Device. ARM Cortex processors provide the CoreSight Debug and Trace Unit. CMSIS-DAP supports target devices that contain one or more Cortex processors.

The Debug Unit can be an integral part of the evaluation board or an external debug adapter.

Requirements

CMSIS-DAP can be used with:

  • MDK-ARM V4.54. (or later).
  • The Debug Unit in use must support the Firmware for the CoreSight Debug Access Port (CMSIS-DAP). The firmware gets implemented by the vendor of the device or debug adapter.
  • CMSIS-DAP firmware needs to be version V1.10 or newer to support SWO trace. Verify the firmware in CMSIS-DAP JTAG/SW Adapter.

Note

  • Ask the vendor of the Debug Unit about CMSIS-DAPsupport.


CMSIS-DAP Debugger User's Guide: Chaining Multiple Targets

Chaining Multiple Targets

Chaining multiple targets, or target chaining, refers to the ability to attach multiple target systems to one single JTAG bus. In this configuration, CMSIS-DAP Debugger can access one target at a time.

In order to chain targets, the devices must support the following:

  • BYPASS register.
  • The IDCODE instruction must immediately follow a reset of the Test Access Port (TAP).
  • Bit 0 of ID Code must be 1.
  • In CAPTURE-IR state, the fixed value 1 must be loaded into the IR.

Setting Up Multiple Targets

The CMSIS-DAP Debugger scans for an IDCODE, a device name, and an IR length for each target, and sets up targets automatically. The results of this scan are displayed in the JTAG Device Chain section of the ARM Target Driver Setup dialog (Project — Options for Target — Debug — Settings).

JTAG Device Chain display

If the automatic setup fails, you may use Manual Configuration to setup the attributes of each device. To use Manual Configuration, the target device must have BYPASS register support.

Connecting Targets

To connect multiple targets:

  • Connect the control signals (TMS and TCLK) connect in parallel.
  • Connect the data signals (TDI and TDO) in series.

The data output from one target (TDO) should be the input to the next target (TDI) in the chain.

Multiple Target Chaining Diagram

Note

  • Target chaining is possible in JTAG mode only.


CMSIS-DAP Debugger User's Guide: Debugging Applications

Debugging Applications

Follow the steps to debug applications using the µVision Debugger and CMSIS-DAP Debugger driver:

  1. Connect the target board to the PC using a USB cable.
  2. Configure CMSIS-DAP Debugger for Debugging.
  3. Start the Debugger.

    Start/Stop Debug Button Use the button Start/Stop Debug Session to start debugging the application.

Note

  • If the flag Update Target before Debugging is set, then the debugger loads the application to target prior to starting a debugging session.
  • Details about debugging features are explained in the µVision User's Guide chapter Debugging, and in the Getting Started User's Guide chapter Start Debugging.


CMSIS-DAP Debugger User's Guide: Downloading to Flash

Downloading to Flash

The CMSIS-DAP Debugger driver allows programming the Flash memory of the target system:

  1. Connect the target board to the PC using a USB cable.
  2. Setup the Flash Download Configuration.
  3. Download the application to Flash.

    Download to Flash Button Click the button Download to Flash to program the application to target.

    The Status Bar shows the download progress.

    Target Download Progress

    In addition, the window Build Output displays the individual download steps.

    Target Download Status

Thereafter, the application can be debugged on target.


CMSIS-DAP Debugger User's Guide: Configure for Flash Programming

Configure for Flash Programming

Flash programming using CMSIS-DAP can be configured in the Button Options for Target Options for Target - Utilities dialog. Available configuration options are explained in Flash Programming section in µVision User's Guide.

Select Target Driver


CMSIS-DAP Debugger User's Guide: Trace Events

Trace Events

Trace Events define which events are generated and captured while tracing. The window Event Counters shows the result.

Target Driver Setup - Trace Events

  • CPI: Cycles per Instruction A general counter for instruction cycle count estimation. This counter increments on each additional cycle required to execute a multi-cycle instruction. The counter also increments on each cycle of any instruction fetch stall. The first cycle of an instruction and those recorded by the LSU are not counted.
  • EXC: Exception Overhead The counter increments on each cycle associated with exception entry or return. That is, it counts the cycles associated with entry stacking, return unstacking, preemption, and other exception-related processes.
  • SLEEP: Sleep Cycles The counter increments on each cycle associated with power saving, whether initiated by a WFI or WFE instruction, or by the sleep-on-exit functionality.
  • LSU: Load Store Unit Cycles This counter increments on each additional cycle required to execute a multi-cycle load-store instruction. It does not count the first cycle required to execute any instruction.
  • FOLD: Folded Instructions The counter increments on any instruction that executes in zero cycles (for example, an IT instruction is folded and does not use any cycles).
  • EXCTRC: Exception Tracing The counter increments on exceptions, interrupt entries, and interrupt exits. The window Trace Exceptions shows the statistics.

Note

  • When too many data are generated and the Status Bar shows a data overflow message, reduce the generated events here.


CMSIS-DAP Debugger User's Guide: General Settings

General Settings

General Settings define the device's overall tracing behavior.

Target Driver Setup - Trace

  • Core Clock is the clock frequency the debugger uses to capture trace information from the target device if Use Core Clock is selected. This frequency must correspond to the system clock frequency in your target application, otherwise the captured data might not be valid.
  • Trace Enable defines whether tracing is turned on or off.
  • Specify a separate Trace Clock if it is not equal to the Core Clock. To be able to enter a value here, disable Use Core Clock.
  • Use Core Clock defines whether the core clock is used for tracing.

Note

  • Some applications start from RESET with a lower CPU Core Clock and switch to higher clock rate in the startup code. When debugging such applications, stop the program execution before the clock rate gets configured, and modify Core Clock to match the new clock rate. Use the menu Debug — Debug Settings..., or assign the new value to the VTREG CORE_CLK.
  • Pay attention to the messages displayed in the Status Bar.


CMSIS-DAP Debugger User's Guide: PC Sampling

PC Sampling

The PC Sampling section defines the interval at which instrumentation trace data are generated. Apart from a periodic generation, PC Sampling can be produced for every memory read/write operation.

Target Driver Setup - PC Sampling

  • Prescaler sets the interval for generating PC Sampling.
  • Periodic enables PC Sampling at regular intervals.
  • Period displays the interval at which PC Sampling is generated. The interval is calculated by dividing the Prescaler through the Core Clock .
  • on Data R/W Sample generates PC Sampling for every memory read/write operation.

Note

  • If the Status Bar shows communication errors, disable PC Sampling or define longer intervals.


CMSIS-DAP Debugger User's Guide: Trace Port

Trace Port

Trace Port defines the port type and frequency for tracing. Only the Serial Wire Output - UART/NRZ encoding method is supported.

Serial Wire Output

Serial Wire Trace Port Options

  • Serial Wire Output - UART/NRZ sets the Serial Wire Trace Output pin (SWO) for tracing. When selecting this option, ensure to set the debug Port to SW.
  • SWO Clock Prescaler defines the SWO Clock frequency. Values from 1 to 8192 can be entered. Set this option to a higher value in case trace overflows are encountered.
  • Autodetect configures the SWO Clock Prescaler automatically for the highest possible SWO Clock supported by the debugger adapter. It will be calculated using the given Trace or Core Clock setting.
  • SWO Clock displays the communication frequency, which is calculated by dividing the Trace or Core Clock by the SWO Clock Prescaler. The maximum frequency is implementation dependent.
  • Detected errors are displayed in the area beneath SWO Clock.


CMSIS-DAP Debugger User's Guide: ITM Stimulus Ports

ITM Stimulus Ports

ITM Stimulus Ports control the access to the Instrumentation Trace Macrocell (ITM) Stimulus Ports.

Target Driver Setup - ITM Stimulus Ports

  • Enable individual check-boxes or type the value into the field.
    Enable Port 0 to view data in the serial window Debug (printf) Viewer.
    Enable Port 31 to view RTX events in Kernel Awareness windows.
  • Privilege sets group access rights. Thus, ports that are used by an operating system can be protected from being accessed through the user-code. When unchecked, accessing ports in User Mode is not allowed. Ports are always accessible when the device is in Privileged Mode.


CMSIS-DAP Debugger User's Guide: Timestamps

Timestamps

The Timestamps section controls the creation of timestamp information.

Trace - Timestamps

  • Enable activates the timestamps, which then are appended to trace packets.
  • Prescaler defines the frequency to generate timestamps. The frequency is calculated by dividing the Core Clock through the Prescaler.

Note

  • It is mandatory to enable timestamps in order to use the Logic Analyzer.
  • Set the Prescaler to a higher value in case you encounter trace overflows.


CMSIS-DAP Debugger User's Guide: Trace Data

Trace Data

The Trace Data Window shows the history of the executed instructions.

Instruction Trace button Open the window from the toolbar or with the menu View – Trace - Trace Data. When using the Simulator, enable the flag View – Trace - Enable Trace Recording.

Trace Data Window

Refer to Trace Data documentation for more information.

Note

This feature is not available with the CMSIS-DAP implementation of ULINK2.


CMSIS-DAP Debugger User's Guide: Event Counters

Event Counters

The Event Counters window displays cumulative numbers, which show how often an event triggered. Open this window through View - Trace - Event Counters.

To display data in this window:

  • Enable Tracing.
  • Enable the event counters dynamically in the window. (Is identical to enabling the counters in Trace Events.)

Event Counters Window

For more information, refer to the Event Counters documentation.

Note

This feature is not available with the CMSIS-DAP implementation of ULINK2.


CMSIS-DAP Debugger User's Guide: Trace Exceptions

Trace Exceptions

The Trace Exceptions window displays statistical data about the traced exceptions and interrupts. Open the window through View - Trace - Trace Exceptions.

To display data in this window:

  • Enable Tracing outside this window.
  • Enable EXCTRC: Exception Tracing. (Is identical to setting the option in Trace Events.)
  • Enable Timestamps Enable. (Is identical to setting the option in Timestamps.)

Exception Trace Records Window

Refer to Trace Exceptions documentation for more information.

Note

This feature is not available with the CMSIS-DAP implementation of ULINK2.


CMSIS-DAP Debugger User's Guide: Debug (printf) Viewer

Debug (printf) Viewer

The Debug (printf) Viewer window displays data streams that are transmitted sequentially via ITM Stimulus Port 0.

Debug (printf) Viewer

Note

  • For more information, refer to the Debug (printf) Viewer documentation.
  • Learn how to set up the debug session for SWO trace.
  • More ITM data can be monitored in the Trace Data Window.

Note

This feature is not available with the CMSIS-DAP implementation of ULINK2.


CMSIS-DAP Debugger User's Guide: Trace Navigation

Trace Navigation

The Trace Navigation window allows scrolling through the records of the Trace Data (Cortex-M) window. This feature is available for Cortex-M devices that support capturing trace.

Trace Navigation bar

Where

Current Time Interval | Shows a time interval of 10 ms. The white section indicates that trace data are available for that period. The gray section indicates that no trace data are available, or the time interval is outside of the trace boundaries.
Total Time Interval | Shows the start and end time of available trace data.
Current Time Interval Slider | Move the slider to scroll through trace data records belonging to the current time interval. As an alternative, arrow-keys can be used for scrolling.
Total Time Interval Slider | Move the slider to scroll through the all available trace data records. As an alternative, arrow-keys can be used for scrolling.
Time Field | Shows the mid value of the Current Time Line. Enter a value into the field to jump to a certain time stamp.

Note

This feature is not available with the CMSIS-DAP implementation of ULINK2.


CMSIS-DAP Debugger User's Guide: System Analyzer

System Analyzer

The System Analyzer is a graphical analysis tool that shows:

  • thread, interrupt, and exception execution over time.
  • Event Recorder messages.
  • value changes of variables or VTREGs.

System Analyzer can be used with any Arm Cortex-M based device that provides trace.

System Analyzer Button Open the System Analyzer from the toolbar or via the menu View - Analysis Windows - System Analyzer.

System Analyzer Window

System Analyzer window display

For more information, refer to the System Analyzer documentation.


CMSIS-DAP Debugger User's Guide: Trace Status

Trace Status

The µVision Status Bar displays trace status messages whenever tracing has been enabled. Additional information is available in the general description of the Status Bar for CPUs that have enabled TrustZone for Armv8-M.

Trace Status Bar

The trace status:

  • Displays progress and error messages when the target processor is running.
  • Refreshes the Running... message every 3 seconds during error-free operations.
  • Is blank, when tracing is stopped without an error.
  • Displays the error message in red when the target stopped with an error.
  • Keeps the error message displayed until tracing is restarted.
Trace Status | Description
Communication Error | An invalid communication has been detected. Incorrect clock settings or hardware problems cause this message. Applications that change the Core Clock in the main() program may throw this message when data are captured incorrectly. This error message disappears once the Core Clock has been adjusted to the system settings.
HW Buffer Overrun | The USB port cannot accept data at the speed the adapter is sending them. Turn off trace events you do not need, or skip PC Sampling.
SW Buffer Overrun | Internal SW buffer overrun on the PC. Adjust the SWO Clock Prescaler of the trace port or the Max Clock of the debug port.
No Synchronization | Synchronization packets are not received from the target. The trace hardware is either not connected or configured improperly. Help can be found in Configure Cortex-M Devices for Tracing. Hints might be available in the device data sheet.
Data Stream Error | Errors are detected in the Trace Data Stream.
Data Overflow | The Trace Port was too busy, and not all trace packets could be transmitted. This happens when too many trace data are captured. Decrease the number of trace events.
Running ... | The target system itself and tracing operations are running without errors.
<is blank> | The target stopped without throwing an error.


CMSIS-DAP Debugger User's Guide: Using the Debugger

Using the Debugger

After µVision and the CMSIS-DAP Debugger driver have been configured, download the application to target and start debugging.

  • Downloading to Flash shows how to download the application to the target system.
  • Debugging Applications explains how to start debugging the application on target.
  • Chaining Multiple Targets describes how to chain multiple targets onto a single adapter.


CMSIS-DAP Debugger User's Guide: µVision Windows

µVision Windows

µVision shows trace information in:

  • The Trace Status that continuously displays status and progress messages.
  • The Component Viewer that shows detailed information about software components.
  • The Event Recorder that displays execution status and event information, which help to analyze the operation of software components.
  • The System Analyzer that graphically shows core clock, power consumption, interrupts, thread and exception execution over time.

Detailed trace information for Cortex-M3, Cortex-M4, and Cortex-M7 processor-based devices can be viewed using the following windows:

  • Debug (printf) Viewer for viewing debugging and program-specific information.
  • Trace Data for viewing the instruction history of Cortex-M processor-based devices.
  • Trace Exceptions window that displays statistics about processor exceptions, which are based on trace events.
  • Event Counters window that displays a counter for each user-selected event.

Note

  • Some of these features are not available with all CMSIS-DAP implementations.
  • Trace Settings explains how to configure the trace output and configure individual devices.
  • The Logic Analyzer that displays up to 4 global or static variables on a time-graph is still available but superseded by System Analyzer which offers the same functionality plus more advanced features.
  • Configuring the correct Core Clock is vital for delivering correct and consistent data.