QSPY: QSPY Host Application Reference Manual

Introduction

Quantum Spy™ (QS) is a real-time tracing instrumentation built into the QP event-driven platform. QS allows you to gain unprecedented visibility into your application by selectively logging almost all interesting events occurring within state machines, the framework, the kernel, and your application code. QS event logging is minimally intrusive, offers precise time-stamping, sophisticated runtime filtering of events, and good data compression. QS can be configured to send the real-time data out of the serial or Ethernet port of the target device, or even write the data to a file. QS is described in Chapter 11 of the book PSiCC2, Newnes 2008.

Every software tracing system consists of a target component and a host component. The host component for the Quantum Spy software tracing system is the QSPY host application. QSPY is a simple console application without any fancy GUI because its purpose is to provide only the QS data parsing, storing,and exporting to such powerful tools as MATLAB or GNU OCTAVE. QSPY has been designed from the ground up to be platform-neutral. The application is written in portable C++, and ports to Linux and Windows with various compilers are provided.

A typical setup for collecting software trace data with 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 easy, because the data link layer is clearly abstracted in a Hardware Abstraction Layer (HAL). The QSPY application accepts several command-line parameters to configure all target dependencies, such as pointer sizes, signal sizes, etc. This means that the single QSPY host application can process data from any target 8-, 16-, or 32-bit.

QSPY provides a simple consolidated, human-readable textual output to the screen. If the QS trace data contains dictionary trace records, QSPY applies this symbolic information to output the provided identifiers for objects, signals, and states. Otherwise, QSPY outputs the hexadecimal values of various pointers and signals. (See Section Human-Readable QSPY Output).

Finally, QSPY can export the trace data in the matrix format readable by MATLAB/Octave. Special MATLAB script to import QSPY trace data to MATLAB/Octave is provided. Once the data is available in MATLAB matrices, it can be conveniently manipulated and visualized with this powerful tool. (See Section QSPY MATLAB/GNU Octave Inteface and QSPY MscGen Inteface).

QSPY Command-Line Parameters

The QSPY host application is designed to work with all possible target CPUs and data links, which requires a wide range of configurability. For example, for any given target CPU the QSPY application must "know" the size of object pointers, function pointers, event signals, timestamp size and so on. You provide this information to QSPY by means of command-line parameters, which are summarized in the following table:

Option	Example	Default	Must match QP macro (QP port header file)	Comments
-h	-h			Help. Prints the summary of options
-q	-q			Quiet mode (no stdout output)
-v	-v 4.1	4.2		Compatibility with QS version
-o	-o qs.txt			Produce output to the specified file
-s	-s qs.spy			Save the binary input to the specified file. Not compatible with -f
-m	-m qs.mat			Generates MATLAB/Octave output to the specified file
-g	-g qs.msc			Generates MscGen output to the specified file
-c	-c COM2	COM1		COM port selection. Not compatible with -t, -p, -f
-b	-b 38400	115200		Baud rate selection. Not compatible with -t, -p, -f
-t	-t			TCP/IP input selection. Not compatible with -c, -b, -f
-p	-p 6602	6601		TCP/IP server port number. Not compatible with -c, -b, -f
-f	-f qs.spy			File input selection. Not compatible with -c, -b, -t, -p
-T	-T 2	4	`QS_TIME_SIZE` (qs_port.h)	Time stamp size in bytes. Valid values: 1, 2, 4
-O	-O 2	4	`QS_OBJ_PTR_SIZE` (qs_port.h)	Object pointer size in bytes. Valid values: 1, 2, 4, 8
-F	-F 2	4	`#QS_FUN_PTR_SIZE` (qs_port.h)	Function pointer size in bytes. Valid values: 1, 2, 4, 8
-S	-S 1	2	`#Q_SIGNAL_SIZE` (qep_port.h)	Signal size in bytes. Valid values: 1, 2, 4
-E	-E 1	2	`#QF_EVENT_SIZ_SIZE` (qf_port.h)	Event-size size in bytes (i.e., the size of variables that hold event size). Valid values: 1, 2, 4
-Q	-Q 1	2	`#QF_EQUEUE_CTR_SIZE` (qf_port.h)	Queue counter size in bytes. Valid values 1, 2, 4
-P	-P 4	2	`#QF_MPOOL_CTR_SIZE` (qf_port.h)	Pool counter size in bytes. Valid values: 1, 2, 4
-B	-B 1	2	`#QF_MPOOL_SIZ_SIZE` (qf_port.h)	Block size size in bytes. (i.e., the size of variables that hold memory block size). Valid values 1, 2, 4
-C	-C 4	2	`#QF_TIMEEVT_CTR_SIZE` (qf_port.h)	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.

Note:: 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:

     ********** 028: Error xx bytes unparsed
     ********** 014: Error -yy bytes unparsed

The number in front of the error indicates the Record ID of the trace record that could not be parsed.

Licensing QSPY

The QSPY host application is licensed the same way as all other components of the QP event-driven platform. See Section licensing.