PDQLogic QTrace User Manual

INTRODUCTION QTRACE - USER MANUAL

Revision 1.01

August 2018

QTRACE - USER MANUAL

Contents

1. INTRODUCTION ............................................................................................................................................ 5

1.1 TRACE OVERVIEW ............................................................................................................................................. 5

1.2 QTRACE SYSTEM CONNECTIONS .......................................................................................................................... 5

1.3 SUPPORTED IDES ............................................................................................................................................. 6

1.4 SUPPORTED TARGET DEVICES .............................................................................................................................. 6

1.5 SYSTEM REQUIREMENTS .................................................................................................................................... 7

1.6 QTRACE HARDWARE SPECIFICATION ..................................................................................................................... 7

1.7 TARGET CONNECTION........................................................................................................................................ 8

1.8 RECOMMENDATIONS FOR PCB LAYOUT OF TRACE SIGNALS ...................................................................................... 8

1.9 FRONT PANEL STATUS LED ................................................................................................................................. 9

1.10 PRECAUTIONS .................................................................................................................................................. 9

2. QTRACE ANALYSER OVERVIEW .................................................................................................................... 10

2.1 INSTALLATION ................................................................................................................................................ 10

2.2 QTRACE ANALYSER LAYOUT ............................................................................................................................. 10

2.2.1 Drop-down menu and toolbar .............................................................................................................. 11

2.2.2 Status bar .............................................................................................................................................. 12

2.2.2.1 Taskbar icon .................................................................................................................................................. 12

2.2.3 Trace views ........................................................................................................................................... 12

3. SOURCE VIEWER .......................................................................................................................................... 13

3.1 FUNCTION TREE-VIEW ..................................................................................................................................... 13

3.2 SOURCE FILE VIEW .......................................................................................................................................... 13

3.2.1 Code coverage....................................................................................................................................... 14

3.2.2 Code coverage pause and clear ............................................................................................................ 16

3.2.3 Single stepping and execution count latency ........................................................................................ 16

3.2.4 Loop timing ........................................................................................................................................... 16

3.2.5 Execution heat map .............................................................................................................................. 16

3.2.6 Navigating to function implementations .............................................................................................. 17

3.2.7 Find text ................................................................................................................................................ 17

3.2.8 Find function from clipboard ................................................................................................................. 18

3.2.9 Source view bookmarks ........................................................................................................................ 18

3.3 ITM DEBUGGING ........................................................................................................................................... 19

3.4 GENERAL SETTINGS ........................................................................................................................................ 21

4. TRACE CAPTURE .......................................................................................................................................... 22

4.1 TRACE CAPTURE TRIGGER ................................................................................................................................ 22

4.1.1 Trace Point ............................................................................................................................................ 23

4.2 TRACE CAPTURE VIEW ..................................................................................................................................... 23

4.2.1 CPU instruction list view ....................................................................................................................... 24

4.2.2 Simple source view ................................................................................................................................ 24

4.2.3 Function timeline .................................................................................................................................. 25

4.2.3.1 Timeline controls .......................................................................................................................................... 25

4.2.3.2 Function pinning ........................................................................................................................................... 26

4.2.3.3 Timeline function search ............................................................................................................................... 26

4.2.3.4 Measuring timeline intervals ........................................................................................................................ 26

4.2.4 Find trace record ................................................................................................................................... 27

4.2.5 Go to source .......................................................................................................................................... 28

4.2.6 Trace record bookmarks ....................................................................................................................... 28

4.2.7 Instruction list-view context menu ........................................................................................................ 28

4.3 EXCEPTION TRACE CAPTURE .............................................................................................................................. 29

4.3.1 Problems setting exception handler trigger .......................................................................................... 30

5. PROFILING ................................................................................................................................................... 31

5.1 CPU TIMING ................................................................................................................................................. 33

6. TRACE CONFIGURATION .............................................................................................................................. 34

6.1 TRACE CONFIGURATION DIALOG ........................................................................................................................ 34

6.1.1 Manufacturer ........................................................................................................................................ 35

6.1.2 Part/Family ........................................................................................................................................... 35

6.1.3 ROM start address ................................................................................................................................ 35

6.1.4 ROM size ............................................................................................................................................... 36

6.1.5 Trace clock divider ................................................................................................................................ 36

