QTools  6.9.4
Collection of Host-Based Tools
QSPY Host Application

About QSPY

As described in the previous section, QSPY is the host-resident component in the QP/Spy software tracing system. QSPY is a simple console application without a GUI, because its main purpose is to provide communication with the QS target-resident component, parsing of the QP/Spy Data Protocol and displaying the data in a simple human-readable format.

QSPY can also export the data in various other formats, such as format suitable for MATLAB/GNU-Octave, and format suitable for generating sequence diagrams. Additionally, QSPY can also save the symbolic information about the Target objects in form of QSPY dictionaries. An example of a QSPY session is shown in the Introduction to QP/Spy.

Finally, QSPY supports also extensible UDP-socket connection, which allows it to serve as a "Back-End" for attaching various "Front-Ends" (such as the QUTest Front-End and QView Front-End).

QSPY is written in portable C with ports to Windows and POSIX (Linux, macOS) provided. QSPY is also designed to be 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).

QSPY Command-Line Parameters

The QSPY application accepts several command-line parameters to configure the data link to the Target, backwards-compatibly with previous versions, and target dependencies, such as pointer sizes, signal sizes, etc. This means that the single QSPY host application can process data from any Target running the QS component. QSPY has been tested with wide range of 8-, 16-, 32-, and 64-bit CPUs.

The general form of invoking QSPY is as follows:

qspy [options]

where options are described in the following table:

Usage: qspy [options]     <arg> = required, [arg] = optional
 Option  Example  Default
 Must match QP macro
(QP port header file)


-h -h

Help. Prints the summary of options

-q [num] -q 99 (key-q)

Quiet mode (reduced stdout output)

-u [UDP_port|0] -u 7701

UDP socket for "Front-Ends".
-u0 suppresses opening the UPD socket

-v <QS_version> -v 6.2 6.6

Enforce backwards-compatibility with the specific QS version

-k -k

suppress keyboard input

-o -o (key-o)

Produce output to the specified file

-s -s (key-s)

Save the binary input to a file. Not compatible with -f

-m -m (key-m)

Produce MATLAB/GNU-Octave output to a file

-g [object-list] -g Table::inst,Philo::inst[0],Philo::inst[1] (key-g)

Produce Sequence diagram output to a file

-t [TCP-port] -t 6601

TCP/IP input selection. Not compatible with -c, -b, -f

-c <port> -c COM2 COM1

COM port selection. Not compatible with -t, -p, -f

-b <baud> -b 38400 115200

Baud rate selection. Not compatible with -t, -p, -f

-f <file> -f qs.spy

File input selection. Not compatible with -c, -b, -t, -p

-d [file] -d qspy150831_144229.dic

Read dictionaries from a file.

Options for configuring Target object sizes:
The Target can report it's configuration to QSPY, which means that you don't need to provide any upper-case options (such as: -T, -O, -F, etc.).

-T <size> -T 2 4 QS_TIME_SIZE

Time stamp size in bytes. Valid values: 1, 2, 4

-O <size> -O 2 4 QS_OBJ_PTR_SIZE

Object pointer size in bytes. Valid values: 1, 2, 4, 8

-F <size> -F 2 4 QS_FUN_PTR_SIZE

Function pointer size in bytes. Valid values: 1, 2, 4, 8

-S <size> -S 1 2 Q_SIGNAL_SIZE

Signal size in bytes. Valid values: 1, 2, 4

-E <size> -E 1 2 QF_EVENT_SIZ_SIZE

Event-size size in bytes (i.e., the size of variables that hold event size). Valid values: 1, 2, 4

-Q <size> -Q 2 1 QF_EQUEUE_CTR_SIZE

Queue counter size in bytes. Valid values 1, 2, 4

-P <size> -P 4 2 QF_MPOOL_CTR_SIZE

Pool counter size in bytes. Valid values: 1, 2, 4

-B <size> -B 1 2 QF_MPOOL_SIZ_SIZE

Block size size in bytes. (i.e., the size of variables that hold memory block size). Valid values 1, 2, 4

-C <size> -C 4 2 QF_TIMEEVT_CTR_SIZE
Time event counter size. Valid values: 1, 2, 4

Your main concern when invoking QSPY is to match exactly the target system you are using. The fourth column of the table above lists the configuration macros used by the target system as well as the platform-specific QP header files where those macros are defined. You need to use the corresponding QSPY command-line option only when the QP macro differs from the default. The default values assumed by QSPY are consistent with the defaults used in QP.

