As described in the previous section, QSPY is the host-resident component in the Q-SPY software tracing system. QSPY is a plain console application without a GUI, because its main purpose is to provide the parsing of the Q-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 message sequence diagrams with MscGen. Additionally, QSPY can also save the symbolic information about the Target objects in form of QSPY dictionaries.
Starting with version 5.5.0, QSPY can serve a "Back-End" for attaching various GUI-based or head-less "Front-Ends" (such as the QSpyView Front-End).
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:
options are described in the following table:
qspy -t 6602 <-- INCORRECT!!
qspy -t6602 <-- CORRECT
| Must match QP macro|
(QP port header file)
Help. Prints the summary of options
Quiet mode (no stdout output)
UDP socket for "Front-Ends"
Compatibility with QS version
Produce output to the specified file
Save the binary input to a file. Not compatible with -f
Produce MATLAB/GNU-Octave output to a file
Produce MscGen output to a file
COM port selection. Not compatible with -t, -p, -f
Baud rate selection. Not compatible with -t, -p, -f
TCP/IP input selection. Not compatible with -c, -b, -f
File input selection. Not compatible with -c, -b, -t, -p
Read dictionaries from a file.
Options for configuring Target object sizes:
Time stamp size in bytes. Valid values: 1, 2, 4
Object pointer size in bytes. Valid values: 1, 2, 4, 8
Function pointer size in bytes. Valid values: 1, 2, 4, 8
Signal size in bytes. Valid values: 1, 2, 4
Event-size size in bytes (i.e., the size of variables that hold event size). Valid values: 1, 2, 4
Queue counter size in bytes. Valid values 1, 2, 4
Pool counter size in bytes. Valid values: 1, 2, 4
Block size size in bytes. (i.e., the size of variables that hold memory block size). Valid values 1, 2, 4
|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.
********** 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.
Starting from version 5.5.0, QSPY accepts keyboard input. The following table shows the currently supported key-strokes:
|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 command to the Target|
|u||send TICK command to the Target|
|d||save Q-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||mtoggle MATLAB Output to a file (open/close)|
|g||toggle MscGen Output to a file (open/close)|
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.
qspyhas 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:
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:
|text (screen) output|
|raw binary output (Q-SPY protocol)|
Next: QSPY Screen Output