6.1.6 C++ project ............................................................................................................................................ 36

6.1.7 Save paths relative to configuration file ............................................................................................... 36

6.1.8 Vector table address ............................................................................................................................. 36

6.1.9 ELF file ................................................................................................................................................... 36

6.1.10 Source paths ..................................................................................................................................... 37

6.1.11 Missing source files ........................................................................................................................... 37

6.1.12 Additional code ranges ..................................................................................................................... 39

6.1.13 Trace configuration source ............................................................................................................... 40

6.1.14 Initialisation RAM area ..................................................................................................................... 40

6.1.15 Debugger script ................................................................................................................................ 40

6.1.16 Trace port voltage ............................................................................................................................ 40

6.2 FINALISING TRACE CONFIGURATION.................................................................................................................... 40

7. TRACE START SEQUENCE ............................................................................................................................. 42

8. SELF TEST MODE .......................................................................................................................................... 44

9. RECOMMENDATIONS .................................................................................................................................. 45

9.1 GENERAL ...................................................................................................................................................... 45

9.2 PROGRAMMING TIPS ...................................................................................................................................... 45

10. PC SPECIFICATION ................................................................................................................................... 46

11. TROUBLESHOOTING ................................................................................................................................ 47

12. TRACING WITH COMMON IDES ............................................................................................................... 49

12.1 LOCATION OF DEBUGGER SCRIPTS ...................................................................................................................... 49

12.2 EXAMPLE PROJECTS ........................................................................................................................................ 49

12.3 SEGGER J-LINK INSTRUCTION SIMULATION........................................................................................................... 50

12.4 ATOLLIC TRUESTUDIO ................................................................................................................................... 51

12.5 IAR EMBEDDED WORKBENCH .......................................................................................................................... 56

12.6 KEIL MDK .................................................................................................................................................... 57

12.7 SEGGER EMBEDDED STUDIO / ROWLEY CROSSWORKS FOR ARM ............................................................................ 58

12.8 ST SYSTEM WORKBENCH ................................................................................................................................. 59

12.9 VISUALGDB .................................................................................................................................................. 61

APPENDIX A MANUAL DRIVER INSTALLATION .................................................................................................... 63

APPENDIX B STM32-EVAL DEMONSTRATOR ...................................................................................................... 65

APPENDIX C NOSLEEP UTILITY ............................................................................................................................ 66

Document History

Revision

Date

Changes

1.00

12/07/18

First release

1.01

06/08/18

Finalising trace configuration section added

Introduction QTRACE - USER MANUAL

1. Introduction

QTrace is a low cost real-time instruction trace system for ARM Cortex M3/M4 processors. It gives exceptional insight and detailed views of how a target application is running and aids locating hard-tofind bugs. The system consists of a hardware trace probe and a Windows based trace analyser. It allows completely unobtrusive full speed tracing and does not require any instrumentation code to be added to the target application.

With QTrace you don’t need to be a high‐end user with a big budget or wait until you encounter a really nasty bug before deciding to purchase a trace system.

1.1 Trace overview

Historically, trace systems have been very expensive and have required large connectors to interface to the users' target board. Trace hardware probes typically contained large amounts of RAM to capture trace data when a user defined event was triggered. The resulting data was then uploaded to the host PC for laborious offline analysis.

With the introduction of the ARM Cortex M3/M4 processor cores comes a small footprint trace interface. Many microcontroller devices based on this core contain a hardware block called an Embedded Trace Macrocell (ETM) which enables instruction tracing of an application in real-time. The interface to the ETM block is typically a clock and 4 data lines which are usually presented as multipurpose microcontroller GPIO lines that can be programmed to operate as a trace port. These high speed trace signals are combined with the standard JTAG or SWD debug signals and connect to a 20 way

0.05" pitch header, see Figure 3. An external trace probe is required to decode the trace data frames streamed by the trace port and transmit their payload data to a host PC.

By implementing a high speed communication link between the trace hardware probe and PC, it is possible to stream the trace data directly to the PC without the need to capture and then review offline. This allows a continuous view of what the target application is doing and makes trace far more useful and easier to visualise than a large collection of static trace records.

To handle high trace data rates resulting from this configuration, the specification of the host PC is important. It needs to decode the trace data and present a summary of the target processor execution in real-time with minimal latency and without losing data. PC specification is outlined in section 10 on page 46.

