8.0.2

Author: quantum-leaps

LICENSES/LicenseRef-QL-dual.qlc

@@ -9,8 +9,8 @@ Copyright (C) 2005 Quantum Leaps, LLC. All rights reserved.
 
 SPDX-License-Identifier: GPL-3.0-or-later OR LicenseRef-QL-commercial
 
-The QP/C++ software is dual-licensed under the terms of the open-source
-GNU General Public License (GPL) or under the terms of one of the closed-
+This software is dual-licensed under the terms of the open-source GNU
+General Public License (GPL) or under the terms of one of the closed-
 source Quantum Leaps commercial licenses.
 
 Redistributions in source code must retain this top-level comment block.
@@ -25,4 +25,4 @@ closed-source distribution.
 Quantum Leaps contact information:
 <www.state-machine.com/licensing>
 <[email protected]>
-#48B37CF39D4FD9DE279250B31FD388AFD0BE9B40
+#E73B85325051C864FE0E4C672EF7577CB16A80DA

README.md

@@ -16,6 +16,39 @@ git clone https://github.com/QuantumLeaps/qpcpp --recurse-submodules --depth 1
 Alternatively, you can also download one of the stable
 [QP/C++ Releases][QP-Rel].
 
+# About QP/C++ Real-Time Embedded Framework
+QP/C++ real-time embedded framework (RTEF) is a lightweight implementation of
+the [Active Object (a.k.a. Actor) model of computation][AOmod] specifically
+tailored for deeply embedded real-time systems, such as microcontrollers (MCUs).
+QP/C++ is both a software infrastructure for building applications consisting
+of Active Objects (Actors) and a runtime environment for executing the Active
+Objects in a deterministic, real-time fashion. Additionally, QP/C++ Framework
+supports Hierarchical State Machines with which to specify the behavior of
+Active Objects [UML 2.5], [Sutter:10], [ROOM:94]. The QP/C++ Framework can be
+viewed as a modern, asynchronous, and truly event driven real-time operating
+system (RTOS).
+
+## QP Framework Family
+QP/C++ framework is part of the larger QP family consisting of the following
+QP editions:
+
+|QP Edition |  Language   |      API         | Safety Functions   |Certification Artifacts| Licensing
+|:----------|:-----------:|:-----------------|:-------------------|:----------------|:---------
+| QP/C      | C (C11)     |same as SafeQP/C  |Selected Assertions |Req/Arch/Design  | [dual][Lic]
+| SafeQP/C  | C (C11)     |same as QP/C      |All Safety Functions|Certification Kit| [commercial][Com]
+| QP/C++    | C++ (C++17) |same as SafeQP/C++|Selected Assertions |Req/Arch/Design  | [dual][Lic]
+| SafeQP/C++| C++ (C++17) |same as QP/C++    |All Safety Functions|Certification Kit| [commercial][Com]
+
+[The documentation](#documentation) of all QP editions includes the
+[Requirements][SRS], [Architecture][SAS], and [Design Specifications][SDS],
+which are the best source of information about the underlying concepts,
+functionality, architecture, and design of the QP Frameworks and the QP
+Applications based on the frameworks.
+
+> **NOTE:** The **SafeQP** frameworks additionally contain **Safety Functions**
+required to achieve the higher safety integrity levels and come with much more
+extensive [Certification Kits][Cert].
+
 
 # Getting Started with QP/C++
 The most recommended way of obtaining QP/C++ is by downloading the
@@ -25,7 +58,7 @@ The main advantage of obtaining QP/C++ bundled together like that is
 that you get all components, tools and examples ready to go.
 
 ### Getting Started Resources
-- ["QP/C++ Tutorial"][Tutorial]
+- ["QP/C++ Tutorial"][Tut]
 describes a series of progressively advanced QP/C++ example applications.
 
 - [Video: "Getting Started with QP Real-Time Embedded Frameworks"][Video]
@@ -67,69 +100,11 @@ have been **removed from the open-source GPL distribution**:
 the active Support Term. Please contact [Quantum Leaps technical support][Sup]
 to get the complete QP/C++ framework distribution.
 
-> NOTE: To request **evaluation** of the complete QP/C++ framework, please contact
+> **NOTE:** To request **evaluation** of the complete QP/C++ framework, please contact
 Quantum Leaps at: https://www.state-machine.com/contact
 
-# About QP/C++
-QP/C++ (Quantum Platform in C++) is a lightweight, open source
-[Real-Time Embedded Framework (RTEF)][RTEF] for building modern embedded
-software as systems of asynchronous, event-driven [Active Objects][Active]
-(actors). The [QP/C++] framework is a member of a [QP] family consisting of
-[QP/C++] and [QP/C] frameworks, which are strictly quality controlled,
-thoroughly documented, and [commercially licensable][Lic].
-
-## Safer Model of Concurrency
-The [QP] framework family implements the
-[Active Object model of computation][AO_model], which is **inherently safer**
-than the traditional "shared state concurrency" based on explicit mutual
-exclusion and managing RTOS threads by blocking. The Active Object model
-supports and automatically enforces the following best practices
-of concurrent programming:
-
-- Keep data isolated and bound to Active Objects' threads. Threads should
-hide (**encapsulate**) their private data and other resources, and not
-share them with the rest of the system.
-
-- Communicate among Active Object threads **asynchronously** via [Event
-objects][Event]. Using asynchronous events keeps the threads running truly
-independently, **without blocking** on each other.
-
-- Active Object threads should spend their lifetime responding to incoming
-events, so their mainline should consist of an **event-loop** that handles
-events one at a time (to completion), thus avoiding any concurrency hazards
-within an Active Object thread itself.
-
-This architecture also provides higher level of abstraction and the *correct*
-abstractions to effectively apply [Hierarchical State Machines][HSM],
-**modeling** and **code generation** to deeply embedded real-time systems.
-
-## Hierarchical State Machines
-The behavior of Active Objects is specified in QP/C++ by means of
-[Hierarchical State Machines][HSM] (UML statecharts). The framework
-supports manual coding of UML state machines in C as well as automatic
-**code generation** by means of the free [QM modeling tool][QM].
-
-## Built-in Real-Time Kernels
-The QP/C++ framework can run on standalone on single-chip microcontrollers,
-without any traditional RTOS. The framework contains a selection of
-**built-in real-time kernels**, such as the [non-preemptive QV kernel][QV],
-the [preemptive non-blocking QK kernel][QK], and the preemptive,
-[dual-mode QXK kernel][QXK] that provides all the features you might expect
-from a traditional RTOS. Native QP ports and ready-to-use examples are provided
-for major CPUs, such as ARM Cortex-M (M0/M0+/M3/M4/M7/M23/M33/...).
-
-## Traditional RTOS/OS
-QP/C++ can also work with a traditional RTOS, such as ThreadX, embOS, FreeRTOS,
-uC/OS-II and Zephyr, as well as with (embedded) Linux (POSIX) and Windows.
-
-## Popularity and Maturity
-With 20 years of continuous development, [400+ commercial licensees][Cust],
-and many times more open source users worldwide, the QP frameworks are the
-most popular such offering on the market. They power countless electronic
-products ranging from implantable medical devices to complex weapon systems.
-
-
-# QP/C++ Documentation
+
+# Documentation
 The online HTML documentation for the **latest** version of QP/C++ is located
 at: https://www.state-machine.com/qpcpp
 
@@ -159,20 +134,25 @@ If you like this project, please give it a star (in the upper-right corner of yo
    [QP]:     <https://www.state-machine.com/products/qp>
    [QP/C]:   <https://github.com/QuantumLeaps/qpc>
    [QP/C++]: <https://github.com/QuantumLeaps/qpcpp>
-   [QS/C++]: <https://www.state-machine.com/qpcpp/srs-qp_qs.html>
-   [QV]:     <https://www.state-machine.com/qpcpp/srs-qp_qv.html>
-   [QK]:     <https://www.state-machine.com/qpcpp/srs-qp_qk.html>
-   [QXK]:    <https://www.state-machine.com/qpcpp/srs-qp_qxk.html>
+   [Cert]:   <https://www.state-machine.com/products/qp#CERT>
    [QM]:     <https://github.com/QuantumLeaps/qm>
    [QTools]: <https://github.com/QuantumLeaps/qtools>
-   [QP-Rel]: <https://github.com/QuantumLeaps/qpcpp/releases>
-   [Active]: <https://www.state-machine.com/qpcpp/srs-qp_ao.html>
-   [AO_model]: <https://www.state-machine.com/qpcpp/srs-qp_ao.html#srs-qp_ao-model>
-   [Event]:  <https://www.state-machine.com/qpcpp/srs-qp_evt.html>
-   [HSM]:    <https://www.state-machine.com/qpcpp/srs-qp_sm.html>
    [Lic]:    <https://www.state-machine.com/licensing>
+   [Com]:    <https://www.state-machine.com/licensing#Commercial>
    [Cust]:   <https://www.state-machine.com/customers>
    [Sup]:    <mailto:[email protected]>
    [AN]:     <https://www.state-machine.com/doc/AN_Getting_Started_with_QP.pdf>
-   [Tutorial]: <https://www.state-machine.com/qpcpp/gs_tut.html>
    [Video]:  <https://youtu.be/O7ER6_VqIH0>
+   [QS]:     <https://www.state-machine.com/qpcpp/srs-qp_qs.html>
+   [QV]:     <https://www.state-machine.com/qpcpp/srs-qp_qv.html>
+   [QK]:     <https://www.state-machine.com/qpcpp/srs-qp_qk.html>
+   [QXK]:    <https://www.state-machine.com/qpcpp/srs-qp_qxk.html>
+   [SRS]:    <https://www.state-machine.com/qpcpp/srs-qp.html>
+   [SAS]:    <https://www.state-machine.com/qpcpp/sas-qp.html>
+   [SDS]:    <https://www.state-machine.com/qpcpp/sds-qp.html>
+   [Active]: <https://www.state-machine.com/qpcpp/srs-qp_ao.html>
+   [AOmod]:  <https://www.state-machine.com/qpcpp/srs-qp_ao.html#srs-qp_ao-model>
+   [Event]:  <https://www.state-machine.com/qpcpp/srs-qp_evt.html>
+   [HSM]:    <https://www.state-machine.com/qpcpp/srs-qp_sm.html>
+   [Tut]:    <https://www.state-machine.com/qpcpp/gs_tut.html>
+   [QP-Rel]: <https://github.com/QuantumLeaps/qpcpp/releases>

examples

@@ -1,10 +1,6 @@
-//$file${include::qequeue.hpp} vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
-//
-// Model: qpcpp.qm
-// File:  ${include::qequeue.hpp}
-//
-// This code has been generated by QM 7.0.0 <www.state-machine.com/qm>.
-// DO NOT EDIT THIS FILE MANUALLY. All your changes will be lost.
+//============================================================================
+// QP/C++ Real-Time Embedded Framework (RTEF)
+// Version 8.0.2
 //
 // Copyright (C) 2005 Quantum Leaps, LLC. All rights reserved.
 //
@@ -14,8 +10,8 @@
 //
 // SPDX-License-Identifier: GPL-3.0-or-later OR LicenseRef-QL-commercial
 //
-// The QP/C++ software is dual-licensed under the terms of the open-source
-// GNU General Public License (GPL) or under the terms of one of the closed-
+// This software is dual-licensed under the terms of the open-source GNU
+// General Public License (GPL) or under the terms of one of the closed-
 // source Quantum Leaps commercial licenses.
 //
 // Redistributions in source code must retain this top-level comment block.
@@ -30,8 +26,7 @@
 // Quantum Leaps contact information:
 // <www.state-machine.com/licensing>
 // <[email protected]>
-//
-//$endhead${include::qequeue.hpp} ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+//============================================================================
 #ifndef QEQUEUE_HPP_
 #define QEQUEUE_HPP_
 
@@ -46,17 +41,16 @@ namespace QP {
 #elif (QF_EQUEUE_CTR_SIZE == 2U)
     using QEQueueCtr = std::uint16_t;
 #else
-    #error "QF_EQUEUE_CTR_SIZE defined incorrectly, expected 1U or 2U"
+    #error QF_EQUEUE_CTR_SIZE defined incorrectly, expected 1U or 2U
 #endif
 
 class QEvt; // forward declaration
 
 } // namespace QP
 
-//$declare${QF::QEQueue} vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
+//============================================================================
 namespace QP {
 
-//${QF::QEQueue} .............................................................
 class QEQueue {
 private:
     QEvt const * volatile m_frontEvt;
@@ -65,22 +59,6 @@ class QEQueue {
     QEQueueCtr volatile m_head;
     QEQueueCtr volatile m_tail;
     QEQueueCtr volatile m_nFree;
-
-#ifndef Q_UNSAFE
-    std::uintptr_t m_frontEvt_dis;
-#endif // ndef Q_UNSAFE
-
-#ifndef Q_UNSAFE
-    QEQueueCtr m_head_dis;
-#endif // ndef Q_UNSAFE
-
-#ifndef Q_UNSAFE
-    QEQueueCtr m_tail_dis;
-#endif // ndef Q_UNSAFE
-
-#ifndef Q_UNSAFE
-    QEQueueCtr m_nFree_dis;
-#endif // ndef Q_UNSAFE
     QEQueueCtr m_nMin;
 
     // friends...
@@ -97,16 +75,10 @@ class QEQueue {
         m_head(0U),
         m_tail(0U),
         m_nFree(0U),
-    #ifndef Q_UNSAFE
-        m_frontEvt_dis(static_cast<std::uintptr_t>(~0U)),
-        m_head_dis(static_cast<QEQueueCtr>(~0U)),
-        m_tail_dis(static_cast<QEQueueCtr>(~0U)),
-        m_nFree_dis(static_cast<QEQueueCtr>(~0U)),
-    #endif
         m_nMin(0U)
     {}
     void init(
-        QEvt const * qSto[],
+        QEvt const * * const qSto,
         std::uint_fast16_t const qLen) noexcept;
     bool post(
         QEvt const * const e,
@@ -120,11 +92,7 @@ class QEQueue {
         return m_nFree;
     }
     QEQueueCtr getNMin() const noexcept {
-        #ifndef Q_UNSAFE
         return m_nMin;
-        #else
-        return 0U;
-        #endif
     }
     bool isEmpty() const noexcept {
         return m_frontEvt == nullptr;
@@ -133,9 +101,11 @@ class QEQueue {
 private:
     QEQueue(QEQueue const & other) = delete;
     QEQueue & operator=(QEQueue const & other) = delete;
+    void postFIFO_(
+        QEvt const * const e,
+        void const * const sender);
 }; // class QEQueue
 
 } // namespace QP
-//$enddecl${QF::QEQueue} ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 #endif // QEQUEUE_HPP_