- [feature#191 "Add QS local filtering to QF_PUBLISH()"](https://sourceforge.net/p/qpc/feature-requests/191/)
The feature has been implemented by means of the "sender" parameter of the `QF_PUBLISH()` macro, which must now be a pointer to a struct that has the `prio` member. This design enables applying QS local filter to the `prio` as the QS-Id. This works for publishing events from active objects. For publishing events outside active objects (e.g., from ISRs), the header file `qs.h` provides a type `QSpyId`, which should be used to define QS ID variables to be used as "sender" in `QF_PUBLISH()`.
@note
This change only affects the Spy build configuration, where the QS software tracing instrumentation is enabled. The existing code could require modifications to provide "sender" pointer that can access `prio` directly. For example, AOs would need to call `QF_PUBLISH(e, &me->super)` instead of `QF_PUBLISH(e, me)`.
- [feature#185 "Add possibility of assigning name to AO threads in QP-RTOS ports"](https://sourceforge.net/p/qpc/feature-requests/185/)
This feature request is now implemented uniformely in all QP-ports to 3rd-party RTOSes by means of the generic QP API QActive_setAttr(). Specifically, the QP port will allow you to set the thread name by calling QActive_setAttr() before calling QACTIVE_START().
__Bug Fixes:__
- [bug#292 "QP-C-C++ on 64 Bit Linux - Setting of Current-Obj - AO_Obj from QView raises segmentation fault"](https://sourceforge.net/p/qpc/bugs/292/)
- [bug#293 "[Qpccp 6.9.2] test of assertion fail now"](https://sourceforge.net/p/qpc/bugs/293/)
- [bug#298 "ARM Cortex-M Erratum 838869 Handled Inconsistently in Ports"](https://sourceforge.net/p/qpc/bugs/298/)
- all examples using `QF_PUBLISH()` - adjusted the `sender` parameter of the macro to have the `prio` member
- `qpc/examples/arm-cm/` - fixed [bug#298](https://sourceforge.net/p/qpc/bugs/298/) (added calls to `QV|QK|QXK_ARM_ERRATUM_838869()`)
- `qpc/examples/qutest/self_test/test/` - added examples of the Python include files (`*.pyi`) for the new [include command](https://www.state-machine.com/qtools/namespacequtest__dsl.html).
- `qpc/examples/arm-cm/dpp_efm32-slstk3401a/win32-gui/` - corrected handling of user-drawn buttons in `bsp.c`
- `qpc/examples/arm-cm/game_efm32-slstk3401a/win32-gui/` - corrected handling of user-drawn buttons in `bsp.c`
__Updated 3rd-Party Components:__
- `qpc/3rd_party/threadx` to version 6.1.6 (latest open source version from [GitHub](https://github.com/azure-rtos/threadx) )
The main purpose of this release is a redesign of the QS-RX (software tracing input) to implement the feature request #187:
- [feature#187 "Make the byte order in QS-RX buffer compatible with DMA"](https://sourceforge.net/p/qpc/feature-requests/187/)
Additionally, as part of the re-design of the internal QS-RX implementation, this release fixes the bug #287 ("QS_rxGetNfree() returns too low value", see the "Bug Fixes" section)
Additionally, this release introduces a new "virtual" function `getStateHandler()` in the `QHsm` base class. This is part of the fix for bug #290 ("QView query object state reports wrong state with QMsm strategy", see the "Bug Fixes" section)
__Source code changes:__
The introduction of the `getStateHandler()` virtual function involves the following code changes:
- `qpc/include/qep.h`
- `qpc/src/qf/qep_hsm.c`
- `qpc/src/qf/qep_msm.c`
- `qpc/src/qf/qf_actq.c`
- `qpc/src/qf/qf_qact.c`
- `qpc/src/qf/qf_qmact.c`
- `qpc/src/qs/qs_rx.c`
- `qpc/src/qs/qutest.c`
- `qpc/src/qxk/qxk_xthr.c`
- `qpc/include/qs.h` file -- added new API QS_queryCurrObj()
The redesign of QS-RX implementation involves the following code changes:
- `qpc/include/qs.h` -- macro `QS_RX_PUT()` now returns `bool` (true if the byte was inserted into the QS-RX buffer and false otherwise)
- `qpc/src/qs/qs_rx.c` - changed several functions
- `qpc/src/qs/qs_fp.c` - improved implementation
__Modified QP/C ports:__
- `qpc/ports/posix/` - modified to take advantage of the QS-RX direct byte ordering
- `qpc/ports/posix-qutest/` - modified to take advantage of the QS-RX direct byte ordering
- `qpc/ports/posix-qv/` - modified to take advantage of the QS-RX direct byte ordering
- `qpc/ports/win32/` - modified to take advantage of the QS-RX direct byte ordering
- `qpc/ports/win32-qutest/` - modified to take advantage of the QS-RX direct byte ordering
- `qpc/ports/win32-qv/` - modified to take advantage of the QS-RX direct byte ordering
The main purpose of this release is a redesign of the [<b>QS Local Filter</b>](https://www.state-machine.com/qtools/qs.html#qs_local) (see also [feature request #127](https://sourceforge.net/p/qpc/feature-requests/127)). This new design supports filtering on __multiple__ active objects (as well as other objects in the Target memory), as opposed to filtering just one such object at a time. The main use case for this redesign of QS Local Filter is an application, where some active objects are very "noisy", and would overwhelm your trace. The new QS Local Filter allows you to selectively silence the "noisy" active objects and let all the others through.
The new QS Local Filter is based on "QS-IDs" associated with various objects in the Target memory. The QS-IDs are small integer numbers, such as the unique priorities assigned to QP Active Objects, but there are more such QS-IDs, which you can assign to various other objects through the macro QS_BEGIN_ID(). Then, you can setup the QS Local Filter to trace only a specific QS-IDs or whole groups of QS-IDs by means of the macro QS_LOC_FILTER() or remotely via the QS-RX channel.
__Source code changes:__
The redesign of the QS Local Filter impacts the QS trace instrumentation in QP/C: both the [<b>pre-defined QS trace records</b>](https://www.state-machine.com/qtools/qs.html#qs_pre) and the [<b>application-specific trace records</b>](https://www.state-machine.com/qtools/qs.html#qs_app). The changes to the pre-defined records are confided to the QP/C source code and are transparent to the application developers. However, the changes to the application-specific trace records require adjusting existing applications as follows:
- use the new macro QS_LOC_FILTER() to set/clear the QS Local Filter
- use the new macro QS_BEGIN_ID() to define [<b>application-specific trace records</b>](https://www.state-machine.com/qtools/qs.html#qs_app).
@note
The macro QS_BEGIN_ID() assigns the specified QS-ID number to the app-specific record, which can be subsequently filtered by the new QS Local Filter. The old macro QS_BEGIN(), with the old Local Filter interface, is still available, but is @ref deprecated "deprecated" and not recommended.
The following macros are __deprecated__:
- macro QS_FILTER_SM_OBJ() does nothing in QP/C 6.9.1
- macro QS_FILTER_AO_OBJ() does nothing in QP/C 6.9.1
- macro QS_FILTER_MP_OBJ() does nothing in QP/C 6.9.1
- macro QS_FILTER_EQ_OBJ() does nothing in QP/C 6.9.1
- macro QS_FILTER_TE_OBJ() does nothing in QP/C 6.9.1
- macro QS_FILTER_AP_OBJ() still works for QS_BEGIN()
- macro QS_FILTER_ON() still works, but uses QS_GLB_FILTER() internally
- macro QS_FILTER_OFF() still works, but uses QS_GLB_FILTER() internally
- macro QS_BEGIN() still works, but uses the old "AP-OBJ" pointer
The following APIs have been __changed__:
- QHSM_INIT() now takes extra `qs_id` parameter
- QHSM_DISPATCH() now takes extra `qs_id` parameter
- QMPool_get() now takes extra `qs_id` parameter
- QMPool_put() now takes extra `qs_id` parameter
- QEQueue_post() now takes extra `qs_id` parameter
- QEQueue_postLIFO() now takes extra `qs_id` parameter
- QEQueue_get() now takes extra `qs_id` parameter
@note
The API changes are __not backwards-compatible__ and require adjusting existing QP/C applications.
Additionally, this release introduces the new pre-defined QS record #QS_QF_NEW_ATTEMPT, which is generated when Q_NEW_X() fails to allocate a dynamic event. Also, this release __reverses the order__ of the pre-defined QS records #QS_QF_NEW and #QS_QF_MPOOL_GET. This was necessary if the dynamic allocation is allowed to fail, because only _after_ attempting to allocate a memory block, the QF_newX_() function can generate either #QS_QF_NEW or #QS_QF_NEW_ATTEMPT.
@note
The reversal of #QS_QF_NEW and #QS_QF_MPOOL_GET trace records has implications for the existing [<b>QUTest test scripts</b>](https://www.state-machine.com/qtools/qutest_script.html), where the order of expectations for "QF-New" and "MP-Get" needs to be reversed as well.
Additionally, this release modifies the @ref qxk "QXK" source code, so that the `QActive.prio` attribute is the fixed priority assigned in QActive_start(), while `QActive.dynPrio` is the "dynamic" priority that can be changed when a @ref qxk_extended "QXK extended thread" acquires a @ref ::QXMutex "mutex".
- all ARM Cortex-M ports (added workaround for the [<b>ARM Erratum 838869</b>](https://www.state-machine.com/doc/Cortex-M4_Software_Developers_Errata_Notice_v3.pdf))
- all QK ports (because of the changed QMPool_get() / QMPool_put() interface)
- all QXK ports (because of the changed QMPool_get() / QMPool_put() interface)
The main purpose of this release is to adjust the QP/C RTEF to the changes and improvements introduced in [QTools 6.9.0](https://www.state-machine.com/qtools/history.html). Specifically, QP/C now includes examples for the new [QView Visualization & Monitoring](https://www.state-machine.com/qtools/qview.html) as well as adjustments for the new version of [QUTest Unit Testing](https://www.state-machine.com/qtools/qutest.html).
__Source code changes:__
Added new #QS_QF_RUN trace record to [QS software tracing](https://www.state-machine.com/qtools/qs.html), which is now generated in all QP/C ports upon the entry to QF_run(). This trace record marks the end of the application startup, at which time all the [QS dictionaries](https://www.state-machine.com/qtools/qs.html#qs_dict) are typically produced.
The addition of the #QS_QF_RUN trace record affects only the [Spy build configuration](https://www.state-machine.com/qpc/struct.html#comp_qs) and is has **no impact** on the Release or Debug build configurations.
__Updated Ports:__
+ All QP/C ports to 3rd-party RTOSes (embOS, FreeRTOS, ThreadX, uC/OS-II) and OSes (POSIX, POSIX-QV, WIN32, WIN32-QV) have been updated to generate the #QS_QF_RUN trace record.
+ The POSIX and POSIX-QV ports have been updated to add the call to `pthread_attr_setinheritsched(&attr, PTHREAD_EXPLICIT_SCHED)` (see also [bug#276](https://sourceforge.net/p/qpc/bugs/276))
+ The MSP430 ports have been extended for the GNU-MSP430 compiler, so that they now work with IAR-MSP40, TI-MSP40 and GNU-MSP430 toolchains.
+ All [QUTest](https://www.state-machine.com/qtools/qutest.html) examples (`qpc\examples\qutest` directory) have been modified to use the new location of the `qutest.py` Python module. Also, all QUTest examples that use the `on_reset()` callback have been modified to call `expect_run()`.
@note
The #QS_QF_RUN record is now generated in [QUTest unit testing](https://www.state-machine.com/qtools/qutest.html), which requires adjustments in the existing [test scripts](https://www.state-machine.com/qtools/qutest_script.html). Specifically, the test scripts that provide their own [on_reset() callback](https://www.state-machine.com/qtools/namespacequtest__dsl.html#aa40735b0e2865f928331d30798090ee2) must now also call [expect_run()](https://www.state-machine.com/qtools/namespacequtest__dsl.html#a6a958064a793bd7edd6ecc39e03c356a).
+ ARM Cortex-M examples for STM32 NUCLEO-L053RE (`qpc\examples\arm-cm\dpp_nucleo-l053r8`) and NUCLEO-L152RE (`qpc\examples\arm-cm\dpp_nucleo-l152re`) have been modified to support bi-directional QSPY communication. These examples now include the QView demos.
+ Added examples of new [Sequence Diagram Generation](https://www.state-machine.com/qtools/html/qspy_seq.html) in QSPY 6.9.0
- Changed definitions of ::QMsm, ::QMActive, and ::QTicker "classes" from using typedef's to using struct's. This means that ::QMsm, ::QMActive, and ::QTicker are now **distinct types** different from the respective base classes: ::QHsm, ::QActive, and ::QActive. Consequently, implicit conversions to the base class are *no longer performed*, which improves the type safety.
@note
This change might cause compiler warning in code that assumes equivalence between ::QHsm and ::QMsm or ::QActive and ::QMActive. Specifically, any "opaque" pointers to the state machine base class should be of type `QHsm *` (and *not* `QMsm *`). Similarly, any "opaque" pointers to the active object base class should be of type `QActive *` (and *not* `QMActive *`)
- Applied the [Doxygen @extends command](https://www.doxygen.nl/manual/commands.html#cmdextends) to indicate **inheritance** and to explicitly specify base classes for all derived classes (e.g., ::QTimeEvt __extends__ ::QEvt).
- Fixed errors in the Doxygen documentation, such as: missing documentation for parameters, wrong parameter names, unresolved references, etc.
- Applied new, clearer styling to the Doxygen documentation.
- Changed the QS trace record name QS_QF_ACTIVE_POST_FIFO to ::QS_QF_ACTIVE_POST and QS_QF_EQUEUE_POST_FIFO to ::QS_QF_EQUEUE_POST. This refactoring now better matches the QP/C API QACTIVE_POST() and QEQueue_post().
__Updated Ports:__
+ enabled #QF_ACTIVE_STOP in the ports: Win32, Win32-QV, Win32-QUTEST, POSIX, POSIX-QV, and POSIX-QUTEST.
+ @ref ucos-ii "port to uC/OS-II" has been adapted to the new uC/OS-II v2.93.00 (recently released by Silicon Labs under the open source Apache 2.0 license).
__Updated Examples:__
+ Modified `Makefile`s for the GNU-ARM projects to use `gcc` as the linker instead of `g++`
+ Modidfied `Makefile`s for the workstation examples to add the `-no-pie` linker option only when `GCC_OLD` environment variable is NOT defined. This is to accommodates older POSIX platforms with older GCC distribution.
+ Modified all ARM-KEIL uVision projects for ARM-CLANG to use the startup code in the ARM-ASM syntax.
+ New uC/OS-II example @ref ucos-ii_dpp_nucleo-l053r8 (Cortex-M0+)
+ Removed uC/OS-II example for the STM32-NUCLEO-L152RE (Cortex-M3)
+ Added QM model files: `workstation/defer/defer.qm` and `workstation/reminder2/reminder2.qm`
__Updated QUTest examples to generate code-coverage information:__
+ Modified `Makefile`s in QUTest examples (directory `examples\qutest`) to generate **code-coverage information**. Specifically, when the `GCOV` environment variable is defined, the `Makefile`s generate code-coverage information for [GCOV](https://en.wikipedia.org/wiki/Gcov).
@note
The GCOV code-coverage generation is currently available only on the hosts.
__Updated 3rd-Party Components:__
+ CMSIS from 5.6.0 to 5.7.0
+ uC/OS-II from 2.92.10 to 2.93.00 (open source Apache 2.0 license)
__Bug Fixes:__
+ [bug#267 "QP/C Spy build configuration fails on 64-bit target"](https://sourceforge.net/p/qpc/bugs/267/)
Improved comments in the QF_stop() function. The comments now make it very clear that after calling QF_stop() the application must terminate and cannot continue. In particular, QF_stop() is **not** intended to be followed by a call to QF_init() to "resurrect" the application. The previous comments apparently were confusing and some developers attempted to "restart" a running application, which led to system crashes.
- [bug#261 QTime_disarm() clears the wrong flag](https://sourceforge.net/p/qpc/bugs/261/)
- [bug#262 Ticker0 does not work in QPC 6.8.0](https://sourceforge.net/p/qpc/bugs/262/)
Also, this release updates the QP/C ports and examples for workstations (Windows and POSIX) by consistently applying the "safe" versions of services from `<stdio.h>` and `<string.h>`. The "portable" versions of these services are defined as macros in the `safe_std.h` header file and include the following services:
These "safe" functions are mapped to the best approximation of these services available on a given platform. For example, `STRCPY_S()` is mapped to `strcpy_s()` on Windows and `strcpy()` on POSIX (Linux/MacOS/etc.).
- Fixed inconsistencies between QP API declarations in the `.h` files and definitions in the `.c` files, such as different parameter names in declarations and definitions (MISRA-C:2012).
- Removed a lot of excessive type casting of compile-time constants, such as `(uint8_t)0`, which is now coded simply as `0U`
- Introduced #Q_NORETURN macro for Q_onAssert(), which can (if defined) inform the compiler that Q_onAssert() does not return. This can potentially improve the code generation and can improve diagnostics generated by the compiler as well as static code analysis tools.
- Moved many @ref qs facilities for internal use (only inside the QP/C source code) from qs.h to qs_pkg.h. These are mostly facilities related to internal QS implementation as well as pre-defined QS trace records, which are only used inside QP and are not needed in the QP applications.
- Removed all pre-conditions from QActiveDummy_start_() function in qutest.c. This is to allow starting dummy AOs the exact same way as the real counterparts (e.g., with stack storage, which QActiveDummy does not really need).
Converted most of the examples for ARM-MDK from the no-longer maintained compiler-5 (RVDS) to the new ARM Compiler-6 (ARM-clang). The examples for ARM Compiler-6 are located in the `armclang` sub-directories.
@note
The older ARM Compiler-5 is still supported, but will be phased out in the future. The only examples for ARM Compiler-5 are for the EK-TM4C123GXL (TivaC LanuchPad) board. These examples are located in the `arm` sub-directories.
The main purpose of this release is providing improved compliance with MISRA-C:2012 (including MISRA-C:2012-Amendment-1) and also to provide support for the [<b>PC-Lint-Plus</b>](https://www.gimpel.com/) static analysis tool (see also feature request [#169](https://sourceforge.net/p/qpc/feature-requests/169/)). Specifically, the QP/C source code and some examples have been adjusted to comply with MISRA-C:2012-Amendment-1 rules, with all deviations captured in the PC-Lint-Plus configuration files. These PC-Lint-Plus configuration files have been provided in the new "port" to PC-Lint-Plus in the directory qpc/ports/lint-plus/.
@note
The support for the older PC-Lint 9.x and the older MISRA-C:2004 has been dropped to avoid confusion and conflicts with the newer MISRA-C:2012 and the newer PC-Lint-Plus.
This release also includes the offline documentation for **this** particular version of QP/C (in the `html/` folder). To view the offline documentation, open the file `html/index.html` in your web browser. (The online HTML documention for the **latest** version of QP/C remains located at: https://www.state-machine.com/qpc/ )
The backwards-compatiblity layer for QP 4.x has been removed. Among others, the macros Q_ROM and Q_ROM_VAR are no longer defined.
Also, this release updates the Windows-GUI examples with the QWIN Prototyping Toolkit to work with the latest Visual Studio 2019 and specifically with the Resource Editor now available. Specifically here, the Game-GUI example (`qpc\examples\arm-cm\game_efm32-slstk3401a\win32-gui`) and the DPP-GUI example (`qpc\examples\arm-cm\dpp_efm32-slstk3401a\win32-gui`) have been updated to build with the Visual Studio 2019.
The main purpose of this release is the change in distribution of the QP/C framework, which is now bundled together with the other QP frameworks (QP/C++ and QP-nano) as well as QM, and the QTools collection into "QP-bundle". This "QP-bundle" provides a single, streamlined and simplified download and installation of all QP frameworks and all the accompanying tools.
This release brings also the following changes:
- removed "//" (double slash) from all comments for compliance with
the MISRA-C:2012 required Rule 3.1. (The "//" sequence was used in the URLs, such as
"http://...").
- converted inclusion guards in header files to uppercase as per coding convention for macros.
- replaced "vtbl" with "vtable" in QP/C source code
- changed the type of the last parameter in QHsm_init_() and QHSM_INIT() from "QEvt const *"
to "void const *" to allow passing arbitrary data during initialization.
- increased #QS_USER from 70 to 100 and made the freed-up records reserved
- changed the QS_Ux_RECORDS groups to partition user trace records 100-124
Also, this release extends the `Makefiles` in the `qpc\examples\qutest` directory to provide the `debug` target. Specificall, the `qpc\examples\qutest\blinky` example has been extended with projects to `build/debug` this example with Visual C++ (on the host) and with ARM-KEIL on embedded target (EK-TM4C123).
This QP/C release matches the [QM release 4.5.0](https://www.state-machine.com/qm/history.html#qm_4_5_0), which introduced new implementation for QP/C++. Even though this has no impact on the QP/C state machine implementation with QM, this release is needed for compatibility checking between QP and QM.
For commonality with the new QP/C++ implementation, this release adds macros #Q_ACTION_NULL and #QM_STATE_NULL, which are used in the code generated from QM 4.5.0. Also, this release comes with several models for **QM 4.5.0**.
Additionally, this release changes the API QTimeEvt_ctr() to QTimeEvt_currCtr(). This is to avoid name shadowing with the `ctr` variables, which is not compliant with MISRA.
Additionally, the examples for `calc1` and `calc1_sub` (with QM 4.5.0 models) have been extended to properly handle the operator precedence (multiplication and division have higher precedence than addition and subtraction).
These additional assertions require #Q_DEFINE_THIS_FILE or #Q_DEFINE_THIS_MODULE at the top of the .c file that calls QHSM_INIT(), QACTIVE_START() or QXTHREAD_START().
- modified examples for ThreadX to define BSP_TICKS_PER_SEC as TX_TIMER_TICKS_PER_SECOND instead of a hardcoded value
- modified examples for uC/OS-II to define BSP_TICKS_PER_SEC as OS_TICKS_PER_SEC instead of a hardcoded value
- modified qassert.h to work correctly when assertions are disabled with #Q_NASSERT and also updated the QP/C source code to build correctly without assertions
- improved the QXK semaphores to handle correctly the maximum number of tokens
- reduced the size of QPSet in case #QF_MAX_ACTIVE does not exceed 8 or 16.
- improved performance of the QF_qlog2() algorithm when #QF_MAX_ACTIVE does not exceed 8 or 16.
- modified Makefiles for workstations (Windows and POSIX) to use compiler options -std=c99 for C and -std=c++11 for C++ as well as -pedantic option.
- fixed examples for MSP430 with CCS and added QUTest support for MSP430.
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-**.
@note
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 `qpc/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 `qpc\examples\` directory have been updated to link the newer "ws2_32" library.
Also, in this release, the prototypes of the internal functions `QActive_start_()`, `QActive_get_()`, `QActive_post_()` and `QActive_postLIFO_()` have been removed from the public QF interface (in qf.h) and moved to the QF-implementation. This is to prevent calling these internal functions directly in the application-level code. The only allowed use of these functions is through the macros QACTIVE_START(), QACTIVE_POST(), QACTIVE_POST_X() and QACTIVE_POST_LIFO().
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).
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 QTimeEvt_wasDisarmed() for checking the status of a ::QTimeEvt object after it has been disarmed. Specifically, the status of the last call to QTimeEvt_disarm() is kept inside the time event object and can be subsequently checked with the 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 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 `qpc/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 `qpc/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 a bug in the example `qutest/TDDbook_LedDriver` so that the code compiles cleanly with the updated header file "qassert.h".
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 (files `src/qs/qutest.c` and `src/qf/qf_actq.c`) 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 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 (`qpc/ports/posix/` and `qpc/ports/posix-qutest/`) no longer produce libraries. Instead all examples for POSIX (`qpc/examples/posix/` and `qpc/examples/qutest`) build the QP/C framework directly from the sources, which promotes consisentcy in the toolchain and options used. For unit testing, the makefiles `posix.mak` have been added for projects `qpc/examples/qutest/dpp/` and `qpc/examples/qutest/self_test/`. These makefiles support remote unit testing of embedded POSIX targets over TCP/IP, where the POSIX target runs only the [test fixture](https://www.state-machine.com/qtools/qutest.html#qutest_struct), but the host (e.g., Windows host) executes both the QSPY host application and runs the [QUTest scripts](https://www.state-machine.com/qtools/qutest.html#qutest_struct). 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 (`qpc/examples/qutest/defer/`)
- dispatching/posting events with parameters (`qpc/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).
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 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.
- @ref freertos_dpp_stm32f746g-disco "DPP on STM32F746G-Discovery (ARM Cortex-M7)" 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 fixes some problems with the native examples for STM32F4 and STM32F7 boards.
Additionally, this release adds a generic function 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 ::QActive and ::QEQueue classes from type `uint_fastX_t` to `uintX_t`. For the ARM Cortex-M port, these changes reduce the memory footprint of each ::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 `qpc/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.c to properly handle transitions from eXit-Points to Entry-Points and from eXit-Points to History connectors in sub-machines. These changes are part of fixing the following bugs reported for QM:
- [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.c to return the parent state in the corner case when the current state is the parent state.
This QP/C 6.0.1 release is the minium version required in 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 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.
This specific problem observed in QSpy turned out to be caused by a bug in the GNU-ARM compiler itself. 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".
This release no longer contains the directory `qpc/source`, which was scheduled to be phased out in QP5. In QP6 the source code is found only in the `qpc/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 qpc_5_9_8 "previous QP/C release 5.9.8".
Specifically, the ::QXMutex class has been extended as follows:
- a mutex initialized with ceiling==0 (QXMutex_init(0)) 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 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`, ::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.c`) has been modified to allow creating event references only for dynamic events `(e->poolId_ == 0)`.
- commented out the call to `__libc_init_array()` in the GNU-ARM startup code for all supported boards in the `3rd_party` directory (because it requires `_init()`)
- Modified all GNU-ARM linker scripts (.ld files) to add the following symbols:
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 ::QXMutex class, 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:
The changes to ::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.
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.
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 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 breaks backwards-compatibility with the existing code that uses the QXSemaphore_init() function.
This release also fixes a bug inside the assertions in 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().
on ARM Cortex-M7 core r0p1 ([SDEN-1068427, erratum 837070](https://www.state-machine.com/doc/Cortex-M7_Software_Developers_Errata_Notice_v8.pdf)). The QP ports to
as described in the AppNote <a href="https://www.state-machine.com/doc/AN_ARM-Cortex-M_Interrupt-Priorities.pdf" target="_blank" class="extern">"Setting ARM Cortex-M Interrupt Priorities in QP 5.x"</a>.
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 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.
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.c. 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 qpc/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 qpc/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 QActive_flushDeferred()
This release is the first official (production) release of the new blocking @ref qxk "QXK" kernel.
Changes in detail:
1. 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.
2. Corrected example projects for the ARM Cortex-M with TI/CCS toolset
The main purpose of this *beta* release is to introduce a new component of the QP/C framework called @ref qxk "QXK" ("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.
3. Added QXK ports to ARM Cortex-M for ARM-KEIL, GNU-ARM, IAR, and TI-ARM toolsets (see @ref arm-cm_qxk)
4. Added QXK examples for ARM Cortex-M (in @ref arm-cm_dpp_ek-tm4c123gxl and @ref arm-cm_dpp_nucleo-l053r8) 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 qpc.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.
The main purpose of this release is the extension of the QS software tracing system to bi-directional communication with embedded Targets. Specifically, the QS-RX (receive channel for QS) has been added with the following capabilities:
1. Set global QS filters inside the Target
2. Set local QS filters inside the Target
3. Inject an arbitrary event to the Target (direct post or publish)
4. Execute a user-defined callback function inside the Target with arguments supplied from QSPY
5. Peek data inside the Target and send to QSPY
6. Poke data (supplied from QSPY) into the Target
7. Execute clock tick inside the Target
8. Request target information (version, all sizes of objects, build time-stamp)
This QP/C version complements the recent release of Qtools 5.5.0, where the <a href="https://www.state-machine.com/qspy ">QSPY host application</a> has been extended with a UDP socket, which is open for communication with various Front-Ends (GUI-based or headless). An example Front-End written in Tcl/Tk called "QspyView" has been developed to demonstrate all the features. The example application located in the directory qpc/examples/arm-cm/dpp_ek-tm4c123gxl/qspy contains customization of the "qspyview" script for the DPP application. Please refer to the documentation of this example (@ref arm-cm_dpp_ek-tm4c123gxl) for more information.
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.c).
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.
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 included in examples have been modified to use the ::QMActive "opaque" pointers.
3. The ROM-able QP version string QP_versionStr[] has been added and used consistently in the macros QEP_getVersion(), QF_getVersion(), QK_getVersion(), QV_getVersion(), and QS_getVersion() macros.
4. The `qpc/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.
5. 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 and assembler when the hardware FPU is used.
6. 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_os "Windows/POSIX", still use QP/C as a pre-compiled library that is statically linked with the application code.)
Even though the QP/C source has been re-packaged in this release, there are no API changes to the code, so it remains **backwards compatible** with the existing applications. (Except the build process, which builds QP/C from sources rather than linking to the QP/C library.)
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"><strong>source</strong></span> folder. Additionally, the source code files have now the **read-only** protection to prevent inadvertent changes to the QP/C soruce code that is part of your projects.
2. It is no longer necessary to define the **QPC 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 board (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 @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.
@note QP/C 5.3.1 remains backwards-compatible with all QP/C ports and
applications
This release fixes the following bugs:
1. QMsm_isInState() returns invalid result (bug #105)
2. QP/C syntax error in qf_pkg.h (bug #104)
3. QF_gc() doc typo (bug #102)
4. POSIX-port Makefile error (bug #65)
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 (qpc.chm file) and online at: https://www.state-machine.com/qpc
