History:
Last updated for QP 4.5.02 on 05-Sep-2012

Description

QP is a lightweight, open source, active object framework for microcontrollers such as ARM Cortex-M3/M0. QP enables you to build well-structured event-driven programs as systems of concurrently executing, encapsulated state machines (active objects a.k.a. actors). You can think of QP as a modern real-time operating system (RTOS) specifically designed for executing state machines. The QP framework does everything you can expect from a traditional RTOS, such as preemptive multitasking, plus many things an RTOS can't do at all.

QP is also an excellent target for automatic code generation. To this end, QP is now supported by the the free graphical QM modeling tool, which can automatically generate complete mbed applications from UML state diagrams. Thus QP is your entry into graphical programming for the mbed platform.

QP improves productivity, because you no longer need to struggle with convoluted if-else "spaghetti" code and you don't need to worry about semaphores and other such low-level RTOS mechanisms. Instead, you can work at a higher level of abstraction of events and state machines.

Background

Traditionally, mbed programs are written in a sequential manner, which means that whenever a mbed program needs to synchronize with some external event, such as a button press, arrival of a character through the serial port, or a time delay, it explicitly waits in-line for the occurrence of the event. Waiting ''in-line'' means that the mbed processor spends all of its cycles constantly checking for some condition in a tight loop (called the polling loop).

Although this approach is functional in many situations, it doesn't work very well when there are multiple possible sources of events whose arrival times and order you cannot predict and where it is important to handle the events in a timely manner. The fundamental problem is that while a sequential program is waiting for one kind of event (e.g., a button press), it is not doing any other work and is ''not responsive'' to other events (e.g., bytes from the serial port).

Another big problem with the sequential program structure is wastefulness in terms of power dissipation. Regardless of how much or how little actual work is being done, the mbed processor is always running at top speed, which drains the battery quickly and prevents you from making truly long-lasting battery-powered devices.

For these and other reasons experienced programmers turn to the long-know design strategy called event-driven programming, which requires a distinctly different way of thinking than conventional sequential programs. All event-driven programs are naturally divided into the application, which actually handles the events, and the supervisory event-driven infrastructure (framework), which waits for events and dispatches them to the application. The control resides in the event-driven framework, so from the application standpoint, the control is inverted compared to a traditional sequential program.

It turns out that the event-driven QP active object framework beautifully complements the mbed platform and provides everything you need to build responsive, robust, and power-efficient mbed programs based on modern hierarchical state machines. Enjoy!

Example Programs

The qp_dpp (Dining Philosophers Problem) program provides a simple example of using the QP framework. Please refer to the QL Notebook page "Building Applications with QP (qp_dpp Example)" for more information. Among others, the qp_dpp program illustrates the use of the preemptive QK kernel.

The qp_pelican (PEdestrian LIght CONtrolled crossing) program provides a more interesting hierarchical state machine example. Please refer to the QL Notebook page "Hierarchical State Machines (qp_pelican Example)" for more information.

About the QP Port for mbed

The QP framework has been designed from the ground up to be highly portable and to date has been ported to more than a dozen different CPU architectures and many different compilers. The QP library offered for the mbed platform is actually the QP/C++ version of QP (the other QP versions are QP/C and QP-nano). The QP port to mbed is based on the QP/C++ port to ARM Cortex, which has been available for a number of years at state-machine.com/arm.

The files comprising the QP/C++ framework for mbed are as follows:

+-qp/                - qp library for mbed
  +-qp_port.h        - QP/C++ port for mbed header file
  +-qp.h             - QP/C++ platform-independent header file
  +-qp.cpp           - QP/C++ platform-independent source code
  +-qk_port.s        - QK port to ARM Cortex-M0/M3, mbed ARM assembler code

Typically you should not need to edit any of the QP source code. Compile-time configuration of the QP library is achieved by a separate header file qp_config.h, which is defined at the application level and included in the qp_port.h header file and is described below.

Configuring QP via the qp_config.h header file

The QP library for mbed is configured through the qp_config.h header file, which must be provided by the application that uses QP. You can use the following version of the qp_config.h header file to copy-and-paste into your applications:

#ifndef qp_config_h
#define qp_config_h

// enable the Q-SPY software tracing instrumentation
#define Q_SPY

// enable preemptive QK kernel (cooperative kernel is used when not defined)
#define QK_PREEMPTIVE

// The maximum number of active objects in the application (could be up to 63)
#define QF_MAX_ACTIVE         16

// Uncomment the following macros only if you want to change the given default
//#define Q_EVT_CTOR            1
//#define Q_SIGNAL_SIZE         2
//#define QF_MAX_EPOOL          3
//#define QF_EVENT_SIZ_SIZE     2
//#define QF_EQUEUE_CTR_SIZE    1
//#define QF_MPOOL_SIZ_SIZE     2
//#define QF_MPOOL_CTR_SIZE     2
//#define QF_TIMEEVT_CTR_SIZE   2 