1.2 QTrace system connections

The block diagram in Figure 1 shows how QTrace connects to a development system and Figure 2 shows a picture of an example hardware set-up. The QTrace probe is a little different to conventional trace units in that it doesn't integrate a JTAG1 interface. Instead it uses a splitter cable to tap-off the trace signals from the 20 way target trace connector. The target JTAG signals connect separately to the users' JTAG adapter.

A USB 3.0 connection from on the development PC is used to power the QTrace probe and to stream trace data from it. A standalone Windows application, the QTrace Analyser, configures the probe then decodes and displays its streamed trace data.

Having a separate analyser application operating independently of the user supplied IDE2 means that investment in existing development tools is not lost. Refer to section 2 for further details of the QTrace Analyser.

References to JTAG also include SWD

IDE refers to an integrated development environment and its debugger

Introduction QTRACE - USER MANUAL

Figure 1 QTrace block diagram

The QTrace system does not control the target JTAG interface and so does not configure target trace hardware directly. Instead, a debug script is run from the IDE to configure the target trace pins and registers. This is done after the target FLASH has been programmed but before the application is run.

1.3 Supported IDEs

A number of debugger scripts are supplied with the QTrace Analyser to support most common IDEs, as shown in Table 1 below.

IDE

Version Tested

See Section

Atollic TrueSTUDIO

V9.0.0

12.4

IAR Embedded Workbench

V8.20

12.5

Keil MDK

V5.20

12.6

Segger Embedded Studio

V3.34

12.7

ST System Workbench

V2.4

12.8

VisualGDB

V5.3r5

12.9

Table 1 Supported IDEs

1.4 Supported target devices

The QTrace probe will interface to any ARM Cortex-M3/M4 based processor with an ETM trace port. Currently the QTrace Analyser supports STM32 F1/F2/F3/F4/L4 devices from ST Microelectronics that have the ETM trace option. More manufacturers and devices will be added, see www.pdqlogic.com for further details.

Introduction QTRACE - USER MANUAL

Figure 2 Example QTrace hardware connection

1.5 System requirements

 A PC running 64-bit Windows 7, 8.1 or 10 with the preferred hardware specification:

 Intel i5/i7 dual or quad core CPU running at 2GHz min.  8GB+ RAM  A spare USB 3.0 port  Screen resolution of 1366 x 768 or better (ideally a 2nd screen)

 A user supplied IDE and JTAG adapter  Target hardware containing an ARM Cortex M3/M4 based processor and a 20 way ETM trace

connector with 4-bit data and clock (1.8V - 3.3V levels), see Figure 3.

1.6 QTrace hardware specification

The following gives an overview of the QTrace hardware specifications

Parameter

Min

Max

Units

Power supply (USB 3.0 powered)

Voltage

4.0

6.0

Volts

Current

300

Input voltage3 range 1 (1.8V nom)

Vin Low

-0.2

0.38

Volts

Vin High

0.8

3.6

Volts

Input voltage3 range 2 (3.3V nom)

Vin Low

-0.2

0.8

Volts

Vin High

2.0

3.6

Volts

Target clock frequency (F

Target

)

(Trace clock = F

Target

/2)

180

MHz

Trace data to clock set-up time

0.0 - ns

Trace data to clock hold-up time

0.2 - ns

EMC compliance

EN55024, EN55032

Table 2 QTrace hardware specification

Input voltage range is specified in the QTrace Analyser configuration dialog

10 to 20 way converter PCB

Splitter Ribbon Cable

QTrace Probe

JTAG Unit (not supplied)

Development Board (not supplied)

Introduction QTRACE - USER MANUAL

1.7 Target connection

Below are the pin assignments for the ARM Cortex-M 20 pin trace connector. It has a 0.05" pitch and provides access to the 4-bit ETM interface and JTAG / SWD signals.

Figure 3 Pin assignments of the ARM Cortex-M 20 pin trace connector

1.8 Recommendations for PCB layout of Trace Signals

A good PCB layout for the trace signals is crucial for reliable operation. Below are some recommendations for PCB layout of the trace signals:

 Place the trace connector close to the processor pins  Add 0402 series termination resistors e.g. 22R next to the processor trace pins  Use low capacitance ESD diodes on the trace signals and place them close to the trace

