To create a usable piece of software, you have to fight for every fix, every feature, every little accommodation that will get one more person up the curve. There are no shortcuts. Luck is involved, but you don't win by being lucky, it happens because you fought for every inch.
For many years, I had been looking for a book or a magazine article that would describe a truly practical way of coding modern state machines (UML1 UML stands for Unified Modeling Language and is the trademark of Object Management Group. statecharts) in a mainstream programming language such as C or C++. I have never found such a technique.
In 2002, I wrote Practical Statecharts in C/C++: Quantum Programming for Embedded Systems (PSiCC), which was the first book to provide what had been missing thus far: a compact, efficient, and highly maintainable implementation of UML state machines in C and C++ with full support for hierarchical nesting of states. PSiCC was also the first book to offer complete C and C++ source code of a generic, state machine-based, real-time application framework for embedded systems.
To my delight, PSiCC continues to be one of the most popular books about statecharts and event-driven programming for embedded systems. Within a year of its publication, PSiCC was translated into Chinese, and a year later into Korean. I've received and answered literally thousands of e-mails from readers who successfully used the published code in consumer, medical, industrial, wireless, networking, research, defense, robotics, automotive, space exploration, and many other applications worldwide. In 2003 I started to speak about the subject matter at the Embedded Systems Conferences on both U.S. coasts. I also began to consult to companies. All this gave me additional numerous opportunities to find out firsthand how engineers actually use the published design techniques in a wide range of application areas.
What you're holding in your hands is the second edition of PSiCC. It is the direct result of the plentiful feedback I've received as well as five years of the “massive parallel testing” and scrutiny that has occurred in the trenches.
As promised in the first edition of PSiCC, I continued to advance the code and refine the design techniques. This completely revised second edition incorporates these advancements as well the numerous lessons learned from readers.
First of all, this book presents an entirely new version of the software, which is now called Quantum Platform (QP) and includes the hierarchical event processor (QEP) and the real-time framework (QF) as well as two new components. QP underwent several quantum leaps of improvement since the first publication six years ago. The enhancements introduced since the first edition of PSiCC are too numerous to list here, but the general areas of improvements include greater efficiency and testability and better portability across different processors, compilers, and operating systems. The two new QP components are the lightweight, preemptive, real-time kernel (QK) described in Chapter 10 and the software-tracing instrumentation (QS) covered in Chapter 11. Finally, I'm quite excited about the entirely new, ultralight, reduced-feature version of QP called QP-nano that scales the approach down to the lowest-end 8- and 16-bit MCUs. I describe QP-nano in Chapter 12.
In 2004, I decided to release the entire QP code as open source under the terms of the GNU General Public License (GPL) version 2, as published by the Free Software Foundation. Independent of the open-source licensing, the QP source code is also available under the terms of traditional commercial licenses, which expressly supersede the GPL and are specifically designed for users interested in retaining the proprietary status of their applications based on QP. This increasingly popular strategy of combining open source with commercial licensing, called dual licensing, is explained in more detail in Appendix A.
Most of the code samples in the first edition of PSiCC pertained to the C++ implementation. However, as I found out in the field, many embedded software developers come from a hardware background (mostly EE) and are often unnecessarily intimidated by C++.
In this edition, I decided to exactly reverse the roles of C and C++. As before, the companion Website contains the complete source code for both C and C++ versions. But now, most of the code examples in the text refer to the C version, and the C++ code is discussed only when the differences between it and the C implementation become nontrivial and important.
As far as the C source code is concerned, I no longer use the C+ object-oriented extension that I've applied and documented in the first edition. The code is still compatible with C+, but the C+ macros are not used.
Compared to the first edition, this book presents more examples of event-driven systems and the examples are more complete. I made a significant effort to come up with examples that are not utterly trivial yet don't obscure the general principles in too many details. I also chose examples that don't require any specific domain knowledge, so I don't need to waste space and your attention explaining the problem specification.
An event-driven infrastructure such as QP can work with a variety of concurrency mechanisms, from a simple “superloop” to fully preemptive, priority-based multitasking. The previous version of QP supported the simple nonpreemptive scheduling natively but required an external RTOS to provide preemptive multitasking, if such capability was required.
In Chapter 10, I describe the new real-time kernel (QK) component that provides deterministic, fully preemptive, priority-based multitasking to QP. QK is a very special, super-simple, run-to-completion, single-stack kernel that perfectly matches the universally assumed run-to-completion semantics required for state machine execution.
A running application built of concurrently executing state machines is a highly structured affair where all important system interactions funnel through the event-driven framework that ties all the state machines together. By instrumenting just this tiny “funnel” code, you can gain unprecedented insight into the live system. In fact, the software trace data from an instrumented event-driven framework can tell you much more about the application than any traditional real-time operating system (RTOS) because the framework “knows” so much more about the application.
Chapter 11 describes the new QS (“spy”) component that provides a comprehensive software-tracing instrumentation to the QP event-driven platform. The trace data produced by the QS component allows you to perform a live analysis of your running real-time embedded system with minimal target system resources and without stopping or significantly slowing down the code. Among other things, you can reconstruct complete sequence diagrams and detailed, timestamped state machine activities for all active objects in the system. You can monitor all event exchanges, event queues, event pools, time events (timers), and preemptions and context switches. You can also use QS to add your own instrumentation to the application-level code.
The event-driven approach with state machines scales down better than any conventional real-time kernel or RTOS. To address really small embedded systems, a reduced QP version called QP-nano implements a subset of features supported in QP/C or QP/C++. QP-nano has been specifically designed to enable event-driven programming with hierarchical state machines on low-end 8- and 16-bit microcontrollers (MCUs), such as AVR, MSP430, 8051, PICmicro, 68HC(S)08, M16C, and many others. Typically, QP-nano requires around 1-2KB of ROM and just a few bytes of RAM per state machine. I describe QP-nano in Chapter 12.
In the first edition of PSiCC, I proposed a quantum-mechanical metaphor as a way of thinking about the event-driven software systems. Though I still believe that this analogy is remarkably accurate, it hasn't particularly caught on with readers, even though providing such a metaphor is one of the key practices of eXtreme Programming (XP) and other agile methods.
Respecting readers’ feedback, I decided to remove the quantum metaphor from this edition. For historical reasons, the word quantum still appears in the names of the software components, and the prefix Q is consistently used in the code for type and function names to clearly distinguish the QP code from other code, but you don't need to read anything into these names.
Most of the code supplied with this book is highly portable C or C++, independent of any particular CPU, operating system, or compiler. However, to focus the discussion I provide executable examples that run in a DOS console under any variant of Windows. I've chosen the legacy 16-bit DOS as a demonstration platform because it allows programming a standard x86-based PC at the bare-metal level. Without leaving your desktop, you can work with interrupts, directly manipulate CPU registers, and directly access the I/O space. No other modern 32-bit development environment for the standard PC allows this much so easily.
The additional advantage of the legacy DOS platform is the availability of mature and free tools. To that end, I have compiled the examples with the legacy Borland Turbo C++ 1.01 toolset, which is available for a free download from Borland.
To demonstrate modern embedded systems programming with QP, I also provide examples for the inexpensive2 At the time of this writing, the EKIEV-LM3S811 kit was available for $49 (http://www.luminarymicro.com). ARM Corterx-M3-based Stellaris EV-LM3S811 evaluation kit form Luminary Micro. The Cortex-M3 examples use the exact same source code as the DOS counterparts and differ only in the board support package (BSP). The Cortex-M3 examples require the 32KB-limited KickStart edition of the IAR EWARM toolset, which is included in the Stellaris kit and is also available for a free download from IAR.
Finally, some examples in this book run on Linux as well as any other POSIX-compliant operating system such as BSD, QNX, Max OS X, or Solaris. You can also build the Linux examples on Windows under Cygwin.
The companion Website to this book at http://www.quantum-leaps.com/psicc2 provides the links for downloading all the tools used in the book, as well as other resources. The Website also contains links to dozens of QP ports to various CPUs, operating systems, and compilers. Keep checking this Website; new ports are added frequently.
This book is intended for the following software developers interested in event-driven programming and modern state machines:
• Embedded programmers and consultants will find a complete, ready-to-use, event-driven infrastructure to develop applications. The book describes both state machine coding strategies and, equally important, a compatible real-time framework for executing concurrent state machines. These two elements are synergistically complementary, and one cannot reach its full potential without the other.
• Embedded developers looking for a real-time kernel or RTOS will find that the QP event-driven platform can do everything one might expect from an RTOS and that, in fact, QP actually contains a fully preemptive real-time kernel as well as a simple cooperative scheduler.
• Designers of ultra low-power systems, such as wireless sensor networks, will find how to scale down the event-driven, state machine-based approach to fit the tiniest MCUs. The ultra-light QP-nano version (Chapter 12) combines a hierarchical event processor, a real-time framework, and either a cooperative or a fully preemptive kernel in just 1–2KB of ROM.
• On the opposite end of the complexity spectrum, designers of very large-scale, massively parallel server applications will find that the event-driven approach combined with hierarchical state machines scales up easily and is ideal for managing very large numbers of stateful components, such as client sessions. As it turns out, the “embedded” design philosophy of QP provides the critical per-component efficiency both in time and space.
• The open-source community will find that QP complements other open-source software, such as Linux or BSD. The QP port to Linux (and more generally to POSIX-compliant operating systems) is described in Chapter 8.
• GUI developers and computer game programmers using C or C++ will find that QP very nicely complements GUI libraries. QP provides the high-level “screen logic” based on hierarchical state machines, whereas the GUI libraries handle low-level widgets and rendering of the images on the screen.
• System architects might find in QP a lightweight alternative to heavyweight design automation tools.
• Users of design automation tools will gain deeper understanding of the inner workings of their tools. The glimpse “under the hood” will help them use the tools more efficiently and with greater confidence.
Due to the code-centric approach, this book will primarily appeal to software developers tasked with creating actual, working code, as opposed to just modeling. Many books about UML already do a good job of describing model-driven analysis and design as well as related issues, such as software development processes and modeling tools.
This book does not provide yet another CASE tool. Instead, this book is about practical, manual coding techniques for hierarchical state machines and about combining state machines into robust event-driven systems by means of a real-time framework.
To benefit from the book, you should be reasonably proficient in C or C++ and have a general understanding of computer architectures. I am not assuming that you have prior knowledge of UML state machines, and I introduce the underlying concepts in a crash course in Chapter 2. I also introduce the basic real-time concepts of multitasking, mutual exclusion, and blocking in Chapter 6.
This book has a companion Website at www.quantum-leaps.com/psicc2 that contains the following information:
Additionally, the Quantum Leaps Website at http://www.quantum-leaps.com has been supporting the QP user community since the publication of the first edition of PSiCC in 2002. This Website offers the following resources:
Finally, QP is also present on SourceForge.net—the world's largest repository of open source code and applications. The QP project is located at https://sourceforge.net/projects/qpc/.