QSPY MATLAB Support

Table of Contents

• Q_STATE Matrix
• Q_ACTIVE Matrix
• Q_EQUEUE Matrix
• Q_MPOOL Matrix
• Q_NEW Matrix
• Q_PUB Matrix
• Q_TIME Matrix
• Q_INT Matrix
• Q_ISR Matrix
• Q_MUTEX Matrix
• Q_SCHED Matrix

The QSPY host application can also export trace data to MATLAB®, 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.

Note

The QSPY MATLAB interface is also compatible with the GNU Octave environment, which is an open source alternative to MATLAB and is compatible with the QSPY MATLAB interface described below.

The following sections provide a reference manual for all 11 the MATLAB matrices generated by the 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 qspy.m script to allow unambiguous identification of the trace records.

• Q_STATE Matrix
• Q_ACTIVE Matrix
• Q_EQUEUE Matrix
• Q_MPOOL Matrix
• Q_NEW Matrix
• Q_PUB Matrix
• Q_TIME Matrix
• Q_INT Matrix
• Q_ISR Matrix
• Q_MUTEX Matrix
• Q_SCHED Matrix

Q_STATE Matrix

The N-by-6 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:

MATLAB index –>	1	2	3	4	5	6
QS Record | V	Time Stamp	Signal	State Machine Object	Source State	New State	Event Hanlder
QS_QEP_STATE_ENTRY	NaN	1	#(2)	#	NaN	1
QS_QEP_STATE_EXIT	NaN	2	#(2)	#	NaN	1
QS_QEP_STATE_INIT	NaN	3	#	#	#	1
QS_QEP_INIT_TRAN	#	3	#(2)	NaN	#	1
QS_QEP_INTERN_TRAN	#	#(1)	#(2)	#	NaN	1
QS_QEP_TRAN	#	#(1)	#(2)	#	#	1
QS_QEP_IGNORED	#	#(1)	#(2)	#	NaN	0
QS_QEP_DISPATCH	#	#(1)	#(2)	#	NaN	0
QS_QEP_UNHANDLED	NaN	#(1)	#(2)	#	NaN	0

(1) The valid USER signal is > 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 Q_STATE matrix:

QS Record	MATLAB Index Matrix
QS_QEP_STATE_ENTRY	Q_STATE(:,2) == 1
QS_QEP_STATE_EXIT	Q_STATE(:,2) == 2
QS_QEP_STATE_INIT	Q_STATE(:,2) == 3
QS_QEP_INIT_TRAN	isnan(Q_STATE(:,4))
QS_QEP_INTERN_TRAN	Q_STATE(:,2) > 3 & isnan(Q_STATE(:,5))
QS_QEP_TRAN	Q_STATE(:,2) > > & ~isnan(Q_STATE(:,5))
QS_QEP_IGNORED	~Q_STATE(:,6)

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

Timing diagrams for all Philo state machines.

Q_ACTIVE Matrix

The N-by-5 Q_ACTIVE matrix stores QS records pertaining to adding/removing active objects and subscribing/unsubscribing to events from active objects. The following table summarizes how the QS records are stored in the matrix:

MATLAB index –>	1	2	3	4	5
QS Record | V	Time Stamp	Signal	Active Object	QF Priority	Delta
QS_QF_ACTIVE_SUBSCRIBE	#	#	#	NaN	+1
QS_QF_ACTIVE_UNSUBSCRIBE	#	#	#	NaN	-1

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

QS Record	MATLAB Index Matrix
QS_QF_ACTIVE_SUBSCRIBE	isnan(Q_ACTIVE(:,4)) & Q_ACTIVE(:,5) > 0
QS_QF_ACTIVE_UNSUBSCRIBE	isnan(Q_ACTIVE(:,4)) & Q_ACTIVE(:,5) < 0

Q_EQUEUE Matrix

The N-by-10 Q_EQUEUE matrix stores QS records pertaining to queuing events in the QF. Both the active object event queues and the "raw" thread-safe queues are included. The 'nUsed' field denotes the current number of used entries in the queue. The 'Maximum nUsed' filed denotes the maximum number of used entries since initialization (high watermark). Both fields contain the number of used entries in the queues ring-buffer plus one, to account for the extra location at the front of the queue. The following table summarizes how the QS records are stored in the matrix:

MATLAB index –>	1	2	3	4	5	6	7	8	9	10
QS Record | V	Time Stamp	Sender	Event Queue (1)	nFree	Minimum Used	Signal	Pool ID	Ref. Count	LIFO	Delta
QS_QF_ACTIVE_POST	#	#	#	#	#	#	#	#	0	+1
QS_QF_ACTIVE_POST_LIFO	#	#	#	#	#	#	#	#	1	+1
QS_QF_ACTIVE_GET	#	NaN	#	#	NaN	#	#	#	0	-1
QS_QF_ACTIVE_GET_LAST	#	NaN	#	NaN	NaN	#	#	#	0	-1
QS_QF_EQUEUE_POST	#	NaN	#	#	#	#	1	#	0	+1
QS_QF_EQUEUE_POST_LIFO	#	NaN	#	#	#	#	#	#	1	+1
QS_QF_EQUEUE_GET	#	NaN	#	#	#	#	#	#	0	-1
QS_QF_EQUEUE_GET_LAST	#	NaN	#	NaN	NaN	#	#	#	0	-1