connector

 Keep tracks the same length  Do not insert vias  Route all tracks over an unbroken ground plane which is on the first inner layer (the FR4

laminate thickness between the top and ground plane layers should typically be 5 mil)

Figure 4 shows an example of trace signal routing on the STM32-EVAL demonstrator PCB (see Appendix B STM32-Eval Demonstrator. The trace signals are highlighted in red and the component outlines of the 0402 series resistors and ESD diodes are highlighted in yellow.

Figure 4 Example trace schematic and PCB signal routing

Introduction QTRACE - USER MANUAL

1.9 Front panel status LED

The bi-colour front panel LED conveys the current status of the QTrace probe. Below is a summary of the possible states:

Colour

QTrace State

Red

Trace decoder hardware is unconfigured

Red flashing

No trace clock detected or unable to synchronise with trace data

Green

Streaming trace data

Green flashing

Trace data has stalled e.g. break point hit

Table 3 Front panel LED states

1.10 Precautions

There are several issues to be aware of when using the QTrace probe:

1) Do not connect a powered target processor to an unpowered QTrace probe i.e. when it isn’t

connected to a PC via a USB 3.0 lead. Doing so will cause internal ESD diodes to continuously conduct which may damage them. It may also damage the trace pins on the target processor.

2) The QTrace probe should not be connected to a USB 3.0 lead greater than 2 metres long. The

lead should have high frequency ferrites at both ends as per the supplied lead.

3) Do not force the USB lead connector into the QTrace probe. If it does not mate easily then the

USB lead connector may be damaged and the lead should be replaced.

QTrace Analyser Overview QTRACE - USER MANUAL

2. QTrace Analyser Overview

The QTrace Analyser is a standalone application that runs on 64-bit Microsoft Windows 7, 8.1 and 10. It interfaces to the QTrace probe via a USB3 connection and configures it for the chosen target device. The analyser then decodes and displays streamed trace data, independently of the IDE.

2.1 Installation

The QTrace Analyser application requires the Microsoft .NET framework v4.0 which should be installed before running the installer (Windows Update routinely installs the latest .NET framework).

The QTrace Analyser should be installed before connecting the QTrace probe to the PC. To launch the installer, run TraceAnalyserSetup_vx.x.x.x.exe. This will install the QTrace Analyser application, scripts, documentation and a USB3 driver. Note that the installer will silently request Administrator privileges to install the driver and the request may fail. If it does, the driver will not be installed and this will have to be done manually, see Appendix A Manual Driver Installation.

The QTrace probe actually requires two drivers and Windows may try to find an updated driver for one or both. If it does, click ‘Skip’:

When installation has successfully completed, the QTrace Analyser will run automatically by default. It can also be run from the Windows Start menu (StartProgramsPDQLogicQTrace Analyser).

2.2 QTrace Analyser layout

The application consists of three main areas, a collection of drop-down menus with toolbar shortcuts, a trace view area with selector tabs and a status bar.

Figure 5 QTrace Analyser layout

Drop-down menus & toolbar

Trace view select

Selected trace view

Status bar

QTrace Analyser Overview QTRACE - USER MANUAL

2.2.1 Drop-down menu and toolbar

The drop-down menu and toolbar are always visible except when in full screen mode. Below is a summary of the menu options and their corresponding toolbar / key press shortcuts:

Option

Toolbar

Button

Key press Shortcut

Description

File

New Configuration…

Ctrl+N

Create a new trace configuration

Open Configuration…

Ctrl+O

Browse for a trace configuration to open

Save Configuration

Ctrl+S

Save current trace configuration

Save Configuration As…

Save current trace configuration as a different name

Recent Configurations

Pick a recent trace configuration

Exit Alt+F4

Exit the QTrace Analyser

Setup

Edit Configuration…

Edit the current trace configuration

Reset Trace Probe

Reset the QTrace probe

Reload ELF File

Reload the ELF specified in the trace configuration

ITM Debug Settings

Show the ITM debug settings

General Settings

Show the general trace system settings

Capture

Enable

Globally enable trace capture

Take Snapshot

Take a snapshot of the last 8M trace records

Insert Trace Point

Insert a trace point at the current source line

View

Clear Code Coverage

Globally clear all code coverage

Pause Code Coverage

Pause code coverage display update

Find in Current File…

Ctrl+F, F3

Find text in current file

