qspy_ref.txt

事件驱动程序设计很好的框架

/**
\page qspy_page QSPY Host Application Reference Manual

\image html logo_qs_TM.jpg

- \ref qspy_intro_sec
- \ref qspy_command
- \subpage qspy_human_format
- \subpage qspy_matlab

\section qspy_intro_sec Introduction

Quantum Spy&tm; (%QS) is a real-time tracing instrumentation built into the
\ref overview "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 \ref 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 <B>QSPY host application</B>. 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 <STRONG>MATLAB</STRONG>. 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.

\image html qspy.jpg "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 \ref qspy_human_format).

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

\section qspy_command 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:

<TABLE SUMMARY="QSPY parameters" cellSpacing=4 cellPadding=1 border=0
ALIGN="center" VALIGN="middle">
  <TR bgColor="#c8cedc">
    <TD><B>&nbsp;Option</B></TD>
    <TD><B>&nbsp;Example</B></TD>
    <TD><B>&nbsp;Default</B></TD>
    <TD><B>&nbsp;Must match QP macro\n (QP port header file)</B></TD>
    <TD><B>&nbsp;Comments</B></TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>-h</TD>
    <TD>-h</TD>
    <TD></TD>
    <TD></TD>
    <TD>Help. Prints the summary of options</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>-q</TD>
    <TD>-q</TD>
    <TD></TD>
    <TD></TD>
    <TD>Quiet mode (no stdout output)</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>-o</TD>
    <TD>-o qs.txt</TD>
    <TD></TD>
    <TD></TD>
    <TD>Produce output to the specified file</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>-s</TD>
    <TD>-s qs.spy</TD>
    <TD></TD>
    <TD></TD>
    <TD>Save the binary input to the specified file. Not compatible with -f
    </TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>-m</TD>
    <TD>-m qs.mat</TD>
    <TD></TD>
    <TD></TD>
    <TD>Generates MATLAB output to the specified file</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>-c</TD>
    <TD>-c COM2</TD>
    <TD>COM1</TD>
    <TD></TD>
    <TD>COM port selection. Not compatible with -t, -p, -f</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>-b</TD>
    <TD>-b 115200</TD>
    <TD>38400</TD>
    <TD></TD>
    <TD>Baud rate selection. Not compatible with -t, -p, -f</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>-t</TD>
    <TD>-t</TD>
    <TD></TD>
    <TD></TD>
    <TD>TCP/IP input selection. Not compatible with -c, -b, -f</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>-p</TD>
    <TD>-p 6602</TD>
    <TD>6601</TD>
    <TD></TD>
    <TD>TCP/IP server port number. Not compatible with -c, -b, -f</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>-f</TD>
    <TD>-f qs.spy</TD>
    <TD></TD>
    <TD></TD>
    <TD>File input selection. Not compatible with -c, -b, -t, -p</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>-T</TD>
    <TD>-T 2</TD>
    <TD>4</TD>
    <TD>\c #QS_TIME_SIZE\n (qs_port.h)</TD>
    <TD>Time stamp size in bytes. Valid values: 1, 2, 4</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>-O</TD>
    <TD>-O 2</TD>
    <TD>4</TD>
    <TD>\c QS_OBJ_PTR_SIZE\n (qs_port.h)</TD>
    <TD>Object pointer size in bytes. Valid values: 1, 2, 4</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>-F</TD>
    <TD>-F 2</TD>
    <TD>4</TD>
    <TD>\c #QS_FUN_PTR_SIZE\n (qs_port.h)</TD>
    <TD>Function pointer size in bytes. Valid values: 1, 2, 4</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>-S</TD>
    <TD>-S 2</TD>
    <TD>1</TD>
    <TD>\c #Q_SIGNAL_SIZE\n (qep_port.h)</TD>
    <TD>Signal size in bytes. Valid values: 1, 2, 4</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>-E</TD>
    <TD>-E 1</TD>
    <TD>2</TD>
    <TD>\c #QF_EVENT_SIZ_SIZE\n (qf_port.h)</TD>
    <TD>Event-size size in bytes (i.e., the size of variables that hold
        event size). Valid values: 1, 2, 4</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>-Q</TD>
    <TD>-Q 1</TD>
    <TD>2</TD>
    <TD>\c #QF_EQUEUE_CTR_SIZE\n (qf_port.h)</TD>
    <TD>Queue counter size in bytes. Valid values 1, 2, 4</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>-P</TD>
    <TD>-P 4</TD>
    <TD>2</TD>
    <TD>\c #QF_MPOOL_CTR_SIZE\n (qf_port.h)</TD>
    <TD>Pool counter size in bytes. Valid values: 1, 2, 4</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>-B</TD>
    <TD>-B 1</TD>
    <TD>2</TD>
    <TD>\c #QF_MPOOL_SIZ_SIZE\n (qf_port.h)</TD>
    <TD>Block size size in bytes. (i.e., the size of variables that hold
        memory block size). Valid values 1, 2, 4</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>-C</TD>
    <TD>-C 4</TD>
    <TD>2</TD>
    <TD>\c #QF_TIMEEVT_CTR_SIZE\n (qf_port.h)</TD>
    <TD>Time event counter size. Valid values: 1, 2, 4</TD>
  </TR>
</TABLE>


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 table above. Please note that the options are case sensitive.


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:

\verbatim
     ********** 028: Error xx bytes unparsed
     ********** 014: Error -yy bytes unparsed
\endverbatim

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


<HR>

\section qspy_licensing Licensing QSPY

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

\image html logo_ql_TM.jpg
Copyright &copy; 2002-2008 Quantum Leaps, LLC. All Rights Reserved.\n
http://www.quantum-leaps.com
*/

