9. Using Software Tracing for Testing and Debugging

This QP/C++ Tutorial is adapted from Chapter 1 of Practical UML Statecharts in C/C++, Second Edition
by Miro Samek, the founder and president of Quantum Leaps, LLC.

Prev: 8. Using the Built-in Real-Time Kernels and Third-Party RTOSes
Next: 10. Comparison to the Traditional Approach

A running application built of active objects is a highly structured affair where all important system interactions funnel through the real-time framework (QF) and the state-machine engine (QEP). This offers a unique opportunity to use software tracing techniques to gain unprecedented insight into the entire system.

Software tracing is a method for obtaining diagnostic information in a live environment without the need to stop the application to get the system feedback. In a nutshell, software tracing is similar to peppering the code with printf() statements for logging and debugging, except that mature software tracing techniques are much less intrusive and more selective than the primitive
printf().

Due to the inversion of a control, software tracing is particularly effective and powerful in combination with the event-driven frameworks. The QP event-driven platorm contains the sophisticated software tracing system called Quantum Spy (QS). The QS trace data can be thorough enough to produce complete sequence diagrams and detailed state machine activity for all state machines in the system. You can selectively monitor all event exchanges, event queues, event pools, and time events because all these elements are controlled by the framework. Additionally, if you use one of the kernels built into QP (the vanilla kernel or the preemptive QK kernel), you can obtain all the data available to a traditional RTOS as well, such as context switches and mutex activity

To show you how software tracing works in practice I present an example of a software tracing session. I use the application. All versions of the "Fly 'n' Shoot" game contain the QS instrumentation. The tracing instrumentation becomes active when you build the "Spy" configuration.

Note:: To build the "Spy" configuration in DOS version, please execute the make.bat script with the spy argument (make spy). To buld the "Spy" configuration in the ARM-Cortex version, please select the "Spy" configuration in the IAR EWARM IDE (see Figure 2-3).

Figure 9-1 shows how to collect the software trace data from the DOS version of the "Fly 'n' Shoot" application, which is located in the directory <qpcpp>\examples\80x86\dos\watcom\l\dpp\spy\dpp.exe. You can re-build the "Spy" configuration by executing make spy from the command line. You need to run the GAME.EXE executable on a target PC with a serial port. You connect the serial port of the target machine to the serial port of a Windows or a Linux host workstation via a NULL-modem cable.

Figure 9-1 Collecting software trace data from a 80x86 target.

Actually, all versions of "Fly 'n' Shoot" applications included in the standard QP distribution are instrumented for software tracing and I encourage you to try them all. For example, you can collect trace data from the LM3S811 board (see Figure 9-2). The LM3S811 board sends the QS trace data through the UART0 connected to the Virtual COM Port (VCP) provided by the USB debugger, so the QSPY host application can conveniently receive the trace data on the host PC. No additional serial cable is needed.

Figure 9-2 Collecting software trace data from the LM3S811 board.

On the host workstation, you need to start the QSPY host application that decompresses and visualizes the QS trace data. The Windows executable of the QSPY host application is located in the directory <qpcpp>\tools\qspy\win32\vc2005\Release\qspy.exe. Assuming that this directory is your current directory, or is in your path, you invoke this console application by typing the following command at the command prompt:

qspy -c COM1 -b 115200

The first command-line parameter -c COM1 tells the QSPY host application to receive the trace data from COM1. If your target is connected to a different COM port, you need to adjust the COM number. The second parameter configures the baud rate of the serial port to 115200. Section QSPY Command-Line Parameters explains the comman-line paratmeters of the QSPY host application.

Note:: In the particular case of a Windows PC, you can use the same machine as the target and the host at the same time. You need to use a machine with two serial ports, which you connect with a NULL modem cable. You can use one serial port for the DPP target application running in a DOS-window and the other for the QSPY host application.

You might also use a Linux host machine. In case of Linux, you must first build the executable by running the Makefile located in the directory <qpcpp>/tools/qspy/linux/gnu/. You invoke the Linux executable by typing the following command at the command prompt:

qspy -c /dev/ttyS0 -b 115200

The first parameter -c /dev/ttyS0 tells the QSPY application to receive the trace data from the ttyS0 serial device. If you connected a different serial port to the target, you need to adjust the ttyS number.

If everything is connected correctly, the QSPY host application should produce the human-readable output of the trace data to the screen. Please refer to QSPY Host Application Reference Manual explains the human-readable format as well as importing the trace data to MATLAB®.

Prev: 8. Using the Built-in Real-Time Kernels and Third-Party RTOSes
Next: 10. Comparison to the Traditional Approach