When you do not match the QSPY host application with the QS target component, the QSPY application will be unable to parse correctly the mismatched trace records and will start generating the following errors:

   ~ ~ ~
   <COMMS> ERROR    4 bytes unused in Rec=QS_QEP_INTERN_TRAN
   ~ ~ ~
   <COMMS> ERROR    2 bytes unused in Rec=QS_QEP_DISPATCH

The name after Rec= indicates the Record ID of the trace record that failed to be parsed.

Default Configuration

The QSPY application invoked without any parameters defaults to the following configuration:

QSPY 6.6.0 Copyright (c) 2005-2019 Quantum Leaps
Documentation: https://www.state-machine.com/qtools/qspy.html
Current timestamp: 190811_124028
-u 7701
-t 6601
-v 660
-T 4
-O 4
-F 4
-S 2
-E 2
-Q 1
-P 2
-B 2
-C 2

Specifically, by default QSPY opens the UDP socket at the default port (-u 7701) for "back-ends" (such as QUTest) and opens the TCP/IP socket at the default port (-t 6601) for communication with the Targets.

The other parameters correspond to 32-bit Target CPUs, such as ARM and x86 compiled in 32-bit mode. The x86 is relevant for running the embedded software on host machines based on the x86 processors.

The default QSPY configuration is specifically designed for running QUTest tests on the x86-based hosts with target executables compiled in the 32-bit x86 mode. This default configuration also matches 32-bit ARM CPUs, but typically requires the single -c <COM> parameter to communicate with the embedded Target via a serial port.

The default QSPY configuration (without any parameters) is also backwards-compatible with the following invocation: qspy -u -t, which is recommended for running QUTest tests on the host computer. Starting with QSPY version 7.x.y, you can use the simpler qspy invocation.

Terminating QSPY

The QSPY host application can be terminated in the following ways:

  • by typing x or X key (works only in the absence of the -k command-line option)
  • by typing Esc key (works only in the absence of the -k command-line option)
  • by typing Ctrl-C (works also with the -k option)
  • by sending the Kill signal to the process running QSPY

QSPY Keyboard Commands

In the absence of the -k (suppress keyboard) command-line option, the QSPY console application accepts keyboard input. The following table shows the currently supported key-strokes:

Key Action
<Esc> Exit QSPY
h display keyboard help and QSPY status
c clear the screen
q toggle quite mode (no Target output to the screen)
r send RESET command to the Target
i send the INFO request to the Target (see also QSPY Dictionaries)
t send TIKC[0] command to the Target
u send TICK[1] command to the Target
d save QP/Spy Dictionaries to a file
o toggle QSPY Human-Readable Output to a file (open/close)
s/b toggle binary file output (open/close)
m toggle MATLAB Output to a file (open/close)
g toggle Sequence Output to a file (open/close)

QSPY can send many more sophisticated commands to the Target by means of the Front-End extension mechanism.

QSPY Communication with the Target

QSPY currently provides the following communication links to the QS target-resident component:

Communication Link Command-Line Option
TCP/IP -t [TCP_port] (default)
Serial port -c <COM_port> and -b<baud_rate>
Binaly File -f <file_name>
Other link
(e.g., JTAG debug probe)
can be added to the QSPY Platform Abstraction Layer

Saving Files from QSPY

QSPY can save the tracing data from the Target in various formats into files. QSPY assigns file names automatically. Also, QSPY can open/close various files multiple times in a single session, so it is no longer necessary to exit QSPY and launch it again with different command-line parameters to save data to a different file.

QSPY saves all files into the current directory from which qspy has been launched.

QSPY uses a very simple naming convention to assign file names. All names start with qspy<time-stamp>, where the time-stamp format is: YYMMDD_hhmmss, where YY is 2-digit year, MM is a 2-digit month, DD is a 2-digit day of the month, hh is a 2-digit hour, mm is a 2-digit minute, and ss is a 2-digit second. The time-stamp is accurate to a one second, so its virtually impossible to have name conflicts for files generated on the same machine. The various types of files are distinguished by the following extensions:

Example Comment
-o o .txt qspy150914_132234.txt text (screen) output
-s s .qs qspy150914_132234.qs raw binary output
-d d .dic qspy150901_101203.dic dictionary output
-m m .mat qspy150914_132234.mat MATLAB output
-g g .seq qspy150914_132234.seq Sequence diagram output
All files except the dictionary output are time-stamped with the local time of the Host. The dictionary output is time-stamped with the build-time of the Target image.

The following sub-sections explain the following QSPY features:

Next: QSPY Screen Output