QSPY Sequence Diagram Generation

share on: 
Share on reddit
Share on linkedin
Share on twitter
Originally published on:  
2021-01-25
Last updated on: 
QSPY sequence diagram generation
Table of Contents
Tags:   

The QSPY host application can now generate sequence diagrams. This new feature replaces the previous support for MscGen and is no longer reliant on any such external tools. 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.

How to Generate Sequence Output

To generate a sequence output to a file, you need to invoke QSPY with the -g [obj-list] command-line option. The option parameter [obj-list] is a comma-separated list of objects you wish to 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 l_SysTick_Handler,Table::inst,Philo::inst[0],Philo::inst[1]
  • -g l_QF_onClockTick,TServer::inst

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
  • 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
  • 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.

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

                +-------+-------+   +-------+-------+   +-------+-------+
[2]             |       ?       |   |l_QF_onClockTic|   | TServer::inst |
                +-------+-------+   +-------+-------+   +-------+-------+
[3]  3115372171         /                   |                   |
[4]  3127751904         *--NEW_REQUEST_SIG--+------------------>|
[5]  3127792184         /                   |           
     3144424365         /                   *--RECEIVED_SIG---->|
     3144429488         /                   |           
     3177742936         /                   *--AUTHORIZED_SIG-->|
[6]  3177796020         /                   |                (RcallA)
     3177816231         /                   |            
     3190753295         *--NEW_REQUEST_SIG--+------------------>|
     3190792988         /                   |           
     3200126862         *--NEW_REQUEST_SIG--+------------------>|
[7]  3200127346         /                   |                (Defer)
     3207429692         /                   *--RECEIVED_SIG---->|
     3207435638         /                   |           
     3240835283         /                   *--AUTHORIZED_SIG-->|
[8]  3240884412         /                   |                   *<=NEW_REQUEST_SIG]
     3240884486         /                   |                (RCall)
     3240902469         /                   |            
     . . . . .         . . .              . . .                . . .
[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 *.
QSPY sequence diagram output for DPP example