The QSPY host application can also present the tracing data as a sequence diagram. To generate a Sequence file, you need to invoke QSPY with the -g [obj-list] command-line option.

The [obj-list] is a comma-separated list of objects shown in the desired sequence. The names in the list must correspond exactly to the object dictionaries produced by the Target. Examples of the valid -g options are shown below:

-g l_SysTick_Handler,Table::inst,Philo::inst[0],Philo::inst[1]
-g l_QF_onClockTick,TServer::inst

Additionally, the list could include a ? (question mark), which denotes System Border.

-g Table::inst,Philo::inst[0],Philo::inst[1],?
-g ?,l_QF_onClockTick,TServer::inst

Note: The Sequence diagram can show only information actually sent from the Target. Therefore, by adjusting QS filters you can control the kind of information displayed in the sequence.

The following QS trace records produce the most interesting output:

#QS_QF_ACTIVE_POST,
#QS_QF_ACTIVE_POST_ATTEMPT,
#QS_QF_ACTIVE_POST_LIFO,
#QS_QF_PUBLISH, and
#QS_QF_TICK.

Additional annotations of the sequence diagrams are also available if the following QS trace records are enabled:

#QS_QEP_TRAN,
#QS_QF_ACTIVE_DEFER,
#QS_QF_ACTIVE_RECALL, and
#QS_QF_ACTIVE_RECALL_ATTEMPT.

Sequence Elements

The main elements of the QSPY sequence diagram shown in the following sequence output are marked with the [xx] labels, which are explained below the listing.

Note: The sequence output generated by QSPY is a simple ASCII file, which you can browse even with the most basic text editor, or a web browser. No special tools are needed to view the sequence diagrams produced from your data.

[1]  -g ?,l_QF_onClockTick,TServer::inst

                +-------+-------+   +-------+-------+   +-------+-------+
[2]             |       ?       |   |l_QF_onClockTic|   | TServer::inst |
                +-------+-------+   +-------+-------+   +-------+-------+
[3]  3115372171         /                   |                   |
[4]  3127751904         *--NEW_REQUEST_SIG--+------------------>|
[5]  3127792184         /                   |               <receive>
     3144424365         /                   *--RECEIVED_SIG---->|
     3144429488         /                   |              <authorize>
     3177742936         /                   *--AUTHORIZED_SIG-->|
[6]  3177796020         /                   |                (RcallA)
     3177816231         /                   |                 <idle>
     3190753295         *--NEW_REQUEST_SIG--+------------------>|
     3190792988         /                   |               <receive>
     3200126862         *--NEW_REQUEST_SIG--+------------------>|
[7]  3200127346         /                   |                (Defer)
     3207429692         /                   *--RECEIVED_SIG---->|
     3207435638         /                   |              <authorize>
     3240835283         /                   *--AUTHORIZED_SIG-->|
[8]  3240884412         /                   |                   *<=NEW_REQUEST_SIG]
     3240884486         /                   |                (recall)
     3240902469         /                   |                 <idle>
     . . . . .         . . .              . . .                . . .

[1] The sequence diagram starts with repeating the -g [obj-list] option, so that you can conveniently copy-and-paste this option to run the same sequence again.

[2] Below that, you can see the header containing the boxes of participating objects from the [obj-list]. From each box descends a lifeline that runs vertically down the page and represents the ordering of exchanged events and other interesting occurrences involving the object.

Remarks: This first object in this particular sequence diagram, denoted as ‘?’, is The System Border Object explained below.
The names in the sequence diagram are truncated to the first 15 characters.
The sequence header is repeated every 100 lines of the sequence output.

[3] Each output line starts with the timestamp followed by the lifelines of all participating objects with event arrows or annotations.

[4] This line shows an event posting (with FIFO policy), which corresponds to the QS records #QS_QF_ACTIVE_POST and #QS_QF_ACTIVE_POST_ATTEMPT. The event source is marked with *, the event target is pointed to with > or <. The source and target are connected with a line *----->. The line is annotated with the signal of the posted event.

[5] This line shows a state change, which corresponds to the QS record #QS_QEP_TRAN. The lifeline of the object is annotated with the new state assumed by the object. The state-name is placed between < or >.

Remarks: This state annotation it shortened to better fit in the allotted space. For example, state names "MyStateMachine_active_123" (in C) or "MyStateMachine::active_123" (in C++) are displayed as <active_123>.

