QTools 6.9.3
QSPY Sequence Output

Table of Contents

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 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 -g l_SysTick_Handler,Table::inst,Philo::inst[0],Philo::inst[1]
  • -g l_QF_onClockTick,TServer::inst

Additionally, the list could include ? (questionmark), which denotes System Border.

  • -g -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:

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

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         /                   |           <TServer::receiv>
     3144424365         /                   *--RECEIVED_SIG---->|
     3144429488         /                   |           <TServer::author>
     3177742936         /                   *--AUTHORIZED_SIG-->|
[6]  3177796020         /                   |                (RcallA)
     3177816231         /                   |            <TServer::idle>
     3190753295         *--NEW_REQUEST_SIG--+------------------>|
     3190792988         /                   |           <TServer::receiv>
     3200126862         *--NEW_REQUEST_SIG--+------------------>|
[7]  3200127346         /                   |                (Defer)
     3207429692         /                   *--RECEIVED_SIG---->|
     3207435638         /                   |           <TServer::author>
     3240835283         /                   *--AUTHORIZED_SIG-->|
[8]  3240884412         /                   |                   *<=NEW_REQUEST_SIG]
     3240884486         /                   |                (RCall)
     3240902469         /                   |            <TServer::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 a given object.

NOTE: This first object in this particular sequence diagram, denoted as‘?’, is the The System Border Object explained below.

NOTE: The names in the sequence diagram are truncated to the first 15 characters.

NOTE: The sequence header is repeated every 100 lines of the sequence output.

3
Each output line starts with the timestamp followed by the life-lines of all participating objects with event arrows or annotations.
4
This line shows a 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 new state assumed by the object. The state-name is placed between < or >.
6
This line shows a 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 (Rcall) or (RcallA), respectively.
7
This line shows a 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 a 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 ? (questionmark), 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 life-line 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 the 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         |                   |                   |                   |                   |                   |            <Philo::hungry>
0001091293         |                   |                   |                   |                   |                   |            <Philo::eating>
0001762885         *--TIMEOUT_SIG------+------------------>|                   |                   |                   |                   |
0001767416         |                   |<------HUNGRY_SIG--*                   |                   |                   |                   |
0001772368         |                   |            <Philo::hungry>            |                   |                   |                   |
0002097460 . . . . * .PAUSE_SIG. . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . .
0002098016         *--PAUSE_SIG------->|                   |                   |                   |                   |                   |
0002101049         |            <Table::paused>            |                   |                   |                   |                   |
0002140275         *--TIMEOUT_SIG------+-------------------+-------------------+------------------>|                   |                   |
0002144842         |                   |<------------------+-------------------+-------HUNGRY_SIG--*                   |                   |
0002149765         |                   |                   |                   |            <Philo::hungry>            |                   |
0002245145         *--TIMEOUT_SIG------+-------------------+------------------>|                   |                   |                   |
0002249676         |                   |<------------------+-------HUNGRY_SIG--*                   |                   |                   |
0002254599         |                   |                   |            <Philo::hungry>            |                   |                   |
0003104906         *--TIMEOUT_SIG------+-------------------+-------------------+-------------------+------------------>|                   |
0003109447         |                   |<------------------+-------------------+-------------------+-------HUNGRY_SIG--*                   |
0003114370         |                   |                   |                   |                   |            <Philo::hungry>            |
0005013277         *--TIMEOUT_SIG------+-------------------+-------------------+-------------------+-------------------+------------------>|
0005016745 . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . . . . . . . . | . . . . DONE_SIG. * . . .
0005017655         |                   |<------------------+-------------------+-------------------+-------------------+---------DONE_SIG--*
0005025076         |                   |                   |                   |                   |                   |           <Philo::thinking>
0007760487         *--TIMEOUT_SIG------+-------------------+-------------------+-------------------+-------------------+------------------>|
0007764998         |                   |<------------------+-------------------+-------------------+-------------------+-------HUNGRY_SIG--*
0007769921         |                   |                   |                   |                   |                   |            <Philo::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         |            <Table::serving>           |                   |                   |                   |                   |
0011864225         |                   |                   |                   |            <Philo::eating>            |                   |
0011874191         |                   |            <Philo::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         |                   |                   |                   |                   |            <Philo::eating>            |
0015294035         |                   |                   |                   |           <Philo::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         |                   |                   |            <Philo::eating>            |                   |                   |
0015571639         |                   |           <Philo::thinking>           |                   |                   |                   |

Next: QSPY MATLAB Support