/**
\page qspy_human_format Human-Readable QSPY Output

The QSPY host application is just a simple console-type program without any
fancy user interface. QSPY application displays the trace data in a
human-readable textual format. The following listing shows fragments of such
a data log generated from the DOS/QK version of the DPP application.

\note The QSPY host application supports also exporting data to the powerful
MATLAB environment, as described in Section \ref qspy_matlab.

\verbatim
qspy host application 3.5.00
Copyright (c) Quantum Leaps, LLC.
Mon Feb 25 12:20:13 2008

-T 4
-O 4
-F 4
-S 1
-E 2
-Q 1
-P 2
-B 2
-C 2

           Obj Dic: 16CA18D8->l_smlPoolSto
           Obj Dic: 16CA1900->l_tableQueueSto
           Obj Dic: 16CA1914->l_philoQueueSto[0]
. . . . . .
           EQ.INIT: Obj=l_tableQueueSto Len= 5
0000000000 AO.ADD : Active=16CA1CB8 Prio= 6
           Obj Dic: 16CA1CB8->&l_table
           Fun Dic: 141E0006->&QHsm_top
           Fun Dic: 12DA00C9->&Table_initial
           Fun Dic: 12DA020B->&Table_serving
           Sig Dic: 00000008,Obj=16CA1CB8 ->HUNGRY_SIG
0000000000 AO.SUB : Active=l_table Sig=DONE_SIG
0000000000 AO.SUB : Active=l_table Sig=TERMINATE_SIG
           Q_INIT : Obj=l_table Source=QHsm_top Target=Table_serving
0000000000 ==>Init: Obj=l_table New=Table_serving
0000070346 QF_isrE: IsrNest= 1, CurrPrio=255
           TICK   : Ctr=         1
0000070367 QF_isrX: IsrNest= 1, CurrPrio=255
0000135566 QF_isrE: IsrNest= 1, CurrPrio=255
           TICK   : Ctr=         2
0000135581 QF_isrX: IsrNest= 1, CurrPrio=255
. . . . .
0000461783 QF_isrE: IsrNest= 1, CurrPrio=255
           TICK   : Ctr=         7
           TE.ADRM: Obj=l_philo[1].timeEvt Act=l_philo[1]
0000461797 TE.POST: Obj=l_philo[1].timeEvt Sig=TIMEOUT_SIG Act=l_philo[1]
0000461808 AO.FIFO: Obj=l_philo[1] Evt(Sig=TIMEOUT_SIG, Pool=0, Ref= 0)
>          Queue(nUsed=  5, nMax=  5)
0000461824 QF_isrX: IsrNest= 1, CurrPrio=255
0000461836 AO.GETL: Active= l_philo[1] Evt(Sig=TIMEOUT_SIG, Pool=0, Ref= 0)
0000461850 NEW    : Evt(Sig=HUNGRY_SIG, size=    3)
0000461862 MP.GET : Obj=l_smlPoolSto nFree=   9 nMin=   9
0000461874 AO.FIFO: Obj=l_table Evt(Sig=HUNGRY_SIG, Pool=1, Ref= 0)
>          Queue(nUsed=  5, nMax=  5)
0000461886 AO.GETL: Active= l_table Evt(Sig=HUNGRY_SIG, Pool=1, Ref= 1)
0000461906 NEW    : Evt(Sig=EAT_SIG, size=    3)
\endverbatim

The QS trace log shown in the listing above contains quite detailed
information, because most QS records are enabled (are not blocked in the QS
filters). The following bullet items highlight the most interesting parts of
the trace and illustrate how you can interpret the trace data:

- The QS log always contains the QSPY application version number, the date and
time of the run, and all the options explicitly provided to the QSPY host
application.
- A log typically starts with the dictionary records that provide a mapping
between addresses of various objects in memory and their symbolic names. The
dictionary entries don't have timestamps.
- After the dictionaries, you see the active object initialization. For
example, the EQ.INIT record indicates event queue initialization with the
l_tableQueueSto buffer. After this the AO.ADD trace record you see adding the
Table object with priority 6. At this point, the time tick interrupt is not
configured, so all timestamps are 0000000000 (timestamps are always placed in
the first 8 columns).
- Active object initialization can contain dictionary entries for items that
are encapsulated within the active object. For example initialization of Table
inserts an object dictionary entry for \c l_table object and three function
dictionary entries for state handlers \c QHsm_top, \c Table_initial and
\c Table_serving. Finally, the top-most initial transition is taken from \c
QHsm_top to \c Table_serving.
- After the active object initialization, interrupts are enabled, and the
first Tick interrupt arrives at the timestamp 0000070346. You can find out the
type of the interrupt by the unique priority number. For example, the priority
of the Tick interrupt is 0xFF == 255.


\section QSPY_QEP QEP Trace Records

<TABLE SUMMARY="QEP Records" cellSpacing=4 cellPadding=1 border=0 width="95%">
  <TR bgColor="#c8cedc">
    <TD><B>Rec.\n Num.</B></TD>
    <TD><B>Rec.\n Enum.</B></TD>
    <TD><B>QSPY\n Abbrev.\n</B></TD>
    <TD><B>Comment</B></TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>0</TD>
    <TD>#QS_QEP_STATE_EMPTY</TD>
    <TD></TD>
    <TD></TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>1</TD>
    <TD>#QS_QEP_STATE_ENTRY</TD>
    <TD>Q_ENTRY</TD>
    <TD>a state was entered</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>2</TD>
    <TD>#QS_QEP_STATE_EXIT</TD>
    <TD>Q_EXIT</TD>
    <TD>a state was exited</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>3</TD>
    <TD>#QS_QEP_STATE_INIT</TD>
    <TD>Q_INIT</TD>
    <TD>an intial transition was taken in a state</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>4</TD>
    <TD>#QS_QEP_INIT_TRAN</TD>
    <TD>==>Init</TD>
    <TD>the top-most initial transition was taken</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>5</TD>
    <TD>#QS_QEP_INTERN_TRAN</TD>
    <TD>Intern</TD>
    <TD>an internal transition was taken</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>6</TD>
    <TD>#QS_QEP_TRAN</TD>
    <TD>==>Tran</TD>
    <TD>a regular transition was taken</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>7</TD>
    <TD>#QS_QEP_IGNORED</TD>
    <TD>Ignored</TD>
    <TD>an event was ignored (silently discarded)</TD>
  </TR>
</TABLE>

\section QSPY_QF QF Trace Records

<TABLE SUMMARY="QF Records" cellSpacing=4 cellPadding=1 border=0 width="95%">
  <TR bgColor="#c8cedc">
    <TD><B>Rec.\n Num.</B></TD>
    <TD><B>Rec.\n Enum.</B></TD>
    <TD><B>QSPY\n Abbrev.\n</B></TD>
    <TD><B>Comment</B></TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>10</TD>
    <TD>#QS_QF_ACTIVE_ADD</TD>
    <TD>ADD</TD>
    <TD>an AO has been added to QF (started)</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>11</TD>
    <TD>#QS_QF_ACTIVE_REMOVE</TD>
    <TD>REM</TD>
    <TD>an AO has been removed from QF (stopped)</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>12</TD>
    <TD>#QS_QF_ACTIVE_SUBSCRIBE</TD>
    <TD>SUB</TD>
    <TD>an AO subscribed to an event</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>13</TD>
    <TD>#QS_QF_ACTIVE_UNSUBSCRIBE</TD>
    <TD>USUB</TD>
    <TD>an AO unsubscribed to an event</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>14</TD>
    <TD>#QS_QF_ACTIVE_POST_FIFO</TD>
    <TD>AO.FIFO</TD>
    <TD>an event was posted (FIFO) directly to AO</TD>
  </TR>