namespace QP { /*! @page struct Structure and Features @tableofcontents @section files Directories and Files The following annotated directory tree lists the top-level directories provided in the standard QP/C++ distribution:

qpcpp/

3rd_party/ — Third-Party code used in the QP/C++ @ref ports "ports" and @ref exa "examples"
examples/ — @ref exa "QP/C++ Examples"
ports/ — @ref ports "QP/C++ Ports"
include/ — Platform-independent QP/C++ API (see include)
src/ — Platform-independent QP/C++ source code (see @ref src)

@note The standard QP/C++ distribution contains many @ref exa "Example Projects", which are specifically designed to help you learn to use QP/C++ and to serve you as starting points for your own projects. ------------------------------------------------------------------------------ @section comp Components of QP/C++

As shown in the diagram below, the QP/C++ framework has a layered structure. The Target hardware sits at the bottom. The Board Support Package (BSP) above it provides access to the board-specific features, such as the peripherals. The real-time kernel (@ref comp_qv "QV", @ref comp_qk "QK", @ref comp_qxk "QXK", or a conventional @ref ports_rtos "3rd-party RTOS") provides the foundation for multitasking, such as task scheduling, context-switching, and inter-task communication. Based on these services, the active object framework (@ref comp_qf "QF") supplies the event-driven infrastructure for executing active objects and ensuring thread-safe event-driven exchanges among them. Finally, the event-processor (@ref comp_qep "QEP") implements the [hierarchical state machine](https://www.state-machine.com/doc/concepts#HSM) semantics (based on UML statecharts). The top layer is the application-level code consisting of loosely-coupled [active objects](https://www.state-machine.com/doc/concepts#Active).

@image html qp_components.jpg "Components of the QP Framework" @n

@subsection comp_qep QEP Hierarchical Event Processor QEP is a universal "event processor" that provides implementation of hierarchical state machines (UML statecharts) in highly readable and portable ANSI-C++. The hallmark of the @ref sm "QEP state machine implementation strategy" is **traceability**, which means that every state machine element is mapped to code precisely, unambiguously, and exactly once. QEP fully supports hierarchical state nesting, which is the fundamental mechanism for reusing behavior across many states instead of repeating the same actions and transitions over and over again. (See @ref qep for detailed documentation).

@subsection comp_qf QF Active-Object Framework QF is a lightweight, event-driven, active object framework specifically designed for real-time embedded (RTE) systems. The main job of the framework is to guarantee **thread-safe**, run-to-completion event processing within each active object. This includes direct event posting as well as publish-subscribe event delivery, event queuing, and time events (time-delayed requests for posing events). (See @ref qf for detailed documentation).

@subsection comp_qv QV Cooperative Kernel QV is a simple cooperative kernel (previously called "Vanilla" kernel). This kernel always processes one event at a time to completion, and performs priority-based scheduling of active objects after processing of each event. The QV kernel is "implicitly-cooperative", because the active object do not need to yield the CPU explicitly. Instead, they simply return to the QV scheduler after completion of event processing. Due to naturally short duration of event processing in state machines, the simple QV kernel is often adequate for many real-time systems. (See @ref qv for detailed documentation). This is the fastest, smallest, and easiest to understand way of executing active objects.

@subsection comp_qk QK Preemptive Non-Blocking Kernel QK is an ultra-fast **preemptive**, priority-based, single-stack, real-time kernel designed specifically for executing active objects. The QK kernel always executes the highest-priority active object that has event(s) queued up, but it processes events as one-shot function calls (instead of endless loops, as traditional RTOS kernels). Still, the QK kernel allows these one-shot event-processing functions to preempt each other, if the priority of the new event is higher than the currently-processed event (very much like prioritized interrupt controllers allow interrupts to preempt each other). This means that QK can use _single stack_ for keeping the context all active objects (in the same way as prioritized interrupt controllers use a single stack to nest all interrupts). QK meets all the requirement of the Rate Monotonic Scheduling (a.k.a. Rate Monotonic Analysis — RMA) and can be used in hard real-time systems. (See @ref qk for detailed documentation).

@subsection comp_qxk QXK Preemptive Blocking Kernel QXK is a small, preemptive, priority-based, **dual-mode** blocking kernel that executes active objects like the @ref comp_qk "QK kernel" (@ref qxk_overview "basic threads"), but can also execute traditional blocking threads (@ref qxk_overview "extended threads"). In this respect, QXK behaves exactly as a conventional RTOS (Real-Time Operating System). QXK has been designed specifically for mixing event-driven active objects with traditional blocking code, such as commercial middleware (TCP/IP stacks, UDP stacks, embedded file systems, etc.) or legacy software. QXK meets all the requirement of the Rate Monotonic Scheduling (a.k.a. Rate Monotonic Analysis — RMA) and can be used in hard real-time systems. (See @ref qxk for detailed documentation). @note QXK has most features you might expect of a traditional blocking RTOS kernel and is recommended as the preferred RTOS kernel for QP/C++ applications that need to mix active objects with traditional blocking code. Due to the tight and optimal integration between QXK and the rest of QP/C++, QXK offers better performance and smaller memory footprint than any QP port to a @ref ports_rtos "3rd-party RTOS".

@subsection comp_qs QS Software Tracing System QS is software tracing system that enables developers to monitor live event-driven QP applications with minimal target system resources and without stopping or significantly slowing down the code. QS is an ideal tool for testing, troubleshooting, and optimizing QP applications. QS can even be used to support acceptance testing in product manufacturing. (See @ref qs for detailed documentation). ------------------------------------------------------------------------------ @section qpcpp_oo Object-Orientation As most C++ frameworks, QP/C++ uses classes, inheritance, and polymorphism as the main mechanisms for customizing the framework into applications. The framework is also layered and consists of components with well defined responsibilities. ------------------------------------------------------------------------------ @section classes Classes in QP/C++ The figure below shows the main classes comprising the QP/C++ framework and their relation to the application-level code, such as the @ref game example application (shown at the bottom 1/3 of the diagram). @image html qp_classes.gif "Main Classes in the QP Framework"

0 The QP::QEvt class represents events without parameters and serves as the base class for derivation of time events and any events with parameters. For example, application-level events `ObjectPosEvt` and `ObjectImageEvt` inherit QP::QEvt and add to it some parameters (see [8]).
1 The abstract QP::QHsm class represents a Hierarchical State Machine (HSM) with full support for hierarchical nesting of states, entry/exit actions, initial transitions, and transitions to history in any composite state. This class is designed for ease of **manual coding** of HSMs in C++, but it is also supported by the QM modeling tool. QP::QHsm is also the base class for the QP::QMsm state machine, which provides a superior efficiency, but requires the use of the QM modeling tool to generate code.@n NOTE: Please refer to Section @ref sm for information on how to code hierarchical state machines with QP/C++.
2 The abstract QP::QActive class represents an active object that uses the QP::QHsm style implementation strategy for state machines. This strategy is tailored to manual coding, but it is also supported by the QM modeling tool. The resulting code is slower than in the QP::QMsm-style implementation strategy. The @ref game application provides an example of application-level classes deriving from QP::QActive and QP::QHsm (see [6] and [7]).
3 The abstract QP::QMsm class (QM State Machine) derives from QP::QHsm and implements the fastest and the most efficient strategy for coding hierarchical state machines, but this strategy designed for **automatic code generation** by the QM model-based design tool. The resulting code is still highly human-readable, but is not designed to be maintained by humans. The QP::QMsm class is abstract, meaning that it cannot be instantiated directly, but rather serves only as the base class for inheritance.@n NOTE: Please refer to Section @ref sm for information on how to code hierarchical state machines with QP/C++.
4 The abstract QP::QMActive class represents an active object that uses the QP::QMsm state machine implementation strategy. This strategy requires the use of the QM modeling tool to generate state machine code automatically, but the code is faster than in the QP::QHsm style implementation strategy and needs less run-time support (smaller event-processor).
5 The QP::QTimeEvt class represents time events in QP. **Time events** are special QP events equipped with the notion of time passage. The basic usage model of the time events is as follows. An active object allocates one or more QP::QTimeEvt objects (provides the storage for them). When the active object needs to arrange for a timeout, it arms one of its time events to fire either just once (one-shot) or periodically. Each time event times out independently from the others, so a QP application can make multiple parallel timeout requests (from the same or different active objects). When QP detects that the appropriate moment has arrived, it inserts the time event directly into the recipient's event queue. The recipient then processes the time event just like any other event.
6 Active Objects in the application derive either from the QP::QActive or QP::QMActive base class.
7 Applications can also use classes derived directly from the QP::QHsm or QP::QMsm base classes to represent "raw" state machines that are not active objects, because they don't have event queue and execution thread. Such "raw" state machines are typically used as "Orthogonal Components".
8 Application-level events with parameters derive from the QP::QEvt class.

@anchor sm_MI @attention The QP/C++ implementation of state machines is not compatible with Multiple Inheritance (MI) in C++. In other words, all subclasses of QP::QHsm (which includes subclasses of QP::QMsm, QP::QActive, and QP::QMActive) should use only *single inheritance*. @remark Multiple inheritance exposes the interface of all listed base classes. This is most likely incorrect with respect to state machine classes, because they should be used exclusively through the event-driven state machine interface (init(), dispatch()). State machines should only be known to the outside clients as opaque state machines and NOT as any other "mix-in" class. This is because interacting with state machines, and especially with active objects (encapsulated state machines), by any other means than events breaks the encapsulation for concurrency. ------------------------------------------------------------------------------ @section hsm Hierarchical State Machines The behavior of each active object in QP/C++ is specified by means of a **hierarchical state machine** (UML statechart), which is the most effective and elegant technique of describing event-driven behavior. The most important innovation of UML state machines over classical finite state machines (FSMs) is the hierarchical state nesting. The value of state nesting lies in avoiding repetitions, which are inevitable in the traditional "flat" FSM formalism and are the main reason for the "state-transition explosion" in FSMs. The semantics of state nesting allow substates to define only the differences of behavior from the superstates, thus promoting sharing and reusing behavior. @htmlonly

Application Note: A Crash Course in UML State Machines

@endhtmlonly The Quantum Leaps Application Note A Crash Course in UML State Machines introduces the main state machine concepts backed up by examples.

@note The hallmark of the QP/C++ implementation of UML state machines is **traceability**, which is direct, precise, and unambiguous mapping of every state machine element to human readable, portable, MISRA compliant C++ code. Preserving the traceability from requirements through design to code is essential for mission-critical systems, such as medical devices or avionic systems. ------------------------------------------------------------------------------ @section coding Coding Standard The QP/C++ framework has been developed in strict adherence to the documented Quantum Leaps Coding Standard. @htmlonly

Application Note: Quantum Leaps C/C++ Coding Standard

@endhtmlonly ------------------------------------------------------------------------------ @section misra MISRA Compliance

The QP/C++ framework complies with most of the Motor Industry Software Reliability Association (MISRA) MISRA-C++:2008 rules.

@htmlonly

Application Note: QP/C++ MISRA-C++:2008 Compliance Matrix

@endhtmlonly All deviations are carefully limited into very specific contexts and are documented with the Application Note: QP/C++ MISRA-C++:2008 Compliance Matrix. @note MISRA and MISRA C++ are registered trademarks of MIRA Ltd, held on behalf of the MISRA Consortium. The MISRA guidelines place great emphasis on the use of static code analysts tools to check compliance with the MISRA-C++ language subset. To this end, QP/C++ comes with an extensive support for automatic rule checking with @ref lint "PC-Lint". The QP frameworks go even beyond MISRA, by complying with the strict type checking of PC-Lint. ------------------------------------------------------------------------------ @section pc-lint PC-Lint Support The QP/C++ framework comes with extensive support for automatic rule checking by means of PC-Lint, which is designed not just for proving compliance of the QP/C++ framework code, but more importantly, to aid in checking compliance of the application-level code. Any organization engaged in designing safety-related embedded software could benefit from the unprecedented quality infrastructure built around the QP/C++ framework. @sa @ref lint "Lint Port" @next{sm} */ /*##########################################################################*/ /*! @dir ../include Platform-independent QP/C++ API @note The QP/C include directory needs to be added to the compiler's include path in the applications using QP/C. */ /*##########################################################################*/ /*! @dir ../src Platform-independent QP/C++ source code Files from this directory need to be added to the project, to build the QP/C++ framework from source code. @note The QP/C src directory needs to be added to the compiler's include path in the applications that build QP/C framework from sources (as opposed to using QP as a pre-built library). */ /*##########################################################################*/ /*! @dir ../src/qf Platform-independent implementation of the @ref qep and @ref qf components. @note Typically, files in this directory need to be added to the application build, but some QP ports might not need all the files in this directory. For example, a QP port to a 3rd-party RTOS kernel might be using a message queue of the RTOS instead of the native QP event queue, in which case the file qf_actq.c would not be needed and should be excluded from the build. */ /*##########################################################################*/ /*! @dir ../src/qv Platform-independent implementation of the @ref qv built-in kernel. @attention Files in this directory need to be included in the QP application build only if the application uses the @ref qv kernel. */ /*##########################################################################*/ /*! @dir ../src/qk Platform-independent implementation of the @ref qk built-in kernel. @attention Files in this directory need to be included in the QP application build only if the application uses the @ref qk kernel. */ /*##########################################################################*/ /*! @dir ../src/qxk Platform-independent implementation of the @ref qxk built-in kernel. @attention Files in this directory need to be included in the QP application build only if the application uses the @ref qxk kernel. */ /*##########################################################################*/ /*! @dir ../src/qs Platform-independent implementation of the @ref qs component (software tracing). */ } // namespace QP