PDQLogic QTrace User manual

QTrace Application Note 005 Copyright © 2021 PDQLogic Ltd Page 1 of 11
Application Note 005
Getting started with QTrace and a STM32F4 Nucleo demo board
This quick start guide shows how to begin evaluating QTrace in minutes using a very low cost STM32
Nucleo-F429ZI board from ST Microelectronics. The supplied demo project can easily be adapted to other
STM32 Nucleo-144 boards to allow tracing of different STM32 variants.
1. Overview
QTrace is a low cost instruction trace system for ARM Cortex M3/M4/M7 based processors. It gives an
exceptional insight into how a target application is running and aids locating hard-to-find bugs. The system
consists of a USB 3.0 powered trace probe and a Windows based trace analyser application.
The QTrace probe is supplied with the following components:
QTrace hardware probe
14-way 0.05” to 20-way 0.1” JTAG/SWD converter PCB
20-way split ribbon cable
USB 3.0 Type A to Micro-B cable
QTrace Analyser application (installed via a link sent to the email address given with the online order)
The ST Nucleo-144 converter PCB above (see https://www.pdqlogic.com/documents/STM32-Nucleo-Trace-Board.pdf) is a
30-way 0.1” to 20-way 0.05” trace converter PCB*and is required for this quick-start guide. The other
prerequisites are:
Nucleo-F429ZI board*, see https://www.st.com/en/evaluation-tools/nucleo-f429zi.html
Micro-USB cable*
RJ45 cable based network connection (optional)
QTrace Analyser is supplied with a demo application created with STM32CubeIDE v1.5 that can be flashed
onto the Nucleo board via a hex file. The demo doesn’t require an IDE but if you already have STM32CubeIDE
installed then go ahead and import the supplied project into your workspace from:
C:\Users\Public\PDQLogic\QTraceAnalyser\Firmware\Examples\Nucleo_F429.
Build and flash the image via the Nucleo’s ST-Link debugger then skip to section 3 to begin evaluating QTrace.
If you aren’t using STM32CubeIDE then flash Nucleo_F429.hex (located in the path above) with an existing
tool and skip to section 3. Alternatively, use the STM32CubeProgrammer from ST as detailed in Section 2.
*Purchased separately
+
ST Nucleo-144
converter PCB

QTrace Application Note 005 Copyright © 2021 PDQLogic Ltd Page 2 of 11
Application Note 005
2. Flashing with STM32CubeProgrammer
STM32CubeProgrammer is a free lightweight application that allows STM32 devices to be programmed
without requiring an IDE. The application can be downloaded from the ST website:
https://www.st.com/en/development-tools/stm32cubeprog.html
The following steps show how to program the supplied hex file onto the Nucleo-F429.
1) Download and run the STM32CubeProgrammer installer, using the default settings. A USB driver for the
ST-Link debugger embedded on the Nucleo board will also be installed.
2) After STM32CubeProgrammer is installed, connect the Nucleo board to the PC via the ST-Link micro USB
connector:
3) Launch STMCubeProgrammer. The ST-Link debugger embedded on the Nucleo should be detected and
displayed:
ST-Link USB
Connector

QTrace Application Note 005 Copyright © 2021 PDQLogic Ltd Page 3 of 11
Application Note 005
4) Click the green Connect button:
5) Once connected, select the Erasing & Programming screen:

QTrace Application Note 005 Copyright © 2021 PDQLogic Ltd Page 4 of 11
Application Note 005
6) Browse for the hex file to program:
C:\Users\Public\PDQLogic\QTraceAnalyser\Firmware\Examples\Nucleo_F429ZI\STM32CubeIDE\Debug\Nucleo_F429.hex
7) Once the hex file is selected, tick the Run after programming checkbox then click the Start Programming
button:

