qspy_ref.txt

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

  <TR bgColor="#c0c0c0">
    <TD>15</TD>
    <TD>#QS_QF_ACTIVE_POST_LIFO</TD>
    <TD>AO.LIFO</TD>
    <TD>an event was posted (LIFO) directly to AO</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>16</TD>
    <TD>#QS_QF_ACTIVE_GET</TD>
    <TD>AO.GET</TD>
    <TD>AO got an event and its queue is still not empty</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>17</TD>
    <TD>#QS_QF_ACTIVE_GET_LAST</TD>
    <TD>AO.GETL</TD>
    <TD>AO got an event and its queue is empty</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>18</TD>
    <TD>#QS_QF_EQUEUE_INIT</TD>
    <TD>EQ.INIT</TD>
    <TD>an event queue was initialized</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>19</TD>
    <TD>#QS_QF_EQUEUE_POST_FIFO</TD>
    <TD>EQ.FIFO</TD>
    <TD>an event was posted (FIFO) to a raw queue</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>20</TD>
    <TD>#QS_QF_EQUEUE_POST_LIFO</TD>
    <TD>EQ.LIFO</TD>
    <TD>an event was posted (LIFO) to a raw queue</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>21</TD>
    <TD>#QS_QF_EQUEUE_GET</TD>
    <TD>EQ.GET</TD>
    <TD>get an event and queue still not empty</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>22</TD>
    <TD>#QS_QF_EQUEUE_GET_LAST</TD>
    <TD>EQ.GETL</TD>
    <TD>get the last event from the queue</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>23</TD>
    <TD>#QS_QF_MPOOL_INIT</TD>
    <TD>MP.INIT</TD>
    <TD>a memory pool was initialized</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>24</TD>
    <TD>#QS_QF_MPOOL_GET</TD>
    <TD>MP.GET</TD>
    <TD>a memory block was removed from a memory pool</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>25</TD>
    <TD>#QS_QF_MPOOL_PUT</TD>
    <TD>MP.PUT</TD>
    <TD>a memory block was returned to a memory pool</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>26</TD>
    <TD>#QS_QF_PUBLISH</TD>
    <TD>PUBLISH</TD>
    <TD>an event was published</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>27</TD>
    <TD>#reserved</TD>
    <TD></TD>
    <TD></TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>28</TD>
    <TD>#QS_QF_NEW</TD>
    <TD>NEW</TD>
    <TD>new event creation</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>29</TD>
    <TD>#QS_QF_GC_ATTEMPT</TD>
    <TD>GC-ATT</TD>
    <TD>garbage collection attempt</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>30</TD>
    <TD>#QS_QF_GC</TD>
    <TD>GC</TD>
    <TD>garbage collection performed</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>31</TD>
    <TD>#QS_QF_TICK</TD>
    <TD>TICK</TD>
    <TD>QF_tick() was called</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>32</TD>
    <TD>#QS_QF_TIMEEVT_ARM</TD>
    <TD>TE.ARM</TD>
    <TD>a time event was armed</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>33</TD>
    <TD>#QS_QF_TIMEEVT_AUTO_DISARM</TD>
    <TD>TE.ADRM</TD>
    <TD>a time event expired and was disarmed</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>34</TD>
    <TD>#QS_QF_TIMEEVT_DISARM_ATTEMPT</TD>
    <TD>TE.DATT</TD>
    <TD>attempt to disarmed a disarmed tevent</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>35</TD>
    <TD>#QS_QF_TIMEEVT_DISARM</TD>
    <TD>TE.DARM</TD>
    <TD>true disarming of an armed time event</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>36</TD>
    <TD>#QS_QF_TIMEEVT_REARM</TD>
    <TD>TE.RARM</TD>
    <TD>rearming of a time event</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>37</TD>
    <TD>#QS_QF_TIMEEVT_POST</TD>
    <TD>TE.POST</TD>
    <TD>a time event posted itself directly to an AO</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>38</TD>
    <TD>#reserved</TD>
    <TD></TD>
    <TD></TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>39</TD>
    <TD>#QS_QF_INT_LOCK</TD>
    <TD>QF_intL</TD>
    <TD>interrupts were locked</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>40</TD>
    <TD>#QS_QF_INT_UNLOCK</TD>
    <TD>QF_intU</TD>
    <TD>interrupts were unlocked</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>42</TD>
    <TD>#QS_QF_ISR_ENTRY</TD>
    <TD>QF_isrE</TD>
    <TD>an ISR was entered</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>42</TD>
    <TD>#QS_QF_ISR_EXIT</TD>
    <TD>QF_isrX</TD>
    <TD>an ISR was exited</TD>
  </TR>
