5.9.7a

2025-01-14 06:43:19 +08:00 · 2017-08-29 15:59:44 -04:00 · 2017-08-29 15:59:44 -04:00 · 6d951c9f06
commit 6d951c9f06
parent da20134c70
23 changed files with 2905 additions and 2464 deletions
--- a/3rd_party/README.txt
+++ b/3rd_party/README.txt
@ -61,6 +61,6 @@ LOSSES.
 Contact Information:
 ====================
 Quantum Leaps, LLC
-Web:   www.state-machine.com
-Email: info@state-machine.com
+https://state-machine.com
+info@state-machine.com
 
--- a/doxygen/Doxyfile
+++ b/doxygen/Doxyfile
@ -41,7 +41,7 @@ OPTIMIZE_OUTPUT_FOR_C  = YES
 OPTIMIZE_OUTPUT_JAVA   = NO
 OPTIMIZE_FOR_FORTRAN   = NO
 OPTIMIZE_OUTPUT_VHDL   = NO
-EXTENSION_MAPPING      =
+EXTENSION_MAPPING      = lnt=Objective-C
 MARKDOWN_SUPPORT       = YES
 AUTOLINK_SUPPORT       = YES
 BUILTIN_STL_SUPPORT    = NO
@ -71,7 +71,7 @@ HIDE_FRIEND_COMPOUNDS  = NO
 HIDE_IN_BODY_DOCS      = NO
 INTERNAL_DOCS          = NO
 CASE_SENSE_NAMES       = NO
-HIDE_SCOPE_NAMES       = NO
+HIDE_SCOPE_NAMES       = YES
 HIDE_COMPOUND_REFERENCE= NO
 SHOW_INCLUDE_FILES     = YES
 SHOW_GROUPED_MEMB_INC  = NO
@ -133,7 +133,6 @@ INPUT                  = \
    ../ports/lint \
    ../../doxygen/glossary.dox

-
 INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          = \
    *.dox \
@ -141,7 +140,8 @@ FILE_PATTERNS          = \
    *.c \
    *.cpp \
    *.s \
-    *.asm
+    *.asm \
+    *.lnt

 RECURSIVE              = YES
 EXCLUDE                = \
@ -313,7 +313,7 @@ EXPAND_ONLY_PREDEF     = NO
 SEARCH_INCLUDES        = YES
 INCLUDE_PATH           =
 INCLUDE_FILE_PATTERNS  =
-PREDEFINED             = Q_SPY QP_IMPL
+PREDEFINED             = Q_SPY QP_IMPL Q_UTEST
 EXPAND_AS_DEFINED      =
 SKIP_FUNCTION_MACROS   = YES
 #---------------------------------------------------------------------------
--- a/doxygen/Doxyfile-CHM
+++ b/doxygen/Doxyfile-CHM
@ -41,7 +41,7 @@ OPTIMIZE_OUTPUT_FOR_C  = YES
 OPTIMIZE_OUTPUT_JAVA   = NO
 OPTIMIZE_FOR_FORTRAN   = NO
 OPTIMIZE_OUTPUT_VHDL   = NO
-EXTENSION_MAPPING      =
+EXTENSION_MAPPING      = lnt=Objective-C
 MARKDOWN_SUPPORT       = YES
 AUTOLINK_SUPPORT       = YES
 BUILTIN_STL_SUPPORT    = NO
@ -71,7 +71,7 @@ HIDE_FRIEND_COMPOUNDS  = NO
 HIDE_IN_BODY_DOCS      = NO
 INTERNAL_DOCS          = NO
 CASE_SENSE_NAMES       = NO
-HIDE_SCOPE_NAMES       = NO
+HIDE_SCOPE_NAMES       = YES
 HIDE_COMPOUND_REFERENCE= NO
 SHOW_INCLUDE_FILES     = YES
 SHOW_GROUPED_MEMB_INC  = NO
@ -133,7 +133,6 @@ INPUT                  = \
    ../ports/lint \
    ../../doxygen/glossary.dox

-
 INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          = \
    *.dox \
@ -141,7 +140,8 @@ FILE_PATTERNS          = \
    *.c \
    *.cpp \
    *.s \
-    *.asm
+    *.asm \
+    *.lnt

 RECURSIVE              = YES
 EXCLUDE                = \
@ -313,7 +313,7 @@ EXPAND_ONLY_PREDEF     = NO
 SEARCH_INCLUDES        = YES
 INCLUDE_PATH           =
 INCLUDE_FILE_PATTERNS  =
-PREDEFINED             = Q_SPY QP_IMPL
+PREDEFINED             = Q_SPY QP_IMPL Q_UTEST
 EXPAND_AS_DEFINED      =
 SKIP_FUNCTION_MACROS   = YES
 #---------------------------------------------------------------------------
--- a/doxygen/Doxyfile-DOC
+++ b/doxygen/Doxyfile-DOC
@ -41,7 +41,7 @@ OPTIMIZE_OUTPUT_FOR_C  = YES
 OPTIMIZE_OUTPUT_JAVA   = NO
 OPTIMIZE_FOR_FORTRAN   = NO
 OPTIMIZE_OUTPUT_VHDL   = NO
-EXTENSION_MAPPING      =
+EXTENSION_MAPPING      = lnt=Objective-C
 MARKDOWN_SUPPORT       = YES
 AUTOLINK_SUPPORT       = YES
 BUILTIN_STL_SUPPORT    = NO
@ -71,7 +71,7 @@ HIDE_FRIEND_COMPOUNDS  = NO
 HIDE_IN_BODY_DOCS      = NO
 INTERNAL_DOCS          = NO
 CASE_SENSE_NAMES       = NO
-HIDE_SCOPE_NAMES       = NO
+HIDE_SCOPE_NAMES       = YES
 HIDE_COMPOUND_REFERENCE= NO
 SHOW_INCLUDE_FILES     = YES
 SHOW_GROUPED_MEMB_INC  = NO
@ -137,7 +137,6 @@ INPUT                  = \
    ../ports/lint \
    ../../doxygen/glossary.dox

-
 INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          = \
    *.dox \
@ -145,7 +144,8 @@ FILE_PATTERNS          = \
    *.c \
    *.cpp \
    *.s \
-    *.asm
+    *.asm \
+    *.lnt

 RECURSIVE              = YES
 EXCLUDE                = \
@ -317,7 +317,7 @@ EXPAND_ONLY_PREDEF     = NO
 SEARCH_INCLUDES        = YES
 INCLUDE_PATH           =
 INCLUDE_FILE_PATTERNS  =
-PREDEFINED             = Q_SPY QP_IMPL
+PREDEFINED             = Q_SPY QP_IMPL Q_UTEST
 EXPAND_AS_DEFINED      =
 SKIP_FUNCTION_MACROS   = YES
 #---------------------------------------------------------------------------
--- a/doxygen/api.dox
+++ b/doxygen/api.dox
@ -164,7 +164,7 @@ Given the simplicity, portability, and low-resource consumption, the QV schedule


 ------------------------------------------------------------------------------
