Preface 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. —Dave Winer Formanyyears,Ihadbeenlookingforabookoramagazinearticlethatwoulddescribe a truly practical way of coding modern state machines (UML1 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 EmbeddedSystems(PSiCC),whichwasthefirstbooktoprovidewhathadbeenmissing 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 alsothefirstbooktooffercompleteCandC++sourcecodeofageneric,statemachine- 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’vereceivedandansweredliterallythousandsofe-mailsfromreaderswhosuccessfully 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 1UMLstands forUnified ModelingLanguageandisthetrademark ofObject Management Group. www.newnespress.com xviii Preface 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. Whatyou’reholdingin yourhandsis thesecondeditionof PSiCC. Itis thedirectresult 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. What’s New in the Second Edition? 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. New Code 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 betterportabilityacrossdifferentprocessors,compilers,andoperatingsystems.Thetwo 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. Open Source and Dual Licensing 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 www.newnespress.com Preface xix 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. C as the Primary Language of Exposition 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. Butnow,mostofthecodeexamplesinthetextrefertotheCversion,andtheC++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. More Examples 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. Preemptive Multitasking Support 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,fullypreemptive,priority-basedmultitasking toQP. QKis avery special, www.newnespress.com xx Preface super-simple, run-to-completion, single-stack kernel that perfectly matches the universally assumed run-to-completion semantics required for state machine execution. Testing Support 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. Ultra-Lightweight QP-nano Version 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. Removed Quantum Metaphor 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 www.newnespress.com Preface xxi 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. What You Need to Use QP 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 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).TheCortex-M3examplesrequirethe32KB-limitedKickStarteditionoftheIAR 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. 2At the time of this writing, the EKIEV-LM3S811 kit was available for $49 ( www.luminarymicro.com). www.newnespress.com xxii Preface The companion Website to this book at 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. Intended Audience This book is intended for the following software developers interested in event-driven programming and modern state machines: (cid:1) 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. (cid:1) 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. (cid:1) Designers of ultra low-power systems, such as wireless sensor networks, will findhowtoscaledowntheevent-driven,statemachine-basedapproachtofitthe 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. (cid:1) 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. (cid:1) 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. www.newnespress.com Preface xxiii (cid:1) 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. (cid:1) System architects might find in QP a lightweight alternative to heavyweight design automation tools. (cid:1) 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. ThisbookdoesnotprovideyetanotherCASEtool.Instead,thisbookisaboutpractical, 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. The Companion Websites This book has a companion Website at www.quantum-leaps.com/psicc2 that contains the following information: (cid:1) Source code downloads for QP/C, QP/C++, and QP-nano (cid:1) All QP ports and examples described in the book (cid:1) Reference manuals for QP/C, QP/C++, and QP-nano in HTML and CHM file formats (cid:1) Links for downloading compilers and other tools used in the book www.newnespress.com xxiv Preface (cid:1) Selected reviews and reader feedback (cid:1) Errata Additionally, the Quantum Leaps Website at 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: (cid:1) Latest QP downloads (cid:1) QP ports and development kits (cid:1) Programmer manuals (cid:1) Application notes (cid:1) Resources and goodies such as Visio stencils for drawing UML diagrams, design patterns, links to related books and articles, and more (cid:1) Commercial licensing and technical support information (cid:1) Consulting and training in the technology (cid:1) News and events (cid:1) Discussion forum (cid:1) Newsletter (cid:1) Blog (cid:1) Links to related Websites (cid:1) And more 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/. www.newnespress.com Acknowledgments First and foremost, I’d like to thank my wonderful family for the unfading support over the years of creating the software and the two editions of this book. I would also like to thank the team at Elsevier, which includes Rachel Roumeliotis and Heather Scherer, and John (Jay) Donahue. Finally, I’m grateful to all the software developers who contacted me with thought- provoking questions, bug reports, and countless suggestions for improvements in the code and documentation. As a rule, a software system only gets better if it is used and scrutinized by many people in many different real-life projects. www.newnespress.com