8.1.0

Author: quantum-leaps

.gitignore

@@ -1,4 +1,7 @@
 *.qms
+*.cov
+*.gcov
+*.log
 *.obj
 *.o
 *.d
@@ -29,17 +32,37 @@
 *.chw
 *.sfr
 *.ewt
+*.csv
 *.user
 *.avrsuo
 *.Debug
 *.Release
 *.bak
 version-*
 JLink*.*
+*.host
+*.trg
+
+dbg/
+rel/
+spy/
+build*/
+settings/
+.settings/
+targetConfigs/
+Debug/
+Release/
+Spy/
+QSpy/
+
+lib/
+obj/
+output/
 
 include/qs.h
 include/qs_pkg.h
 include/qxk.h
+
 src/qs/qs.c
 src/qs/qs_64bit.c
 src/qs/qs_fp.c
@@ -49,29 +72,14 @@ src/qxk/qxk.c
 src/qxk/qxk_mutex.c
 src/qxk/qxk_sema.c
 src/qxk/qxk_xthr.c
-zephyr/qutest_port.c
 
 ports/arm-cm/qxk/
 ports/arm-cm/qutest/
 ports/posix-qutest/
 ports/win32-qutest/
+zephyr/qutest_port.c
 
-priv/
-html/
-latex/
-dbg/
-rel/
-spy/
-build*/
-settings/
-.settings/
-targetConfigs/
-
-Debug/
-Release/
-Spy/
-QSpy/
+static-analysis/pclp/
 
-lib/
-obj/
-output/
+tests/TIN*/
+tests/TUN*/

3rd_party

