IDE MCUXpresso Instruction Manual
MCUXpresso IDE Instruction
Trace Guide
Rev. 11.3.0 — 2 April, 2021 User guide
NXP Semiconductors MCUXpresso IDE Instruction Trace Guide
MCUXpresso IDE Instruction Trace Guide -
User Guide
2 April, 2021
Copyright © 2021 NXP Semiconductors
All rights reserved.
All information provided in this document is subject to legal disclaimers
Rev. 11.3.0 — 2 April, 2021
© 2021 NXP Semiconductors. All rights reserved.
ii
NXP Semiconductors MCUXpresso IDE Instruction Trace Guide
1. Trace Overview ............................................................................................................ 1
1.1. Instruction Trace Overview ................................................................................. 1
1.1.1. Supported Targets .................................................................................. 1
2. Getting Started ............................................................................................................. 3
2.1. Configuring the Cortex-M0+ for Instruction Trace ................................................. 3
2.2. Trace the Most Recently Executed Instructions ................................................... 3
2.3. Stop Trace When a Variable is Set (Cortex M3 or M4 using ETB) ......................... 5
3. Concepts ...................................................................................................................... 7
3.1. Micro Trace Buffer (MTB) .................................................................................. 7
3.1.1. Enabling the MTB ................................................................................... 7
3.1.2. MTB Memory Configuration ..................................................................... 7
3.1.3. MTB Watermarking ................................................................................. 8
3.1.4. MTB Auto-Resume ................................................................................. 8
3.1.5. MTB Downloading Trace ......................................................................... 8
3.2. Embedded Trace Macrocell (ETM) ..................................................................... 8
3.2.1. Stalling ................................................................................................... 9
3.2.2. ETM Events ............................................................................................ 9
3.2.3. Event Resources .................................................................................... 9
3.2.4. Watchpoint Comparator Event Resource .................................................. 9
3.2.5. Counter Event Resource ......................................................................... 9
3.2.6. Trace Start/Stop Unit Event Resource .................................................... 10
3.2.7. External Event Resource ....................................................................... 10
3.2.8. Hard Wired Event Resource .................................................................. 10
3.3. Embedded Trace Buffer (ETB) ......................................................................... 10
3.3.1. Triggers ................................................................................................ 11
3.3.2. Timestamps .......................................................................................... 12
3.3.3. Debug Request ..................................................................................... 12
3.3.4. Output All Branches .............................................................................. 12
3.4. Data Watchpoint and Trace .............................................................................. 12
3.4.1. Instruction Address Comparator ............................................................. 12
3.4.2. Data Value Comparator ......................................................................... 13
3.4.3. Cycle Count .......................................................................................... 14
4. Reference .................................................................................................................. 15
4.1. Instruction Trace View ..................................................................................... 15
4.1.1. Instruction Trace View Toolbar Buttons .................................................. 15
4.1.2. Record Trace Continuously .............................................................. 16
4.1.3. Show Instruction Trace Config View .................................................. 16
4.1.4. Download Trace Buffer .................................................................... 16
4.1.5. Link to Source ................................................................................. 16
4.1.6. Link to Disassembly ......................................................................... 17
4.1.7. Show Profile Information .................................................................. 17
4.1.8. Save Trace ...................................................................................... 17
4.1.9. Jump to Trigger ............................................................................... 17
4.1.10. Stop Auto-Resume ......................................................................... 17
4.1.11. Select Columns .............................................................................. 18
4.2. Instruction Trace Config View for the MTB ........................................................ 18
4.2.1. Configuring the Buffer ........................................................................... 19
4.2.2. Enabling ............................................................................................... 19
4.2.3. Buffer ................................................................................................... 19
4.2.4. Watermark ............................................................................................ 19
4.2.5. Viewing the State of the MTB ................................................................ 20
4.2.6. Instruction Trace Config View for the ETB .............................................. 20
4.2.7. ETM Event Configuration ....................................................................... 21
5. Troubleshooting .......................................................................................................... 23
MCUXpresso IDE Instruction Trace Guide -
User Guide
All information provided in this document is subject to legal disclaimers
Rev. 11.3.0 — 2 April, 2021
© 2021 NXP Semiconductors. All rights reserved.
iii
NXP Semiconductors MCUXpresso IDE Instruction Trace Guide
5.1. General ........................................................................................................... 23
5.1.1. Instruction Trace Claims Target Not Supported When it Should Be ........... 23
5.2. MTB ................................................................................................................ 23
5.2.1. Target Crashes When MTB is Enabled .................................................. 23
5.3. Target Keeps Resuming Itself and I Cannot Stop It ........................................... 23
5.4. ETB ................................................................................................................ 23
5.4.1. Trigger Packet Missing from Trace Even Though Trigger Occurred .......... 23
5.5. Comparator Sharing ......................................................................................... 23
5.5.1. Watchpoints – Requesting and Releasing Comparators ........................... 24
5.5.2. SWO Data Watch Comparators ............................................................. 24
5.5.3. Instruction Trace ................................................................................... 25
MCUXpresso IDE Instruction Trace Guide -
User Guide
All information provided in this document is subject to legal disclaimers
Rev. 11.3.0 — 2 April, 2021
© 2021 NXP Semiconductors. All rights reserved.
iv
NXP Semiconductors MCUXpresso IDE Instruction Trace Guide
1. Trace Overview
There are two different kinds of tracing technologies available directly within MCUXpresso IDE.
• Instruction Trace - capturing an instruction stream within onboard RAM of the MCU. This
data can then be retrieved, decoded, and displayed within the IDE.
• Available with any supported debug probe.
• SWO Trace - capturing events occurring on a running MCU in real time
• Available with any supported debug probe.
The Trace functionality available depends on the features supported by your target MCU and
the features supported by your debug probe.
The rest of this guide looks at Instruction Trace. For information regarding SWO Trace, see the
SWO Trace guide.
Compatibility
Introduced in MCUXpresso IDE version 10.2.0 : Instruction Trace functionality can
now be used with all supported debug solutions. Previous versions of MCUXpresso
IDE only supported instruction trace for LinkServer (including CMSIS-DAP) debug
connections.
1.1 Instruction Trace Overview
Instruction Trace provides the ability to record and review the sequence of instructions executed
on a target. The MCUXpresso IDE provides support for Instruction Trace via on-chip RAM trace
buffers. Instruction Trace makes use of the Embedded Trace Buffer (ETB) on Cortex M3 and M4
parts and the Micro Trace Buffer (MTB) on the Cortex-M0+. The instruction trace information,
which is generated at high speed within the CPU, can be captured in real time and stored in
these on-chip buffers, so that they can be downloaded at lower speeds without the need for an
expensive external trace capture box.
The MCUXpresso IDE exposes the powerful Embedded Trace Macrocell (ETM) on Cortex M3
and M4 to focus the generated trace stored in the ETB. Trace can be focused on specific areas
of code, or triggered by complex events, for example. On the Cortex M0+, the MTB provides
simple Instruction Trace using shared SRAM.
This documentation is divided into four parts.
• Getting Started [3] - Tutorials to help you learn how to use Instruction Trace
• Concepts [7] - The technical background of instruction tracing
• Reference [15] - Details of the interface and operation of Instruction Trace
• Troubleshooting [23] - solutions to common challenges you may face
1.1.1 Supported Targets
Instruction Trace is not supported on all targets. It only works on targets that have the necessary
hardware. Instruction Trace is currently supported on the following targets from NXP.
• MTB is supported on a range of Cortex-M0+ MCU parts from NXP including:
• LPC8xx
• LPC11U6x / LPC11UEx
• Many Kinetis KL series parts, including MKL43Z
• ETB is supported on a range of Cortex-M3, M4 and M7 MCU parts from NXP including:
• LPC18xx / LPC43xx
• Many Kinetis K series parts, including MK64F
MCUXpresso IDE Instruction Trace Guide -
User Guide
All information provided in this document is subject to legal disclaimers
Rev. 11.3.0 — 2 April, 2021
© 2021 NXP Semiconductors. All rights reserved.
1
NXP Semiconductors MCUXpresso IDE Instruction Trace Guide
Note that Instruction Trace is not supported with LPC17xx MCUs (which do not implement an
ETB) or LPC13xx/LPC15xx MCUs (which do not implement ETM or ETB).
MCUXpresso IDE Instruction Trace Guide -
User Guide
All information provided in this document is subject to legal disclaimers
Rev. 11.3.0 — 2 April, 2021
© 2021 NXP Semiconductors. All rights reserved.
2
NXP Semiconductors MCUXpresso IDE Instruction Trace Guide
2. Getting Started
The following tutorials guide you through the process of using Instruction Trace.
2.1 Configuring the Cortex-M0+ for Instruction Trace
Instruction Trace on Cortex-M0+ targets requires some SRAM to be reserved. The Micro Trace
Buffer (MTB) that provides the Instruction Trace capabilities stores the execution trace to SRAM.
It is therefore necessary to reserve some SRAM to ensure that user data is not overwritten by
trace data.
Note:
This configuration is not required for Instruction Trace on Cortex-M3 and CortexM4 MCU parts.
MCUXpresso IDE’s new project wizard will automatically include a file called mtb.c for parts that
support MTB trace. This file places an array called __mtb_buffer__ into memory at the required
alignment. The MTB will then be configured to use this space as its buffer, allowing it to record
execution trace without overwriting user code or data. The array __mtb_buffer__ should not be
used within your code, since the MTB will overwrite any data entered into it.
The enablement and size of the __mtb_buffer__ is controlled by three symbols:
• __MTB_DISABLE - If this symbol is defined, then the buffer array for the MTB will not be created.
• __MTB_BUFFER_SIZE - a symbol specifying the size of the buffer array for the MTB. This must be
a power of 2 in size, and fit into the available RAM. The MTB buffer will also be aligned to its
‘size’ boundary and be placed at the start of a RAM bank (which should ensure minimal or
zero padding due to alignment).
• __MTB_RAM_BANK - allows MTB Buffer to be placed into a specific RAM bank. When this is not
defined, the “default” (first if there are several) RAM bank is used.
To change or add these symbols, click on Quickstart Panel->Quick Settings->Defined Symbols.
If you have a project for an MTB supported part that does not already contain the mtb.c file, you
simply need to copy the mtb.c file from an existing project, or create a new project and copy the
file from there.
Warning
Enabling the MTB manually without properly configuring the target’s memory usage
will result in unpredictable behavior. The MTB can overwrite user code or data, which
is likely to result in a hard fault.
2.2 Trace the Most Recently Executed Instructions
This tutorial will get you started using the Instruction Trace capabilities of MCUXpresso IDE. You
will configure the target’s trace buffer as a circular buffer, let your program run on your target,
suspend it, and download the list of executed instructions.
First, you will debug code on your target. You can import an example project or use one of your
own.
MCUXpresso IDE Instruction Trace Guide -
User Guide
Note:
Instruction Trace depends on optional components in the target. These components
may or may not be available on the LPC device you are working with. See the
Instruction Trace Overview [1] for more information.
All information provided in this document is subject to legal disclaimers
Rev. 11.3.0 — 2 April, 2021
© 2021 NXP Semiconductors. All rights reserved.
3
NXP Semiconductors MCUXpresso IDE Instruction Trace Guide
Step 0: Configure memory, if using a Cortex-M0+ part
If you are using a Cortex-M0+ part with an MTB you must first configure the memory usage of
your code to avoid conflicts. See Configuring the Cortex-M0+ for Instruction Trace [3] to
learn how to do this.
Step 1: Start the target and show the Instruction Trace View
1. Build and execute your code on the target.
2. Suspend the execution of your target by selecting Run -> Suspend.
3.
Display the Instruction Trace View by clicking Window -> Show View -> Instruction Trace.
Step 2: Configure the trace buffer
1.
Press the Record Trace Continuously button in Instruction Trace.
2. Resume execution of your target by selecting Run -> Resume.
The trace buffer should now be configured as a circular buffer, and your target should be running
your code. Once the trace buffer is filled up, older trace data is overwritten by the newer trace
data. Configuring the trace buffer as a circular buffer ensures that the most recently executed
code is always stored in the buffer.
If the Record Trace Continuously button was grayed out, or you encountered an error,
check out the troubleshooting guide [23].
Step 3: Download the content of the buffer
1. Suspend the execution of your target by selecting Run -> Suspend.
2.
Press Download trace in the Instruction Trace View.
There may be a short delay as the trace is downloaded from the target and decompressed.
Once the trace has been decompressed, it is displayed as a list of executed instructions in the
Instruction Trace View.
Step 4: Review the captured trace
In this step we explore the captured trace by stepping through it in the instruction View and linking
the currently selected instruction to the source code that generated it, as well as seeing it in
context in the disassembly View.
1.
Toggle the Link to source button so that it is selected.
2.
Toggle the Link to disassembly so that it is also selected.
3. Select a row in the Instruction Trace View.
4. Use the up and down cursor keys to scroll through the rows in the Instruction Trace View.
As a row becomes selected, the source code corresponding to the instruction in that row should
be highlighted in the source code editor. The disassembly View should also update with the
current instruction selected. There can be a slight lag in the disassembly View as the instructions
are downloaded from the target and disassembled.
Step 5: Highlight the captured instructions
In this step we turn on the profile View. In the source code editor the instructions that were traced
will be highlighted. This highlighting can be useful for seeing code coverage. In the disassembly
View each instruction is labeled with the number of times each it was executed.
•
Toggle the Profile information button
MCUXpresso IDE Instruction Trace Guide -
User Guide
All information provided in this document is subject to legal disclaimers
Rev. 11.3.0 — 2 April, 2021
© 2021 NXP Semiconductors. All rights reserved.
4
NXP Semiconductors MCUXpresso IDE Instruction Trace Guide
2.3 Stop Trace When a Variable is Set (Cortex M3 or M4 using ETB)
In this next tutorial you will configure Instruction Trace to stop when the value of a variable is
set to a specific value.
This tracing could be useful for figuring out why a variable is being set to a garbage value.
Suppose we have a variable that is mysteriously being set to 0xff when we expect it to always
be between 0x0 and 0xA for example.
Note – For Cortex-M0+ based systems, this functionality requires additional hardware to be
implemented alongside the MTB. Some parts such as the LPC8xx and LPC11U6x families do
not provide this.
To trace the instructions that resulted in the write of the unexpected value we are going to
have trace continuously enabled with the ETB acting as a circular buffer. Next we will set up a
trigger [11] to stop trace being written to the ETB after the value 0xff gets written to the variable
we are interested in. The trigger event requires two DWT comparators. One of the comparators
watches for any write to the address of the variable and the other watches for the value 0xff being
written to any address. The position of the trigger in the trace is set to capture a small amount of
data after the trigger and then to stop putting data into the ETB.
Step 1: Start the target and show the Instruction Trace Config View
1. Build and execute your code on the target.
2. Suspend the execution of your target by selecting Run -> Suspend
3.
Display the Instruction Trace Config View by clicking Window -> Show View -> Instruction
Trace Config
4.
Press the refresh button in the Instruction Trace Config View
Step 2: Find the address of the variable
1.
Display the Disassembly View by clicking Window -> Show View -> Disassembly
2. Enter the variable name into the location search box and hit enter.
3. Copy the address of the variable to clipboard.
Note:
We are assuming that the variable is a global variable.
Step 3: Enable trace
In this step we configure trace to be generated unconditionally in the Instruction Trace Config
View.
1. In the Enable trace section:
a. Select the Simple tab
b. Select enable
Step 4: Enable stalling
To make sure that no packets get lost if the ETM becomes overwhelmed we enable stalling.
Setting the stall level to 14 bytes mean that the processor will stall when there are only 14 bytes
left in the formatting buffer. This setting ensures that we do not miss any data, however, it comes
at the cost of pausing the CPU when the ETM cannot keep up with it. See stalling [9] in the
Concepts section for more information.
1. Check the Stall processor check box
2. Drag the slider to set the Stall level to 14 bytes
MCUXpresso IDE Instruction Trace Guide -
User Guide
All information provided in this document is subject to legal disclaimers
Rev. 11.3.0 — 2 April, 2021
© 2021 NXP Semiconductors. All rights reserved.
5
Loading...