#endif                                                          // qp_config_h

The most important options are:

• Q_SPY: if defined, activates the software tracing instrumentation in the QP framework. This means that virtually any activity inside a framework is output to a circular buffer in memory and can be sent to the host for inspection (please see Section "Software Tracing" below). If the macro Q_SPY is not defined, the software tracing instrumentation becomes inactive both in the framework and in the application. "Inactive" means that the software tracing instrumentation the software tracing instrumentation remains in the code, but stops generating any code, so no overhead of any kind is incurred.

• QK_PREEMPTIVE: if defined, configures QP to use the preemptive QK kernel. If the macro QK_PREEMPTIVE is not defined, the simpler cooperative "vanilla" kernel is used. NOTE: using the preemptive kernel requires adding special macros (QK_ISR_ENTRY and QK_ISR_EXIT) to every interrupt service routine (ISR). Also, the two kernels use different idle callbacks (QK_onIdle() and QF_onIdle(), respectively).

• QF_MAX_ACTIVE: determines the maximum number of active objects in the application. The term "active object" comes from the UML and denotes an autonomous object running in its own thread of execution. In QP active objects are state machines with a private event queue and unique priority level. The number of active objects in QP must not exceed 63, inclusive, but setting a lower limit than this maximum saves some memory (RAM).

Free Modeling and Code Generation Tool

All QP examples for the mbed microcontroller have been automatically generated by the QM (QP Modeler) tool. QM is a free, cross-platform, graphical UML modeling tool for designing and implementing real-time embedded applications based on the QP state machine frameworks. QM provides best-in-class, intuitive diagramming environment and generates very compact C or C++ code that is 100% traceable from your design. QM is available for Windows, Linux, and Mac OS X. The steps of obtaining the free QM tool and generating the code are described in the QL Notebook page "Graphical Modeling and Automatic Code Generation ".

The following screen shot shows the Dining Philosopher Problem (DPP) model open in QM (click on the picture to enlarge it to 100%):

Preemptive Multitasking

The QP framework contains a fully preemptive real-time, priority-based kernel called QK. QK is a special run-to-completion kernel type particularly suitable for executing state machines. QK achieves deterministic execution of high-priority tasks, which is as good as any traditional preemptive kernel. The details of implementing the QK kernel on ARM Cortex are described in the Quantum Leaps Application Note: QP and ARM-Cortex (see also the "Documentation and Resources" at the end of this page).

Software Tracing Instrumentation

One of the biggest problems with developing embedded software is very low visibility into the running code inside the target system. You simply don't know what's going on in there. For generations, embedded developers have been using printf() statements coupled with serial port output to get some feedback from the embedded systems to their host workstations. This technique, known as software tracing is particularly popular with the mbed platform, because the online development system offers no traditional single-step debugger.

However, clogging any time-sensitive code with printf() statements is often too intrusive and simply not workable in many systems. When you think about it, printf(), which performs very time-consuming formatting of binary data to ASCII, is exactly not what you should be doing in the resource-constrained target. Instead, you should perform the absolute minimum of work in the target and let the powerful host computer do the heavy lifting of formatting and pretty-printing of the data. Additional benefit of sending unformatted, binary tracing data from the target is natural data compression. It simply takes much less bytes to send the same information in binary than in ASCII.

The QP framework offers a software tracing system called QP-Spy based on binary data transmission, sophisticated data filtering, flexible data output, decoupling of data collecting from data transmission, use of the idle task for data transmission to minimize the impact on the target, thread-safety, and many other features expected from a professional software tracing system.

As any software tracing system, QP-Spy consists of a target-resident component, called QS, and the application running on the hots workstation, called QSPY.

Target-resident QS Component

On the mbed platform, the QS component sends the tracing data through the UART0, connected to the USB virtual COM port, so the tracing data arrives on the host through the same USB cable that powers mbed. The qp_dpp example program contains fully functional tracing implementation for mbed.

Host-resident QSPY Application

The binary QS output needs to be decompressed and formatted by the QSPY host application, which is available for download from SourceForge.net. The ZIP file contains pre-compiled QSPY for Windows and Linux hosts. The source code is also provided, so you can customize it and compile QSPY on any other platform.

QSPY is a console-style application that you invoke from a command line. It outputs human-readable tracing data to the console and also to a file, if you choose so. The reference manual of QSPY is available online at state-machine.com/doxygen/qspy.

Documentation and Resources

Obviously this Notebook page can only highlight some aspects of a mature software framework like QP. If you are interested to learn more about event-driven programming for embedded systems and modern hierarchical state machines, the following resources can get you started.