[6] This line shows an event recall, which corresponds to the QS records #QS_QF_ACTIVE_RECALL, and #QS_QF_ACTIVE_RECALL_ATTEMPT. The lifeline of the object is annotated with (Recall) or (RcallA), respectively.

[7] This line shows an event deferral, which corresponds to the QS record #QS_QF_ACTIVE_DEFER. The lifeline of the object is annotated with (Defer).

[8] This line shows an event self-posting with LIFO policy, which corresponds to the QS record #QS_QF_ACTIVE_POST_LIFO. The event source/target is marked with *<; the LIFO policy of the event posting is denoted by the = line right before the signal of the posted event.

The System Border Object

As mentioned before, the [obj-list] that specifies objects participating in the sequence might include ? (question mark), which denotes System Border. The system border is the "environment" that can produce and consume events. The "System Border" denotes possibly multiple objects that are not explicitly listed in the [obj-list], including even objects without object dictionaries. The sequence diagram in the previous section shows the "System Border", labeled as ? and lifeline shown as //////.

Note: You can place the "System Border" (the ?) anywhere in the [obj-list]. However, it is customary to place it either as the very first or the very last object in the list, as shown in the sequence diagram below:

The listing below shows a sequence output (.seq) generated from the Deferred Event example application with the following -g option:

-g ?,l_QF_onClockTick,TServer::inst

More Involved Example

The listing below shows an example of a more involved sequence diagram output (.seq) generated from the Dining Philosophers Problem (DPP) application with the following -g option:

-g l_SysTick_Handler,Table::inst,Philo::inst[0],Philo::inst[1],Philo::inst[2],Philo::inst[3],Philo::inst[4]

In addition to the elements described above, this sequence diagram illustrates event publishing, which corresponds to the #QS_QF_PUBLISH trace record. The event multicasting is represented as a horizontal line . . . ., with the event source marked as *.

-g l_SysTick_Handler,Table::inst,Philo::inst[0],Philo::inst[1],Philo::inst[2],Philo::inst[3],Philo::inst[4]

           +-------+-------+   +-------+-------+   +-------+-------+   +-------+-------+   +-------+-------+   +-------+-------+   +-------+-------+
           |l_SysTick_Handl|   |  Table::inst  |   |Philo::inst[0] |   |Philo::inst[1] |   |Philo::inst[2] |   |Philo::inst[3] |   |Philo::inst[4] |
           +-------+-------+   +-------+-------+   +-------+-------+   +-------+-------+   +-------+-------+   +-------+-------+   +-------+-------+