Find in Files…

Ctrl+Shift+F

Find text in all source files specified by ELF file

Find Function From Clipboard

Ctrl+V

Match the function name on the Clipboard and display the source implementation if found

Show Indentation Guides

Show/hide indentation guide lines in the main source view

Show Function List

Show/hide the file / function tree view

Navigate Backward

Alt+Left

Go to the previously displayed line in the source view

Navigate Forward

Alt+Right

Go to the next displayed line in the source view

Toggle Bookmark

Ctrl+F2

Insert/delete a bookmark at the current source line

Next Bookmark

Go to the next bookmarked source line

Display Bookmarks…

Show the bookmark dialog

Target Exception Handlers

Show the target exception handler dialog

ITM Viewer…

Show/hide the ITM terminal viewer

Toggle Full Screen

Toggle between full screen and normal view

Help

User Manual

Open the user manual in the system PDF viewer

ITM Code Example

Show example C source for ITM printf-style output

Trace Diagnostics…

Show the trace trouble shooter dialog

Self Test

Enter self-test mode

Report a Problem

Send bug report to PDQLogic

About…

Display software versions and legal notices

Table 4 Menu options summary

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26

QTrace Analyser Overview QTRACE - USER MANUAL

2.2.2 Status bar

The status bar gives a quick at-at-glance overview of system operation.

Table 5 Status bar feature summary

2.2.2.1 Taskbar icon

As well as the main status bar, the application icon in the Windows Taskbar is also used to convey system status. This is useful when the QTrace Analyser is hidden by another application. The following colours indicate key events:

Yellow Target reset detected

Green Tracing is in progress

Green / Red flashing A trace capture event

occurred

Red A target exception or a

trace error occurred

Table 6 Taskbar icon states

2.2.3 Trace views

There are three primary trace views which can be selected using the coloured tabs labelled Trace view select in Figure 5 above. Each gives a different visualisation of target program execution:

1. Source Viewer

2. Trace Capture

3. Profiling

The operation of each trace view is detailed in the following sections.

Trace hardware interface status

Trace capture

status e.g. disabled,

armed, triggered

Selected target

trace interface

voltage level

Detected CPU clock

speed (useful for PLL

verification)

Average

instruction

rate

Code coverage

overall value

Source Viewer QTRACE - USER MANUAL

3. Source Viewer

The source viewer is the default view and is shown in Figure 6. It is split into 3 resizable areas:

1. Function tree-view

2. Source file view

3. A setup/status view with multiple pages selected with tabs at the bottom of the view

Figure 6 Source viewer

3.1 Function tree-view

The function tree-view is populated with source filenames and functions decoded from the ELF file. Each file node can be expanded to show the functions it contains. The size of the code generated from each source file can optionally be appended to the filename by ticking the ‘ROM’ check box at the top of the view. The full path can also be displayed by ticking the ‘Path’ check box.

If any source files are missing, and there is debug information in the ELF file which specifies their original source file names, then ticking the ‘Missing Files’ check box will show the files and their functions in

light grey. If the ‘Missing Files’ check box is disabled then all source files and functions specified in the

ELF file have been found and are displayed. Functions that cannot be associated with a source file are grouped together in a pseudo file entry in the

tree-view called {library functions}. Clicking on any function in the tree-view will display its implementation in the corresponding source file

in the source file view. If no source file can be found then the source view will be cleared and “<Source not available>” displayed.

3.2 Source file view

The currently selected function in the tree-view is displayed in the source file view. Clicking on a line in the source file view that contains code will show the underlying disassembly in the setup/status view when the ‘Disassembly’ tab is active.

2 1 3

Source Viewer QTRACE - USER MANUAL

One of the most useful features in the source file view is the yellow vertical margin in the left hand side of the view which displays execution counts for each source line. This is referred to as code coverage.

3.2.1 Code coverage

A purple block to the right of the source file line number indicates that there are underlying processor instructions i.e. it is not just a comment or white space. To the right of each purple ‘code block’ is a count of how many times the source line has been executed. If there is no count displayed i.e. it is blank, then the line has not yet been executed. A similar view is shown in the disassembly window in its pink coloured margin.

Figure 7 Code coverage in source and disassembly views