QTrace Application Note 005 Copyright © 2021 PDQLogic Ltd Page 5 of 11
Application Note 005
8) Once successfully programmed click Disconnect:
After a short delay, a green LED (LD1) on the Nucleo board will start blinking. Remove the USB lead from the
Nucleo board before connecting to the QTrace probe.

QTrace Application Note 005 Copyright © 2021 PDQLogic Ltd Page 6 of 11
Application Note 005
3. Tracing with the Nucleo-F429
The Nucleo-F429 board contains a STM32F429 ARM Cortex-M4 processor running up to 180MHz. It has
several external interfaces that are useful for demonstrating the key QTrace features.
After the Nucleo_F429.hex demo file has been flashed on the Nucleo board, follow the steps below to trace
the demo application. Note that the demo firmware will configure the STM32 ETM trace interface, removing
the need for an IDE/debugger to demonstrate QTrace features.
1) Launch QTrace Analyser after it has been installed and then connect the QTrace probe to a USB 3.0 port
on your PC via the supplied USB-A to USB micro-B cable.
Note: During the installation of QTrace Analyser, a USB driver is also installed. Windows may also
attempt to search online for a driver. If it does, just click ‘Skip’ in the pop-up message.
2) QTrace Analyser should detect the QTrace probe and then configure it. The front panel LED of the probe
will flash red when configuration has successfully completed.
Note:
i. QTrace Analyser may prompt to retry connecting to the probe if Windows takes a while to install
the USB driver. If this happens, select retry after the driver installation is complete. If the problem
persists, or no probe is detected, disconnect the QTrace probe USB lead and then reconnect it.
ii. The target must remain disconnected until the probe has been configured by QTrace Analyser.
3) The first time QTrace Analyser is run it will load the ‘quick start’trace configuration file supplied with the
Nucleo-F429 STM32CubeIDE project. If not, select menu option File  Open Example... and browse to:
C:\Users\Public\PDQLogic\QTraceAnalyser\Firmware\Examples\Nucleo_F429\Nucleo_F429_QuickStart.tcf.
Note: If the demo is being run in conjunction with STM32CubeIDE then load Nucleo_F429.tcf instead.
4) Connect the 10-way socket on the shorter length of the split ribbon cable to the QTrace probe:
Note: the socket on the other half of the ribbon is not used in this quick-start guide.
5) Fit the trace converter PCB to CN9 on the Nucleo board then connect the QTrace 20-way ribbon socket
to the trace header. Optionally connect a network cable to the RJ45 socket (connect the other end to a
network with a DHCP server). Lastly, connect the micro USB lead to power the board as shown.
Reset
button

QTrace Application Note 005 Copyright © 2021 PDQLogic Ltd Page 7 of 11
Application Note 005
6) The front panel LED on the QTrace probe will turn green when trace data is detected. The target clock
speed and instruction execution rate in MIPS will also be displayed in the QTrace Analyser status bar:
If the target is not detected then press the black Nucleo reset button board or unplug the Nucleo USB
lead and reconnect it. If this has no effect then press the toolbar button to reset the QTrace probe.
Note: Trace is usually configured via a debugger script that runs after the image is flashed but before the
CPU is started. The demo firmware configures the trace interface internally to simplify this guide.
7) For an example of Live Coverage, click in the function tree-view on stm32f4xx_hal.c (highlighted in red)
to display its source and its execution heat map to the right of the view. Select the function Hal_IncTick()
to scroll its source into view.Hover the mouse over the execution counts in the yellow column to show a
pop-up execution rate display. Also notice the corresponding counts in the pink column of the
disassembly view.
8) If the Nucleo board is connected to a network then press the toolbar button to open the ITM debug
window, otherwise skip to step 9.
This debug window displays printf-style debug messages sent via the low overhead ITM channel by the
target. Refer to ITM Debugging in the user manual for further details. The demo firmware implements a
DHCP client to obtain an IP address which is output as an ITM debug message. Select the line starting
with “http://...” then press Ctrl+C to copy the URL to the clipboard.
Note: Ensure the network cable, if used, was connected before the CPU was started. Also, it may take
several seconds for the Nucleo board to obtain an IP address.
Execution
Heatmap