-@section api_qk Preemptive Run-to-Completion Kernel (QK)
+@section api_qk QK (Preemptive Run-to-Completion Kernel)
 QK is a tiny **preemptive**, priority-based, non-blocking kernel designed specifically for executing active objects. QK runs active objects in the same way as prioritized interrupt controller (such as NVIC in ARM Cortex-M) runs interrupts using the single stack. Active objects process their events in run-to-completion (RTC) fashion and remove themselves from the call stack, the same way as nested interrupts remove themselves from the stack upon completion. At the same time high-priority active objects can preempt lower-priority active objects, just like interrupts can preempt each other under a prioritized interrupt controller. QK meets all the requirement of the Rate Monotonic Scheduling (a.k.a. Rate Monotonic Analysis RMA) and can be used in hard real-time systems.


@ -185,7 +185,7 @@ QK is a tiny **preemptive**, priority-based, non-blocking kernel designed specif


 ------------------------------------------------------------------------------
-@section api_qxk Preemptive Dual-Mode (Run-to-Completion/Blocking) RTOS Kernel
+@section api_qxk QXK (Preemptive Dual-Mode RTOS Kernel)
 QXK is a small, preemptive, priority-based, dual-mode **blocking** kernel that executes active objects like the @ref qk "QK kernel", but can also execute traditional __blocking__ threads (extended threads). In this respect, QXK behaves exactly as a conventional __RTOS__ (Real-Time Operating System). QXK has been designed specifically for mixing event-driven active objects with traditional blocking code, such as commercial middleware (TCP/IP stacks, UDP stacks, embedded file systems, etc.) or legacy software.


--- a/doxygen/exa_native.dox
+++ b/doxygen/exa_native.dox
@ -145,53 +145,333 @@ You can hover the mouse cursor over the <span class="board"></span>&nbsp;&nbsp;
 - @subpage msp430_blinky_msp-exp430f5529lp <a class="preview board" href="bd_MSP-EXP430F5529LP.jpg" title="MSP-EXP430F5529LP"></a>
 - @subpage msp430_dpp_msp-exp430g2 <a class="preview board" href="bd_MSP-EXP430G2.jpg" title="MSP-EXP430G2"></a>
 */