0000042339 . . . . * .SERVE_SIG. . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . .
0000042896         *--SERVE_SIG------->|                   |                   |                   |                   |                   |
0001070723         *--TIMEOUT_SIG------+-------------------+-------------------+-------------------+-------------------+------------------>|
0001075362         |                   |<------------------+-------------------+-------------------+-------------------+-------HUNGRY_SIG--*
0001079065 . . . . | . . . . . . . . . * .EAT_SIG. . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . .
0001079975         |                   *--EAT_SIG----------+-------------------+-------------------+-------------------+------------------>|
0001080774         |                   *--EAT_SIG----------+-------------------+-------------------+------------------>|                   |
0001081583         |                   *--EAT_SIG----------+-------------------+------------------>|                   |                   |
0001082382         |                   *--EAT_SIG----------+------------------>|                   |                   |                   |
0001083181         |                   *--EAT_SIG--------->|                   |                   |                   |                   |
0001087412         |                   |                   |                   |                   |                   |                <hungry>
0001091293         |                   |                   |                   |                   |                   |                <eating>
0001762885         *--TIMEOUT_SIG------+------------------>|                   |                   |                   |                   |
0001767416         |                   |<------HUNGRY_SIG--*                   |                   |                   |                   |
0001772368         |                   |                <hungry>               |                   |                   |                   |
0002097460 . . . . * .PAUSE_SIG. . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . .
0002098016         *--PAUSE_SIG------->|                   |                   |                   |                   |                   |
0002101049         |                <paused>               |                   |                   |                   |                   |
0002140275         *--TIMEOUT_SIG------+-------------------+-------------------+------------------>|                   |                   |
0002144842         |                   |<------------------+-------------------+-------HUNGRY_SIG--*                   |                   |
0002149765         |                   |                   |                   |                <hungry>               |                   |
0002245145         *--TIMEOUT_SIG------+-------------------+------------------>|                   |                   |                   |
0002249676         |                   |<------------------+-------HUNGRY_SIG--*                   |                   |                   |
0002254599         |                   |                   |                <hungry>               |                   |                   |
0003104906         *--TIMEOUT_SIG------+-------------------+-------------------+-------------------+------------------>|                   |
0003109447         |                   |<------------------+-------------------+-------------------+-------HUNGRY_SIG--*                   |
0003114370         |                   |                   |                   |                   |                <hungry>               |
0005013277         *--TIMEOUT_SIG------+-------------------+-------------------+-------------------+-------------------+------------------>|
0005016745 . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . . . DONE_SIG. * . . .
0005017655         |                   |<------------------+-------------------+-------------------+-------------------+---------DONE_SIG--*
0005025076         |                   |                   |                   |                   |                   |                <thinking>
0007760487         *--TIMEOUT_SIG------+-------------------+-------------------+-------------------+-------------------+------------------>|
0007764998         |                   |<------------------+-------------------+-------------------+-------------------+-------HUNGRY_SIG--*
0007769921         |                   |                   |                   |                   |                   |                <hungry>
0011827861 . . . . * .SERVE_SIG. . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . .
0011828417         *--SERVE_SIG------->|                   |                   |                   |                   |                   |
0011832381 . . . . | . . . . . . . . . * .EAT_SIG. . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . .
0011833291         |                   *--EAT_SIG----------+-------------------+-------------------+-------------------+------------------>|
0011834089         |                   *--EAT_SIG----------+-------------------+-------------------+------------------>|                   |
0011834887         |                   *--EAT_SIG----------+-------------------+------------------>|                   |                   |
0011835685         |                   *--EAT_SIG----------+------------------>|                   |                   |                   |
0011836483         |                   *--EAT_SIG--------->|                   |                   |                   |                   |
0011839510 . . . . | . . . . . . . . . * .EAT_SIG. . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . .
0011840421         |                   *--EAT_SIG----------+-------------------+-------------------+-------------------+------------------>|
0011841199         |                   *--EAT_SIG----------+-------------------+-------------------+------------------>|                   |
0011841977         |                   *--EAT_SIG----------+-------------------+------------------>|                   |                   |
0011842755         |                   *--EAT_SIG----------+------------------>|                   |                   |                   |
0011843533         |                   *--EAT_SIG--------->|                   |                   |                   |                   |
0011846001         |               <serving>               |                   |                   |                   |                   |
0011864225         |                   |                   |                   |                <eating>               |                   |
0011874191         |                   |                <eating>               |                   |                   |                   |
0015268086         *--TIMEOUT_SIG------+-------------------+-------------------+------------------>|                   |                   |
0015271590 . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . * .DONE_SIG . . . . | . . . . . . . . . | . . .
0015272500         |                   |<------------------+-------------------+---------DONE_SIG--*                   |                   |
0015276635 . . . . | . . . . . . . . . * .EAT_SIG. . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . .
0015277545         |                   *--EAT_SIG----------+-------------------+-------------------+-------------------+------------------>|
0015278343         |                   *--EAT_SIG----------+-------------------+-------------------+------------------>|                   |
0015279141         |                   *--EAT_SIG----------+-------------------+------------------>|                   |                   |
0015279939         |                   *--EAT_SIG----------+------------------>|                   |                   |                   |
0015280737         |                   *--EAT_SIG--------->|                   |                   |                   |                   |
0015289641         |                   |                   |                   |                   |                <eating>               |
0015294035         |                   |                   |                   |               <thinking>              |                   |
0015540732         *--TIMEOUT_SIG------+------------------>|                   |                   |                   |                   |
0015544272 . . . . | . . . . . . . . . | . . . . . . . . . * .DONE_SIG . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . .
0015545182         |                   |<--------DONE_SIG--*                   |                   |                   |                   |
0015549317 . . . . | . . . . . . . . . * .EAT_SIG. . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . .
0015550227         |                   *--EAT_SIG----------+-------------------+-------------------+-------------------+------------------>|
0015551025         |                   *--EAT_SIG----------+-------------------+-------------------+------------------>|                   |
0015551823         |                   *--EAT_SIG----------+-------------------+------------------>|                   |                   |
0015552621         |                   *--EAT_SIG----------+------------------>|                   |                   |                   |
0015553419         |                   *--EAT_SIG--------->|                   |                   |                   |                   |
0015567245         |                   |                   |                <eating>               |                   |                   |
0015571639         |                   |               <thinking>              |                   |                   |                   |

QSPY UDP InterfaceQSPY MATLAB Support