As shown in the figure below, any software tracing system consist of the target-resident component and a host-resident component. QSPY is the host-resident component of the Q-SPY software tracing system built into the QP/C and QP/C++ active object frameworks. QSPY is a console application available for Windows and Linux hosts. The job of QSPY is to receive the trace data produced by an instrumented QP/C or QP/C++ application running on an embedded Target, visualize the data, and optionally to save the data in various formats (such as MATLAB or MscGen). Also, starting with version 5.5.0, QSPY can send commands to the Target for testing and control (bi-directional QSPY).
QSPY is easily adaptable to various target-host communication links. Out of the box, the QSPY host application supports serial (RS232), TCP/IP, and file communication links. Adding other communication links is straightforward, because the data link is accessed only through a generic Platform Abstraction Layer (PAL).
The QSPY application accepts several command-line parameters to configure the data link and all target dependencies, such as pointer sizes, signal sizes, etc. This means that the single QSPY host application can process data from any embedded target. The application has been tested with wide range of 8-, 16-, 32-, and 64-bit Targets.
Starting with QSPY version 5.5.0, the QSPY application offers a UDP socket for attaching various "Front-Ends", such as GUI-based or head-less scripts to control and test the embedded Target. As an example of a GUI-based extensions, QSPY comes with a Tcl/Tk Front-End called QSpyView.
As you can see in the figure above, the QSPY console application (QSPY Back-End) opens a UDP socket, which forwards all trace data from the Target to the QSpyView "Front-End", so the Front-End has access to all this information. Additionally, the Front-End can send commands to QSPY and, ultimately, to the Target. Currently, the following commands are supported:
QSPY is included as a component inside the Qtools collection, which is available for download from SourceForge.net. The Qtools download is provided as a platform-independent ZIP or as a Windows EXE. (The EXE installer is recommended, because it is digitally signed by Quantum Leaps and provides an uninstaller). Uninstalling Qtools is easy and requires only deleting the
qtools directory from your disk.
To use the Qtools, it is highly recommended to add the
<qtools>\bin directory to the global
PATH on your system, where
<qtools> denotes the directory where you have unzipped the
PATHwill enable you to invoke QSPY by simply typing
qspyat the command prompt, regardless of your current directory. This will come handy, because typically you will not invoke
qspyfrom its installation directory.
To use the Qtools source code (such as parts of the QSPY) in builds of the QP applications, it is highly recommended to define the environment variable
QTOOLS to point to the installation directory of Qtools.
The following annotated directory tree in the standard Qtools distribution lists the top-level directories and files pertaining to QSPY:
To show you how software tracing works in practice this section presents an example of a software tracing session (on a Windows machine). This example uses the Dining Philosophers Problem (DPP) test application running on the EK-TM4C123GXL board (TivaC LaunchPad), located in the QP/C and QP/C++ downloads (version 5.5.0 or newer). Specifically, the example is located in the directory
<qpx> stands either for QP/C or QP/C++ installation directory on your system.
The first step is to prepare the embedded Target (the TivaC LaunchPad in this case) to run the instrumented application code. For that, you need to build the QSPY build configuration, because only in this configuration the instrumentation inside the QP framework and your application becomes active.
dpp_ek-tm4c123gxl example is available with the cooperative QV kernel and the preemptive QK kernel. Each version is also available for the ARM-Keil toolset, GNU-ARM toolset, and IAR toolset. All of them provide the QSPY build configuration, but for the sake of this discussion, let's select the QK kernel and GNU-ARM toolset, located in the sub-directory
<qpx>\examples\arm-cm\dpp_ek-tm4c123gxl\qk\gnu. At the command prompt, change to this directory (
cd c:\qp\qpc\examples\arm-cm\dpp_ek-tm4c123gxl\qk\gnu) and type:
Next, connect the TivaC LaunchPad to the USB port on your PC and program the produced image into the board by means of the
flash.bat script. (This script assumes that you have installed the
LmFlash.exe utility from Texas Instruments.)
After you reset the board (by pressing the Reset button), the board should start blinking the 3-color LED and it should also start producing Q-SPY data to the virtual COM port.
dpp_ek-tm4c123gxlexample is also available for other toolsets, such as ARM-Keil and IAR. The DPP example comes with project files that can be opened in the IDEs provided with those tools. These IDEs are also used to load the code into the TivaC board.
To view the Q-SPY data produced by the TivaC Target, you can't use a generic serial terminal, because the data is in binary format. You need to use the special host-resident console application called QSPY.
Assuming that you have added the
qtools\bin directory to your
PATH, you can run QSPY from any directory by simply typing
qspy at the command prompt. However, you should choose the current directory carefully, because
qspy will produce all output files into the directory from which it was launched.
As you can see in the screen-shot above,
qspy has been launched with the command-line parameters
-u -cCOM4. The
-u parameter means that
qspy should open the UDP socket for attaching various "Front-Ends". The
-cCOM4 option instructs
qspy to open the specified COM port for the communication with the Target. (NOTE: you should adjust the actual COM port number to the virtual COM port assigned to your TivaC board. The COM port is visible in the Windows Device Manager).
Regarding all other command-line QSPY options, you can obtain a quick summary of options by providing
-h command line option, or by pressing the
h when QSPY is running, as shown in the screen-shot below. The section QSPY Command-Line Parameters for description of all options.
Besides displaying the tracing data in human-readable format, the QSPY console application can accomplish the following tasks:
Being just a console application, QSPY is limited in how it can interact with the User. However, starting with version 5.5.0, QSPY provides an extension mechanism for attaching various "Front-Ends", which might provide a GUI, or might be "head-less" to drive automated testing, for example.
The "Front-Ends" can interact with QSPY though a UDP socket that QSPY opens when it receives the
-u command-line option. (The default port number for the UDP socket is
7701, but this port number can be overridden by providing an optional value to the
-u option. For example
-u8803 will open a UDP socket at port number
The first available "Front-End" for QSPY is called QSpyView and is written in Tcl/Tk. QSpyView is itself extensible in order to support visualization and control of specific QP applications. For instance, the DPP application requires different views and control than a "Fly'n'Shoot" game.
To support such customizations, QSpyView is broken up into modules (separate Tcl scripts). The directory qtools/qspy/qspyview/ contains the generic scripts for UDP communication with the QSPY "Back-End" (qspy.tcl), and a generic GUI (qspyview.tcl).
The script qspyview.tcl can be further customized by providing a command-line parameter in the invocation of the script, such as dpp.tcl for the DPP application. This latter script is co-located with the DPP example, which makes the much more sense than cluttering the qtools/qspy/qspyview/ directory.
In the end, the QSpyView "Front-End", customized for the DPP application, can be very easily and conveniently launched by means of the qspyview shortcut located in the qtools/qspy/qspyview/. The following screen shot shows how to adjust the shortcut in Windows.
QTOOLSenvironment variable is defined.
As shown in the screen shot above, the QSpyView "Front-End" provides in this case a customized views for the DPP example application running on the TivaC LaunchPad.
The QSpyView Front-End can perform many more actions in the Target, such as:
Please post any technical questions to the Free Support Forum hosted on SourceForge.net. Posts to this forum benefit the whole community and are typically answered the same day.
Direct Commercial Support is available to the commercial licensees. Every commercial license includes one year of Technical Support for the licensed software. The support term can be extended annually.
Training and consulting services are also available from Quantum Leaps. Please refer to the Support web-page for more information.
The QS target-resident component is part of the QP/C and QP/C++ active object frameworks and is licensed the same way as QP.
The QSPY/QSpyView host applications are licensed under the GPL open source license.
Copyright © 2002-2015 Quantum Leaps, LLC. All Rights Reserved.
Next: Concepts and Structure