(1) This field (index 3) is actually the pointer to the ring buffer of the queue.

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

QS Record	MATLAB Index Matrix
QS_QF_ACTIVE_POST	Q_EQUEUE(:,3) == <active obj> & ~Q_EQUEUE(:,9) & Q_EQUEUE(:,10) > 0
QS_QF_ACTIVE_POST_LIFO	Q_EQUEUE(:,3) == <active obj> & Q_EQUEUE(:,9) & Q_EQUEUE(:,10) > 0
QS_QF_ACTIVE_GET	Q_EQUEUE(:,3) == <active obj> & ~isnan(Q_EQUEUE(:,4) & Q_EQUEUE(:,10) < 0
QS_QF_ACTIVE_GET_LAST	Q_EQUEUE(:,3) == <active obj> & isnan(Q_EQUEUE(:,4) & Q_EQUEUE(:,10) < 0
QS_QF_EQUEUE_POST	Q_EQUEUE(:,3) == <raw queue> & ~Q_EQUEUE(:,9) & Q_EQUEUE(:,10) > 0
QS_QF_EQUEUE_POST_LIFO	Q_EQUEUE(:,3) == <raw queue> & Q_EQUEUE(:,9) & Q_EQUEUE(:,10) > 0
QS_QF_EQUEUE_GET	Q_EQUEUE(:,3) == <raw queue> & ~isnan(Q_EQUEUE(:,4) & Q_EQUEUE(:,10) < 0
QS_QF_EQUEUE_GET_LAST	Q_EQUEUE(:,3) == <raw queue> & isnan(Q_EQUEUE(:,4) & Q_EQUEUE(:,10) < 0

Q_MPOOL Matrix

The N-by-5 Q_MPOOL matrix stores QS records pertaining to memory pools in the QF. The 'nFree' field denotes the current number of free blocks in the event pool. The 'Minimum nFree' filed denotes the minimal number of free blocks since initialization (low watermark). The following table summarizes how the QS records are stored in the matrix:

MATLAB index –>	1	2	3	4	5
QS Record | V	Time Stamp	Pool Object	nFree	Minimal nFree	Delta
QS_QF_MPOOL_GET	#	#	#	#	-1
QS_QF_MPOOL_PUT	#	#	#	NaN	+1

The cumulative sum over the 'Delta' column should not have any long-time trends, because this would indicate a leak from the pool. The following picture shows the plot for the test data.

Plot stairs(Q_MPOOL(:,1), cumsum(Q_MPOOL(:,5)))

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

QS Record	MATLAB Index Matrix
QS_QF_MPOOL_GET	Q_MPOOL(:,5) < 0
QS_QF_MPOOL_PUT	Q_MPOOL(:,5) > 0

Q_NEW Matrix

The N-by-6 Q_NEW matrix stores QS records pertaining to dynamic event allocation and automatic event recycling (garbage collection) in the QF. The following table summarizes how the QS records are stored in the matrix:

MATLAB index –>	1	2	3	4	5	6
QS Record | V	Time Stamp	Signal	PoolID	Ref. Count	Event Size	Delta
QS_QF_NEW	#	#	NaN	NaN	#	+1
QS_QF_GC_ATTEMPT	#	#	#	#	NaN	0
QS_QF_GC	#	#	#	NaN	NaN	-1

The cumulative sum over the 'Delta' column should not have any long-time trends, because this would indicate event leak. The following picture shows the plot for the test data.

Plot stairs(Q_NEW(:,1), cumsum(Q_NEW(:,6)))

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

QS Record	MATLAB Index Matrix
QS_QF_NEW	Q_NEW(:,6) > 0
QS_QF_GC_ATTEMPT	Q_NEW(:,6) == 0
QS_QF_GC	Q_NEW(:,6) < 0

Q_PUB Matrix

The N-by-7 Q_PUB matrix stores QS records pertaining to publishing events in QF. The following table summarizes how the QS records are stored in the matrix:

MATLAB index –>	1	2	3	4	5	6	7
QS Record | V	Time Stamp	Sender	Signal	PoolID	Ref. Count	# Events Multicast	Delta
QS_QF_PUBLISH	#	#	#	#	#	#

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

QS Record	MATLAB Index Matrix
QS_QF_PUBLISH	Q_PUB(:,7) > 0

Q_TIME Matrix

The N-by-7 Q_TIME matrix stores QS records pertaining to time events in QF. The following table summarizes how the QS records are stored in the matrix:

MATLAB index –>	1	2	3	4	5	6	7
QS Record | V	Time Stamp	QTimeEvt Object	Signal	QActive Object	QTimeEvt Counter	QTimeEvt Interval	QTimeEvt Delta
QS_QF_TICK	NaN	NaN	NaN	NaN	#(1)	NaN	0
QS_QF_TIMEEVT_ARM	#	#	NaN	#	#	#	+1
QS_QF_TIMEEVT_DISARM	#	#	NaN	#	#	#	-1
QS_QF_TIMEEVT_AUTO_DISARM	NaN	#	NaN	#	NaN	NaN	-1
QS_QF_TIMEEVT_DISARM_ATTEMPT	#	#	NaN	#	NaN	NaN	0
QS_QF_TIMEEVT_REARM	#	#	NaN	#	#	#	#(2)
QS_QF_TIMEEVT_POST	#	#	#	#	NaN	NaN	0

(1) For QS_QF_TICK record this matrix element contains the Tick Counter.

(2) For QS_QF_TIMEEVT_REARM event this matrix element is 0 if the time event was disarmed and rearmed again, and 1 if the time event was only armed.

The cumulative sum over the 'Delta' column indicates the total number of armed time events at any given time. The following picture shows the plot for the test data:

Plot stairs(Q_TIME(:,1), cumsum(Q_TIME(:,7)))

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

QS Record	MATLAB Index Matrix
QS_QF_TICK	isnan(Q_TIME(:,2))
QS_QF_TIMEEVT_ARM	Q_TIME(:,7) > 0
QS_QF_TIMEEVT_DISARM	~isnan(Q_TIME(:,1)) & Q_TIME(:,7) < 0
QS_QF_TIMEEVT_AUTO_DISARM	isnan(Q_TIME(:,1)) & Q_TIME(:,7) < 0
QS_QF_TIMEEVT_DISARM_ATTEMPT	isnan(Q_TIME(:,3)) & isnan(Q_TIME(:,5)) & Q_TIME(:,7) == 0
QS_QF_TIMEEVT_REARM	isnan(Q_TIME(:,3)) & ~isnan(Q_TIME(:,5))
QS_QF_TIMEEVT_POST	~isnan(Q_TIME(:,3)) & ~isnan(Q_TIME(:,4))

Q_INT Matrix

The N-by-3 Q_INT matrix stores QS records pertaining to interrupt disabling and enabling. The following table summarizes how the QS records are stored in the matrix:

MATLAB index –>	1	2	3
QS Record | V	Time Stamp	Interrupt Nesting	Nesting Delta
QS_QF_INT_DISABLE	#	#	+1
QS_QF_INT_ENABLE	#	#	-1

The cumulative sum over the 'Delta' column indicates interrupt lock nesting and should closely follow column 2.

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

QS Record	MATLAB Index Matrix
QS_QF_INT_DISABLE	Q_INT(:,3) > 0
QS_QF_INT_ENABLE	Q_INT(:,3) < 0

Q_ISR Matrix

The N-by-4 Q_ISR matrix stores QS records pertaining to interrupt entry and exit. The following table summarizes how the QS records are stored in the matrix:

MATLAB index –>	1	2	3	4
QS Record | V	Time Stamp	Interrupt Nesting	ISR Priority	Nesting Delta
QS_QF_ISR_ENTRY	#	#	#	+1
QS_QF_ISR_EXIT	#	#	#	-1

The cumulative sum over the 'Delta' column indicates interrupt nesting level and should closely follow column 2.

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

QS Record	MATLAB Index Matrix
QS_QF_ISR_ENTRY	Q_ISR(:,4) > 0
QS_QF_ISR_EXIT	Q_ISR(:,4) < 0

Q_MUTEX Matrix

The N-by-4 Q_MUTEX matrix stores QS records pertaining to the priority-ceiling mutex activity in QK. The following table summarizes how the QS records are stored in the matrix:

MATLAB index –>	1	2	3	4
QS Record | V	Time Stamp	Original Priority	Priority Ceiling	Nesting Delta
QS_MUTEX_LOCK	#	#	#	+1
QS_MUTEX_UNLOCK	#	#	#	-1

The cumulative sum over the 'Delta' column indicates QK scheduler lock nesting level.

Plot stairs(Q_MUTEX(:,1), cumsum(Q_MUTEX(:,4)), 'r') (red)

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

QS Record	MATLAB Index Matrix
QS_MUTEX_LOCK	Q_MUTEX(:,4) > 0
QS_MUTEX_UNLOCK	Q_MUTEX(:,4) < 0

Q_SCHED Matrix

The N-by-3 Q_SCHED matrix stores QS records pertaining to scheduling next task in QK. The following table summarizes how the QS records are stored in the matrix:

MATLAB index –>	1	2	3
QS Record | V	Time Stamp	Preempted Priority	New Priority
QS_SCHED_NEXT	#	#	#

---

Next: QUTest™ Unit Testing Harness