QTrace Application Note 005 Copyright © 2021 PDQLogic Ltd Page 8 of 11
Application Note 005
9) Select ToggleBlueLED using the function search:
Double click in the drop-down function list to display ToggleBlueLED in the source view.
10) Select the ToggleBlueLED function definition in the source view (line 306) then press F9. A brown square
will appear between the line number and the pale yellow execution count column. A Trace Point has
been set-up on this line (an analogy to an IDE breakpoint). When this line has been executed, the
instructions leading up to this point will be captured and displayed as a call stack.
11) If the Nucleo board is connected to a network then navigate to the URL copied in step (8) with your web
browser. You should see the webpage as shown on the next page. Click the blue oval button in the
webpage and note that the blue LED on the Nucleo board is illuminated. ToggleBlueLED will be called by
the CGI handler that is configured to respond to the button press.
If the Nucleo board is not connected to a network, or it was unable to obtain an IP address, then briefly
press and release the blue button on the Nucleo board. This will also call ToggleBlueLED to illuminate the
blue LED.
In both cases the Trace Point will be triggered.

QTrace Application Note 005 Copyright © 2021 PDQLogic Ltd Page 9 of 11
Application Note 005
12) At this point QTrace Analyser will have switched to the Code Capture view to provide a call stack history
of up to 8M instructions executed before ToggleBlueLED:
The vertical purple marker on the right hand side of the graph indicates the trigger point. The blue
highlighted instruction and corresponding vertical blue marker in the graph identify the instruction being
inspected. Unlike an IDE breakpoint, the captured call stack can be reviewed while the CPU is still running,
one instruction at a time, or one source line at a time using the orange highlighted Source Line buttons.
Source
Stepping

QTrace Application Note 005 Copyright © 2021 PDQLogic Ltd Page 10 of 11
Application Note 005
13) To see QTrace Analyser respond to a target hard fault exception, press and hold the blue button on the
Nucleo board for one second. This will deliberately cause a read from an invalid memory location and
generate a hard fault. QTrace Analyser will switch to the Code Capture display to show the location of
the fault both graphically and in disassembly / source code form, see below:
After reviewing the captured instructions, press the black reset button to resume normal operation (or
reset the CPU from the IDE).
Refer to the user manual for other Code Capture features such as function search & filtering, 64M
instruction capture and post-trigger (capture a specified number of instructions after the trigger).
14) For an overview of the functions being executed in the application, click on the yellow Profiling tab in
QTrace Analyser. Various statistics for every function are displayed in columns and each column can be
used to sort the functions. Also, the function search window shown in step 9 can be used to locate a
function of interest.
To show the source code of any function in the profiling view, simply double click on its entry in the list.
See the HAL_TIM_IRQHandler() example below:
Deliberate
Hard Fault

QTrace Application Note 005 Copyright © 2021 PDQLogic Ltd Page 11 of 11
Application Note 005
15) The profiled functions can be filtered to show only interrupt handlers. Select the IRQ Handler radio
button and then hover over any handler to see its corresponding interrupt rate:
16) To conclude this quick start guide, select the FreeRTOS tab to display the current real-time CPU load
graph and a dynamic thread stats list.
Click the red Snapshot button in the top right to freeze all events captured so far and display them
graphically and as a time-stamped list:
Note: QTrace Analyser connects to the running debugger to retrieve target information. However, as
this quick-start guide does not use a debugger, certain information will be displayed generically or as
‘unnamed’ objects such as queues, semaphores, etc.
17) For further details of QTrace Analyser, press F1 in QTrace Analyser for online help or open the PDF user
manual located at C:\Program Files\PDQLogic\QTraceAnalyser\Documents\QTrace-User-Manual.pdf