Virtual Platform UART Use Number 4: Connecting to an RTOS Tracing Framework

This is the last installment of my series on different uses for the UART in Virtual Platforms. Today's article is about how to use a UART as a way to capture logging information about a running system.

One of the challenges of developing embedded software is trying to understand what is happening. Having a debugger to control the software is useful, but debuggers work at a very low level, stopping the software at defined breakpoints in specific places in the source code. Understanding the big picture of a running system is not always so easy.

The example I have today is based on the Quantum Platform state machine framework. Describing QP itself is a big topic and better left to the experts at Quantum Leaps. I encourage you to spend some time on the website, but the application I ran is the Dining Philosopher example. In the example there are 5 philosophers sitting at the table eating spaghetti and there are 5 forks available. Two forks must be acquired in order for a philosopher to eat. The example demonstrates a state machine that models the philosophers as they think, get hungry, try to get two forks, and eat.

For demo purposes we built a small GUI that models the LCD on the demo board and displays the state of the philosophers as hungry, eating, or thinking. Of course the first philosopher is number 0 since everybody knows engineers always start counting with 0 instead of 1. The display is shown below:

One of the utilities provided by QP is something called qspy. This program runs on the host machine and receives output from the running QP framework about what is going on. The instrumentation is built into the framework itself and has very low overhead so there is really nothing that the user needs to do.

When using a real board, a physical cable is used to connect the serial port on the board to the host machine and the qspy program runs on the host and displays the data coming from QP. In the Virtual Platform we don't have any cables so we just connect the UART output directly to the qspy program. The trick is bridging the UART output to the qspy program.

The command line options for qspy allow it to work with either serial input from something like a PC COM port or with TCP/IP input from a network socket. Since it can work with the network socket, all that is needed is to take the UART output from the simulation and send it into a network socket and tell qspy to listen to that socket. The best part is that the communication is only one direction; all data flows out of the simulated system into the network socket and is displayed by qspy.

You may ask what does this qspy do? Doesn't everybody output print messages to the UART to see what is going on? Because qspy is specific to the QP framework it encodes the data which cuts down the total data transmission compared to a normal ASCII information stream. In fact, if you just hook up a regular terminal to the output stream coming from the UART you will see it is not human readable, just junk.

To connect qspy to a Virtual Platform we can use a model that is very much like the SystemC tterm model we used in previous articles. This one is actually easier since the communication is only one direction. This model I call spyterm, and the source code for spyterm.h and spyterm.cpp is available.

The main differences are to eliminate all of the code that sends data into the UART and to change the port number to the default port of qspy (6601) so we don't have to bother with setting the port on the qspy command line.

Here are the command line options for qspy:

It's easy to run just qspy -t and have the output in the terminal where qspy is started.

Here is a screenshot showing the qspy output from the running system:

If the same output is sent to a regular terminal it's just garbage:

Initially when I saw the qspy output it was interesting, but I'm not an expert in QP so the data is not all that meaningful to me. To help understand things there is another utility that produces a graphical picture of the sequence diagrams, but I had a hard time to get it working as advertised on the website. The generated files were very large and I was unable to use mscgen to convert the data into a picture. Oh well, the picture from the website will have to do for now.

I hope this series of articles about the uses of the UART in different Virtual Platform situations has been useful. As always, feel free to share your own ideas about how you use Virtual Platforms for software development.

Jason Andrews