</TABLE>

\section QSPY_QK QK Trace Records

<TABLE SUMMARY="QK 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>50</TD>
    <TD>#QS_QK_MUTEX_LOCK</TD>
    <TD>QK_muxL</TD>
    <TD>the QK mutex was locked</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>51</TD>
    <TD>#QS_QK_MUTEX_UNLOCK</TD>
    <TD>QK_muxU</TD>
    <TD>the QK mutex was unlocked</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>52</TD>
    <TD>#QS_QK_SCHEDULE</TD>
    <TD>QK_sche</TD>
    <TD>the QK scheduled a new task to execute</TD>
  </TR>
</TABLE>

\section QSPY_MISC Miscellaneous Trace Records

<TABLE SUMMARY="Miscellaneous 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>60</TD>
    <TD>#QS_SIG_DICTIONARY</TD>
    <TD>Sig Dic</TD>
    <TD>signal dictionary entry</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>61</TD>
    <TD>#QS_OBJ_DICTIONARY</TD>
    <TD>Obj Dic</TD>
    <TD>object dictionary entry</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>62</TD>
    <TD>#QS_FUN_DICTIONARY</TD>
    <TD>Fun Dic</TD>
    <TD>function dictionary entry</TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>63</TD>
    <TD>#QS_ASSERT</TD>
    <TD>!ASSERT</TD>
    <TD>Assertion fired</TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>...</TD>
    <TD></TD>
    <TD></TD>
    <TD></TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>70</TD>
    <TD>#QS_USER</TD>
    <TD>UserXXX</TD>
    <TD>the first record available for user QS records</TD>
  </TR>
</TABLE>


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