Trace data is constantly being decoded as the target program is running and as long as there is no trace buffer overflow4 then the number of times that each CPU instruction has been executed will be recorded. These instructions are cross referenced to C/C++ source lines and are displayed as execution counts in the in the yellow source view margin next to the source line. The CPU instruction execution counts are displayed in the pink margin of the disassembly window.

Note that recording execution counts for each instruction is not the same as recording every single instruction that has been executed since reset to allow an entire execution timeline to be reconstructed. There is, however, a similar feature in the QTrace Analyser which is limited to 8 million consecutive instructions, see Trace Capture in section 4.

Having an indication of whether a source line has been executed, and how many times, is very powerful. This feature is similar to having a breakpoint on every source code line but without actually affecting processor execution. Although variables and register values can’t be inspected, knowing where the processor has been and how many times is a ‘smoking gun’ for debugging tricky problems. This is something that break-and-step debugging only gives when a breakpoint is hit and will be missed if a break point was not in place when code of interest was executed.

This feature is much more effective and timesaving than sprinkling code with printf debug statements to know if a particular line was executed. Adding debug code will alter execution timing and may compound an issue being investigated.

Overflow shouldn’t happen with a suitable PC specification (see Section 10)

Source Viewer QTRACE - USER MANUAL

The following are examples of what debug information can be inferred from code coverage without having to stop the CPU, or insert break-points and re-run the application or insert printf statements:

Figure 8 Code coverage #1 – Inferred time duration

Figure 9 Code coverage #2 – Multiple conditionals on separate lines

Figure 10 Code coverage #3 - Only 1 mutex created

Figure 11 Code coverage #4 – Blocked thread

Conditional statements on separate lines quickly show which tests passed & failed (line 891 didn’t execute therefore Device_SaveSettings() on line 888 failed)

17 x 100ms delays (button held between 1.7s & 1.8s)

Line not yet executed (blocked on line 134 above)

xQueueCreateMutex() called only once (unusual for a typical multi-threaded application)

Source Viewer QTRACE - USER MANUAL

3.2.2 Code coverage pause and clear

The dynamic code coverage updating can be paused by selecting View  Pause Code Coverage. This will freeze the currently displayed values but the underlying counting will continue. Selecting the menu option again will resume coverage updating.

The code coverage counts can be cleared by selecting View  Clear Code Coverage.

3.2.3 Single stepping and execution count latency

When the processor hits a break point and is then single stepped, the execution counts will likely be several steps behind the current processor location. This is because the processors’ internal trace hardware compresses and buffers execution information for multiple instructions before it transmits it to the trace port. Because the QTrace Analyser does not have access to the JTAG port it cannot flush the buffer and thus there will be latency in execution count updates. This does not result in any trace data being lost however.

3.2.4 Loop timing

There are many occasions while debugging when knowing the timing of a loop is very helpful. Examples include interrupt rates, timer periods, state machine cycle times, thread execution intervals, etc. The QTrace Analyser shows this information effortlessly and without the need to modify the code to toggle an I/O pin to view on an oscilloscope. By simply hovering the mouse cursor over an incrementing execution count in the source file view will cause a pop-up window to be displayed that shows the rate at which the line of code is being executed. Filtering is applied to the timing calculation with a time constant of several seconds to derive an accurate average rate.

Figure 11 shows an example of loop timing for the SysTick handler which is being called every millisecond as expected.

Figure 12 Source view loop timing

3.2.5 Execution heat map

On the right hand side of the source view, left of the vertical scrollbar, a thin resizable vertical window shows an overview of the lines that have been executed in the current source file. Coloured lines on the heat map denote source lines that have been executed. The colour of each line indicates the execution count for that line as a percentage of the total number of counts in the source file. The colours range from blue for the smallest number of counts up to red for the largest number. This is depicted by the colours on the heat-map set-up button at the top right of the source view:

When the button is pressed, a pop-up menu appears allowing the appearance of the heat map to be changed. The width of the heat map can be changed by moving the mouse cursor over the left edge then clicking and dragging. Also, any source line can be instantly scrolled into view by clicking on an area

Loop timing pop-up

Source Viewer QTRACE - USER MANUAL

of interest on the map. This is particularly useful to instantly see which line in a source file is being executed the most by clicking on the red coloured line on the heat map.

Figure 13 Source view execution heat map

3.2.6 Navigating to function implementations