+
 /*##########################################################################*/
 /*! @page arm-cm_blinky_ek-tm4c123gxl Blinky on EK-TM4C123GXL

+@tableofcontents
+
+<p>This example implements the @ref blinky "Blinky sample application" on the EK-TM4C123GLX board (ARM Cortex-M4F).
+</p>
+
@image html bd_EK-TM4C123GXL.jpg EK-TM4C123GXL board
-@n
-@n
+
+
+The Blinky example is located in the directory <span class="img folder">qpc/examples/arm-cm/blinky_ek-tm4c123gxl</span>, which is organized as follows:
+
+@code{.x}
+ qpc/                - QP/C installation directory
+  +-examples/        - QP/C examples directory (application)
+  | +-arm-cm/        - QP/C examples for ARM Cortex-M
+  | | +-blinky_ek-tm4c123gxl/ - Blinky example on the EK-TM4C123GLX board
+  | | | +-qk/        - QK version
+  | | | | +-arm/     - ARM-KEIL toolset
+  | | | | | +-blinky-qk.uvprojx - uVision project
+  | | | | +-gnu/     - GNU-ARM toolset
+  | | | | | +-Makefile          - Makefile for building the project
+  | | | | +-iar/     - IAR-ARM toolset
+  | | | | | +-blinky-qk.eww     - IAR EW-ARM workspace
+  | | | | +-bsp.c    - BSP for the QK kernel
+  | | | +-qv/        - QV version
+  | | | | +-arm/     - ARM-KEIL toolset
+  | | | | | +-blinky-qk.uvprojx - uVision project
+  | | | | +-gnu/     - GNU-ARM toolset
+  | | | | | +-Makefile          - Makefile for building the project with GNU-ARM
+  | | | | +-iar/     - IAR-ARM toolset
+  | | | | | +-blinky-qk.eww     - IAR EW-ARM workspace
+  | | | | +-bsp.c    - BSP for the QV kernel
+  | | | +-win32/     - Windows emulation (multithreaded)
+  | | | | +-Makefile          - Makefile for building the project with MinGW
+  | | | | +-bsp.c    - BSP for the Win32
+  | | | +-win32-qv/  - Windows emulation (single thread)
+  | | | | +-Makefile          - Makefile for building the project with MinGW
+  | | | | +-bsp.c    - BSP for the Win32-QV
+@endcode
+
+
+------------------------------------------------------------------------------
+@section arm-cm_blinky_ek-tm4c123gxl_feat Features Demonstrated
+- cooperative QV kernel
+  + with ARM-KEIL toolset
+  + with GNU-ARM toolset
+  + with IAR-ARM toolset
+- preemptive run-to-completion QK kernel
+  + with ARM-KEIL toolset
+  + with GNU-ARM toolset
+  + with IAR-ARM toolset
+- Windows emulation (console multithreaded)
+- Windows emulation (console, single threaded: win32-qv)
+
+
+------------------------------------------------------------------------------
+@section arm-cm_blinky_ek-tm4c123gxl_run Running the Example
+Once programmed into the board, the example blinks the on-board LED about once a second.
+
@image html blinky_ek-tm4c123gxl.gif Blinky on EK-TM4C123GLX (TivaC LaunchPad)
-@n
-Simple "Blinky" example for Texas Instruments TivaC123GXL MCU (Cortex-M4F), ARM (MDK-ARM), GNU-ARM, IAR EWARM toolsets.
-@n
+
+
+------------------------------------------------------------------------------
+@section arm-cm_blinky_ek-tm4c123gxl_win Windows Emulation
+The Windows emulation is a simple console application that produces the following output:
+
@image html blinky_win32.png Blinky emulation running in a Windows console
-@n
-@n
-@image html under_construction.jpg
+
+@next{arm-cm_blinky_efm32-slstk3401a}
 */
 /*##########################################################################*/
 /*! @page arm-cm_blinky_efm32-slstk3401a Blinky on EFM32-SLSTK3401A

+@tableofcontents
+
+<p>This example implements the @ref blinky "Blinky sample application" on the EFM32-SLSTK3401A board (ARM Cortex-M4F).
+</p>
+
@image html bd_EFM32-SLSTK3401A.jpg EFM32-SLSTK3401A board
-@n
-Simple "Blinky" example for for Silicon Labs Pearl Gecko MCU (Cortex-M4F), ARM (MDK-ARM), GNU-ARM, IAR EWARM toolsets.
-@n
+
+The Blinky example is located in the directory <span class="img folder">qpc/examples/arm-cm/blinky_efm32-slstk3401a</span>, which is organized as follows:
+
+@code{.x}
+ qpc/                - QP/C installation directory
+  +-examples/        - QP/C examples directory (application)
+  | +-arm-cm/        - QP/C examples for ARM Cortex-M
+  | | +-blinky_efm32-slstk3401a/ - Blinky example on the EFM32-SLSTK3401A board
+  | | | +-qk/        - QK version
+  | | | | +-arm/     - ARM-KEIL toolset
+  | | | | | +-blinky-qk.uvprojx - uVision project
+  | | | | +-gnu/     - GNU-ARM toolset
+  | | | | | +-Makefile          - Makefile for building the project
+  | | | | +-iar/     - IAR-ARM toolset
+  | | | | | +-blinky-qk.eww     - IAR EW-ARM workspace
+  | | | | +-bsp.c    - BSP for the QK kernel
+  | | | +-qv/        - QV version
+  | | | | +-arm/     - ARM-KEIL toolset
+  | | | | | +-blinky-qk.uvprojx - uVision project
+  | | | | +-gnu/     - GNU-ARM toolset
+  | | | | | +-Makefile          - Makefile for building the project with GNU-ARM
+  | | | | +-iar/     - IAR-ARM toolset
+  | | | | | +-blinky-qk.eww     - IAR EW-ARM workspace
+  | | | | +-bsp.c    - BSP for the QV kernel
+  | | | +-win32/     - Windows emulation (multithreaded)
+  | | | | +-Makefile          - Makefile for building the project with MinGW
+  | | | | +-bsp.c    - BSP for the Win32
+  | | | +-win32-qv/  - Windows emulation (single thread)
+  | | | | +-Makefile          - Makefile for building the project with MinGW
+  | | | | +-bsp.c    - BSP for the Win32-QV
+@endcode
+
+
+------------------------------------------------------------------------------
+@section arm-cm_blinky_efm32-slstk3401a_feat Features Demonstrated
+- cooperative QV kernel
+  + with ARM-KEIL toolset
+  + with GNU-ARM toolset
+  + with IAR-ARM toolset
+- preemptive run-to-completion QK kernel
+  + with ARM-KEIL toolset
+  + with GNU-ARM toolset
+  + with IAR-ARM toolset
+- Windows emulation (console multithreaded)
+- Windows emulation (console, single threaded: win32-qv)
+
+
+------------------------------------------------------------------------------
+@section arm-cm_blinky_efm32-slstk3401a_run Running the Example
+Once programmed into the board, the example blinks the on-board LED about once a second.
+
+
+------------------------------------------------------------------------------
+@section arm-cm_blinky_efm32-slstk3401a_win Windows Emulation
+The Windows emulation is a simple console application that produces the following output:
+
@image html blinky_win32.png Blinky emulation running in a Windows console
-@n
-@n
-@image html under_construction.jpg
+
+@next{arm-cm_dpp_ek-tm4c123gxl}
 */
 /*##########################################################################*/
 /*! @page arm-cm_dpp_ek-tm4c123gxl DPP on EK-TM4C123GXL

+@tableofcontents
+
+<p>This example implements the @ref dpp "Dining Philosophers Problem" sample application on the EK-TM4C123GLX board (ARM Cortex-M4F).
+</p>
+
@image html bd_EK-TM4C123GXL.jpg EK-TM4C123GXL board

-Dining Philosophers Problem (DPP) example for Texas Instruments TivaC123GXL MCU (Cortex-M4F), ARM (MDK-ARM), GNU-ARM, IAR EWARM toolsets.
+The DPP example is located in the directory <span class="img folder">qpc/examples/arm-cm/dpp_ek-tm4c123gxl</span>, which is organized as follows:
+
+@code{.x}
+ qpc/                - QP/C installation directory
+  +-examples/        - QP/C examples directory (applications)
+  | +-arm-cm/        - QP/C examples for ARM Cortex-M
+  | | +-dpp_ek-tm4c123gxl/ - DPP example on the EK-TM4C123GLX board
+  | | | +-lint/      - PC-Lint version (static analysis of the application code)
+  | | | | +-lin.bat  - batch file for running the PC-Lint
+  | | | | +-options.lnt - PC-Lint options file for the DPP application code
+  | | | +-qk/        - QK version
+  | | | | +-arm/     - ARM-KEIL toolset
+  | | | | | +-dpp-qk.uvprojx - uVision project
+  | | | | +-gnu/     - GNU-ARM toolset
+  | | | | | +-Makefile          - Makefile for building the project
+  | | | | +-iar/     - IAR-ARM toolset
+  | | | | | +-dpp-qk.eww     - IAR EW-ARM workspace
+  | | | | +-ti/      - TI-ARM toolset (CCS)
+  | | | | | +-.ccsproject  - CCS project
+  | | | | | +-.cproject    - C Eclipse project
+  | | | | | +-.project     - Eclipse project
+  | | | | +-bsp.c    - BSP for the QK kernel
+  | | | | +-main.c   - main() for the QK kernel
+  | | | +-qv/        - QV version
+  | | | | +-arm/     - ARM-KEIL toolset
+  | | | | | +-dpp-qk.uvprojx - uVision project
+  | | | | +-gnu/     - GNU-ARM toolset
+  | | | | | +-Makefile          - Makefile for building the project with GNU-ARM
+  | | | | +-iar/     - IAR-ARM toolset
+  | | | | | +-blinky-qk.eww     - IAR EW-ARM workspace
+  | | | | +-bsp.c    - BSP for the QV kernel
+  | | | | +-main.c   - main() for the QV kernel
+  | | | +-qxk/       - QXK version
+  | | | | +-arm/     - ARM-KEIL toolset
+  | | | | | +-dpp-qk.uvprojx - uVision project
+  | | | | +-gnu/     - GNU-ARM toolset
+  | | | | | +-Makefile          - Makefile for building the project
+  | | | | +-iar/     - IAR-ARM toolset
+  | | | | | +-dpp-qk.eww     - IAR EW-ARM workspace
+  | | | | +-ti/      - TI-ARM toolset (CCS)
+  | | | | | +-.ccsproject  - CCS project
+  | | | | | +-.cproject    - C Eclipse project
+  | | | | | +-.project     - Eclipse project
+  | | | | +-bsp.c    - BSP for the QXK kernel
+  | | | | +-main.c   - main() for the QXK kernel
+  | | | | +-test.c   - extended (blocking) test threads
+  | | | +-qspyview/  - visualization and monitoring for the DPP example
+  | | | | +-dpp.tcl        - QSpyView specialization for the DPP
+  | | | | +-qspyview.bat   - batch file for launching QSpyView for DPP
+@endcode
+
+
+------------------------------------------------------------------------------
+@section arm-cm_dpp_ek-tm4c123gxl_feat Features Demonstrated
+- cooperative QV kernel
+  + with ARM-KEIL toolset
+  + with GNU-ARM toolset
+  + with IAR-ARM toolset
+  + with TI-ARM toolset (CCS)
+- preemptive run-to-completion QK kernel
+  + with ARM-KEIL toolset
+  + with GNU-ARM toolset
+  + with IAR-ARM toolset
+  + with TI-ARM toolset (CCS)
+- preemptive dual-mode QXK kernel
+  + with ARM-KEIL toolset
+  + with GNU-ARM toolset
+  + with IAR-ARM toolset
+  + with TI-ARM toolset (CCS)
+- QP/Spy software tracing (output)
+- QP/Spy software tracing (input QS-RX)
+- Unit Testing with QUTest
+- Windows emulation with GUI (multithreaded)
+- Windows emulation with GUI (single threaded, win32-qv)
+
+
+------------------------------------------------------------------------------
+@section arm-cm_dpp_ek-tm4c123gxl_run Running the Example
+Once programmed into the board, the example rapidly toggles the Blue LED from the idle loop (blue LED glows) and toggles the Red and Green LEDs as the Philosophers change their state. Additionally, you can depress and hold the SW1 button (left) to PAUSE the application (Table transitions into the "paused" state). Releasing the SW1 button causes transition back to the "serving" state.
+
+
+------------------------------------------------------------------------------
+@section arm-cm_dpp_ek-tm4c123gxl_qutest Unit Testing
+The examples demonstrates the QUTest unit tests for the application.
+
+
+------------------------------------------------------------------------------
+@section arm-cm_dpp_ek-tm4c123gxl_spy QP/Spy Software Tracing
+The application also demonstrates <a href="https://state-machine.com/qtools/qpspy.html" target="_blank" class="extern">QP/Spy</a> software tracing output and input. To exercise this feature, you need to build and upload the Spy build configuration into the board.

-@image html dpp_win32.png DPP emulation running in Windows GUI
-@n
-@n
-@image html under_construction.jpg
 */
 /*##########################################################################*/
 /*! @page arm-cm_dpp_efm32-slstk3401a DPP on EFM32-SLSTK3401A

+@tableofcontents
+
+<p>This example implements the @ref dpp "Dining Philosophers Problem" sample application on the EFM32-SLSTK3401A board (ARM Cortex-M4F).
+</p>
+
@image html bd_EFM32-SLSTK3401A.jpg EFM32-SLSTK3401A board
-@n
-Dining Philosophers Problem (DPP) example for for Silicon Labs Pearl Gecko MCU (Cortex-M4F), ARM (MDK-ARM), GNU-ARM, IAR EWARM toolsets.
-@n
-@image html under_construction.jpg
+
+The DPP example is located in the directory <span class="img folder">qpc/examples/arm-cm/dpp_efm32-slstk3401a</span> and includes versions for @ref qv "cooperative QV kernel", the  @ref qk "preemptive QK kernel", and the @ref qxk "preemptive dual mode QXK RTOS kernel"  each provided for the ARM-KEIL, GNU-ARM, and IAR-ARM. The following annotated directory listing describes the contents of the example folder:
+
+@code{.x}
+ qpc/                - QP/C installation directory
+  +-examples/        - QP/C examples directory (application)
+  | +-arm-cm/        - QP/C examples for ARM Cortex-M
+  | | +-dpp_efm32-slstk3401a/ - DPP example on the EK-TM4C123GLX board
+  | | | +-lint/      - PC-Lint version (static analysis of the application code)
+  | | | | +-lin.bat  - batch file for running the PC-Lint
+  | | | | +-options.lnt - PC-Lint options file for the DPP application code
+  | | | +-qk/        - QK version
+  | | | | +-arm/     - ARM-KEIL toolset
+  | | | | | +-dpp-qk.uvprojx - uVision project
+  | | | | +-gnu/     - GNU-ARM toolset
+  | | | | | +-Makefile          - Makefile for building the project
+  | | | | +-iar/     - IAR-ARM toolset
+  | | | | | +-dpp-qk.eww     - IAR EW-ARM workspace
+  | | | | +-bsp.c    - BSP for the QK kernel
+  | | | | +-main.c   - main() for the QK kernel
+  | | | +-qv/        - QV version
+  | | | | +-arm/     - ARM-KEIL toolset
+  | | | | | +-dpp-qk.uvprojx - uVision project
+  | | | | +-gnu/     - GNU-ARM toolset
+  | | | | | +-Makefile          - Makefile for building the project with GNU-ARM
+  | | | | +-iar/     - IAR-ARM toolset
+  | | | | | +-blinky-qk.eww     - IAR EW-ARM workspace
+  | | | | +-bsp.c    - BSP for the QV kernel
+  | | | | +-main.c   - main() for the QV kernel
+  | | | +-qxk/       - QXK version
+  | | | | +-arm/     - ARM-KEIL toolset
+  | | | | | +-dpp-qk.uvprojx - uVision project
+  | | | | +-gnu/     - GNU-ARM toolset
+  | | | | | +-Makefile          - Makefile for building the project
+  | | | | +-iar/     - IAR-ARM toolset
+  | | | | | +-dpp-qk.eww     - IAR EW-ARM workspace
+  | | | | +-bsp.c    - BSP for the QXK kernel
+  | | | | +-main.c   - main() for the QXK kernel
+  | | | | +-test.c   - extended (blocking) test threads
+  | | | +-qspyview/  - visualization and monitoring for the DPP example
+  | | | | +-dpp.tcl        - QSpyView specialization for the DPP
+  | | | | +-qspyview.bat   - batch file for launching QSpyView for DPP
+@endcode
+
+
+------------------------------------------------------------------------------
+@section arm-cm_dpp_efm32-slstk3401a_feat Features Demonstrated
+- cooperative QV kernel
+  + with ARM-KEIL toolset
+  + with GNU-ARM toolset
+  + with IAR-ARM toolset
+- preemptive run-to-completion QK kernel
+  + with ARM-KEIL toolset
+  + with GNU-ARM toolset
+  + with IAR-ARM toolset
+- preemptive dual-mode QXK kernel
+  + with ARM-KEIL toolset
+  + with GNU-ARM toolset
+  + with IAR-ARM toolset
+- QP/Spy software tracing (output)
+- QP/Spy software tracing (input QS-RX)
+- Unit Testing with QUTest
+- Windows emulation with GUI (multithreaded)
+- Windows emulation with GUI (single threaded, win32-qv)
+
+
+------------------------------------------------------------------------------
+@section arm-cm_dpp_efm32-slstk3401a_run Running the Example
+Once programmed into the board, the example rapidly toggles the LED1 from the idle loop (LED1 glows) and toggles LED0 as the Philosophers change their state. Additionally, you can depress and hold the BTN0 button (left) to PAUSE the application (Table transitions into the "paused" state). Releasing the BTN0 button causes transition back to the "serving" state.
+
+
+------------------------------------------------------------------------------
+@section arm-cm_dpp_efm32-slstk3401a_spy QP/Spy Software Tracing
+The application also demonstrates <a href="https://state-machine.com/qtools/qpspy.html" target="_blank" class="extern">QP/Spy</a> software tracing output and input. To exercise this feature, you need to build and upload the Spy build configuration into the board.
+
 */
 /*##########################################################################*/
 /*! @page arm-cm_dpp_mbed-lpc1768 DPP on mbed-LPC1768
--- a/doxygen/history.dox
+++ b/doxygen/history.dox
@ -2,11 +2,11 @@
@page history Revision History

@section qpc_5_9_7 Version 5.9.7, 2017-08-18
-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>.
-
+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().
@ -18,10 +18,10 @@ All related QXK and QK examples have been updated to use the selective scheduler
 - @ref arm-cm_dpp_ek-tm4c123gxl

@attention
-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.
-
+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.
+
@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. 
+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).

--- a/doxygen/metrics.dox
+++ b/doxygen/metrics.dox
--- a/doxygen/ports_native.dox
+++ b/doxygen/ports_native.dox
@ -20,8 +20,113 @@
 /*##########################################################################*/
 /*! @page lint PC-Lint

-@image html under_construction.jpg
+@tableofcontents

+<p>The QP/C distribution contains a "port" to <a href="http://www.gimpel.com/html/products.htm" target="_blank" class="extern"><b>PC-Lint/FlexeLint</b></a> static analysis tool from <a href="http://www.gimpel.com" target="_blank" class="extern">Gimpel Software</a>, which is a static analysis tool for C and C++ with one of the longest track records and best value of the money in the industry. The "PC-Lint port" allows you to statically analyze the QP/C source code and facilitates static analysis of your **application code** based on QP/C.
+</p>
+The QP/C "port" to PC-Lint is located in the directory <span class="img folder">qpc/ports/lint</span> and includes also lint configuration files located in the <span class="img folder">qpc/include</span> directory, as well as an example of "linting" application code in the directory <span class="img folder">qpc/examples/arm-cm/dpp_ek-tm4c123gxl/</span>. The following listing describes the most important files in these three directories.
+
+@code{.x}
+ qpc\                  - QP/C installation directory
+  |
+  +-include/           - QP/C platform-independent includes
+  | +-au-ds.lnt        - Dan Saks recommendations
+  | +-au-misra2.lnt    - Main PC-Lint MISRA-C:2004 compliance options
+  | +-qpc.lnt          - PC-Lint options for QP/C applications
+  | +-std.lnt          - Standard PC-Lint settings recommended by Quantum Leaps
+  | +-. . .            - QP/C header files...
+  | |
+  | +-ports/           - QP/C ports directory
+  | | +-lint/          - QP/C "port" to PC-Lint
+  | | | +-MISRA_Exemplar_Suite_test\ - MISRA Exemplar Suite rule coverage test
+  | | | +-qk/          - QP/C port with the QK kernel
+  | | | +-qv/          - QP/C port with the QV kernel
+  | | | +-qxk/         - QP/C port with the QXK kernel
+  | | | +-lin.bat      - Batch file to invoke PC-Lint to run analysis of QP/C code
+  | | | +-options.lnt  - PC/Lint options for "linting" QP/C source code
+  | | | +-lint_qf.log  - PC/Lint output for the QEP/QF components of QP/C
+  | | | +-lint_qs.log  - PC/Lint output for the QS  component of QP/C
+  | | | +-lint_qv.log  - PC/Lint output for the QV  component of QP/C
+  | | | +-lint_qk.log  - PC/Lint output for the QK  component of QP/C
+  | | | +-lint_qxk.log - PC/Lint output for the QXK component of QP/C
+  | | | +-qep_port.h   - QEP component "port" to a generic ANSI C compiler
+  | | | +-qf_port.h    - QF  component "port" to a generic ANSI C compiler
+  | | | +-qs_port.h    - QS  component "port" to a generic ANSI C compiler
+  | | | +-stdbool.h    - Standard Boolean type and constants for an ANSI C compiler
+  | | | +-stdint.h     - Standard exact-width integers for an ANSI C compiler
+  | |
+  | +-examples\        - QP/C examples directory (application)
+  | | +-arm-cm\        - QP/C examples for ARM Cortex-M
+  | | | +-dpp_ek-tm4c123gxl\ - DPP example on the EK-TM4C123GLX board
+  | | | | +-lint\      - directory for linting the application
+  | | | | | +-lin.bat  - Batch to run PC-Lint analysis of application code
+  | | | | | +-options.lnt - PC/Lint options for "linting" of application code
+@endcode
+
+
+------------------------------------------------------------------------------
+@section lint_qpc Linting the QP/C Source Code
+The directory <span class="img folder">qpc/ports/lint</span> (see listing above) contains also the **lin.bat** batch file for "linting" the QP/C source code. The lin.bat batch file invokes PC-Lint and generates the lint output files. As shown in the listing above, the lint output is collected into four text files `lint_qf.log`, `lint_qs.log`, `lint_qk.log`, `lint_qv.log`, and `lint_qs.log`, for QEP/QF, QK, QV, QXK and QS components of the QP/C framework, respectively.
+
+@note
+In order to execute the **lin.bat** file on your system, you might need to adjust the symbol  `PC_LINT_DIR` at the top of the batch file, to the PC-Lint installation directory on your computer.
+
+@note
+The lin.bat batch file invoked without any command-line options checks the QP/C code in the Q_SPY build configuration with software tracing enabled. However, by the nature of software tracing, the Q_SPY configuration transgresses many more MISRA-C:2-004 rules than the standard configuration. However, the Q_SPY configuration is never used for production code, so the MISRA-C compliance of the QP/C framework should not be judged by the deviations that happen only in the Q_SPY configuration.
+
+According to the PC-Lint guidelines, the lin.bat uses two option files: the **std.lnt option file discussed before and the options.lnt option file that covers all deviations from the MISRA-C rules in the QP/C source code. Section 3 (MISRA compliance matrix) cross-references all these deviations, while Section 5 (deviation procedures) describes the reasons for deviations in those, very specific contexts.
+
+
+------------------------------------------------------------------------------
+@section lint_app Linting QP/C Application Code
+The QP/C baseline code contains an example of MISRA-C compliance checking with PC/Lint: the DPP example for the EK-TM4C123GLX Cortex-M4F board, located in the directory <span class="img folder">qpc/examples/arm-cm/dpp_ek-tm4c123gxl/lint</span>. The PC-Lint analysis is very simple and requires invoking the **lin.bat** file from the `lint` sub-directory.
+
+@note
+In order to execute the **lin.bat** file on your system, you might need to adjust the symbol  `PC_LINT_DIR` at the top of the batch file, to the PC-Lint installation directory on your computer. You
+
+The `lint` subdirectory in each of the application folders contains also the `options.lnt` with the PC-Lint options specific to linting the application. There is also a choice of the compiler, whereas `options_gcc.lnt` are for the GCC-ARM and `options_iar.lnt` are for `IAR-ARM` compilers, respectively. These files specify the include directory for the specific embedded compiler used to compile the application, and you most likely need to adjust it for your system.
+Running PC-Lint on embedded projects (such as the DPP example for ARM Cortex-M) requires option files for the specific compilers (`co-iar-arm.lnt` file for IAR ARM and `co-gnu-arm.lnt` file GNU ARM, respectively). These option files are provided in the <a href="https://state-machine.com/qtools/" target="_blank" class="extern">QTools collection</a>. The location of the QTools directory in your system is specified in the `options.lnt` file, and you most likely need to adjust it for your system.
+
+@note
+The QTools collection is available for a separate download from https://sourceforge.net/projects/qpc/files/QTools. Quantum Leaps is committed to keep adding more and more PC-Lint option files for various embedded C/C++ cross-compilers in the QTools collection.
+
+
+------------------------------------------------------------------------------
+@section lint_options Structure of PC-Lint Options for QP/C
+PC-Lint has several places where it reads its currently valid options:
+- From special Lint option files (usually called `*.lnt`)
+- From the command line
+- From within the special lint-comments in the source code modules (not recommended)
+
+The QP/C source code and example application code has been "linted" only by means of the first alternative (option files) with possibility of adding options via command line. The third alternative--lint comments--is not used and Quantum Leaps does not recommend this alternative.
+
+@note
+The QP/C source code is completely free of lint comments, which are viewed as a contamination of the source code.
+
+The structure of the PC-Lint option files used for "linting" QP/C follows exactly the <a href="http://www.gimpel.com" target="_blank" class="extern">Gimpel Software</a> guidelines for configuring PC-Lint (See Section 3.2 "Configuration" in the *PC-Lint/FlexeLint Manual*). The design and grouping of the lint options also reflects the fact that static code analysis of a software framework, such as QP/C, has really two major aspects. First, the source code of the framework itself has to be analyzed. But even more important and helpful to the users of the framework is providing the infrastructure to effectively analyze the application-level code based on the framework. With this in mind, the PC-Lint options for static analysis of QP/C are divided into two groups, located in directories <span class="img folder">qpc/include</span> and <span class="img folder">qpc/ports/lint</span>. These two groups are for analyzing QP/C **applications** and QP/C **source code**, respectively.
+
+As shown in the PC-Lint "port" files description, the directory <span class="img folder">qpc/include</span>, contains the PC-Lint options for "linting" the application code along with all platform-independent QP/C header files required by the applications. This collocation of lint options with header files simplifies "linting", because specifying just `-iqpc/include` include directory to PC-Lint accomplishes both inclusion of QP/C header files and PC-Lint options.
+Note that the `qpc/include` directory contains all PC-Lint option files used in "linting" the code, including the standard MISRA-C:2004 `au-misr2.lnt` option file as well as Dan Saks' recommendations `au-ds.lnt`, which are copied from the PC-Lint distribution. This design freezes the lint options for which the compliance has been checked.
+
+
+<div class="separate"></div>
+@subsection lint_std_lnt The std.lnt option file
+According to the Gimpel Software *PC-Lint Configuration Guidelines*, the file `qpc/include/std.lnt` file, contains the top-level options, which Quantum Leaps recommends for all projects. These options include the formatting of the PC-Lint messages and making two passes to perform better cross-module analysis. However, the most important option is `-restore_at_end`, which has the effect of surrounding each source file with options `-save` and `-restore`. This precaution prevents options from "bleeding" from one file to another.
+
+<b>Top-level option file std.lnt</b>
+@include std.lnt
+
+
+<div class="separate"></div>
+@subsection lint_qpc_lnt  The qpc.lnt option file
+The most important file for "linting" QP/C applications is the **qpc.lnt** option file. This file handles all deviations from the MISRA-C:2004 rules, which might arise at the application-level code from the use of the QP/C framework. In other words, the **qpc.lnt** option file allows completely clean "linting" of the application-level code, as long as the application code does not violate any of the MISRA-C:2004 rules.
+
+At the same time, the **qpc.lnt** option file has been very carefully designed not to suppress any MISRA-C:2004 rule checking outside the very specific context of the QP/C API. In other words, the qpc.lnt option file still supports 100% of the MISRA-C:2004 rule checks that PC-Lint is capable of performing.
+
+@remarks
+For example, for reasons explained in Section 5.10 of the <a href="https://state-machine.com/doc/AN_QP-C_MISRA.pdf" target="_blank" class="extern">"QP/C MISRA Compliance Matrix"</a>, QP/C extensively uses function-like macros, which deviates from the MISRA-C:2004 advisory rule 19.7 and which PC-Lint checks with the warning 961. However, instead of suppressing this warning globally (with the -e961 directive), the qpc.lnt option file suppresses warning 961 only for the specific QP function-like macros that are visible to the application level. So specifically, the qpc.lnt file contains directives `-estring(961, Q_TRAN, Q_SUPER, ...)`, which suppresses the warning only for the specified macros, but does not disable checking of any other macros in the application-level code.
+
+@next{arm-cm}
 */
 /*##########################################################################*/
 /*! @page arm-cr ARM Cortex-R
@ -34,6 +139,7 @@

@section arm-cr_qv Cooperative QV Kernel

+@next{arm7-9}
 */
 /*##########################################################################*/
 /*! @page arm7-9 ARM7/ARM9
@ -46,6 +152,7 @@

@section arm7-9_qv Cooperative QV Kernel

+@next{msp430}
 */
 /*##########################################################################*/
 /*! @page msp430 MSP430
--- a/examples/win32/dpp/bsp.c
+++ b/examples/win32/dpp/bsp.c
@ -1,7 +1,7 @@
 /*****************************************************************************
 * Product: DPP example, Windows (console)
-* Last updated for version 5.8.0
-* Last updated on  2016-11-29
+* Last updated for version 5.9.7
+* Last updated on  2017-08-25
 *
 *                    Q u a n t u m     L e a P s
 *                    ---------------------------
@ -84,6 +84,8 @@ void Q_onAssert(char const * const module, int_t loc) {
 }
 /*..........................................................................*/
 void BSP_init(int argc, char *argv[]) {
+    (void)argc;
+    (void)argv;

    printf("Dining Philosophers Problem example"
           "\nQP %s\n"
--- a/include/qpc.lnt
+++ b/include/qpc.lnt
@ -1,36 +1,40 @@
-//============================================================================
-// Product: PC-Lint 9.x option file for linting QP/C applications
-// Last updated for version 5.9.4
-// Last updated on  2017-07-05
-//
-//                    Q u a n t u m     L e a P s
-//                    ---------------------------
-//                    innovating embedded systems
-//
-// Copyright (C) 2005-2017 Quantum Leaps, LLC. All rights reserved.
-//
-// This program is open source software: you can redistribute it and/or
-// modify it under the terms of the GNU General Public License as published
-// by the Free Software Foundation, either version 3 of the License, or
-// (at your option) any later version.
-//
-// Alternatively, this program may be distributed and modified under the
-// terms of Quantum Leaps commercial licenses, which expressly supersede
-// the GNU General Public License and are specifically designed for
-// licensees interested in retaining the proprietary status of their code.
-//
-// This program is distributed in the hope that it will be useful,
-// but WITHOUT ANY WARRANTY; without even the implied warranty of
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-// GNU General Public License for more details.
-//
-// You should have received a copy of the GNU General Public License
-// along with this program. If not, see <http://www.gnu.org/licenses/>.
-//
-// Contact information:
-// https://state-machine.com
-// mailto:info@state-machine.com
-//============================================================================
+/// @file
+/// @brief PC-Lint 9.x option file for linting QP/C applications
+/// @cond
+///===========================================================================
+/// Product: QP/C
+/// Last Updated for Version: 5.9.7
+/// Date of the Last Update:  2017-08-20
+///
+///                    Q u a n t u m     L e a P s
+///                    ---------------------------
+///                    innovating embedded systems
+///
+/// Copyright (C) Quantum Leaps. All rights reserved.
+///
+/// This program is free software: you can redistribute it and/or modify
+/// it under the terms of the GNU General Public License as published by
+/// the Free Software Foundation, either version 3 of the License, or
+/// (at your option) any later version.
+///
+/// Alternatively, this program may be distributed and modified under the
+/// terms of Quantum Leaps commercial licenses, which expressly supersede
+/// the GNU General Public License and are specifically designed for
+/// licensees interested in retaining the proprietary status of their code.
+///
+/// This program is distributed in the hope that it will be useful,
+/// but WITHOUT ANY WARRANTY; without even the implied warranty of
+/// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+/// GNU General Public License for more details.
+///
+/// You should have received a copy of the GNU General Public License
+/// along with this program. If not, see <http://www.gnu.org/licenses/>.
+///
+/// Contact information:
+/// https://state-machine.com
+/// info@state-machine.com
+///============================================================================
+/// @endcond

 // General
 -estring(793,6)       // ANSI/ISO limit of 6 significant chars exceeded
@ -456,8 +460,8 @@
 QFsm_ctor,
 QF_onIdle)
 -estring(961,         // MISRA04-19.7(adv) function-like macro
- QHsm_init,
- QHsm_dispatch,
+ QMsm_init,
+ QMsm_dispatch,
 QFsm_init,
 QFsm_dispatch,
 QActive_start,
@ -469,8 +473,8 @@
 QTimeEvt_postEvery,
 Q_ROM_BYTE)
 -esym(960,            // MISRA04-19.4(req) Disallowed macro definition
- QHsm_init,
- QHsm_dispatch,
+ QMsm_init,
+ QMsm_dispatch,
 QFsm_init,
 QFsm_dispatch,
 QActive_start,
--- a/include/std.lnt
+++ b/include/std.lnt
@ -1,36 +1,41 @@
-//============================================================================
-// Product: PC-Lint 9.x standard option file
-// Last Updated for Version: 5.7.1
-// Date of the Last Update:  2016-09-18
-//
-//                    Q u a n t u m     L e a P s
-//                    ---------------------------
-//                    innovating embedded systems
-//
-// Copyright (C) Quantum Leaps. All rights reserved.
-//
-// This program is free software: you can redistribute it and/or modify
-// it under the terms of the GNU General Public License as published by
-// the Free Software Foundation, either version 3 of the License, or
-// (at your option) any later version.
-//
-// Alternatively, this program may be distributed and modified under the
-// terms of Quantum Leaps commercial licenses, which expressly supersede
-// the GNU General Public License and are specifically designed for
-// licensees interested in retaining the proprietary status of their code.
-//
-// This program is distributed in the hope that it will be useful,
-// but WITHOUT ANY WARRANTY; without even the implied warranty of
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-// GNU General Public License for more details.
-//
-// You should have received a copy of the GNU General Public License
-// along with this program. If not, see <http://www.gnu.org/licenses/>.
-//
-// Contact information:
-// Web:   http://www.state-machine.com
-// Email: info@state-machine.com
-//============================================================================
+/// @file
+/// @brief PC-Lint 9.x standard option file
+/// @ingroup lint
+/// @cond
+///===========================================================================
+/// Product: QP/C
+/// Last Updated for Version: 5.9.7
+/// Date of the Last Update:  2017-08-20
+///
+///                    Q u a n t u m     L e a P s
+///                    ---------------------------
+///                    innovating embedded systems
+///
+/// Copyright (C) Quantum Leaps. All rights reserved.
+///
+/// This program is free software: you can redistribute it and/or modify
+/// it under the terms of the GNU General Public License as published by
+/// the Free Software Foundation, either version 3 of the License, or
+/// (at your option) any later version.
+///
+/// Alternatively, this program may be distributed and modified under the
+/// terms of Quantum Leaps commercial licenses, which expressly supersede
+/// the GNU General Public License and are specifically designed for
+/// licensees interested in retaining the proprietary status of their code.
+///
+/// This program is distributed in the hope that it will be useful,
+/// but WITHOUT ANY WARRANTY; without even the implied warranty of
+/// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+/// GNU General Public License for more details.
+///
+/// You should have received a copy of the GNU General Public License
+/// along with this program. If not, see <http://www.gnu.org/licenses/>.
+///
+/// Contact information:
+/// https://state-machine.com
+/// info@state-machine.com
+///============================================================================
+/// @endcond

 // output: a single line, file info always, use full path names
 -hF1
--- a/ports/lint/options.lnt
+++ b/ports/lint/options.lnt
@ -1,36 +1,40 @@
-//////////////////////////////////////////////////////////////////////////////
-// Product: PC-Lint 9.x option file for linting QP/C
-// Last updated for version 5.9.6
-// Last updated on  2017-08-01
-//
-//                    Q u a n t u m     L e a P s
-//                    ---------------------------
-//                    innovating embedded systems
-//
-// Copyright (C) Quantum Leaps, LLC. All rights reserved.
-//
-// This program is open source software: you can redistribute it and/or
-// modify it under the terms of the GNU General Public License as published
-// by the Free Software Foundation, either version 3 of the License, or
-// (at your option) any later version.
-//
-// Alternatively, this program may be distributed and modified under the
-// terms of Quantum Leaps commercial licenses, which expressly supersede
-// the GNU General Public License and are specifically designed for
-// licensees interested in retaining the proprietary status of their code.
-//
-// This program is distributed in the hope that it will be useful,
-// but WITHOUT ANY WARRANTY; without even the implied warranty of
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-// GNU General Public License for more details.
-//
-// You should have received a copy of the GNU General Public License
-// along with this program. If not, see <http://www.gnu.org/licenses/>.
-//
-// Contact information:
-// http://www.state-machine.com
-// mailto:info@state-machine.com
-//////////////////////////////////////////////////////////////////////////////
+/// @file
+/// @brief PC-Lint 9.x option file for linting QP/C source code
+/// @cond
+///===========================================================================
+/// Product: QP/C
+/// Last Updated for Version: 5.9.7
+/// Date of the Last Update:  2017-08-20
+///
+///                    Q u a n t u m     L e a P s
+///                    ---------------------------
+///                    innovating embedded systems
+///
+/// Copyright (C) Quantum Leaps. All rights reserved.
+///
+/// This program is free software: you can redistribute it and/or modify
+/// it under the terms of the GNU General Public License as published by
+/// the Free Software Foundation, either version 3 of the License, or
+/// (at your option) any later version.
+///
+/// Alternatively, this program may be distributed and modified under the
+/// terms of Quantum Leaps commercial licenses, which expressly supersede
+/// the GNU General Public License and are specifically designed for
+/// licensees interested in retaining the proprietary status of their code.
+///
+/// This program is distributed in the hope that it will be useful,
+/// but WITHOUT ANY WARRANTY; without even the implied warranty of
+/// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+/// GNU General Public License for more details.
+///
+/// You should have received a copy of the GNU General Public License
+/// along with this program. If not, see <http://www.gnu.org/licenses/>.
+///
+/// Contact information:
+/// https://state-machine.com
+/// info@state-machine.com
+///============================================================================
+/// @endcond

 // library headers
 +libclass()       // lint all header files, including "foreign"
--- a/ports/posix/qf_port.c
+++ b/ports/posix/qf_port.c
@ -4,8 +4,8 @@
 * @ingroup ports
 * @cond
 ******************************************************************************
-* Last Updated for Version: 5.8.2
-* Date of the Last Update:  2016-12-22
+* Last Updated for Version: 5.9.7
+* Date of the Last Update:  2017-08-25
 *
 *                    Q u a n t u m     L e a P s
 *                    ---------------------------
@ -56,6 +56,7 @@ Q_DEFINE_THIS_MODULE("qf_port")
 pthread_mutex_t QF_pThreadMutex_;

 /* Local objects -----------------------------------------------------------*/
+static pthread_mutex_t l_startupMutex;
 static bool l_isRunning;
 static struct timespec l_tick;
 enum { NANOSLEEP_NSEC_PER_SEC = 1000000000 }; /* see NOTE05 */
@ -71,6 +72,14 @@ void QF_init(void) {
    /* init the global mutex with the default non-recursive initializer */
    pthread_mutex_init(&QF_pThreadMutex_, NULL);

+    /* init the startup mutex with the default non-recursive initializer */
+    pthread_mutex_init(&l_startupMutex, NULL);
+
+    /* lock the startup mutex to block any active objects started before
+    * calling QF_run()
+    */
+    pthread_mutex_lock(&l_startupMutex);
+
    /* clear the internal QF variables, so that the framework can (re)start
    * correctly even if the startup code is not called to clear the
    * uninitialized data (as is required by the C Standard).
@ -97,6 +106,11 @@ int_t QF_run(void) {
        /* setting priority failed, probably due to insufficient privieges */
    }

+    /* unlock the startup mutex to unblock any active objects started before
+    * calling QF_run()
+    */
+    pthread_mutex_unlock(&l_startupMutex);
+
    l_isRunning = true;
    while (l_isRunning) { /* the clock tick loop... */
        QF_onClockTick(); /* clock tick callback (must call QF_TICK_X()) */
@ -104,6 +118,7 @@ int_t QF_run(void) {
        nanosleep(&l_tick, NULL); /* sleep for the number of ticks, NOTE05 */
    }
    QF_onCleanup(); /* invoke cleanup callback */
+    pthread_mutex_destroy(&l_startupMutex);
    pthread_mutex_destroy(&QF_pThreadMutex_);

    return (int_t)0; /* return success */
@ -119,6 +134,11 @@ void QF_stop(void) {
 /*..........................................................................*/
 static void *thread_routine(void *arg) { /* the expected POSIX signature */
    QActive *act = (QActive *)arg;
+
+    /* block this thread until the startup mutex is unlocked from QF_run() */
+    pthread_mutex_lock(&l_startupMutex);
+    pthread_mutex_unlock(&l_startupMutex);
+
    /* loop until m_thread is cleared in QActive_stop() */
    do {
        QEvt const *e = QActive_get_(act); /* wait for the event */
--- a/ports/win32/qf_port.c
+++ b/ports/win32/qf_port.c
@ -4,8 +4,8 @@
 * @ingroup qf
 * @cond
 ******************************************************************************
-* Last Updated for Version: 5.8.2
-* Date of the Last Update:  2016-12-22
+* Last Updated for Version: 5.9.7
+* Date of the Last Update:  2017-08-25
 *
 *                    Q u a n t u m     L e a P s
 *                    ---------------------------
@ -54,6 +54,7 @@ Q_DEFINE_THIS_MODULE("qf_port")

 /* Local objects ===========================================================*/
 static CRITICAL_SECTION l_win32CritSect;
+static CRITICAL_SECTION l_startupCritSect;
 static DWORD l_tickMsec = 10U; /* clock tick in msec (argument for Sleep()) */
 static bool  l_isRunning;      /* flag indicating when QF is running */

@ -66,6 +67,12 @@ void QF_init(void) {

    InitializeCriticalSection(&l_win32CritSect);

+    /* initialize and enter the startup critical section object to block
+    * any active objects started before calling QF_run()
+    */
+    InitializeCriticalSection(&l_startupCritSect);
+    EnterCriticalSection(&l_startupCritSect);
+
    /* clear the internal QF variables, so that the framework can (re)start
    * correctly even if the startup code is not called to clear the
    * uninitialized data (as is required by the C Standard).
@ -91,6 +98,11 @@ int_t QF_run(void) {

    QF_onStartup(); /* application-specific startup callback */

+    /* leave the startup critical section to unblock any active objects
+    * started before calling QF_run()
+    */
+    LeaveCriticalSection(&l_startupCritSect);
+
    l_isRunning = true; /* QF is running */

    /* set the ticker thread priority below normal to prevent
@ -105,6 +117,7 @@ int_t QF_run(void) {
    }
    QF_onCleanup();  /* cleanup callback */
    QS_EXIT();       /* cleanup the QSPY connection */
+    //DeleteCriticalSection(&l_startupCritSect);
    //DeleteCriticalSection(&l_win32CritSect);
    return (int_t)0; /* return success */
 }
@ -128,7 +141,7 @@ void QActive_start_(QActive * const me, uint_fast8_t prio,
                    void *stkSto, uint_fast16_t stkSize,
                    QEvt const *ie)
 {
-    int   win32Prio;
+    int win32Prio;

    Q_REQUIRE_ID(700, ((uint_fast8_t)0 < prio) /* priority must be in range */
                 && (prio <= (uint_fast8_t)QF_MAX_ACTIVE)
@ -175,6 +188,11 @@ void QActive_stop(QActive * const me) {
 static DWORD WINAPI ao_thread(LPVOID arg) { /* for CreateThread() */
    QActive *act = (QActive *)arg;

+    /* block this thread until the startup critical section is exited
+    * from QF_run() */
+    EnterCriticalSection(&l_startupCritSect);
+    LeaveCriticalSection(&l_startupCritSect);
+
    /* Active Object's event loop. QActive_stop() stops the loop */
    do {
        QEvt const *e = QActive_get_(act); /* wait for event */
--- a/src/qf/qep_hsm.c
+++ b/src/qf/qep_hsm.c
@ -1,6 +1,6 @@
 /**
 * @file
-* @brief QHsm implementation
+* @brief ::QHsm implementation
 * @ingroup qep
 * @cond
 ******************************************************************************
--- a/src/qf/qep_msm.c
+++ b/src/qf/qep_msm.c
@ -1,6 +1,6 @@
 /**
 * @file
-* @brief QMsm implementation
+* @brief ::QMsm implementation
 * @ingroup qep
 * @cond
 ******************************************************************************
--- a/src/qf/qf_act.c
+++ b/src/qf/qf_act.c
@ -1,6 +1,6 @@
 /**
 * @file
-* @brief QActive services and QF support code
+* @brief ::QActive services and ::QF support code
 * @ingroup qf
 * @cond
 ******************************************************************************
--- a/src/qf/qf_actq.c
+++ b/src/qf/qf_actq.c
@ -1,8 +1,9 @@
 /**
 * @file
-* @brief QActive native queue operations (based on QEQueue)
+* @brief ::QActive native queue operations (based on ::QEQueue)
 *
-* @note this source file is only included in the QF library when the native
+* @note
+* this source file is only included in the application build when the native
 * QF active object queue is used (instead of a message queue of an RTOS).
 *
 * @ingroup qf
--- a/src/qf/qf_dyn.c
+++ b/src/qf/qf_dyn.c
@ -4,8 +4,8 @@
 * @ingroup qf
 * @cond
 ******************************************************************************
-* Last updated for version 5.9.3
-* Last updated on  2017-06-19
+* Last updated for version 5.9.7
+* Last updated on  2017-08-25
 *
 *                    Q u a n t u m     L e a P s
 *                    ---------------------------
@ -270,14 +270,14 @@ void QF_gc(QEvt const * const e) {
 QEvt const *QF_newRef_(QEvt const * const e, QEvt const * const evtRef) {
    QF_CRIT_STAT_

-    /* the provided event reference must not be in use */
-    Q_REQUIRE_ID(500, evtRef == (QEvt const *)0);
+    /*! @pre the event must be dynamic and the provided event reference
+    * must not be already in use */
+    Q_REQUIRE_ID(500,
+        (e->poolId_ != (uint8_t)0)
+        && (evtRef == (QEvt const *)0));

    QF_CRIT_ENTRY_();
-    /* is the current event dynamic? */
-    if (e->poolId_ != (uint8_t)0) {
-        QF_EVT_REF_CTR_INC_(e); /* increments the ref counter */
-    }
+    QF_EVT_REF_CTR_INC_(e); /* increments the ref counter */
    QF_CRIT_EXIT_();

    return e;
--- a/src/qf/qf_mem.c
+++ b/src/qf/qf_mem.c
@ -1,7 +1,7 @@
 /**
 * @file
 * @ingroup qf
-* @brief Memory management services
+* @brief ::QMPool implementatin (Memory Pool)
 * @cond
 ******************************************************************************
 * Last updated for version 5.5.0
--- a/src/qf/qf_qeq.c
+++ b/src/qf/qf_qeq.c
@ -1,6 +1,6 @@
 /**
 * @file
-* @brief QEQueue implementation
+* @brief ::QEQueue implementation (QP native thread-safe queue)
 * @ingroup qf
 * @cond
 ******************************************************************************
--- a/src/qf/qf_time.c
+++ b/src/qf/qf_time.c
@ -1,6 +1,6 @@
 /**
 * @file
-* @brief QF time events and time management services
+* @brief ::QTimeEvt implementation and QF system clock tick QF_tickX_())
 * @ingroup qf
 * @cond
 ******************************************************************************