@@ -13,8 +13,10 @@ it is recommended that you clone this repo like that:
 git clone https://github.com/QuantumLeaps/qpc --recurse-submodules --depth 1
 ```
 
-Alternatively, you can also download one of the stable
-[QP/C Releases][QP-Rel].
+However, the easiest and most recommended way of
+[getting started with QP/C](#getting-started-with-qpc) is to download
+the QP-bundle, as [described below](#getting-started-with-qpc).
+
 
 # About QP/C Real-Time Event Framework
 QP/C real-time event framework (RTEF) is a lightweight implementation of
@@ -25,56 +27,94 @@ 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
+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/C framework is part of the larger QP family, consisting of the following
+QP editions (please also see [__QP Frameworks Feature Comparison__](https://www.state-machine.com/products/qp#Features)
+):
 
 |QP Edition |  Language   |      API         | Safety Functions   |Certification Artifacts| Licensing
 |:----------|:-----------:|:-----------------|:-------------------|:----------------|:---------
-| QP/C      | C (C11)     |same as SafeQP/C  |Selected Assertions |Req/Arch/Design  | [dual][Lic]
-| QP/C++    | C++ (C++17) |same as SafeQP/C++|Selected Assertions |Req/Arch/Design  | [dual][Lic]
-| SafeQP/C  | C (C11)     |same as QP/C      |All Safety Functions|Extensive<br>Certification Kit| [commercial][Com]
-| SafeQP/C++| C++ (C++17) |same as QP/C++    |All Safety Functions|Extensive<br>Certification Kit| [commercial][Com]
+| QP/C      | C (C11)     |same as<br>SafeQP/C  |Selected Assertions |Req/Arch/Design  | [open-source & commercial][Lic]
+| QP/C++    | C++ (C++17) |same as<br>SafeQP/C++|Selected Assertions |Req/Arch/Design  | [open-source & commercial][Lic]
+| SafeQP/C  | C (C11)     |same as<br>QP/C      |All Safety Functions|[SafeQP/C<br>Certification Kit][CERT-KIT]| [commercial][Com]
+| SafeQP/C++| C++ (C++17) |same as<br>QP/C++    |All Safety Functions|[SafeQP/C++<br>Certification Kit][CERT-KIT]| [commercial][Com]
 
 The **SafeQP/C** and **SafeQP/C++** frameworks were originally derived from QP/C and QP/C++,
 respectively, but were extensively reengineered for the safety market using compliant
 Software Safety Lifecycle (SSL). In this process, the QP framework functional model has been
 subjected to a full Hazard and Risk Analysis, which identified all areas of weakness within
-the functional model and API. These findings led to creation of Safety Requirements and risk
+the functional model and API. These findings led to the creation of Safety Requirements and risk
 mitigation by Safety Functions, which were subsequently implemented, verified, and validated.
 The SafeQP frameworks are accompanied by the "SafeQP Certification Kits", which provide
 developers with ready-to-use artifacts, enabling them to save time, mitigate risk, and reduce
 costs during application certification for safety-critical devices in the industrial, medical,
 aerospace, and automotive industries. Please [contact Quantum Leaps](#contact-information)
 for more information about the SafeQP frameworks and the "Certification Kits".
 
-> **NOTE:** The SafeQP/C edition remain fully API- and functionally compatible with the
+> **NOTE:** The SafeQP/C edition remains fully API- and functionally compatible with the
 corresponding standard QP/C framework. This ensures existing QP/C Applications can transition
-seamlessly to SafeQP/C without requiring any modifications. SafeQP/C edition retain QP/C
-Frameworks' hallmark features, including a small memory footprint, excellent efficiency,
-and hard real-time functionality.
+seamlessly to SafeQP/C without requiring any modifications. SafeQP/C edition retains QP/C
+Frameworks' hallmark features: a small memory footprint, excellent efficiency, and hard
+real-time performance.
 
 
 # Getting Started with QP/C
-The most recommended way of obtaining QP/C is by downloading the
-[QP-bundle](https://www.state-machine.com/#Downloads), which includes QP/C
-as well as the [QM modeling tool][QM] and the [QTools collection][QTools].
-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"][Tut]
-describes a series of progressively advanced QP/C example applications.
-
+The most recommended way to get started with QP/C is by
+[__downloading the QP-bundle__](https://www.state-machine.com/#Downloads),
+which includes QP/C as well as the [QM modeling tool][QM] and the
+[QTools collection][QTools]. The main advantage of obtaining QP/C bundled
+together is that you get all components, tools, and _examples_ all ready to go.
+
+> **NOTE:**
+Perhaps the most important fact to remember is that in embedded systems,
+nothing works until everything works. This means that you should always start
+with a _working system_ and gradually evolve it, changing one thing at a time
+and making sure that it keeps working every step of the way.
+
+The provided [__QP/C example projects__](examples), such as the super-simple
+[Blinky](examples/arm-cm/blinky_nucleo-u545re/), or a bit more advanced
+[Dining Philosophers Problem (DPP)](examples/arm-cm/dpp_nucleo-u545re/),
+allow you to get started with a __working project__ rather than starting from
+scratch. You should also always try one of the unmodified examples on one
+of the very inexpensive evaluation boards (such as
+[STM32 NUCLEO-U545RE](examples/arm-cm/dpp_nucleo-u545re/stm32-nucleo-u545re.webp))
+that it was designed for, _before_ attempting to immediately adapt the projects
+to your specific hardware. Only once an example project is built and runs on
+the evaluation board, can you use it as a starting point for your specific hardware
+and software development.
+
+
+## Getting Started Resources
 - [Video: "Getting Started with QP Real-Time Event Frameworks"][Video]
 provides instructions on how to download, install, and get started with QP.
 
 - [AppNote: "Getting Started with QP Real-Time Event Frameworks"][AN]
 contains also a tutorial, in which you build a simple "Blinky" application.
 
+- ["QP/C Tutorial"][Tut]
+describes a series of progressively advanced QP/C example applications.
+
+## QP/C Extras
+The open source GPL distribution of QP/C can be augmented by the
+["QP/C Extras"][QPX/C], which provide more advanced QP/C features, such as:
+- [QS software tracing][QS] component (QP Spy)
+- [QXK real-time kernel][QXK] component
+- Static-analysis configuration and automation scripts for PC-Lint-Plus (MISRA-C:2025 compliance)
+- Test suite (based on the [QUTest trace-based test harness][QUTest])
+that demonstrates 100% lines of code and 100% MC/DC code coverage for QP/C.
+
+> **NOTE:** The ["QP/C Extras"][QPX/C] are [licensed commercially][Lic] only
+and available to the commercial licensees with the active Support Term. Please contact
+[Quantum Leaps technical support][Sup] to get the matching ["QP/C Extras"][QPX/C]
+for the public QP/C version.
+
+> **NOTE:** The ["QP/C Extras"][QPX/C] are also __available for evaluation__
+([upon request][ReqForm]).
+
+
 # Licensing
 The QP/C real-time event framework is licensed under the
 [dual licensing model](https://www.state-machine.com/licensing), with
@@ -101,21 +141,6 @@ any open source license and you do not violate your policy.
 are licensed commercially only.
 
 
-## Files Removed from the QP/C Open Source GPL Distribution
-Due to the widespread non-compliance with the GPL, as well as infringement on the
-[dual-licensing model of QP frameworks][Lic], the following QP/C components
-have been **removed from the open-source GPL distribution**:
-- QS target-resident software tracing component
-- QXK dual-mode kernel
-
-> NOTE: These components are available to the [commercial licensees][Cust] with
-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
-Quantum Leaps at: https://www.state-machine.com/contact
-
-
 # Documentation
 The online HTML documentation for the **latest** version of QP/C is located
 at: https://www.state-machine.com/qpc
@@ -126,7 +151,7 @@ To view the offline documentation, open the file [html/index.html](html/index.ht
 in your web browser.
 
 
-# Contact Information
+# Support & Contact Information
 - [Free Support Forum](https://sourceforge.net/p/qpc/discussion/668726)
 - [Bug Reports](https://sourceforge.net/p/qpc/bugs/)
 - [Feature Requests](https://sourceforge.net/p/qpc/feature-requests/)
@@ -146,11 +171,15 @@ 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>
-   [Cert]:   <https://www.state-machine.com/products/qp#CERT>
+   [QPX/C]:  <https://www.state-machine.com/qpc/gs_extras.html>
+   [QPX/C++]:  <https://www.state-machine.com/qpcpp/gs_extras.html>
+   [CERT-KIT]: <https://www.state-machine.com/products/qp#CERT-KIT>
    [QM]:     <https://github.com/QuantumLeaps/qm>
    [QTools]: <https://github.com/QuantumLeaps/qtools>
+   [QUTest]: <https://www.state-machine.com/qtools/qutest.html>
    [Lic]:    <https://www.state-machine.com/licensing>
    [Com]:    <https://www.state-machine.com/licensing#Commercial>
+   [ReqForm]: <https://www.state-machine.com/licensing#RequestForm>
    [Cust]:   <https://www.state-machine.com/customers>
    [Sup]:    <mailto:[email protected]>
    [AN]:     <https://www.state-machine.com/doc/AN_Getting_Started_with_QP.pdf>

README.md

@@ -46,13 +46,13 @@ struct QEvt; // forward declaration
 //============================================================================
 //! @class QEQueue
 typedef struct QEQueue {
-    struct QEvt const * volatile frontEvt; //!< @private @memberof QEQueue
-    struct QEvt const * * ring;            //!< @private @memberof QEQueue
-    QEQueueCtr end;                        //!< @private @memberof QEQueue
-    QEQueueCtr volatile head;              //!< @private @memberof QEQueue
-    QEQueueCtr volatile tail;              //!< @private @memberof QEQueue
-    QEQueueCtr volatile nFree;             //!< @private @memberof QEQueue
-    QEQueueCtr nMin;                       //!< @private @memberof QEQueue
+    struct QEvt const *frontEvt;   //!< @private @memberof QEQueue
+    struct QEvt const * *ring;     //!< @private @memberof QEQueue
+    QEQueueCtr end;                //!< @private @memberof QEQueue
+    QEQueueCtr head;               //!< @private @memberof QEQueue
+    QEQueueCtr tail;               //!< @private @memberof QEQueue
+    QEQueueCtr nFree;              //!< @private @memberof QEQueue
+    QEQueueCtr nMin;               //!< @private @memberof QEQueue
 } QEQueue;
 
 //! @public @memberof QEQueue
@@ -76,18 +76,15 @@ struct QEvt const * QEQueue_get(QEQueue * const me,
     uint_fast8_t const qsId);
 
 //! @public @memberof QEQueue
-static inline QEQueueCtr QEQueue_getNFree(QEQueue const * const me) {
-    return me->nFree;
-}
+uint16_t QEQueue_getFree(QEQueue const * const me);
 
 //! @public @memberof QEQueue
-static inline QEQueueCtr QEQueue_getNMin(QEQueue const * const me) {
-    return me->nMin;
-}
+uint16_t QEQueue_getUse(QEQueue const * const me);
 
 //! @public @memberof QEQueue
-static inline bool QEQueue_isEmpty(QEQueue const * const me) {
-    return me->frontEvt == (struct QEvt *)0;
-}
+uint16_t QEQueue_getMin(QEQueue const * const me);
+
+//! @public @memberof QEQueue
+bool QEQueue_isEmpty(QEQueue const * const me);
 
 #endif // QEQUEUE_H_