/**
\page qspy_matlab QSPY MATLAB Inteface

The QSPY host application can also export trace data to MATLAB&reg;, which is
a popular numerical computing environment and a high-level technical
programming language. Created by The MathWorks, Inc., MATLAB allows easy
manipulation and plotting of data represented as matrices.

The following sections provide a reference manual for all 11 the MATLAB
matrices generated by the \c qspy.m script. By MATLAB convention, the
different variables are put into columns, allowing observations to vary down
through the rows. Therefore, a data set consisting of twenty four time samples
of six variables is stored in a matrix of size 24-by-6. The pound sign '#' in
a given cell of the matrix represents data available from the target. Other
values, represent data added by the \c qspy.m script to allow unambiguous
identification of the trace records.

- \ref MATLAB_Q_STATE
- \ref MATLAB_Q_ACTIVE
- \ref MATLAB_Q_EQUEUE
- \ref MATLAB_Q_MPOOL
- \ref MATLAB_Q_NEW
- \ref MATLAB_Q_PUB
- \ref MATLAB_Q_TIME
- \ref MATLAB_Q_INT
- \ref MATLAB_Q_ISR
- \ref MATLAB_Q_MUTEX
- \ref MATLAB_Q_SCHED


\section MATLAB_Q_STATE Q_STATE Matrix

The N-by-6 \c Q_STATE matrix stores all QS records generated by the QEP
hierarchical event processor and pertaining to all the state machines in the
system. The following table summarizes how the QS records are stored in the
matrix:

<TABLE SUMMARY="Q_STATE Matrix" cellSpacing=4 cellPadding=1 border=0
ALIGN="center">
  <TR bgColor="#c8cedc" ALIGN="center">
    <TD><B>&nbsp;MATLAB index --&gt;</B></TD>
    <TD><B>1</B></TD>
    <TD><B>2</B></TD>
    <TD><B>3</B></TD>
    <TD><B>4</B></TD>
    <TD><B>5</B></TD>
    <TD><B>6</B></TD>
  </TR>

  <TR bgColor="#f0f0f0" ALIGN="center">
    <TD><B>QS Record\n |\n V</B></TD>
    <TD><B>Time\n Stamp</B></TD>
    <TD><B>Signal</B></TD>
    <TD><B>State\n Machine\n Object</B></TD>
    <TD><B>Source\n State</B></TD>
    <TD><B>New\n State</B></TD> <TD><B>Event\n Hanlder</B></TD>
  </TR>

  <TR bgColor="#c0c0c0" ALIGN="center">
    <TD>\c #QS_QEP_STATE_ENTRY</TD>
    <TD>NaN</TD>
    <TD>1</TD>
    <TD>#(2)</TD>
    <TD>#</TD>
    <TD>NaN</TD>
    <TD>1</TD>
  </TR>

  <TR bgColor="#f0f0f0" ALIGN="center">
    <TD>\c #QS_QEP_STATE_EXIT</TD>
    <TD>NaN</TD>
    <TD>2</TD>
    <TD>#(2)</TD>
    <TD>#</TD>
    <TD>NaN</TD>
    <TD>1</TD>
  </TR>

  <TR bgColor="#c0c0c0" ALIGN="center">
    <TD>\c #QS_QEP_STATE_INIT</TD>
    <TD>NaN</TD>
    <TD>3</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>1</TD>
  </TR>

  <TR bgColor="#f0f0f0" ALIGN="center">
    <TD>\c #QS_QEP_INIT_TRAN</TD>
    <TD>#</TD>
    <TD>3</TD>
    <TD>#(2)</TD>
    <TD>NaN</TD>
    <TD>#</TD>
    <TD>1</TD>
  </TR>

  <TR bgColor="#c0c0c0" ALIGN="center">
    <TD>\c #QS_QEP_INTERN_TRAN</TD>
    <TD>#</TD>
    <TD>#(1)</TD>
    <TD>#(2)</TD>
    <TD>#</TD>
    <TD>NaN</TD>
    <TD>1</TD>
  </TR>

  <TR bgColor="#f0f0f0" ALIGN="center">
    <TD>\c #QS_QEP_TRAN</TD>
    <TD>#</TD>
    <TD>#(1)</TD>
    <TD>#(2)</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>1</TD>
  </TR>

  <TR bgColor="#c0c0c0" ALIGN="center">
    <TD>\c #QS_QEP_IGNORED</TD>
    <TD>#</TD>
    <TD>#(1)</TD>
    <TD>#(2)</TD>
    <TD>#</TD>
    <TD>NaN</TD>
    <TD>0</TD>
  </TR>
</TABLE>
(1) The valid USER signal is &gt; 3

(2) Per inheritance, an active object is a state machine object as well



The following criteria (index matrices in MATLAB) unambiguously select the QS
records from the \c Q_STATE matrix:

<TABLE SUMMARY="Q_STATE records" cellSpacing=4 cellPadding=1 border=0
ALIGN="center">
  <TR bgColor="#c8cedc" ALIGN="center">
    <TD><B>QS Record</B></TD>
    <TD><B>MATLAB Index Matrix</B></TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>\c #QS_QEP_STATE_ENTRY</TD>
    <TD><TT>Q_STATE(:,2) == 1</TT></TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>\c #QS_QEP_STATE_EXIT</TD>
    <TD><TT>Q_STATE(:,2) == 2</TT></TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>\c #QS_QEP_STATE_INIT</TD>
    <TD><TT>Q_STATE(:,2) == 3</TT></TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>\c #QS_QEP_INIT_TRAN</TD>
    <TD><TT>isnan(Q_STATE(:,4))</TT></TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>\c #QS_QEP_INTERN_TRAN</TD>
    <TD><TT>Q_STATE(:,2) &gt; 3 & isnan(Q_STATE(:,5))</TT></TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>\c #QS_QEP_TRAN</TD>
    <TD><TT>Q_STATE(:,2) > &gt; & ~isnan(Q_STATE(:,5))</TT></TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>\c #QS_QEP_IGNORED</TD>
    <TD><TT>~Q_STATE(:,6)</TT></TD>
  </TR>

</TABLE>

For example, the following MATLAB plot shows the timing diagrams for all
Philo state machines in the DPP example application made by the
\c philo_timing.m script located in the directory \c \\tools\\qspy\\matlab\\
(see Section \ref files_page). The vertical axis represents states "thinking"
(lowest), "hungry" (middle) and "eating" (top) states.