The mouse cursor will turn into a hand when it is hovered over a function implementation in the source view. The function name will turn into hyperlink which can be clicked on to navigate to the function source. This can be in the current source file or another file. Note that this feature will be inactive if the function source is unavailable or if the function is a macro.

To go back to the previous view after clicking on a hyperlinked function, click the back button on the toolbar

Note: to disable this feature, e.g. when copying text, hold the Ctrl key down while hovering over a function.

3.2.7 Find text

The source view has a text search feature that can find specified text in the current file or in all available source files that were used to build the ELF file. The Find dialog below is displayed by selecting menu option View  Find in Current File… or by pressing Ctrl+F.

Figure 14 Source view find text

If the text is found, it will be scrolled into view. Pressing F3 will find the next occurrence if one exists. The Find-in-Files dialog is identical to the Find dialog and is displayed by selecting menu option View 

Find in Files… or by pressing Ctrl+Shift+F. The Find-in-Files results will be listed in the ‘Find Results’ page in the setup/status view. Clicking on any entry will display highlighted search text on the line and file where it was found.

Source Viewer QTRACE - USER MANUAL

A useful feature in the find dialog is the check box option to return only results where the line on which the text is found has been executed 1 or more times. This is particularly useful for Find-in-Files where there will inevitably be more results and all of them would otherwise need to be reviewed.

Figure 15 Source view find in files results

3.2.8 Find function from clipboard

When switching between the IDE and QTrace Analyser there is an option to find a function implementation from a name saved on the Clipboard. In the IDE copy the function name of interest to the Clipboard then in the QTrace Analyser select View  Find Function From Clipboard or press Ctrl+V. If the function name can be matched then the implementation will be displayed in the source view.

3.2.9 Source view bookmarks

A bookmark can be placed or removed in the current file by selecting menu option View  Toggle Bookmark or by pressing Ctrl+F2. A marker is placed on the selected line in the margin next to the line number and is remembered between successive edit-download cycles. By selecting View  Next Bookmark or pressing F2, the source file and line for each bookmark will be displayed.

All defined bookmarks can be viewed and deleted by selecting View  Bookmarks… as shown in Figure

16. This view will also show the locations of any WFE/WFI sleep instructions that have been detected by the QTrace Analyser. These instructions will cause erratic tracing behaviour because they suspend the trace signals and should be disabled in builds to be traced.

Search results

Source Viewer QTRACE - USER MANUAL

Figure 16 Source view bookmark list

The following features are not specifically related to the source viewer but their settings are accessed via tabs in the Settings / Status window in the source viewer and so are detailed here.

3.3 ITM debugging

The trace interface allows a very convenient, low overhead, way of passing debug data from a target application to the QTrace Analyser for viewing in a debug window. This is achieved in the firmware simply writing bytes to a specific memory location, effectively creating a debug channel. It is possible to redirect the output of standard printf style library functions to this channel by implementing a custom _write() function. This is typically implemented as a stub function in a file usually named syscalls.c. For further details of writing to the ITM debug port, refer to the example C code installed with the QTrace Analyser here:

C:\Users\Public\PDQLogic\QTraceAnalyser\Firmware\Examples\ITM The ITM debug window is shown / hidden by from the menu option View  ITM Viewer… or via the

toolbar:

The debug window below shows output from the STM32-Eval demonstrator detailed in Appendix B:

Source Viewer QTRACE - USER MANUAL

Figure 17 ITM debug window

The ITM debug window toolbar buttons are summarised below:

Button

Description

Clear debug window

Copy selected line to Clipboard

Copy all lines to Clipboard

Save debug buffer to log file

Stop debug window being updated (changes to ‘Enable’ when pressed)

Table 7 ITM debug window buttons

Figure 18 shows the settings associated with the ITM debug window. These are accessed from the ITM Debug tab in the Settings / Status window in the Source Viewer and are summarised in Table 8.

Figure 18 ITM debug settings

Setting

Description

Enable / disable ITM debug function

Number of lines that the debug window can display

Wrap lines when they exceed 256 bytes or discard bytes

Select the character which will terminate a line

Optionally clear the window when the target is reset

Size of circular buffer used to store received debug characters (also sets max. log file size)

Path to store time stamped debug logs when the save button is pressed in the debug viewer

Table 8 ITM debug settings summary

+ 46 hidden pages

PDQLogic QTrace User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual