The main purpose of this release is the update the `Makefiles` that use the [GNU-ARM Embedded Toolchain](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm) to match the recent update in [QTools for Windows 6.3.8](https://sourceforge.net/projects/qpc/files/QTools/). Specifically, all `Makefiles` in the `examples` directory have been updated to use the GNU-ARM toolchain located in `qtools\gnu_arm-none-eabi` and use the tools prefix **arm-none-eabi-**.
The `Makefiles` that use the GNU-ARM included in this release require [QTools for Windows version 6.3.8 or newer](https://sourceforge.net/projects/qpc/files/QTools/) and will **NOT** work with the older QTools collection.
The main goal of this release is to provide Python test scripts that match the newly re-designed Python support for the [QUTest unit testing harness](https://www.state-machine.com/qtools/qutest.html) (see QTools **6.3.7**). Specifically, the Python tests scripts (*.py files) in the `qpcpp/examples/qutest` directory) have been all upgraded to the new syntax and format. Also, all the makefiles in that directory have been modified to execute Python test scripts by default, and Tcl test scripts only when the argument `SCRIPTS=tcl` is specified.
@note
The new scripting interface [qutest.py](https://www.state-machine.com/qtools/qutest_script.html) is now the primary supported QUTest scripting interface. The older interfaces, such as TCL ("qutest.tcl") and "qspypy" are considered *obsolete* and are **not recommended** for writing new test scripts.
The second change in this release is updating the QP ports to Win32 and POSIX to eliminate the obsolete function `gethostbyname()` and replacing it with `getaddrinfo()`. This change has ripple effects on Windows, because it requires linking with "ws2_32" library, instead of "wsock2". All affected `Makefiles` in the `qpcpp\examples\` directory have been updated to link the newer "ws2_32" library.
Finally, this release updates the internal implementation of QXK function `QXThread::post_()` for software tracing and testing with QUTest.
This release brings important changes and improvements to the unit-testing support for [QUTest](https://www.state-machine.com/qtools/qutest.html). Specifically, a new "dummy" active object class ::QActiveDummy for testing has been added. Instances of this "dummy" AO can be now used as test-doubles for active objects that are recipients of events directly posted by the active object under test (AOUT). This, in turn, eliminates the need to alter the existing event-posting implementation, so that more of the actual QP code can be used in the QP test-stub (qutest.c).
@note
The QUTest projects that are built QP from sources need to include the qf_time.cpp file.
As a consequence of the changes in the [QUTest](https://www.state-machine.com/qtools/qutest.html) support, the @ref exa_qutest "QUTest examples" have been re-designed and improved. Here, the most important changes include the new code organization, which reflects the customary separation of the code-under-test (CUT) from the code for testing. Also, the tests based on the ["TDD book" by James Grenning](https://www.amazon.com/Driven-Development-Embedded-Pragmatic-Programmers/dp/193435662X) have been replaced with fully functional tests based on the [Unity testing framework](http://www.throwtheswitch.org/unity/). This is to directly compare the traditional approach (Unity) with QUTest.
The next change related to unit testing is adding ::QS_RX_QUERY_CURR facility to QS-RX (software tracing input channel) and the reply ::QS_QUERY_DATA to the QS output channel. These two extensions allow you to query the status of the "current object" inside the target. The most important example is querying the current state-machine object (::SM_OBJ), which returns the **current state**.
@note
The new "query" facilities in QP/C++ match the latest additions to the [QSPY host application](https://www.state-machine.com/qtools/qspy.html).
Also this release adds [QS dictionary](https://www.state-machine.com/qtools/qs.html#qs_dict) generation for all registered event pools. The generated object dictionaries are `EvtPool1` for pool-1, `EvtPool2` for pool-2, etc.
@note
Applications no longer need to generate QS object dictionaries for the event pool storage buffers, such as `smlPoolSto[]`, etc.
Another big change in this release is re-designing of the @ref exa_os "examples for workstations" (previously `win32`, `win32-qv`, `posix` and `posix-qv`). All these types of examples have been consolidated in the @ref exa_os "exampes/workstation" folder, where the provided `Makefiles` have been extended to be cross-platform so that they work on Windows, Linux, and MacOS without changes.
To facilitate the creation of truly portable, cross-platform examples, the existing @ref ports_os "QP ports to Windows/POSIX" have been augmented with abstractions for portable console access. Also, the [QS software tracing](https://www.state-machine.com/qtools/qs.html) support via TCP/IP has been now added to the ports themselves. This means that applications no longer need to repeat the code for QS callbacks in the BSP implementation.
Finally, this release fixes a bug in the @ref posix-qv "POSIX-QV port", where the internal condition variable `QV_condVar_` has not been initialized.
This release adds new API QP::QTimeEvt::wasDisarmed() for checking the status of a QP::QTimeEvt object after it has been disarmed. Specifically, the status of the last call to QP::QTimeEvt::disarm() is kept inside the time event object and can be subsequently checked with the QP::QTimeEvt::wasDisarmed() API. This new function is designed to be used directly as a guard condition on the timeout event, as described in the [PSiCC2 book](/psicc2), Section 7.7.3 "Arming and Disarming a Time Event" on page 359. The QP::QTimeEvt::wasDisarmed() has a side effect of setting the "was disabled" status, so the guard evaluates to 'true' the next time it is checked.
This release adds Python test scripts to the QUTest examples (folder `qpcpp/examples/qutest`). Specifically, the makefiles have been augmented to accept symbol `SCRIPT=py`, in which case the Python test scripts (`*.py`) are used instead of the default Tcl test scripts (`*.tcl`).
@remark
This release does not change any QP/C++ APIs, QP/C++ implementation, ports, or other examples.
- [bug#215 "QP is internally inconsistent in calling assertion macros"](https://sourceforge.net/p/qpc/bugs/215/).
Also, this release improves the QUTest DPP example (directory `qpcpp/examples/qutest/dpp`) by demonstrating the proper use of QS_TEST_PAUSE() and the corresponding test scripts. This example now matches the [QUTest documentation of this feature](https://www.state-machine.com/qtools/qutest_rtc.html#qutest_pause).
Finally, this release modifies the QP/C++ ports to POSIX and POSIX-QV by allowing to configure the p-thread priority of the ticker thread. This is achieved by adding a `tickPrio` parameter to the `QF_setTickRate()` function. (**NOTE** this modification will require changing existing QP applications for POSIX or POSIX-QV that call `QF_setTickRate()`.
This release migrates the [QUTest](https://www.state-machine.com/qtools/qutest.html) examples to [QM 4.2.1](https://www.state-machine.com/qm/history.html#qm_4_2_1), which now can generate QS_FUN_DICTIONARY() records automatically. This release also adds a generic, simple blinky example for QUTest located in `examples/qutest/blinky`. Also, this release fixes the QF_INT_DISABLE() / QF_INT_ENABLE() macros in the QUTest ports to use the QP namespace. Without this fix, the code fails to compile when the directive "using namespace QP" is not used.
Also, this release adds the missing QS macro QS_SIG() to produce symbolic signal output from [application specific QS records](https://www.state-machine.com/qtools/qs.html#qs_app).
Finally, this release adjusts the code in qs_rx.cpp to use QF_EVT_REF_CTR_INC_() instead of accessing the event's reference counter directly. This direct access fails in case, when event constructors are configured (Q_EVT_CTOR is defined). In that case, the QP::QEvt class protects the reference counter, so it cannot be accessed directly. This option is currently used only in the QP/C++ port to Qt.
The main purpose of this release is fixing the sub-machine support in the QP/Spy build configuration. Specifically, this release fixes the following bug:
- [bug#213 "QP/C/C++ applications with submachines occasionally crash in Spy build configuration"](https://sourceforge.net/p/qpc/bugs/213/)
@attention
This release matches [QM 4.2.0](https://www.state-machine.com/qm/history.html#qm_4_2_0).
Additionally, the release contains some re-factoring of the QS-RX input channel.
The main purpose of this release is extednding the functionality of the [QUTest unit testing](https://www.state-machine.com/qtools/qutest.html) for QP/C++ applications. Specifically, this release adds support for testing of **self-posting** of events in active objects, which is an essential element in the [Reminder](https://www.state-machine.com/doc/Pattern_Reminder.pdf) and [Deferred Event](https://www.state-machine.com/doc/Pattern_DeferredEvent.pdf) design patterns. To implement this new feature, the QS-RX (QS receive channel) has been extened by a small scheduler that processes all secondary events gnenerated by dispatching, posting, or publishing events (only active when the #Q_UTEST macro is defined). Also, the implementation of the target resident QUTest components (file `src/qs/qutest.cpp` and `src/qf/qf_actq.cpp`) have been modified to allow posting of events during unit testing.
Additionally, the release adds standard QS trace records (the `qs.h` header file) for event deferring and recalling (::QS_QF_ACTIVE_DEFER and ::QS_QF_ACTIVE_RECALL) as well as recall-attempt (::QS_QF_ACTIVE_RECALL_ATTEMPT). Also standard QS trace records have been added for creating/deleting new event references (::QS_QF_NEW_REF and ::QS_QF_DELETE_REF, respectively). To make room for these new records, the following rarely-used records have been removed: QS_QF_ACTIVE_ADD, QS_QF_ACTIVE_REMOVE, QS_QF_EQUEUE_INIT, and QS_QF_MPOOL_INIT. The global filter settings in the QS_filterOn() and QS_filterOff() functions have been updated to the augmented and re-organized QS trace records.
@note
Because of the changes in the standard QS trace recods, this release requires the matching **QSPY 6.2.0** or later. Also, because of the changes this release might break some existing QUTest unit test scripts, which need to be re-adjusted to the new trace records.
Additionally, this release improves support for tracing and unit-testing embedded POSIX targets, such as embedded Linux, or OSes/RTOSes with the POSIX compatiblity layer. Specifically, the POSIX ports (`qpcpp/ports/posix/` and `qpcpp/ports/posix-qutest`) no longer produce libraries. Instead all examples for POSIX (`qpcpp/examples/posix/` and `qpcpp/ports/qutest`) build the QP/C framework directly from the sources, which promotes consisentcy in the toolchain and options used. For unit testing, `posix.mak` makefiles have been added for projects `qpcpp/examples/qutest/dpp` and `qpcpp/examples/qutest/self_test`. These makefiles support remote testing of embedded POSIX targets over TCP/IP, where the POSIX target runs only the test fixture, but the host (e.g., Windows host) executes both the QSPY host application and runs the QUTest scripts. The previous makefiles for POSIX have been renamed to `posix_host.mak`, because they are intended to use POSIX as a *host*, as opposed to a *target*.
Also, this release adds new QUTest exampes, which illustrate:
- event deferral (`qpcpp/examples/qutest/defer`)
- dispatching/posting events with parameters (`qpcpp/examples/qutest/evt_par`).
Additionally, this release updates the QP/C++ ports to win32-qv and posix-qv to allow a "tickless" mode, where the "tickerThread" is not created. This mode is set by configuring the system clock tick rate to 0 (QF_setTickRate(0)).
Finally, this release phases out the `qp_port.h` header file. If any of your projects still includes this file, please replace it with the qpc.h heder file.
The main purpose of this release is adding the context-switch callbacks to the preemptive @ref qk "QK" and @ref qxk "QXK" kernels. The QK_onContextSw() and QXK_onContextSw() callback functions provide a mechanism to perform additional custom operations when QK/QXK switches context from one thread to another. To avoid extra overhead when this functionality is not needed and for backwards-compatiblity with the existing applications, the callbacks are enabled only when the macros #QK_ON_CONTEXT_SW (for QK) and #QXK_ON_CONTEXT_SW (for QXK) are defined. These macros can be defined either directly in command-line for the compiler, or in the QK/QXK port files (qk_port.c for QK and qxk_port.c for QXK). Examples for the context-switch callbacks have been provided for for the @ref arm-cm_dpp_nucleo-l053r8 "NUCLEO-L053R8" (Cortex-M0+) and the @ref arm-cm_dpp_nucleo-h743zi "NUCLEO-H743ZI" (Cortex-M7).
Also, this release changes the ARM Cortex-M ports for the IAR-ARM toolchain in that it replaces the assembly modules with the equivalent C implementation. This change enables using the configuration macros #QK_ON_CONTEXT_SW (for QK) and QXK_ON_CONTEXT_SW (for QXK) in the ports. All existing example projects for IAR-ARM have been updated to use the `q(x)k_port.c` files instead of `q(x)k_port.s` files.
Also, this release adds new project files for the Atollic TRUEstudio for STM32. The TRUEstudio projects (Eclipse) have been added for the @ref arm-cm_dpp_nucleo-l053r8 "NUCLEO-L053R8" (Cortex-M0+) and the @ref arm-cm_dpp_nucleo-h743zi "NUCLEO-H743ZI" (Cortex-M7).
Also, this relese updates the CMSIS to version 5.3.0 (see `qpcpp/3rd_party/CMSIS`
The main purpose of this release is adding the support for the [<strong>ARM Compiler 6 (ARM-Clang)</strong>](https://developer.arm.com/products/software-development-tools/compilers/arm-compiler), which is a C/C++ toolchain for ARM processors based on the modern [Clang frontend](https://clang.llvm.org/) and the [LLVM framework](https://llvm.org/). This release adds the ARM-Clang ports and examples for all built-in kernels (QV, QK, and QXK) for the ARM Cortex-M CPU cores.
This release also adds support for the STM32H7 high-performance Cortex-M7 with the **double-precision FPU** (FPv5-DP-D16-M). Specifically, this release provides examples for the [NUCLEO-H743ZI board](http://www.st.com/en/evaluation-tools/nucleo-h743zi.html) (Cortex-M7 with FPv5-DP-D16-M). The @ref arm-cm_dpp_nucleo-h743zi "examples for NUCLEO-H743ZI board" include all built-in kernels with ARM-CLANG, ARM-KEIL, GNU-ARM, and IAR-ARM. Additionally the NUCLEO-H743ZI examples also include the QP FreeRTOS with ARM-KEIL, GNU-ARM, and IAR-ARM.
Also, this release changes the ARM Cortex-M ports for the GNU-ARM toolchain in that it replaces the assembly modules with the equivalent C implementation. This change enables using wider range of GNU-ARM toolchain distributions, such as GNU-ARM Linaro, which had trouble with the assembly modules, but compiles correctly the C modules. All related GNU-ARM example projects have been modifed to use the new C-ports.
Also, this release fixes build problems with IAR EWARM caused by the CMSIS v5.1.1, where the IAR C++ compiler failed to compile the CMSIS "mpu_armv7.h" header file. The problem was caused by the `restrict` keyword, which was supported by default in the IAR C compiler, but was **not** supported by default by the IAR C++ compiler. The fix was to add explicit compiler option `--enable-restrict` to all IAR projects for Cortex-M processors.
Also, this release updates the existing projects for the Code Composer Studio (CCS) to CCSv7. All existing CCS projects for the EK-TM4C123GXL (TivaC LauchPad) and LaunchXL2-TMS57012 (Hercules) boards have been upgraded and tested.
Also, all examples for MSP430 with CCS have been updated to CCSv7 and re-tested on the supported boards.
The main purpose of this release is the provision of the official @ref freertos "QP/C++ port to FreeRTOS" (version 10). The QP/C++ port to FreeRTOS is completely generic and should work on any CPU supported by FreeRTOS. The port comes with the following examples (see examples/freertos/):
- @ref freertos_dpp_ek-tm4c123gxl "DPP on EK-TM4C123GXL (ARM Cortex-M4F)" with ARM-KEIL, GNU-ARM and IAR-ARM toolchains.
This release also replaces assembly with C implementation in the ARM-KEIL ports or the QK and QXK kernels to Cortex-M to take advantage of the `__asm` functions. (NOTE: this change has impact on the existing QP/C++ applications that use the ARM-KEIL toolchain and the QK or QXK kernels.)
Additionally, this release modifies all IAR-ARM example projects by adding compiler option "--enable_restrict". This option is necessary to compile the CMSIS header file "mpu_armv7.h" under the IAR C++, where the "restrict" keyword is not supported by default.
Additionally, this release fixes some problems with the native examples for STM32F4 and STM32F7 boards.
Additionally, this release adds a generic function QP::QActive::setAttr() to set thread attributes in various QP ports to 3rd-party RTOSes. This function is then used in the @ref embos "embOS port" and the @ref ucos-ii "uC/OS-II port".
Finally, this release fixes the following bug in the @ref threadx "ThreadX port":
- [bug#197 "Problems with scheduler locking in QP/C/C++ ports to ThreadX"](https://sourceforge.net/p/qpc/bugs/197/)
- fixed [bug#193 "QXK: context switch from extended to basic thread fails"](https://sourceforge.net/p/qpc/bugs/193/)
- replaced attributes of QP::QActive and QP::QEQueue classes from type `uint_fastX_t` to `uintX_t`. For the ARM Cortex-M port, these changes reduce the memory footprint of each QP::QActive instance from 50 to 38 bytes (25% improvement).
- improved the performance of the ARM Cortex-M0/M0+ ports, which do not supprt the CLZ (count leading zeros) instruction. All QP ports to Cortex-M0/M0+ (qv, qk and qxk) now contain hand-optimized assembly implementation of the LOG2 (log-base-2) function. The implementation executes only in 14 machine instructions and uses only 16-byte look-up-table (LUT). This replaces LOG2 implementation based on a 256-byte LUT.
- changed the interrupt disabling policy in ARM Cortex-M ports back to "unconditional interrupt disabling", which is simpler and faster than "saving-and-restoring interrupt status".
- added a port to ARM Cortex-M with the LLVM compiler (currently only for the dual-mode QXK kernel). Unlike the other ARM Cortex-M ports, the port to LLVM uses the "saving-and-restoring interrupt status" interrupt disabling policy (explicit request from a commercial customer).
- removed ARM Cortex-M port and examples for the TI-ARM compiler. (Projects for the TI CCS can use the GNU-ARM toolchain and the existing GNU-ARM ports).
- Added the DPP-COMP example (Dining Philosophers Problem) with the "Orthogonal Component" state pattern located in `qpcpp/examples/win32/dpp-comp`. This example demonstrates also a partitioned QM model into external packages for the Container (Table active object) and the Components (Philo active objects).
@note
This release does not change any of the QP/C++ APIs.
The main focus of this release is to fix the remaining problems with transitions out of eXit-Points in sub-machines. Specifically, this release modifies the QMsm-based state machine implementation strategy (file src/qf/qep_msm.cpp to properly handle transitions from eXit-Points to Entry-Points and to History connectors in sub-machines. These changes are part of fixing the following bugs reported for QM:
- [bug#190 "Exit-Point segment targeting History doesn't work](https://sourceforge.net/p/qpc/bugs/190/)
- [bug#189 "Exit-Point segment targeting an Entry-Point to sub-machine state doesn't work"](https://sourceforge.net/p/qpc/bugs/189/)
Additionally, this release fixes the following bug in transitions to "shallow history":
- [bug#191 "Transition to shallow history in QMsm causes assertion qep_msm#810"](https://sourceforge.net/p/qpc/bugs/191/)
The bug#191 is fixed by modifying the function QMsm::childStateObj() in qep_msm.cpp to return the parent state in the corner case when the current state is the parent state.
@note
This QP/C++ 6.0.1 release is the minium version required in the upcoming QM 4.1.0. This is because QM 4.1.0 assumes the modified QMsm-state machine implementation strategy in order to properly handle the various transitions out of eXit-Points in sub-machine states.
Additionally, this release changes the QXK implementation still related to the [bug#186 "QXK: Extended thread context switch causes assertion in PendSV_Handler"](https://sourceforge.net/p/qpc/bugs/186/). Specifically, the case of context switching away and back to the same thread (which can arise under specific interrupt preemption scenarios) is now handled as a simple return from PendSV. The QXK scheduler has been modified to set the "next" thread pointer to NULL when it detects switching back to the "current" thread.
Additionally, this release includes a workaround for a [bug indetified in the GNU-ARM toolset](https://bugs.launchpad.net/gcc-arm-embedded/+bug/1722849). This problem affected the ARMv6-M architecture (Cortex-M0/M0+/M1) and manifested itself in generation of incorrect code for the QP critical section at certain gcc optimization levels (such as -O). This bug was first discovered and filed as [bug#184](https://sourceforge.net/p/qpc/bugs/184/). The bug affected the GNU-ARM ports to all built-in kernels @ref qv "QV", @ref qk "QK", and @ref qxk "QXK".
@note
This release no longer contains the directory `qpcpp/source`, which was scheduled to be phased out in QP5. In QP6 the source code is found only in the `qpcpp/src` directory.
This release implements the feature request [#132 "Extend the QXK mutex to support also simple operation without the priority-ceiling protocol"](https://sourceforge.net/p/qpc/feature-requests/132/).
@note
This release is completely backwards-compatible with the @ref qpcpp_5_9_8 "previous QP/C++ release 5.9.8".
Specifically, the QP::QXMutex class has been extended as follows:
- a mutex initialized with ceiling==0 (see QP::QXMutex::init()) means "no ceiling", so such mutex will NOT use the priority-ceiling protocol.
- in this case the mutex will NOT require a unique priority level
- in this case the mutex will not change (boost) the priority of the holding thread in the QP::QXMutex::lock() operation.
- in this case the mutex will still support nesting of locks (as before), up to 255 levels of nesting.
- when initialized with `ceiling>0`, QP::QXMutex WILL use the priority-ceiling protocol, as before. It will require that the ceiling priority be unique and not used by any other thread or mutex. In other words, the previous functionality remains unchanged.
This release fixes the QXK kernel [bug#182 " Inconsistent QXThread::post_() behavior with respect to the 'margin' parameter"](https://sourceforge.net/p/qpc/bugs/182/).
Also, the pre-condition assertion in the function QF::newRef_() (file `src/qf/qf_dyn.cpp`) has been modified to allow creating event references only for dynamic events `(e->poolId_ == 0)`.
Modifed ARM Cortex-M examples with the GNU-ARM toolset to be compatible with C++ RTTI and C++ Exception handling, as follows:
The main focus of this release are new requested features for the @ref qxk "dual-mode QXK kernel":
- <a href="https://sourceforge.net/p/qpc/feature-requests/129" class="extern">feature#129 "Allow blocking while holding a mutex in QXK"</a>; and
- <a href="https://sourceforge.net/p/qpc/feature-requests/130" class="extern">feature#130 "Allow QXK mutex locks to nest while acquired by the same thread"</a>; and
- <a href="https://sourceforge.net/p/qpc/feature-requests/131" class="extern">feature#131 "Add a non-blocking "tryLock()" operation to the QXK mutex"</a>.
Additionally, this release adds also the non-blocking QXSemaphore::tryWait() operation.
In the process of re-implementing the QP::QXMutex, the previouis non-blocking priority ceiling mutex has been replaced with an equivalent selective QXK scheduler locking up to the specified ceiling priority. Specifically, this feature has been implemented with two new operations QXK::schedLock() and QXK::schedUnlock().
For consistency, the non-blocking mutex of the @ref qk "QK kernel" has been also replaced by the operations QK::schedLock() and QK::schedUnlock().
All related QXK and QK examples have been updated to use the selective scheduler locking instead of the mutex. The new blocking QXK mutex has been demonstrated in the following updated examples:
- @ref arm-cm_dpp_efm32-slstk3401a
- @ref arm-cm_dpp_ek-tm4c123gxl
@attention
The changes to QP::QXMutex in QXK and the now obsolete QMutex in QK **break backwards-compatiblity** with the exising code that relies these features. In the exising code, the mutexes should be replaced with selective scheduler locking.
@attention
Also, the blocking APIs with timeouts, such as QXMutex::lock(), QXSemaphore::wait(), QXThread::delay(), and QXThread::queueGet() no longer require the last `tickRate` parameter. This also **breaks backward-compatiblity** with the exising code that uses these operations.
This release also updates CMSIS to version 5.1.0 (3rd_party/CMSIS).
This release also adds the @ref api "API Reference" section to the QP/C++ documentation.
The main focus of this release are improvements to the "dual-mode" QXK kernel. Specifically, this release implements the <a href="https://sourceforge.net/p/qpc/feature-requests/128/" class="extern">featrue request #128 "QP Semaphore Max Value Setting"</a> for QXK. This feature changes the QXK function QP::QXSemaphore::init(), which now takes additional parameter `count`. This parameter specifies the maximum allowed count for the semaphore (e.g., count of 1 makes the semaphore a binary-semaphore).
@note
This change does NOT break any existing code, because the additional parameter has a default value (0xFFFF).
This release also fixes a bug inside the assertions in QP::QXSemaphore::signal(), where the check for the extended-thread is performed.
Also, this release adds assertions to the QXK code, which ensure that any available blocking calls can only be made from extended-threads and not from basic-threads (active objects) or ISRs.
Also, this release adds protection in the IRQ priorities initialization in QK/QV/QXK for ARM Cortex-M3/M4/M7, so that the number of IRQs is extracted from bits 0-2 of the ICTR register (INTLINESNUM).
Finally, this release consistently changes all example projects (for all toolchains) to use the **src/** directory for QP/C++ source code, instead of the **source/** directory. The source/ directory is now truly obsolete, but is still provided in this release for backwards compatibility with user projects.
- <a href="https://sourceforge.net/p/qpc/bugs/178/" class="extern">bug#178</a> "GNU-ARM compiler reports "Error: unaligned opcodes..." in startup code for QP/C/C++/nano examples". The bug fix entails modifying the startup code for the GNU-ARM compiler in the `3rd_party` directory. Specifically, the proper alignment directives have been added to the inline assembly in the exception handlers.
- <a href="https://sourceforge.net/p/qpc/bugs/179/" class="extern">bug#179</a> "Assertion ID 210 fires when signaling on a QXK semaphore"
- <a href="https://sourceforge.net/p/qpc/bugs/169/" target="_blank" class="extern">bug#169 "Submachine-state eXit Point does not work correctly"</a>
@note
The bug only affects sub-machines and does not affect any other
aspects of QMsm-style state machines.
Also, this release changes the organization of the QP/C++ source code to
make it more friendly for the Eclipse CDT, as proposed in the <a href="https://sourceforge.net/p/qpc/feature-requests/123/" target="_blank" class="extern">feature
request #123 "Eclipse-friendly source directory structure for QP/C/C++"</a>.
Specifically, the QP/C++ source code is now provided in the
`qpc/src/` directory with the following structure:
QUTest™ is the fundamental tooling for Test-Driven Development (TDD) of QP/C++ applications, which is a highly recommended best-practice. This release introduces changes in the QS-RX (receive) channel and adds several new callbacks.
@note The signature of the QS::onCommand() has changed and the function now takes 3 arbitrary 32-bit parameters instead of one. This introduces backwards-incompatibility with previous code that used QS::onCommand().
This release also changes the critical section for QP/C++ ports to ARM Cortex-M
in that the policy of "save and restore interrupt status" is used. This policy
permits nesting of critical sections, which was requested by customers.
Additionally, this release changes the selective interrupt disabling for
ARM Cortex-M3/4/7 (with the BASEPRI register) to address the hardware problem
on ARM Cortex-M7 core r0p1 (ARM-EPM-064408, errata 837070). The QP ports to
ARM Cortex-M3/4/7 now implement the workaround recommended by ARM, which is
to surround MSR BASEPRI with the "CPSID i"/"CPSIE i" pair. This workaround
works also for Cortex-M3/M4 cores.
New ports:
- ports/win32-qutest folder contains port to QUTest for Windows
- ports/posix-qutest folder contains port to QUTest for POSIX (Linux)
- ports/arm-cm/qutest folder contains port to QUTest for ARM Cortex-M
New examples:
- examples/qutest/dpp folder contains the QUTest DPP test for various
platforms (Win32, EFM32-SLSTK3401A and EK-TM4C123GXL)
- examples/qutest/qhsmtst folder contains the QUTest test for
the QHsmTst state machine (structural test)
- examples/qutest/qmsmtst folder contains the QUTest test for
the QMsmTst state machine (structural test)
- examples/qutest/self_test folder contains the QUTest self-test for
various features of QUTest
Updates of 3rd_party software:
- the 3rd_party/CMSIS folder has been updated to CMSIS 5.0.2.
- the 3rd_party/embOS folder has been updated to embOS 4.34.1
Finally, this release fixes the following bugs:
- bug#162 "QF critical sections require modification for M7 core"
This release adds support for sub-machines and sub-machine states for reusing pieces of state machines (an advanced UML concept) to the QMsm-state machine implementation strategy. This feature is to match the upcoming QM 4.0.0.
Also, this release adds support for the ARM Cortex-R processor. Specifically, the release contains a generic port to ARM Cortex-R with the IAR and TI-CCS toolsets and @ref arm-cr_dpp_launchxl2-tms57012 "examples for the TI Hercules TMS570LS12x" safety MCU (LAUNCHPADXL2-TMS57012).
Also, this release changes once more the QK port to ARM Cortex-M, to reduce the interrupt latecy. This has been achieved by shortening the critical section in the PendSV exception. Also, this QK port to Cortex-M no longer uses the NMI exception.
Also, this release changes slightly the QXK port to ARM Cortex-M, where again the critical section in PendSV has been slighly shortened.
Finally, this release replaces all absolute paths with relative paths in all CCS-Eclipse project files (for TivaC, Hercules, and MSP430).
This release adds support for the new board: EFM32-SLSTK3401A (Pearl Gecko Starter Kit from Silicon Labs). This board replaces the Stellaris EK-LM3S811 board, which has been discontinued. (The Stellaris EK-LM3S811 board had been used in the "Fly 'n' Shoot" game example accompanying the PSiCC2 book).
The main purpose of this release is to introduce _atomic event multicasting_, meaning that event publishing to all subscribers is now protected from preemption. This eliminates potential for re-ordering of events under preemptive kernels (such as QK, QXK, or 3rd-party RTOSes), when events are published from low-priority AOs and some higher-priority subscribers can preempt multicasting and post/publish events of their own (before the original event is posted to all subscribers).
The atomic event multicasting is implemented by means of selective scheduler locking--very much like a priory-ceiling mutex. During event multicasting the scheduler gets locked, but only up to the highest-priority subscriber to a given event. The whole point here is that active objects with priorities above such "priority ceiling" are _not_ affected. Please see the discussion thread:
This release also changes the implementation of the priority-ceiling mutex in the preemptive built-in kernels: QK and QXK. Specifically, the implementation now re-uses the selective scheduler locking mechanism. In this new implementation, the QXMutex of the QXK kernel is much more efficient and lightweight, but it _cannot block_ while holding a mutex.
Finally, this release changes the QP ports to 3rd-party RTOSes by performing any RTOS operations (like posting events to message queues) outside critical sections. Also the ports have been augmented to support scheduler locking (this feature depends on what's available in the specific RTOSes).
Changes in detail:
1. Added scheduler locking to QF::publish_() in qf_ps.cpp. This feature is added in a portable way, via macros #QF_SCHED_STAT_TYPE_, QF_SCHED_LOCK_() and QF_SCHED_UNLOCK_(), which need to be implemented in every QP port.
2. Modified QV kernel to provide (dummy) implementation of selective scheduler locking.
3. Modified QK kernel to implement selective scheduler locking via modified priority-ceiling mutex QMutex.
4. Modified QXK kernel to implement selective scheduler locking via modified priority-ceiling mutex QXMutex.
5. Modified embOS port to provide (global) scheduler locking, which affects all priorities, because that's all embOS supports. Also, modified the embOS port to perform event posting outside the QF critical section.
6. Modified uC/OS-II port to provide (global) scheduler locking, which affects all priorities, because that's all uC/OS-II supports. Also, modified the uC/OS-II port to perform event posting outside the QF critical section.
7. Modified ThreadX port to provide selective scheduler locking, by means of "priority-threshold" available in ThreadX. Also, modified the ThreadX port to perform event posting outside the QF critical section.
8. Changed the ThreadX example to run on ARM Cortex-M4 board (STM32DiscoveryF4), instead of Win32 emulation (see qpcpp/examples/threadx/arm-cm/dpp_stm32f429-discovery).
9. Modified the Win32 port to provide (global) scheduler locking, which is implemented by Win32 critical section.
10. Fixed Bug#122 (QP didn't initiate some internal variables) https://sourceforge.net/p/qpc/bugs/122/ by adding explicit clearing of all QP variables in QF::init().
11. Modified the POSIX port to dummy-out scheduler locking. This means that this port currently does NOT lock scheduler around event publishing. (At this point it is not clear how to implement POSIX scheduler locking in a portable way.)
12. Modified QK and QXK examples in qpcpp/examples/arm-cm/dpp_ek-tm4c123gxl to demonstrate the usage of the new priority-ceiling mutexes.
13. Fixed the 3rd-party file startup_stm32l32l1xx.c to include exceptions for Cortex-M3 (MemManage_Handler, BusFault_Handler, and UsageFault_Handler).
14. Updated the 3rd-party files for the EK-TM4C123GXL board (TivaC LaunchPad).
15. Modified Makefiles for the EK-TM4C123GXL board with GNU-ARM toolset to define the symbol TARGET_IS_TM4C123_RB1 for compatibility with the updated 3rd-party files.
16. Implemented Feature Request #110 as well as the duplicate Request #62 by adding function QMActive::flushDeferred()
This release is the first official (production) release of the new blocking @ref qxk "QXK kernel" ("eXtended Quantum Kernel"). QXK is a small, preemptive, priority-based, **blocking** kernel that provides most features you might expect of a traditional blocking RTOS kernel.
QXK has been designed specifically for applications that need to mix event-driven active objects with traditional blocking code, such as commercial middleware (TCP/IP stacks, UDP stacks, embedded file systems, etc.) or legacy software. The QXK kernel is integrated tightly and optimally with the rest of the QP. It reuses all mechanisms already provided in QP, thus avoiding any code duplication, inefficient layers of indirection, and additional licensing costs, which are inevitable when using 3rd-party RTOS kernels to run QP/C++ applications.
@note
The QXK documentation is available in the QP/C Reference Manual at @ref qxk
Additionally, this release removes the macros Q_ROM, Q_ROM_BYTE, and Q_ROM_VAR from the QP/C++ code. These macros have been necessary for odd Harvard-architecture 8-bit CPUs (such as AVR, 8051) to place constant data in ROM. As QP/C++ stopped supporting those CPUs, the non-standard extensions could be removed from the QP/C++ code base.
Additionally, this release re-designs the priority-ceiling mutex in the QK kernel, which now works the same as the mutex of the new QXK kernel. Also, the QK ports to ARM Cortex-M no longer need or use the SVC_Handler (Supervisor Call). This is done to make the QK ports compatible with various "hypervisors" (such as mbed uVisor or Nordic SoftDevice), which use the SVC exception.
Finally, this release modifies the GNU-ARM ports of QK for ARM Cortex-M, to use the __ARM_ARCH macro to distinguish among different architectures (ARCHv6 vs ARCHv7).
Changes in detail:
1. Added new header files for QXK: qxk.h, and qxthread.h.
2. Added new source files for QXK: qxk.cpp, qxk_mutex.cpp, qxk_pkg.h, qxk_sema.cpp, qxk_xthr.cpp.
3. Added QXK ports to ARM Cortex-M for ARM-KEIL, GNU-ARM, IAR, and TI-ARM toolsets (see qpcpp/ports/arm-cm/qxk)
4. Added QXK examples for ARM Cortex-M (in qpcpp/examples/arm-cm/dpp_ek-tm4c123gxl/qxk and qpcpp/examples/arm-cm/dpp_nucleo-l053r8/qxk) for all supported toolsets.
5. Removed Q_ROM, Q_ROM_BYTE, and Q_ROM_VAR from the QP/C++ code.
6. Added Q_ROM, Q_ROM_BYTE to the compatibility-layer in qpcpp.h.
7. Removed ports and examples for the following 3rd-party RTOSes: CMSIS-RTX and FreeRTOS, as QXK provided all the features found in those kernels and is recommended over those kernels.
8. Removed AVR ports and examples.
9. Re-designed the QK priority-mutex in files qk.h and qk_mutex.cpp.
10. Provided QK mutex examples in qpcpp/examples/arm-cm/dpp_ek-tm4c123gxl/qk and qpcpp/examples/arm-cm/dpp_nucleo-l053r8/qk.
11. Updated Makefiles for GNU-ARM to use the __ARM_ARCH macro for defining the ARM architecture.
12. Updated CMSIS from 4.2 to 4.3 in qpcpp/3rd-party/CMSIS
13. Added error directives to source files from different built-in kernels (QV, QK, and QXK) to generate meaningful error messages when these files are mixed in one project. For example, a project based on QK will report errors when source files for QV or QXK are included in it.
14. Corrected example projects for the ARM Cortex-M with TI/CCS toolset
The purpose of this release is to improve the AAPCS compliance of the ARM Cortex-M port to the QK preemptive kernel. Specifically, the PendSV handler in assembly did not always maintain the 8-byte stack alignment, which is required by AAPCS. This version corrects the stack misalignment in the qk_port.s files for all supported ARM compilers (ARM-Keil, GNU, and IAR). All these ports should also be ready for ARM Cortex-M7.
The main focus of this release is to improve the support for "dual targeting" of QP/C++ applications, which is developing of deeply embedded code as much as possible on the desktop OS, such as Windows. Experience shows that "dual targeting" dramatically improves productivity of embedded systems developers, perhaps more than any other technique.
This release makes it possible to use exactly the **same** application code, main function, and the Board Support Package interface (bsp.h) on both deeply embedded target and on Windows. The only differences between these targets can be completely encapsulated in the Board Support Package implementation (bsp.cpp).
The support for "dual targeting" in this QP/C++ release works both for Win32 console and Win32 GUI applications. The Win32-GUI support enables developers to easily emulate the front-panels of the embedded devices, with LCD-screens (graphical and segmented), LEDs, buttons, switches, sliders, etc.
1. Modified the QP/C++ ports to Windows (both @ref win32 and @ref win32-qv) so that they support both Win32 console and Win32-GUI applications. The newly introduced pre-processor #WIN32_GUI macro is now required to use the Win32-GUI facilities.
2. Added portable "safe" macros from `<stdio.h>` and `<string.h>` to the QP/C++ ports to Windows. These macros encapsulate the differences between Microsoft Visual C++ and other compilers (such as MinGW).
3. Simplified the structure of the QP/C++ Windows ports by eliminating one level of directories for the compilers used. Both VC++ and MinGW builds can now be run in the same port directory.
4. Modified the QF::stop() function in the QP/C++ port to @ref win32-qv, so that it unblocks the QV event-loop and thus lets the application terminate.
5. Modified all examples for Windows to use the new port structure.
6. Improved all Makefiles (for the MinGW toolset) in all Windows examples, to make them easier to adapt to custom applications, both Win32 console and Win32 GUI.
7. Moved several examples from the `examples/win32/` and examples/win32-qv directories to `examples/arm-cm/` directory with native embedded examples for ARM Cortex-M. This co-location of the Win32 emulation with the embedded code running on the actual board demonstrates better the "dual targeting" development approach.
8. Updated all Windows examples to the latest QP API by compiling the code with the macro #QP_API_VERSION set to 9999 (latest API without backwards compatibility)
This release changes the active object class hierarchy so that ::QMActive is now more fundamental and is the base class for QActive. (Previously ::QMActive was a subclass of ::QActive). The newly added documentation section about @ref classes "QP/C++ Design" shows the current class hierarchy.
@note
Because the types QMActive and QActive are equivalent in QP/C++, this change has minimal impact on the applications, but it is now more correct to use QMActive as the base class for all "opaque" active object pointers.
Also, this release brings several cosmetic improvements:
1. All QM models have been saved with QM 3.3.0, which means that they will not open with QM 3.2.x or earlier QM versions.
2. The `qpcpp/ports/arm-cm/qk/gnu/qk_port.s` ARM Cortex-M port to QK with GNU has been modified to use the CMSIS-compliant symbol __FPU_PRESENT instead of the FPU_VFP_V4_SP_D16 symbol.
3. All Makefiles for the GNU toolset have been cleaned up, whereas any `/` (back-slash) characters in the paths have been repalced with `/` (forward-slash) characters. Also all these Makefiles have been updated to provide the __FPU_PRESENT to C/C++ and assembler when the hardware FPU is used.
4. The file display drver for the EK-LM2S811 board locate at `qpc/3rd_party/ek-lm3s811/display96x16x1.c` has been modified to fix the problem with incorrect hardware delay with the GNU compiler at higher levels of optimization. The in-line assembly for the GNU compiler has been updated such that the delay loop cannot be "optimized away".
This release changes the basic philosophy of distributing the QP frameworks by **combining** the "QP/C++ Baseline Code" with all currently available "QP/C++ Development Kits" (QDK/C++). This is done to eliminate any potential mistakes in downloading and installing separate pieces of code.
Additionally, this release changes the basic philosophy of building your embedded applications with the QP/C++ framework. Starting with this release, all @ref exa "examples" for embedded boards include the QP/C++ framework as **source code** within the projects, instead of statically linking with a QP/C++ library. (**NOTE:** It is still possible to use QP/C++ as a library, but you need to build such libraries yourself, as they are no longer provided in the QP/C++ distribution.)
The move to building QP/C++ from sources ensures the consistent toolset version and compiler options applied to the application code as well as the QP/C++ framework code. (**NOTE:** The QP/C++ examples for "big operating systems", like @ref exa_win32 "Windows" or @ref exa_posix "Linux", still use QP/C++ as a pre-compiled library that is statically linked with the application code.)
This release also changes the active object class hierarchy so that QMActive is now more fundamental and is the base class for QActive. (Previously QMActive was a subclass of ::QActive). The newly added documentation section about @ref classes "QP/C++ Design" shows the current class hierarchy.
Even though the QP/C++ source has been re-packaged in this release, the changes have minimal impact on the existing QP/C++ applications. The biggest difference is that "opaque" pointers to active objects derived from QMActive now need to be also typed QMActive (as opposed to QActive), because QMActive is no longer a subclass of QActive and the automatic upcast no longer applies.
The changes in basic approach to distributing and building the framework have also the following ripple effects:
1. The QP/C++ source code has been simplified and has been re-packaged into a much smaller number of source files. The whole QP/C++ source code now resides in the single <span class="img folder"><a href="dir_b2f33c71d4aa5e7af42a1ca61ff5af1b.html"><strong>source</strong></a></span> folder. Additionally, the source code files have now the **read-only** protection to prevent inadvertent changes to the QP/C++ source code that is part of your projects.
2. It is no longer necessary to define the **QPCPP environment variable** to build the QP/C++ examples. All directories and files referenced by example projects are **relative** to the project folder. This change reflects the fact that most development tools add source files to the project using relative paths (and now the projects contain QP/C++ source code, not just the QP library).
3. The QP/C++ <span class="img folder">@ref ports</span> folder has been reorganized to contain all currently available QP/C++ ports. The ports are organized into three categories: @ref ports_native "native QP/C++ ports" ("bare-metal"), @ref ports_rtos "ports to 3rd-party RTOSes", and @ref ports_os "ports to big operating systems" (Windows and Linux).(**NOTE**: the ports are now documented in the this <strong>QP/C++ Reference Manual</strong>. Each port sub-directory contains a <span class="img qp_link">README</span> link to the corresponding page in the online documentation)
5. The QP/C++ <span class="img folder">@ref exa</span> folder has been reorganized to reduce the repetitions and contains all currently available QP/C++ examples. The folder includes four categories of examples: @ref exa_native "native QP/C++ examples" ("bare-metal"), @ref exa_rtos "examples for 3rd-party RTOSes", @ref exa_os "examples for big operating systems" (Windows and Linux), and @ref exa_mware "examples for 3rd-party Middleware". As mentioned before, all example projects for embedded systems use QP/C++ as source code and not as a library. The <span class="img folder">examples</span> folder has been expanded to contain all currently available QP/C++ examples, many of them are new in this release. (**NOTE**: the currently available examples are now documented in the <strong>QP/C++ Reference Manual</strong>. Each example sub-directory contains a <span class="img qp_link">README</span> link to the corresponding page in the online documentation)
6. A new <span class="img folder">3rd_party</span> folder created to contain the Third-Party code used in the QP/C++ ports and examples, such as MCU register files, low-level startup code, device drivers, etc. The <span class="img folder">3rd_party</span> folder avoids the need to repeat such code in every project. Also, the separation of the Third-Party components helps to clearly indicate code that comes from various sources, and to which Quantum Leaps, LLC expressly makes **no claims of ownership**. The Third-Party software components included in this "3rd_party" folder are licensed under a variety of different licensing terms that are defined by the respective owners of this software and are spelled out in the README.txt or LICENSE.txt files included in the respective sub-folders.
7. This release also comes with the much expanded online <strong>QP/C++ Reference Manual</strong>, which is cross-linked with the ports and examples.
Changes in detail:
1. Renamed the "Vanilla" scheduler to the @ref comp_qv "QV cooperative kernel" for symmetry with the @ref comp_qk "QK preemptive kernel". Renamed QF::onIdle() callback to QV::onIdle().
2. Removed class QFsm (which is now deprecated). Legacy state machines coded in the "QFsm-style" will continue to work, but will use the QHsm implementation internally. There is no longer any efficiency advantage in using the "QFsm-style" state machines.
3. Applied a slight performance improvement to the ARM Cortex-M port to the QK preemptive kernel. The QK port now checks for ISR context by looking at the IPSR register, instead of incrementing and decrementing the `QK_intNest_` up-down counter.
4. Updated @ref exa_arm-cm "ARM Cortex-M examples" and provided new examples for NXP mbed-LPC1768, and STM32 NUCLEO-L053R8, and NUCLEO-L152RE boards. All examples now use the latest CMSIS (V4.3.0). All ARM Cortex-M exampels are provided for the ARM-KEIL, GNU-ARM, and IAR-ARM toolsets.
5. Added the native @ref arm7-9 "port" and @ref exa_arm7-9 "examples" to the @ref arm7-9 "classic ARM7/9" with AT91SAM7S-EK board and the IAR-ARM toolset.
6. Added the native @ref avr "port" and @ref exa_avr "examples" to the AVR (AVRmega) with GNU-AVR and IAR-AVR toolsets. The @ref exa_avr "examples" are provided for the Arduino-UNO board.
7. Added the native @ref msp430 "port" and @ref exa_msp430 "examples" to MSP430 with TI CCS-430 and IAR-430 toolsets. The @ref exa_msp430 "examples" are provided for the MSP430 LauchPad boards (the MSP-EXP430G2 and MSP-EXP430F5529LP for the "classic" MSP430 and "extened" MSP430X, respectively).
8. Added port to @ref cmsis-rtx "CMSIS-RTOS RTX". Examples are available for TI EK-TM4C123GLX, STM32 NUCLEO-L053R8, and NUCLEO-L152RE boards with ARM-KEIL, GNU-ARM, and IAR-ARM toolsets.
9. Updated port to @ref embos "embOS". Examples are available for STM32 STM32F4-Discovery board with IAR-ARM toolset.
10. Updated port to @ref freertos "FreeRTOS" for the latest version 8.2.1. Examples are available for TI EK-TM4C123GLX board with GNU-ARM and IAR-ARM toolsets.
11. Added @ref threadx "port to Thread-X". Example is available for the Thread-X demo with Visual Studio on Windows.
12. Updated port to @ref ucos-ii "uC/OS-II" for the latest version v2.92. Examples are available for TI EK-TM4C123GLX and STM32 NUCLEO-L152RE boards with ARM-KEIL and IAR-ARM toolsets.
13. Updated @ref win32 "port to Win32" (Windows). Modified the port to apply a generous "fudge factor" in over-sizing QP event queues and event pools, to minimize the risk of overflowing queues/pools due to non-deterministic Windows behavior.
14. Updated the @ref qt "QP-Qt Port" (QP/C++ port to the Qt cross-platform GUI framework).
1. QMsm::isInState() returns invalid result (bug #105)
2. QF::gc() doc typo (bug #102)
3. POSIX-port Makefile error (bug #65)
4. Problematic friendship to extern "C" function in qf.h (bug #106)
Also, this release updates the PC-Lint options and removes all the remaining PC-Lint warnings for the latest PC-Lint 9.00k.
Additionally, this release improves the uC/OS-II port in that it is now generic and applicable for any CPU, for which uC/OS-II port exists. Specifically, all references to DOS or x86 have been removed from the QP port and any CPU-specific dependencies have been placed in the separate part of the port.
Finally, this release improves the "QP/C++ Reference Manual" generated by Doxygen and available both inside the QP/C++ baseline distribution (qpcpp.chm file) and online at: https://www.state-machine.com/qpcpp
