GitHub/qpc
1
0
Fork 0
mirror of https://github.com/QuantumLeaps/qpc.git synced 2025-01-28 07:03:10 +08:00
Code Issues Projects Releases Wiki Activity

7.1.3

Browse Source 
7.1.3

Replaced QF_EVT_REF_CTR_INC_() with QEvt_refCtr_inc_() in ports
- embOS
- ESP-IDF
- Qt

7.1.3

7.1.3

7.1.3

7.1.3

7.1.3

7.1.3

7.1.2

first commit after fixing history

Revert "7.1.2"

This reverts commit 90cf4e1471b5e9c0853af97af8ec0bc67c7e19c6.

7.1.2

first commit after fixing the history

7.0.1
This commit is contained in:
MMS 2022-04-30 18:29:48 -04:00
parent b844ddd797
commit e032055963
1317 changed files with 396865 additions and 378148 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
.gitignore vendored
View File

@ -3,6 +3,7 @@
*.d
*.lib
*.a
*.bin
*.elf
*.err
*.hex
@ -32,12 +33,14 @@
*.Debug
*.Release
*.bak
*.qlc
JLink*.*
.qpc
version-*
JLink*.*
3rd_party/
html/
latex/
cert-pack/
cert-latex/
test_priv/
dbg/
rel/

3
.gitmodules vendored Normal file
View File

@ -0,0 +1,3 @@
[submodule "3rd_party"]
path = 3rd_party
url = https://github.com/QuantumLeaps/3rd_party.git

3
.vscode/settings.json vendored
View File

@ -1,3 +0,0 @@
{
"cmake.configureOnOpen": false
}

1
3rd_party Submodule

@ -0,0 +1 @@
Subproject commit cc0333938b9618b5a25394ebd81c8f235f5ff192

26
LICENSES/LicenseRef-QL-dual.qlc Normal file
View File

@ -0,0 +1,26 @@
Any user of the QP/C real-time embedded framework
qpc
2023-12-31
Copyright (C) 2005 Quantum Leaps, LLC <state-machine.com>.
SPDX-License-Identifier: GPL-3.0-or-later OR LicenseRef-QL-commercial
This software is dual-licensed under the terms of the open source GNU
General Public License version 3 (or any later version), or alternatively,
under the terms of one of the closed source Quantum Leaps commercial
licenses.
The terms of the open source GNU General Public License version 3
can be found at: <www.gnu.org/licenses/gpl-3.0>
The terms of the closed source Quantum Leaps commercial licenses
can be found at: <www.state-machine.com/licensing>
Redistributions in source code must retain this top-level comment block.
Plagiarizing this software to sidestep the license obligations is illegal.
Contact information:
<www.state-machine.com/licensing>
<info@state-machine.com>
#F04C7A28E6F84BAFDD11A028A9B7CFE2F4DE1FD7

46
LICENSES/QP-Arduino_GPL_Exception.txt Normal file
View File

@ -0,0 +1,46 @@
QP/C++ and QP-nano FRAMEWORK EXCEPTION FOR ARDUINO
Version 3.0, December 22, 2021
Copyright (c) 2005-2021 Quantum Leaps, LLC. <https://www.state-machine.com/>
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
This QP/C++ and QP-nano Framework Exception for Arduino ("Exception")
is an additional permission under section 7 of the GNU General Public
License, version 3 ("GPLv3"). It applies to the QP/C++ and QP-nano
source code (the "QP Frameworks") that is distributed as part of the
QP-Arduino Support Package.
When you use QP Frameworks inside your program, the QP Frameworks' code
is combined with your code of the program. The purpose of this Exception
is to allow non-GPL (including proprietary) programs to use, in this way,
the QP Frameworks' code covered by this Exception.
0. Definitions.
"QP Frameworks" are lightweight real-time embedded frameworks (RTEFs)
as well as all supporting ports and examples, as distributed from:
<https://www.state-machine.com> and
<https://github.com/QuantumLeaps>
"Arduino-Certified Board" means any board with an Arduino-supported
CPU that bears an official Arduino logo and/or is officially certified
under the Arduino Certified Program
(see <https://www.arduino.cc/en/hardware>).
"Target Code" refers to output from any compiler and linker in
executable form suitable for execution by an embedded microcontroller.
1. Grant of Additional Permission
As a special Exception, the copyright holder of QP Frameworks gives you
permission to propagate a work of Target Code formed by combining
the QP Frameworks with your own source code without the requirement
to expose your proprietary source code, provided that all Target Code
will execute on Arduino-Certified Board(s).
2. No Weakening of GPL
The availability of this Exception does not imply any general
presumption that third-party software linking to the QP Framework is
unaffected by the copyleft requirements of the GPLv3 license.

48
LICENSES/QP-RasPi_GPL_Exception.txt Normal file
View File

@ -0,0 +1,48 @@
QP/C and QP/C++ FRAMEWORKS EXCEPTION FOR RASPBERRY PI
Version 2.0, 2 August 2022
Copyright (c) 2005-2021 Quantum Leaps, LLC. <https://www.state-machine.com/>
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
This QP/C++ and QP-nano Framework Exception for Arduino ("Exception")
is an additional permission under section 7 of the GNU General Public
License, version 3 ("GPLv3"). It applies to the QP/C++ and QP-nano
source code (the "QP Frameworks") that is distributed as part of the
QP-Arduino Support Package.
When you use QP Frameworks inside your program, the QP Frameworks' code
is combined with your code of the program. The purpose of this Exception
is to allow non-GPL (including proprietary) programs to use, in this way,
the QP Frameworks' code covered by this Exception.
0. Definitions.
"QP Frameworks" are lightweight real-time embedded frameworks (RTEFs)
as well as all supporting ports and examples, as distributed from:
<https://www.state-machine.com> and
<https://github.com/QuantumLeaps>
"Raspberry Pi" is a low cost, credit-card sized computer that is
designed by the Raspberry Pi Foundation based in the UK and registered
as UK educational charity under the number 1129409. For the purpose of
this license, Raspberry Pi means only genuine Raspberry Pi computer
bearing the Raspberry Pi logo, as described at
<https://www.raspberrypi.com/trademark-rules>.
"Target Code" refers to output from any compiler and linker in
executable form suitable for execution by Raspberry Pi.
1. Grant of Additional Permission
As a special Exception, the copyright holder of QP Frameworks gives you
permission to propagate a work of Target Code formed by combining the QP
Frameworks with your own source code without the requirement to expose
your propriatory source code, provided that all Target Code will execute
on a genuine Raspberry Pi computer(s).
2. No Weakening of GPL
The availability of this Exception does not imply any general
presumption that third-party software linking to the QP Framework is
unaffected by the copyleft requirements of the GPLv3 license.

42
LICENSES/QP-mbed_GPL_Exception.txt Normal file
View File

@ -0,0 +1,42 @@
QP/C and QP/C++ FRAMEWORKS EXCEPTION FOR ARM mbed
Version 2.0, August 2022
Copyright (c) 2005-2014 Quantum Leaps, LLC. <https://www.state-machine.com/>
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
This QP/C++ and QP-nano Framework Exception for Arduino ("Exception")
is an additional permission under section 7 of the GNU General Public
License, version 3 ("GPLv3"). It applies to the QP/C++ and QP-nano
source code (the "QP Frameworks") that is distributed as part of the
QP-Arduino Support Package.
When you use QP Frameworks inside your program, the QP Frameworks' code
is combined with your code of the program. The purpose of this Exception
is to allow non-GPL (including proprietary) programs to use, in this way,
the QP Frameworks' code covered by this Exception.
0. Definitions.
"QP Frameworks" are lightweight real-time embedded frameworks (RTEFs)
as well as all supporting ports and examples, as distributed from:
<https://www.state-machine.com> and
<https://github.com/QuantumLeaps>
"mbed-Enabled Board" means any board with an ARM Cortex-M CPU that is
listed on the official "mbed platforms" website
<https://os.mbed.com/platforms>.
1. Grant of Additional Permission
As a special Exception, the copyright holder of QP Frameworks gives you
permission to propagate a work of Target Code formed by combining
the QP Frameworks with your own source code without the requirement
to expose your proprietary source code, provided that all Target Code will
execute on an "mbed-Enabled Board".
2. No Weakening of GPL
The availability of this Exception does not imply any general
presumption that third-party software linking to the QP Framework is
unaffected by the copyleft requirements of the GPLv3 license.

63
README.md
View File

@ -1,18 +1,19 @@
![QP Framework](doxygen/images/qp_banner.jpg)
> **NOTE:** If your company has a policy forbidding open source in your
products, all QP frameworks can be
[licensed commercially](https://www.state-machine.com/licensing),
in which case you don't use any open source license and you do not violate
your policy.
---------------------------------------------------------------------------
# What's New?
View QP/C Revision History at: https://www.state-machine.com/qpc/history.html
> **NOTE:** If you're interested in the latest QP/C version from GitHub,
it is recommened that you clone this repo like that:
```
git clone https://github.com/QuantumLeaps/qpc --recurse-submodules --depth 1
```
Alternatively, you can also download the latest
[QP/C Release](https://github.com/QuantumLeaps/qpc/releases).
---------------------------------------------------------------------------
# Getting Started with QP/C
The most recommended way of obtaining QP/C is by downloading the
[QP-bundle](https://www.state-machine.com/#Downloads), which includes QP/C
@ -20,15 +21,10 @@ as well as the QM modeling tool and the QTools collection. The main advantage of
obtaining QP/C bundled together like that is that you get all components,
tools and examples ready to go.
><span style="background:yellow;"><strong>NOTE:</strong></span>
If you're interested in the latest QP/C version from Git,
it is highly recommened that you download the latest
[QP/C Release](https://github.com/QuantumLeaps/qpc/releases)
as opposed to cloning the repo directy. This is because the `3rd_party`
directory needed to build the examples is no longer provided in the
`qpc` repository (and is provided in the QP/C release).
### Getting Started Resources
- ["QP/C Tutorial"][Tutorial]
describes a series of progressively advanced QP/C example applications.
- [Video: "Getting Started with QP Real-Time Embedded Frameworks"][Video]
provides instructions on how to download, install, and get started with QP.
@ -36,17 +32,6 @@ provides instructions on how to download, install, and get started with QP.
contains also a tutorial, in which you build a simple "Blinky" application.
---------------------------------------------------------------------------
# Documentation
The online HTML documention for the **latest** version of QP/C is located
at: https://www.state-machine.com/qpc
The offline HTML documentation for **this** particular version of QP/C
is located in the sub-folder [html](html). To view the offline documentation,
open the file [html/index.html](html/index.html) in your web browser.
---------------------------------------------------------------------------
# About QP/C
QP/C (Quantum Platform in C) is a lightweight, open source
[Real-Time Embedded Framework (RTEF)][RTEF] for building modern embedded
@ -104,9 +89,9 @@ and many times more open source users worldwide, the QP
most popular such offering on the market. They power countless electronic
products ranging from implantable medical devices to complex weapon systems.
---------------------------------------------------------------------------
# QP/C Licensing
QP/C is licensed under the increasingly popular [dual licensing model][Lic],
QP/C is licensed under the sustainable [dual licensing model][Lic],
in which both the open source software distribution mechanism and
traditional closed source software distribution models are combined.
@ -115,11 +100,15 @@ product, all QP frameworks can be [licensed commercially][Lic], in which case
you don't use any open source license and you do not violate your policy.
---------------------------------------------------------------------------
# QP/C Documentation
The **QP/C Manual** is located online at: https://www.state-machine.com/qpc
The online HTML documention for the **latest** version of QP/C is located
at: https://www.state-machine.com/qpc
The offline HTML documentation for **this** particular version of QP/C
is located in the sub-folder [html](html). To view the offline documentation,
open the file [html/index.html](html/index.html) in your web browser.
---------------------------------------------------------------------------
# How to Get Help?
- [Free Support Forum](https://sourceforge.net/p/qpc/discussion/668726)
- [Bug Reports](https://sourceforge.net/p/qpc/bugs/)
@ -128,6 +117,13 @@ The **QP/C Manual** is located online at: https://www.state-machine.com/qpc
- [Quantum Leaps licensing](https://www.state-machine.com/licensing)
- [info@state-machine.com](mailto:info@state-machine.com)
# How to Help this Project?
If you like this project, please give it a star (in the upper-right corner of your browser window):
![GitHub star](doxygen/images/github-star.jpg)
[RTEF]: <https://www.state-machine.com/rtef>
[QP]: <https://www.state-machine.com/products/qp>
[QP/C]: <https://www.state-machine.com/qpc>
@ -138,4 +134,5 @@ The **QP/C Manual** is located online at: https://www.state-machine.com/qpc
[Lic]: <https://www.state-machine.com/licensing>
[Cust]: <https://www.state-machine.com/customers>
[AN]: <https://www.state-machine.com/doc/AN_Getting_Started_with_QP.pdf>
[Tutorial]: <https://www.state-machine.com/qpc/gs_tut.html>
[Video]: <https://youtu.be/O7ER6_VqIH0>

96
doxygen/Doxyfile
View File

@ -1,17 +1,18 @@
# Doxyfile 1.9.3
# Doxyfile 1.9.5
@INCLUDE = ../../ql-doxygen/Doxyfile-QL
@INCLUDE = ../../ql-doxygen/ql-doxyfile
#---------------------------------------------------------------------------
# Project related configuration options
#---------------------------------------------------------------------------
DOXYFILE_ENCODING = UTF-8
PROJECT_NAME = QP/C
PROJECT_NUMBER = 7.0.0
PROJECT_NUMBER = 7.1.3
PROJECT_BRIEF = "Real-Time Embedded Framework"
PROJECT_LOGO = images/logo_ql.png
PROJECT_LOGO = ../../ql-doxygen/images/logo_ql.png
OUTPUT_DIRECTORY =
CREATE_SUBDIRS = NO
CREATE_SUBDIRS_LEVEL = 6
ALLOW_UNICODE_NAMES = NO
OUTPUT_LANGUAGE = English
BRIEF_MEMBER_DESC = YES
@ -41,7 +42,7 @@ PYTHON_DOCSTRING = YES
INHERIT_DOCS = YES
SEPARATE_MEMBER_PAGES = NO
TAB_SIZE = 4
OPTIMIZE_OUTPUT_FOR_C = YES
OPTIMIZE_OUTPUT_FOR_C = NO
OPTIMIZE_OUTPUT_JAVA = NO
OPTIMIZE_FOR_FORTRAN = NO
OPTIMIZE_OUTPUT_VHDL = NO
@ -116,17 +117,21 @@ WARN_IF_INCOMPLETE_DOC = YES
WARN_NO_PARAMDOC = NO
WARN_AS_ERROR = NO
WARN_FORMAT = "$file:$line: $text"
WARN_LINE_FORMAT = "at line $line of file $file"
WARN_LOGFILE =
#---------------------------------------------------------------------------
# Configuration options related to the input files
#---------------------------------------------------------------------------
INPUT = main.dox \
gs.dox \
../../cert-pack/cert-pack.dox \
../../cert-pack/srs.dox \
../../cert-pack/sas.dox \
../../cert-pack/sds.dox \
../../cert-pack/sds_sm-c.dox \
../../cert-pack/misra.dox \
api.dox \
../../cert-pack/metrics.dox \
history.dox \
exa.dox \
exa_native.dox \
exa_rtos.dox \
@ -138,27 +143,17 @@ INPUT = main.dox \
ports_arm-cm.dox \
ports_rtos.dox \
ports_os.dox \
metrics.dox \
history.dox \
modules.dox \
api.dox \
../../ql-doxygen/help.dox \
dir.dox \
macros.h \
../include/qpc.h \
../include/qep.h \
../include/qf.h \
../include/qequeue.h \
../include/qmpool.h \
../include/qpset.h \
../include/qv.h \
../include/qk.h \
../include/qxk.h \
../include/qxthread.h \
../include/qs.h \
config.h \
../include \
../src \
../../ql-doxygen/help.dox
../ports/lint-plus/std.lnt \
../ports/lint-plus/qpc.lnt \
../ports/lint-plus/options.lnt
INPUT_ENCODING = UTF-8
INPUT_FILE_ENCODING =
FILE_PATTERNS = *.dox \
*.h \
*.hpp \
@ -167,20 +162,19 @@ FILE_PATTERNS = *.dox \
*.s \
*.asm \
*.lnt
RECURSIVE = YES
EXCLUDE = ../include/qs_dummy.h
EXCLUDE = ../include/qs_dummy.h \
../include/quit.h
EXCLUDE_SYMLINKS = NO
EXCLUDE_PATTERNS =
EXCLUDE_SYMBOLS = QP_IMPL
EXAMPLE_PATH = snippets \
EXAMPLE_PATH = gen \
snippets \
../include \
../src \
../ports \
../ports/lint-plus \
../examples
EXAMPLE_PATTERNS = *
EXAMPLE_RECURSIVE = NO
IMAGE_PATH = images \
@ -191,12 +185,13 @@ FILTER_PATTERNS =
FILTER_SOURCE_FILES = NO
FILTER_SOURCE_PATTERNS =
USE_MDFILE_AS_MAINPAGE =
FORTRAN_COMMENT_AFTER = 72
#---------------------------------------------------------------------------
# Configuration options related to source browsing
#---------------------------------------------------------------------------
SOURCE_BROWSER = YES
INLINE_SOURCES = NO
STRIP_CODE_COMMENTS = YES
STRIP_CODE_COMMENTS = NO
REFERENCED_BY_RELATION = NO
REFERENCES_RELATION = NO
REFERENCES_LINK_SOURCE = YES
@ -218,18 +213,23 @@ IGNORE_PREFIX =
GENERATE_HTML = YES
HTML_OUTPUT = ../html
HTML_FILE_EXTENSION = .html
HTML_HEADER = ../../ql-doxygen/header-awesome.html
HTML_FOOTER = ../../ql-doxygen/footer-awesome.html
HTML_HEADER = ../../ql-doxygen/ql-header-awesome.html
HTML_FOOTER = ../../ql-doxygen/ql-footer-awesome.html
HTML_STYLESHEET =
HTML_EXTRA_STYLESHEET = ../../ql-doxygen/doxygen-awesome.css \
../../ql-doxygen/doxygen-awesome-sidebar-only.css \
../../ql-doxygen/doxygen-awesome-sidebar-only-darkmode-toggle.css \
../../ql-doxygen/ql-awesome.css
HTML_EXTRA_FILES = ../../ql-doxygen/doxygen-awesome-darkmode-toggle.js \
../../ql-doxygen/preview.js
../../ql-doxygen/doxygen-awesome-fragment-copy-button.js \
../../ql-doxygen/doxygen-awesome-paragraph-link.js \
../../ql-doxygen/ql-preview.js
HTML_COLORSTYLE = AUTO_LIGHT
HTML_COLORSTYLE_HUE = 209
HTML_COLORSTYLE_SAT = 255
HTML_COLORSTYLE_GAMMA = 113
HTML_TIMESTAMP = NO
HTML_DYNAMIC_MENUS = NO
HTML_DYNAMIC_MENUS = YES
HTML_DYNAMIC_SECTIONS = NO
HTML_INDEX_NUM_ENTRIES = 100
GENERATE_DOCSET = NO
@ -255,16 +255,15 @@ QHP_SECT_FILTER_ATTRS =
QHG_LOCATION =
GENERATE_ECLIPSEHELP = NO
ECLIPSE_DOC_ID = com.state-machine.qp
DISABLE_INDEX = YES
DISABLE_INDEX = NO
GENERATE_TREEVIEW = YES
FULL_SIDEBAR = NO
ENUM_VALUES_PER_LINE = 4
TREEVIEW_WIDTH = 300
TREEVIEW_WIDTH = 335
EXT_LINKS_IN_WINDOW = NO
OBFUSCATE_EMAILS = NO
HTML_FORMULA_FORMAT = png
FORMULA_FONTSIZE = 10
FORMULA_TRANSPARENT = YES
FORMULA_MACROFILE =
USE_MATHJAX = NO
MATHJAX_VERSION = MathJax_2
@ -291,17 +290,20 @@ INCLUDE_FILE_PATTERNS =
PREDEFINED = Q_SPY \
QP_IMPL \
Q_UTEST \
QF_MAX_ACTIVE=32 \
QF_MAX_TICK_RATE=2 \
QF_MAX_EPOOL=3 \
QF_EVENT_SIZ_SIZE=2 \
QF_EQUEUE_CTR_SIZE=2 \
QF_MPOOL_SIZ_SIZE=2 \
QF_MPOOL_CTR_SIZE=2 \
QF_TIMEEVT_CTR_SIZE=4 \
QF_ACTIVE_STOP=0 \
QS_TIME_SIZE=4 \
QF_EQUEUE_TYPE=QEQueue \
QF_OS_OBJECT_TYPE=void* \
QF_THREAD_TYPE=void* \
QK_ON_CONTEXT_SW \
QXK_ON_CONTEXT_SW \
QF_MAX_ACTIVE \
QF_MAX_TICK_RATE \
QF_MAX_EPOOL \
QF_EVENT_SIZ_SIZE \
QF_EQUEUE_CTR_SIZE \
QF_MPOOL_SIZ_SIZE \
QF_MPOOL_CTR_SIZE \
QF_TIMEEVT_CTR_SIZE \
QF_ACTIVE_STOP \
QS_TIME_SIZE
QXK_ON_CONTEXT_SW
EXPAND_AS_DEFINED =
SKIP_FUNCTION_MACROS = YES

10
doxygen/Doxyfile-CERT
View File

@ -1,10 +0,0 @@
# Doxyfile 1.9.3
@INCLUDE = Doxyfile
#---------------------------------------------------------------------------
# Configuration options related to the input files
#---------------------------------------------------------------------------
ENABLED_SECTIONS += CERT

11
doxygen/Doxyfile-CHM
View File

@ -1,15 +1,12 @@
# Doxyfile 1.9.3
# Doxyfile 1.9.5
@INCLUDE = Doxyfile
#---------------------------------------------------------------------------
# Configuration options related to the HTML output
#---------------------------------------------------------------------------
PROJECT_LOGO = images/logo_ql-comp.png
HTML_OUTPUT = tmp
HTML_HEADER = ../../ql-doxygen/header.html
HTML_FOOTER = ../../ql-doxygen/footer.html
HTML_HEADER = ../../ql-doxygen/ql-header.html
HTML_FOOTER = ../../ql-doxygen/ql-footer.html
HTML_EXTRA_STYLESHEET = ../../ql-doxygen/ql.css
HTML_EXTRA_FILES = ../../ql-doxygen/preview.js
HTML_EXTRA_FILES = ../../ql-doxygen/ql-preview.js
GENERATE_HTMLHELP = YES

43
doxygen/Doxyfile-LATEX Normal file
View File

@ -0,0 +1,43 @@
# Doxyfile 1.9.5
@INCLUDE = Doxyfile
#---------------------------------------------------------------------------
# Configuration options related to the input files
#---------------------------------------------------------------------------
INPUT = main.dox \
gs.dox \
../../cert-pack/cert-pack.dox \
../../cert-pack/srs.dox \
../../cert-pack/sas.dox \
../../cert-pack/sds.dox \
../../cert-pack/sds_sm-c.dox \
../../cert-pack/misra.dox \
../../cert-pack/metrics.dox \
history.dox \
exa.dox \
exa_native.dox \
exa_rtos.dox \
exa_os.dox \
exa_qutest.dox \
exa_mware.dox \
ports.dox \
ports_native.dox \
ports_arm-cm.dox \
ports_rtos.dox \
ports_os.dox \
api.dox \
dir.dox \
config.h \
../include \
../src \
../ports/lint-plus/std.lnt \
../ports/lint-plus/qpc.lnt \
../ports/lint-plus/options.lnt
GENERATE_LATEX = YES
ENABLED_SECTIONS += LATEX
# no source code in latex
SOURCE_BROWSER = NO
VERBATIM_HEADERS = NO

40
doxygen/api.dox
View File

@ -1,6 +1,7 @@
/*! @page api API Reference
@tableofcontents
@ifnot LATEX
@nav_next{deprecated}
@endif
@section api_qep QEP (Hierarchical State Machines)
QEP is a universal, UML-compliant event processor that enables developers to code UML state machines in highly readable ANSI-C, in which every state machine element is mapped to code precisely, unambiguously, and exactly once (traceability). QEP fully supports hierarchical state nesting, which is the fundamental mechanism for reusing behavior across many states instead of repeating the same actions and transitions over and over again.
@ -18,7 +19,7 @@ QEP is a universal, UML-compliant event processor that enables developers to cod
- QMsm_ctor()
- QMsm_isInState()
- QMsm_stateObj()
- Q_STATE_CAST()
@section api_qf QF (Active Object Framework)
@ -49,7 +50,7 @@ QF is a portable, event-driven, real-time framework for execution of active obje
- QActive_unsubscribeAll()
@subsection api_qf_evt Dynamic Events
@subsection api_qf_evt Event Management
- ::QEvt class
- QF_poolInit()
- Q_NEW()
@ -57,6 +58,7 @@ QF is a portable, event-driven, real-time framework for execution of active obje
- Q_NEW_REF()
- Q_DELETE_REF()
- QF_gc()
- Q_EVT_CAST()
@subsection api_qf_time Time Events
@ -89,8 +91,7 @@ QF is a portable, event-driven, real-time framework for execution of active obje
- QMPool_put()
@section api_qs QS ("Quantum Spy" Software Tracing)
@section api_qs QS (Software Tracing)
QS is a software tracing system that enables developers to monitor live event-driven QP applications with minimal target system resources and without stopping or significantly slowing down the code. QS is an ideal tool for testing, troubleshooting, and optimizing QP applications. QS can even be used to support acceptance testing in product manufacturing.
@ -121,6 +122,7 @@ QS is a software tracing system that enables developers to monitor live event-dr
@subsection api_qs_dict QS Dictionaries
- QS_SIG_DICTIONARY()
- QS_OBJ_DICTIONARY()
- QS_OBJ_ARR_DICTIONARY()
- QS_FUN_DICTIONARY()
- QS_USR_DICTIONARY()
@ -156,8 +158,8 @@ Given the simplicity, portability, and low-resource consumption, the QV schedule
- QV_CPU_SLEEP()
@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.
@section api_qk QK (Preemptive RTC Kernel)
QK is a tiny **preemptive**, run-to-completion (RTC) 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.
@subsection api_qk_ctrl Kernel Initialization and Control
@ -173,9 +175,8 @@ QK is a tiny **preemptive**, priority-based, non-blocking kernel designed specif
- QK_ISR_EXIT()
@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.
@section api_qxk QXK (Dual-Mode Kernel)
QXK is a small, preemptive, priority-based, dual-mode (run-to-completion/**blocking**) kernel that executes active objects like the @ref srs_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.
@subsection api_qxk_ctrl Kernel Initialization and Control
@ -200,7 +201,8 @@ QXK is a small, preemptive, priority-based, dual-mode **blocking** kernel that e
- QXThread_delay()
- QXThread_delayCancel()
- QXThread_queueGet()
- QXK_current()
- QXK_TLS()
@subsection api_qxk_sema Semaphores
- ::QXSemaphore class (Semaphore Control Block)
@ -224,23 +226,19 @@ QXK is a small, preemptive, priority-based, dual-mode **blocking** kernel that e
- QXThread_queueGet() - waiting (blocking) on message queue
@subsection api_qxk_mem Memory Pools
- ::QMPool class
- QMPool_init()
- QMPool_get()
- QMPool_put()
@subsection api_qxk_tls Thread-Local Storage
- QXK_current()
- QXK_TLS()
@next{deprecated}
@ifnot LATEX
@nav_next{deprecated}
@endif
*/
/*##########################################################################*/
##############################################################################
/*! @page deprecated Deprecated APIs
__The following QP/C APIs are now deprecated:__
**The following QP/C APIs are now deprecated:**
*/

411
doxygen/config.h Normal file
View File

@ -0,0 +1,411 @@
/**
* @file
* @brief Various macros for configuring and porting QP/C
*/
/*! The maximum number of active objects in the application.
*
* @description
* This macro *must* be defined in the QF port and should be in range
* of 1U..64U, inclusive. The value of this macro determines the maximum
* priority level of an active object in the system. Not all priority
* levels must be used, but the maximum priority cannot exceed
* #QF_MAX_ACTIVE.
*
* @note Once you choose a certain value of #QF_MAX_ACTIVE, you must
* consistently use the same value in building all the QP component libraries
* and your own application code. The consistency is guaranteed if you define
* this macro only once in the qf_port.h header file and henceforth include
* this header file in all builds.
*/
#define QF_MAX_ACTIVE 32U
/*! The maximum number of clock tick rates in the application.
*
* @description
* This macro can be defined in the QF ports and should be in range
* of 1U..15U, inclusive. The value of this macro determines the maximum
* number of clock tick rates for time events (::QTimeEvt).
*
* If the macro is not defined, the default value is 1U.
*
* @note Once you choose a certain value of #QF_MAX_TICK_RATE, you must
* consistently use the same value in building all the QP component libraries
* and your own application code. The consistency is guaranteed if you define
* this macro only once in the qf_port.h header file and henceforth include
* this header file in all builds.
*/
#define QF_MAX_TICK_RATE 1U
/*! The maximum number of event pools in the application.
*
* @description
* This macro can be defined in the QF ports and should be in range
* of 1U..255U, inclusive. The value of this macro determines the maximum
* event pools in the system. Not all event pools must be actually used,
* but the maximum number of pools cannot exceed #QF_MAX_EPOOL.
*
* If the macro is not defined, the default value is 3U. Defining the value
* below the maximum saves some memory, mostly for the subscriber-lists.
* @sa ::QSubscrList.
*
* @note Once you choose a certain value of #QF_MAX_EPOOL, you must
* consistently use the same value in building all the QP component libraries
* and your own application code. The consistency is guaranteed if you define
* this macro only once in the qf_port.h header file and henceforth include
* this header file in all builds.
*/
#define QF_MAX_EPOOL 3U
/*! The size (in bytes) of the event-size representation in the QF.
* Valid values: 1U, 2U, or 4U; default 2U
*
* @description
* This macro can be defined in the QF ports to configure the size
* of the event-size.
*
* @note Once you choose a certain value of #QF_EVENT_SIZ_SIZE, you must
* consistently use the same value in building all the QP component libraries
* and your own application code. The consistency is guaranteed if you define
* this macro only once in the qf_port.h header file and henceforth include
* this header file in all builds.
*/
#define QF_EVENT_SIZ_SIZE 2U
/*! The size (in bytes) of the ring-buffer counters used in the native QF
* event queue implementation. Valid values: 1U, 2U, or 4U; default 1U
*
* @description
* This macro can be defined in the QF ports to configure the ::QEQueueCtr
* type. If the macro is not defined, the default of 1 byte will be chosen in
* qequeue.h. The valid #QF_EQUEUE_CTR_SIZE values of 1U, 2U, or 4U, correspond
* to ::QEQueueCtr of uint8_t, uint16_t, and uint32_t, respectively. The
* ::QEQueueCtr data type determines the dynamic range of numerical values of
* ring-buffer counters inside event queues, or, in other words, the maximum
* number of events that the native QF event queue can manage.
* @sa ::QEQueue
*
* @note Once you choose a certain value of #QF_EQUEUE_CTR_SIZE, you must
* consistently use the same value in building all the QP component libraries
* and your own application code. The consistency is guaranteed if you define
* this macro only once in the qf_port.h header file and henceforth include
* this header file in all builds.
*/
#define QF_EQUEUE_CTR_SIZE 1U
/*! The size (in bytes) of the block-size representation in the native QF
* event pool. Valid values: 1U, 2U, or 4U; default #QF_EVENT_SIZ_SIZE.
*
* @description
* This macro can be defined in the QF ports to configure the ::QMPoolSize
* type. If the macro is not defined, the default of #QF_EVENT_SIZ_SIZE
* will be chosen in qmpool.h, because the memory pool is primarily used for
* implementing event pools.
*
* The valid #QF_MPOOL_SIZ_SIZE values of 1U, 2U, or 4U, correspond to
* ::QMPoolSize of uint8_t, uint16_t, and uint32_t, respectively. The
* ::QMPoolSize data type determines the dynamic range of block-sizes that
* the native ::QMPool can handle.
* @sa #QF_EVENT_SIZ_SIZE, ::QMPool
*
* @note Once you choose a certain value of #QF_MPOOL_SIZ_SIZE, you must
* consistently use the same value in building all the QP component libraries
* and your own application code. The consistency is guaranteed if you define
* this macro only once in the qf_port.h header file and henceforth include
* this header file in all builds.
*/
#define QF_MPOOL_SIZ_SIZE 2U
/*! The size (in bytes) of the block-counter representation in the
* native QF event pool. Valid values: 1U, 2U, or 4U; default 2U.
*
* @description
* This macro can be defined in the QF ports to configure the ::QMPoolCtr
* type. If the macro is not defined, the default of 2 bytes will be chosen
* in qmpool.h. The valid #QF_MPOOL_CTR_SIZE values of 1U, 2U, or 4U,
* correspond to ::QMPoolSize of uint8_t, uint16_t, and uint32_t, respectively.
* The ::QMPoolCtr data type determines the dynamic range of block-counters
* that the native ::QMPool can handle, or, in other words, the maximum number
* of blocks that the native QF event pool can manage.
* @sa ::QMPool
*
* @note Once you choose a certain value of #QF_MPOOL_CTR_SIZE, you must
* consistently use the same value in building all the QP component libraries
* and your own application code. The consistency is guaranteed if you define
* this macro only once in the qf_port.h header file and henceforth include
* this header file in all builds.
*/
#define QF_MPOOL_CTR_SIZE 2U
/*! The size (in bytes) of the time event-counter representation
* in the ::QTimeEvt struct. Valid values: 1U, 2U, or 4U; default 2U.
*
* @description
* This macro can be defined in the QF ports to configure the internal tick
* counters of Time Events. If the macro is not defined, the default of 4
* bytes will be chosen in qf.h. The valid #QF_TIMEEVT_CTR_SIZE values of 1,
* 2, or 4, correspond to tick counters of uint8_t, uint16_t, and uint32_t,
* respectively. The tick counter representation determines the dynamic range
* of time delays that a Time Event can handle.
* @sa ::QTimeEvt
*
* @note Once you choose a certain value of #QF_TIMEEVT_CTR_SIZE, you must
* consistently use the same value in building all the QP component libraries
* and your own application code. The consistency is guaranteed if you define
* this macro only once in the qf_port.h header file and henceforth include
* this header file in all builds.
*/
#define QF_TIMEEVT_CTR_SIZE 4U
/*! Define the interrupt disabling policy.
*
* @description
* This macro encapsulates platform-specific way of disabling interrupts
* from "C" for a given CPU and compiler.
*
* @note
* the #QF_INT_DISABLE macro should always be used in pair with the
* macro #QF_INT_ENABLE.
*/
#define QF_INT_DISABLE() intDisable()
/*! Define the interrupt enabling policy.
*
* @description
* This macro encapsulates platform-specific way of enabling interrupts
* from "C" for a given CPU and compiler.
*
* @note the #QF_INT_DISABLE macro should always be used in pair with the
* macro #QF_INT_ENABLE.
*/
#define QF_INT_ENABLE() intEnable()
void intDisable(void);
void intEnable(void);
/*! Define the type of the critical section status.
*
* @description
* Defining this macro configures the "saving and restoring critical section
* status" policy. Coversely, if this macro is not defined, the simple
* "unconditional critical section exit" is used.
*/
#define QF_CRIT_STAT_TYPE crit_stat_t
/*! Define the critical section entry policy.
*
* @description
* This macro enters a critical section (often by means of disabling
* interrupts). When the "saving and restoring critical section status"
* policy is used, the macro sets the @a status_ argument to the critical
* section status just before the entry. When the policy of "unconditional
* critical section exit" is used, the macro does not use the @a status_
* argument.
*
* @note the #QF_CRIT_ENTRY macro should always be used in pair with the
* macro #QF_CRIT_EXIT.
*/
#define QF_CRIT_ENTRY(stat_) ((stat_) = critEntry())
/*! Define the critical section exit policy.
/*
* @description
* This macro enters a critical section (often by means of disabling
* interrupts). When the "saving and restoring critical section status"
* policy is used, the macro restores the critical section status from the
* @a status_ argument. When the policy of "unconditional critical section
* exit" is used, the macro does not use the @a status argument and
* exits the critical section unconditionally (often by means of enabling
* interrupts).
*
* @note the #QF_CRIT_ENTRY macro should always be used in pair with the
* macro #QF_CRIT_EXIT.
*/
#define QF_CRIT_EXIT(stat_) critExit(stat_)
typedef unsigned int crit_stat_t;
crit_stat_t critEntry(void);
void critExit(crit_stat_t stat);
/*! Enable the QActive_stop() API in the QF port.
*
* @description
* Defining this macro enables the QActive_stop() API in a given port.
* This feature should be used with caution, as stopping and re-starting
* active objects **cleanly** can be tricky.
*/
#define QF_ACTIVE_STOP
/*! The preprocessor switch to disable checking assertions
*
* @description
* When defined, Q_NASSERT disables the following macros #Q_ASSERT,
* #Q_REQUIRE, #Q_ENSURE, #Q_INVARIANT, #Q_ERROR as well as
* #Q_ASSERT_ID, #Q_REQUIRE_ID, #Q_ENSURE_ID, #Q_INVARIANT_ID, and
* #Q_ERROR_ID do _not_ evaluate the test condition passed as the
* argument to these macros.
*
* @note The notable exceptions are the macros #Q_ALLEGE and
* #Q_ALLEGE_ID, that still evaluate the test condition, but do not
* report assertion failures when the switch #Q_NASSERT is defined.
*/
#define Q_NASSERT
/*! The preprocessor switch to activate the QS software tracing
* instrumentation in the code
*
* @description
* When defined, Q_SPY activates the QS software tracing instrumentation.
* When Q_SPY is not defined, the QS instrumentation in the code does
* not generate any code.
*/
#define Q_SPY
/*! The preprocessor switch to activate the QUTest unit testing
* instrumentation in the code
*
* @note
* This macro requires that #Q_SPY be defined as well.
*/
#define Q_UTEST
/*! The preprocessor switch to enable constructor in the ::QEvt class
* instrumentation in the code
*
* @tr{RQP005}
*/
#define Q_EVT_CTOR
/*! This macro defines the type of the thread handle used for AOs */
#define QF_THREAD_TYPE void*
/*! This macro defines the type of the event-queue used for AOs */
#define QF_EQUEUE_TYPE QEQueue
/*! This macro defines the type of the OS-Object used for blocking
* the native ::QEQueue when the queue is empty
*
* @description
* This macro is used when ::QEQueue is used as the event-queue for AOs
* but also the AO queue must *block* when the queue is empty.
* In that case, #QF_OS_OBJECT_TYPE specifies the blocking mechanism.
* For example, in the POSIX port, the blocking mechanism is a condition
* variable.
*/
#define QF_OS_OBJECT_TYPE pthread_cond_t
/*! Platform-dependent macro defining how QF should block the
* calling task when the QF native queue is empty
*
* @note
* This is just an example of QACTIVE_EQUEUE_WAIT_() for the QK-port
* of QF. QK never activates a task that has no events to process, so in
* this case the macro asserts that the queue is not empty. In other QF
* ports you need to define the macro appropriately for the underlying
* kernel/OS you're using.
*/
#define QACTIVE_EQUEUE_WAIT_(me_) \
(Q_ASSERT((me_)->eQueue.frontEvt != (QEvt *)0))
#if (QF_MAX_ACTIVE <= 8U)
#define QACTIVE_EQUEUE_SIGNAL_(me_) do { \
QPSet8_insert(&QF_readySet_, (me_)->prio); \
if (QF_intNest_ == 0U) { \
uint_fast8_t p = QK_schedPrio_(); \
if (p != 0U) { \
QK_sched_(p); \
} \
} \
} while (0)
#else
/*! Platform-dependent macro defining how QF should signal the
* active object task that an event has just arrived.
*
* @description
* The macro is necessary only when the native QF event queue is used.
* The signaling of task involves unblocking the task if it is blocked.
*
* @note QACTIVE_EQUEUE_SIGNAL_() is called from a critical section.
* It might leave the critical section internally, but must restore
* the critical section before exiting to the caller.
*
* @note This is just an example of QACTIVE_EQUEUE_SIGNAL_() for the
* QK-port of QF. In other QF ports you need to define the macro
* appropriately for the underlying kernel/OS you're using.
*/
#define QACTIVE_EQUEUE_SIGNAL_(me_) do { \
QPSet64_insert(&QF_readySet_, (me_)->prio); \
if (QF_intNest_ == 0U) { \
uint_fast8_t p = QK_schedPrio_(); \
if (p != 0U) { \
QK_sched_(p); \
} \
} \
} while (0)
#endif
/*! This macro defines the type of the event pool used in the QK kernel.
*
* @note This is a specific implementation for the QK-port of QF.
* In other QF ports you need to define the macro appropriately for
* the underlying kernel/OS you're using.
*/
#define QF_EPOOL_TYPE_ QMPool
/*! This macro enables calling the QK context-switch callback
* QK_onContextSw()
*/
#define QK_ON_CONTEXT_SW
/*! This macro enables calling the QXK context-switch callback
* QXK_onContextSw()
*/
#define QXK_ON_CONTEXT_SW
/*! Platform-dependent macro defining the event pool initialization
*
* @note
* This is an example implementation based on the native ::QMPool class.
* In other QF ports, the port might be using a memory pool from the
* underlying kernel/OS.
*/
#define QF_EPOOL_INIT_(p_, poolSto_, poolSize_, evtSize_) \
(QMPool_init(&(p_), (poolSto_), (poolSize_), (QMPoolSize)(evtSize_)))
/*! Platform-dependent macro defining how QF should obtain the
* event pool block-size
*
* @note
* This is a specific implementation for the built-in kernels.
* In other QF ports you need to define the macro appropriately for
* the underlying kernel/OS you're using.
*/
#define QF_EPOOL_EVENT_SIZE_(p_) ((uint32_t)(p_).blockSize)
/*! Platform-dependent macro defining how QF should obtain an event
* @a e_ from the event pool @a p_ with the free margin @a m_.
*
* @note
* This is an example implementation based on the native ::QMPool class.
* In other QF ports, the port might be using a memory pool from the
* underlying kernel/OS.
*/
#define QF_EPOOL_GET_(p_, e_, m_, qs_id_) \
((e_) = (QEvt *)QMPool_get(&(p_), (m_), (qs_id_)))
/*! Platform-dependent macro defining how QF should return an event
* @a e_ to the event pool @a p_
*
* @note
* This is an example implementation based on the native ::QMPool class.
* In other QF ports, the port might be using a memory pool from the
* underlying kernel/OS.
*/
#define QF_EPOOL_PUT_(p_, e_, qs_id_) \
(QMPool_put(&(p_), (e_), (qs_id_)))
/*! Macro defined only for the internal QP implementation. It should
* be not defined for the application-level code
*/
#define QP_IMPL

50
doxygen/dir.dox
View File

@ -1,15 +1,13 @@
/*##########################################################################*/
/*! @dir ../include
Platform-independent QP&trade;/C API
/*! @dir include
@brief Platform-independent QP&trade;/C API
@attention
The QP&trade;/C <span class="img folder">include</span> directory needs to be added to the compiler's include path in the applications using QP&trade;/C.
*/
/*##########################################################################*/
/*! @dir ../src
Platform-independent QP&trade;/C source code
/*! @dir src
@brief Platform-independent QP&trade;/C source code
Files from this directory need to be added to the project, to build the QP&trade;/C framework from source code.
@ -17,44 +15,44 @@ Files from this directory need to be added to the project, to build the QP&trade
The QP&trade;/C <span class="img folder">src</span> directory needs to be added to the compiler's include path in the applications that build QP&trade;/C framework from sources (as opposed to using QP as a pre-built library).
*/
/*##########################################################################*/
/*! @dir ../src/qf
Platform-independent implementation of the @ref qep and @ref qf components.
/*! @dir src/qf
@brief Platform-independent implementation of the @ref qep and @ref qf components.
@note
Typically, files in this directory need to be added to the application build, but some QP ports might not need all the files in this directory. For example, a QP port to a 3rd-party RTOS kernel might be using a message queue of the RTOS instead of the native QP event queue, in which case the file qf_actq.c would not be needed and should be excluded from the build.
*/
/*##########################################################################*/
/*! @dir ../src/qv
Platform-independent implementation of the @ref qv built-in kernel.
/*! @dir src/qv
@brief Platform-independent implementation of the @ref srs_qv built-in kernel.
@attention
Files in this directory need to be included in the QP application build only if the application uses the @ref qv kernel.
Files in this directory need to be included in the QP application build only if the application uses the @ref srs_qv kernel.
*/
/*##########################################################################*/
/*! @dir ../src/qk
Platform-independent implementation of the @ref qk built-in kernel.
/*! @dir src/qk
@brief Platform-independent implementation of the @ref srs_qk built-in kernel.
@attention
Files in this directory need to be included in the QP application build only if the application uses the @ref qk kernel.
Files in this directory need to be included in the QP application build only if the application uses the @ref srs_qk kernel.
*/
/*##########################################################################*/
/*! @dir ../src/qxk
Platform-independent implementation of the @ref qxk built-in kernel.
/*! @dir src/qxk
@brief Platform-independent implementation of the @ref srs_qxk built-in kernel.
@attention
Files in this directory need to be included in the QP application build only if the application uses the @ref qxk kernel.
Files in this directory need to be included in the QP application build only if the application uses the @ref srs_qxk kernel.
*/
/*##########################################################################*/
/*! @dir ../src/qs
Platform-independent implementation of the @ref qs component (software tracing).
/*! @dir src/qs
@brief Platform-independent implementation of the @ref qs component (software tracing).
*/
/*##########################################################################*/
/*! @dir ../3rd_party
/*! @dir test
@brief System-level tests of the QP/C framework itself.
3rd-Party code used in the QP&trade;/C @ref ports "ports" and @ref exa "examples"
@note
The `qpc/test/` directory is planned to contain a growing number of system-level tests, which are based on QUTest, but *without* the QP-stub. The tests take advantage of the new QUTest configuration, where the QP-stub is NOT included (because the actual QP framework is linked). This configuration is activated by defining macro `Q_UTEST=0`.
@attention
Many tests provided in the `qpc/test/` directory run only on embedded targets and cannot run on the host machine.
*/

348
doxygen/exa.dox
View File

@ -1,7 +1,5 @@
/*! @page exa Examples
@tableofcontents
@section exa_gen General Comments
The QP/C distribution contains many @subpage exa_ref "example projects" to demonstrate various QP/C features. Each example project is described on its own dedicated page that you can find using several criteria (see @ref exa_ref). The example projects have the following main goals:
@ -15,202 +13,77 @@ The QP/C distribution contains many @subpage exa_ref "example projects" to demon
It is highly recommended that you create your own projects by **copying and modifying** existing example projects rather than starting your QP/C projects from scratch.
@subsection exa_code Example Code Structure
QP/C examples are located in sub-directories of the <span class="img folder">examples</span> <a href="files.html">top-level folder</a>, with the hierarchical organization outlined below:
<ul class="tag">
<li><span class="img folder">examples/</span>
</li>
<ul class="tag">
<li><span class="img folder">arm-cm/</span> &mdash; Native examples for ARM-Cortex-M (bare-metal) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <span class="tag">A</span>
</li>
<ul class="tag">
<li><span class="img folder">blinky_ek-tm4c123gxl/</span> &mdash; Blinky example for EK-TM4C123GXL board
</li>
<li><span class="img folder">dpp_ek-tm4c123gxl/</span> &mdash; DPP example for EK-TM4C123GXL board
</li>
<li><span class="img folder">qk/</span> &mdash; Version for the @ref comp_qk "preemptive QK kernel"
</li>
<ul class="tag">
<li><span class="img folder">arm/</span> &mdash; build with ARM-KEIL (Compiler Version 5) toolchain
</li>
<li><span class="img folder">armclang/</span> &mdash; build with ARM-Clang (Compiler Version 6) toolchain
</li>
<ul class="tag">
<li><span class="img folder">dbg/</span> &mdash; Debug @ref exa_sec_conf "build configuration"
</li>
<li><span class="img folder">rel/</span> &mdash; Release build configuration
</li>
<li><span class="img folder">spy/</span> &mdash; Spy build configuration
</li>
</ul>
<li><span class="img folder">gnu/</span> &mdash; build with GNU toolchain
</li>
<li><span class="img folder">iar/</span> &mdash; build with IAR toolchain
</li>
<li><span class="img file_c">...</span> &mdash; source code independent on the toolchain
</li>
</ul>
<li><span class="img folder">qv/</span> &mdash; Version for the @ref comp_qv "cooperative QV kernel"
</li>
<li><span class="img folder">qxk/</span> &mdash; Version for the @ref comp_qxk "blocking QXK kernel"
</li>
</ul>
<li><span class="img folder">.../</span> &mdash; Native examples for other CPU architectures...
</li>
<br>
@code{.c}
qpc/ // QP/C installation directory
+---examples/ // examples directory (applications)
| |
| [1]--arm-cm/ // examples for ARM Cortex-M
| | +---dpp_ek-tm4c123gxl/ // DPP example on the EK-TM4C123GLX board
| | | +---qk/ // version for preemptive QK kernel
| | | | +---armclang/ // build with ARM-Clang (Compiler Version 6) toolchain
| | | | | +---dbg/ // debug build configuration
| | | | | +---rel/ // release build configuration
| | | | | +---spy/ // spy build configuration (QP/Spy tracing enabled)
| | | | +---gnu/ // build with GNU-ARM toolchain
| | | | +---iar/ // build with IAR toolchain
| | | | ~ ~ ~ // source files independent from the toolchain
| | | +---qv/ // version for cooperative QV kernel
| | | \---qxk/ // version for dual-mode QXK kernel
| |
| [2]--freertos/ // examples for FreeRTOS (3rd-party RTOS)
| | +---arm-cm/ // examples for ARM Cortex-M
| | | +---dpp_ek-tm4c123gxl/ // DPP example on the EK-TM4C123GLX board
| | | | +---gnu/ // build with GNU-ARM toolchain
| |
| [3]--lwip/ // examples for lwIP (3rd-party middleware)
| | +---arm-cm/ // examples for ARM Cortex-M
| | | +---qk/ // version for preemptive QK kernel
| | | +---qv/ // version for cooperative QV kernel
| | | \---qxk/ // version for dual-mode QXK kernel
| |
| [4]--qutest/ // examples for QUTest unit testing harness
| | +---blinky/ // simple Blinky example
| | | +---src/ // source code under test
| | | | blinky.h // header file
| | | | blinky.c // source file
| | | +---test/ // code for unit testing
| | | | Makefile // makefile for testing on the host
| | | | make_nucleo-l053r8 // makefile for testing on NUCLEO board
| | | | make_tm4c123 // makefile for testing on NUCLEO board
| | | | test_blinky.c // test fixture
| | | | test_blinky.py // test script
| |
| [5]--workstation/ // examples for workstations (Windows, Linux, macOS)
| | +---blinky/ // simple Blinky example
| | +---calc/ // calculator example
| | +---comp/ // "Orthogonal Component" example
| | +--- ~ ~ ~ // other examples from the PSiCC2 book
@endcode
<li><span class="img folder">threadx/</span> &mdash; Examples for ThreadX (3rd-party RTOS) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <span class="tag">B</span>
</li>
<ul class="tag">
<li><span class="img folder">arm-cm/</span> &mdash; Examples for ARM-Cortex-M
</li>
<ul class="tag">
<li><span class="img folder">dpp_ek-tm4c123gxl/</span> &mdash; DPP example for EK-TM4C123GXL board
</li>
<ul class="tag">
<li><span class="img folder">iar/</span> &mdash; build with IAR toolchain
</li>
<ul class="tag">
<li><span class="img folder">dbg/</span> &mdash; Debug build configuration
</li>
<li><span class="img folder">rel/</span> &mdash; Release build configuration
</li>
<li><span class="img folder">spy/</span> &mdash; Spy build configuration
</li>
</ul>
</ul>
</ul>
</ul>
<li><span class="img folder">.../</span> &mdash; Native examples for other 3rd-party RTOSes...
</li>
`[1]` @subpage exa_native "Native examples"
are located in sub-directories named after the CPU architecture, such as <span class="img folder">arm-cm</span> for ARM Cortex-M. Under that directory, the sub-directories <span class="img folder">blinky_ek-tm4c123gxl</span> contain the specific example on the specified board, such as "Blinky" on the EK-TM4C123GXL board here. In the specific example folder, you find sub-folders for the @ref comp_qv "QV", @ref comp_qk "QK" and @ref comp_qxk "QXK" kernels, respectively.
<li><span class="img folder">lwip/</span> &mdash; Examples for lwIP (3rd-party TCP/IP) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <span class="tag">C</span>
</li>
<ul class="tag">
<li><span class="img folder">arm-cm/</span> &mdash; Examples for ARM-Cortex-M
</li>
<ul class="tag">
<li><span class="img folder">lwip_ek-lm3s6965/</span> &mdash; lwIP example for EK-LM3S6965 board
</li>
<ul class="tag">
<li><span class="img folder">qk/</span> &mdash; Version for the @ref comp_qk "preemptive QK kernel"
</li>
<ul class="tag">
<li><span class="img folder">gnu/</span> &mdash; build with GNU toolchain
</li>
<ul class="tag">
<li><span class="img folder">dbg/</span> &mdash; Debug build configuration
</li>
<li><span class="img folder">rel/</span> &mdash; Release build configuration
</li>
<li><span class="img folder">spy/</span> &mdash; Spy build configuration
</li>
</ul>
<li><span class="img folder">iar/</span> &mdash; build with IAR toolchain
</li>
</ul>
<li><span class="img folder">qv/</span> &mdash; Version for the @ref comp_qv "cooperative QV kernel"
</li>
<ul class="tag">
<li><span class="img folder">gnu/</span> &mdash; build with GNU toolchain
</li>
<li><span class="img folder">iar/</span> &mdash; build with IAR toolchain
</li>
</ul>
</ul>
</ul>
</ul>
<li><span class="img folder">.../</span> &mdash; Examples for other 3rd-party middleware...
</li>
`[2]` @subpage exa_rtos "Examples for 3rd-party RTOS"
are located in sub-directories named after the RTOS/OS, such as <span class="img folder">freertos</span> for uc-os2 RTOS. Under that directory, the sub-directories, such as <span class="img folder">arm-cm</span>, contain examples for the specified CPU architecture, such as ARM Cortex-M here.
<li><span class="img folder">qutest/</span> &mdash; Examples for QUTest unit testing harness &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <span class="tag">D</span>
</li>
<ul class="tag">
<li><span class="img folder">blinky/</span> &mdash; The simple Blinky example
</li>
<ul class="tag">
<li><span class="img folder">src/</span> &mdash; source code under test
</li>
<ul class="tag">
<li><span class="img file_c">blinky.c</span> &mdash; Blinky implementation
</li>
<li><span class="img file_h">blinky.h</span> &mdash; Blinky header
</li>
</ul>
</ul>
<ul class="tag">
<li><span class="img folder">test/</span> &mdash; code for unit testing
</li>
<ul class="tag">
<li><span class="img file_mak">Makefile</span> &mdash; cross-platform makefile
</li>
<li><span class="img file_c">test_blinky.c</span> &mdash; test fixture for Blinky
</li>
<li><span class="img file_py">test_blinky.py</span> &mdash; test script for Blinky (Python)
</li>
</ul>
</ul>
<li><span class="img folder">.../</span> &mdash; Other QUTest examples...
</li>
</ul>
`[3]` @subpage exa_mware "Examples for 3rd-party Middleware"
are located in sub-directories named after the middleware, such as <span class="img folder">lwIP</span> for the lwIP TCP/IP stack. Under that directory, the sub-directories, such as <span class="img folder">arm-cm</span>, contain examples for the specified CPU architecture, such as ARM Cortex-M here.
<li><span class="img folder">workstation/</span> &mdash; Examples for workstations (Windows, Linux, MacOS) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <span class="tag">E</span>
</li>
<ul class="tag">
<li><span class="img folder">blinky/</span> &mdash; The simple Blinky example
</li>
<ul class="tag">
<li><span class="img folder">build/</span> &mdash; Debug build configuration
</li>
<li><span class="img folder">build_rel/</span> &mdash; Release build configuration
</li>
<li><span class="img folder">build_spy/</span> &mdash; Spy build configuration
</li>
<li><span class="img file_c"> blinky.c</span> &mdash; blinky source code
</li>
<li><span class="img file_qm"> blinky.qm</span> &mdash; QM model file for Blinky
</li>
<li><span class="img file_mak"> Makefile</span> &mdash; cross-platform Makefile (Windows, Linux, MacOS)
</li>
</ul>
<li><span class="img folder">calc/</span> &mdash; The Calculator example
</li>
<li><span class="img folder">comp/</span> &mdash; The Orthogonal-Component example
</li>
<li><span class="img folder">defer/</span> &mdash; The Deferred-Event example
</li>
<li><span class="img folder">dpp/</span> &mdash; The Dining-Philosophers Problem example
</li>
<li><span class="img folder">.../</span> &mdash; other examples for workstations...
</li>
</ul>
`[4]` @subpage exa_qutest "Examples for QUTest"
illustrate unit testing of embedded event-driven code. <span class="highlight"><b>NOTE:</b> Examples in this directory can run on all types of workstations (Windows, Linux, MacOS), as well as embedded targets.</span>
</ul>
</ul>
`[5]` @subpage exa_os "Examples for Workstations"
General-Purpose OS (GPOS) examples described in the [PSiCC2](/psicc2) book, which you can try directly on your workstation without any embedded hardware. <span class="highlight"><b>NOTE:</b> Examples in this directory can also be used on the <b>embedded</b> versions of the desktop operating systems, such as embedded-Linux and Windows-embedded.</span>
<ul class="tag">
<li><span class="tag">A</span> @subpage exa_native "Native examples" are located in sub-directories named after the CPU architecture, such as <span class="img folder">arm-cm</span> for ARM Cortex-M. Under that directory, the sub-directories <span class="img folder">blinky_ek-tm4c123gxl</span> contain the specific example on the specified board, such as "Blinky" on the EK-TM4C123GXL board here. In the specific example folder, you find sub-folders for the @ref comp_qv "QV", @ref comp_qk "QK" and @ref comp_qxk "QXK" kernels, respectively.
</li>
<li><span class="tag">B</span> @subpage exa_rtos "Examples for 3rd-party RTOS"/@ref exa_os "OS" are located in sub-directories named after the RTOS/OS, such as <span class="img folder">ucos-ii</span> for uCOS-II RTOS. Under that directory, the sub-directories, such as <span class="img folder">arm-cm</span>, contain examples for the specified CPU architecture, such as ARM Cortex-M here.
</li>
<li><span class="tag">C</span> @subpage exa_mware "Examples for 3rd-party Middleware" are located in sub-directories named after the middleware, such as <span class="img folder">lwIP</span> for the lwIP TCP/IP stack. Under that directory, the sub-directories, such as <span class="img folder">arm-cm</span>, contain examples for the specified CPU architecture, such as ARM Cortex-M here.
</li>
<li><span class="tag">D</span> @subpage exa_qutest "Examples for QUTest" illustrate unit testing of embedded event-driven code. <span class="highlight"><b>NOTE:</b> Examples in this directory can run on all types of workstations (Windows, Linux, MacOS), as well as embedded targets.</span>
</li>
<li><span class="tag">E</span> @subpage exa_os "Examples for Workstations" provide console-based examples described in the [PSiCC2](/psicc2) book, which you can try directly on your workstation without any embedded hardware. <span class="highlight"><b>NOTE:</b> Examples in this directory can also be used on the <b>embedded</b> versions of the desktop operating systems, such as embedded-Linux and Windows-embedded.</span>
</li>
</ul>
@note
Because the QP distribution contains *all* examples, the number of sub-directories and files in the <span class="img folder">examples</span> folder may seem daunting. However, knowing the structure of the <span class="img folder">examples</span> folder, you can simply ignore or even delete the sub-directories that are not interesting to you.
@subsection exa_sec_apps Example Applications
To demonstrate QP/C features on an embedded board, you need to create an application that does "something interesting". Instead of inventing this "something interesting" for each and every example, the example projects implement one of the three "example applications", which are described on the @ref gs_tut "QP&trade;/C Tutorial":
@ -228,12 +101,10 @@ Beyond these basic applications for demonstrating and testing the various @ref p
While some provided examples can run on your @ref exa_os "desktop computer", most embedded example projects require special hardware in form of @ref exa_sec_boards, which you need to acquire to be able to run the examples. The boards chosen for the examples are generally inexpensive and self-contained with no need for external hardware (such as external JTAG debuggers or power supplies).
@subsection exa_sec_tools Development Tools
Most provided examples require special embedded cross-development tools, such as embedded compilers, linkers, debuggers and IDEs, which you need to acquire independently from the QP/C distribution. Generally, the examples work with the free (size limited) evaluation versions of the commercial tools. The examples list the versions of tools they were developed and tested with. Please refer to the @ref exa_ref "cross-reference section" @ref exa_sec_tools to see which embedded toolchains are used.
@subsection exa_sec_conf Build Configurations
QP examples @ref ports "QP ports" are provided in the following three **build configurations**:
@ -249,7 +120,6 @@ QP examples @ref ports "QP ports" are provided in the following three **build co
The different phases of embedded software life cycle pose different challenges. During the development and maintenance phase, for example, the emphasis is on the ease of debugging and verifying the correctness of the code, which require lower levels of optimization and special scaffolding code. In contrast, for releasing the code in the final product, the emphasis is on small memory footprint and CPU time efficiency, which require high-level of optimization and removal of any scaffolding code. To address these conflicting needs, the same source code is compiled into multiple **build configurations** that differ in the use of compiler options and activation of the scaffolding code.
@subsection exa_sec_qm QM Models
Many example projects contain code auto-generated by the <a class="extern" target="_blank" href="https://www.state-machine.com/qm"><strong>QM modeling tool</strong></a>. Such projects always contain the corresponding **QM model** file, which you can open in QM, modify, and re-generate the code.
@ -257,7 +127,6 @@ Many example projects contain code auto-generated by the <a class="extern" targe
The auto-generated files are saved as **read-only**. This protects them from inadvertent modifications, which will get lost when the files are re-generated by QM (or QMC). All modifications to the auto-generated code should be done in the QM model, not in the code.
@subsection exa_sec_3rd Third-Party Code
The QP/C example projects often need to use various additional code, such as MCU register definition files, startup code, device drivers, etc., which are provided by Third-Party vendors. All such code is located in the <span class="img folder">3rd_party</span> <a href="files.html">top-level folder</a>.
@ -272,9 +141,7 @@ The Third-Party software components included in the <span class="img folder">3rd
sub-folders.
@subsection exa_own Creating your Own QP/C Projects
Perhaps the most important fact of life to remember is that in embedded systems nothing works until everything works. This means that you should always start with a <strong>working system</strong> and gradually evolve it, changing one thing at a time and making sure that it keeps working every step of the way.
Keeping this in mind, the provided QP/C application examples, such as the super-simple Blinky, or a bit more advanced @ref dpp or @ref game, allow you to get started with a working project rather than starting from scratch. You should also always try one of the provided example projects on the same evaluation board that it was designed for, before making any changes.
@ -288,13 +155,12 @@ Even before you acquire a specific evaluation board, you can always at least **b
Only after convincing yourself that the example project works "as is", you can think about creating your own projects. At this point, the easiest and recommended way is to copy the existing working example project folder (such as the Blinky example) and rename it.
After copying the project folder, you still need to change the name of the project/workspace. The easiest and safest way to do this is to open the project/workspace in the corresponding IDE and use the Save As... option to save the project under a different name. You can do this also with the QM model file, which you can open in QM and "Save As" a different model.
After copying the project folder, you still need to change the name of the project/workspace. The easiest and safest way to do this is to open the project/workspace in the corresponding IDE and use the Save As~~~ option to save the project under a different name. You can do this also with the QM model file, which you can open in QM and "Save As" a different model.
@note
By copying and re-naming an existing, working project, as opposed to creating a new one from scratch, you inherit the correct compiler and linker options an other project settings, which will help you get started much faster.
@subsection exa_doc Next Steps and Further Reading About QP and QM
To work with QP/C effectively, you need to learn a bit more about active objects and state machines. Below is a list of links to enable you to further your knowledge:
@ -305,15 +171,14 @@ To work with QP/C effectively, you need to learn a bit more about active objects
4. QP Application Notes (https://www.state-machine.com/an/ )
5. "State Space" Blog (https://www.state-machine.com/category/blog/ )
@next{exa_ref}
@ifnot LATEX
@nav_next{exa_ref}
@endif
*/
/*##########################################################################*/
/*! @page exa_ref Cross-Reference
@tableofcontents
@section exa_ref_kernel Native Examples (by Built-in Kernel)
- @ref exa_qv
- @ref exa_qk
@ -321,11 +186,6 @@ To work with QP/C effectively, you need to learn a bit more about active objects
@section exa_ref_tool Native Examples (by Development Toolchain)
@n
@subsection exa_ref_arm-keil ARM-Keil Toolchain (ARM Compiler 5)
- @ref arm-cm_blinky_ek-tm4c123gxl <a class="preview board" href="bd_EK-TM4C123GXL.jpg" title="EK-TM4C123GXL"></a> &nbsp; (Cortex-M4)
@subsection exa_ref_arm-clang ARM-Clang Toolchain (ARM Compiler 6)
@ -337,10 +197,8 @@ To work with QP/C effectively, you need to learn a bit more about active objects
- @ref arm-cm_dpp_nucleo-l152re <a class="preview board" href="bd_NUCLEO-L152RE.jpg" title="NUCLEO-L152RE"></a> &nbsp; (Cortex-M3)
- @ref arm-cm_game_efm32-slstk3401a <a class="preview board" href="bd_EFM32-SLSTK3401A.jpg" title="EFM32-SLSTK3401A"></a> &nbsp; (Cortex-M4)
- @ref arm-cm_dpp_stm32f4-discovery <a class="preview board" href="bd_STM32F4-Discovery.jpg" title="STM32F4-Discovery"></a>
- @ref arm-cm_dpp_stm32f746g-disco <a class="preview board" href="bd_STM32F746G-Disco.jpg" title="STM32F746G-Discovery"></a> &nbsp; (Cortex-M7)
- @ref arm-cm_dpp_nucleo-l053r8 <a class="preview board" href="bd_NUCLEO-L053R8.jpg" title="NUCLEO-L053R8"></a> &nbsp; (Cortex-M0+)
- @ref arm-cm_dpp_efm32-slstk3401a <a class="preview board" href="bd_EFM32-SLSTK3401A.jpg" title="EFM32-SLSTK3401A"></a> &nbsp; (Cortex-M4)
- @ref arm-cm_dpp_stm32f746g-disco <a class="preview board" href="bd_STM32F746G-Disco.jpg" title="STM32F746G-Discovery"></a> &nbsp; (Cortex-M7)
- @ref arm-cm_dpp_nucleo-h743zi <a class="preview board" href="bd_NUCLEO-H743ZI.jpg" title="NUCLEO-H743ZI"></a> &nbsp; (Cortex-M7)
@ -354,16 +212,13 @@ To work with QP/C effectively, you need to learn a bit more about active objects
- @ref arm-cm_dpp_nucleo-l152re <a class="preview board" href="bd_NUCLEO-L152RE.jpg" title="NUCLEO-L152RE"></a> &nbsp; (Cortex-M3)
- @ref arm-cm_game_efm32-slstk3401a <a class="preview board" href="bd_EFM32-SLSTK3401A.jpg" title="EFM32-SLSTK3401A"></a> &nbsp; (Cortex-M4)
- @ref arm-cm_dpp_stm32f4-discovery <a class="preview board" href="bd_STM32F4-Disco.jpg" title="STM32F4-Discovery"></a>
- @ref arm-cm_dpp_stm32f746g-disco <a class="preview board" href="bd_STM32F746G-Disco.jpg" title="STM32F746G-Discovery"></a> &nbsp; (Cortex-M7)
- @ref lwip_ek-lm3s6965 <a class="preview board" href="bd_EK-LM3S6965.jpg" title="EK-LM3S6965"></a> &nbsp; (Cortex-M3)
- @ref arm7-9_dpp_at91sam7s-ek <a class="preview board" href="bd_AT91SAM7S-EK.jpg" title="AT91SAM7S-EK"></a> &nbsp; (ARM7TDMI)
@subsection exa_ref_gnu-ccs GNU-ARM with TI CCS IDE
- @ref arm-cm_dpp_ek-tm4c123gxl <a class="preview board" href="bd_EK-TM4C123GXL.jpg" title="EK-TM4C123GXL"></a> &nbsp; (Cortex-M4)
@subsection exa_ref_iar-arm IAR EWARM
- @ref arm-cm_blinky_ek-tm4c123gxl <a class="preview board" href="bd_EK-TM4C123GXL.jpg" title="EK-TM4C123GXL"></a> &nbsp; (Cortex-M4)
- @ref arm-cm_blinky_efm32-slstk3401a <a class="preview board" href="bd_EFM32-SLSTK3401A.jpg" title="EFM32-SLSTK3401A"></a> &nbsp; (Cortex-M4)
@ -373,11 +228,9 @@ To work with QP/C effectively, you need to learn a bit more about active objects
- @ref arm-cm_dpp_nucleo-l053r8 <a class="preview board" href="bd_NUCLEO-L053R8.jpg" title="NUCLEO-L053R8"></a> &nbsp; (Cortex-M0+)
- @ref arm-cm_dpp_nucleo-l152re <a class="preview board" href="bd_NUCLEO-L152RE.jpg" title="NUCLEO-L152RE"></a> &nbsp; (Cortex-M3)
- @ref arm-cm_game_efm32-slstk3401a <a class="preview board" href="bd_EFM32-SLSTK3401A.jpg" title="EFM32-SLSTK3401A"></a> &nbsp; (Cortex-M4)
- @ref arm-cm_dpp_stm32f746g-disco <a class="preview board" href="bd_STM32F746G-Disco.jpg" title="STM32F746G-Discovery"></a> &nbsp; (Cortex-M7)
- @ref arm-cr_blinky_launchxl2-tms57012 <a class="preview board" href="bd_LAUNCHXL2-TMS57012.jpg" title="LAUNCHXL2-TMS57012"></a> &nbsp; (Cortex-R4)
- @ref arm-cr_dpp_launchxl2-tms57012 <a class="preview board" href="bd_LAUNCHXL2-TMS57012.jpg" title="LAUNCHXL2-TMS57012"></a> &nbsp; (Cortex-R4)
- @ref lwip_ek-lm3s6965 <a class="preview board" href="bd_EK-LM3S6965.jpg" title="EK-LM3S6965"></a> &nbsp; (Cortex-M3)
- @ref arm7-9_dpp_at91sam7s-ek <a class="preview board" href="bd_AT91SAM7S-EK.jpg" title="AT91SAM7S-EK"></a> &nbsp; (ARM7TDMI)
@subsection exa_ref_ccs-430 CCS for MSP430
@ -393,7 +246,6 @@ To work with QP/C effectively, you need to learn a bit more about active objects
@section exa_ref_native Native Examples (by Processor)
- @ref exa_arm-cm
- @ref exa_arm-cr
- @ref exa_arm7-9 ("classic ARM")
- @ref exa_msp430 ("classic" MSP430 and "extended" MSP430x)
@ -401,7 +253,7 @@ To work with QP/C effectively, you need to learn a bit more about active objects
- @ref exa_embos (SEGGER)
- @ref exa_freertos (Amazon Web Services)
- @ref exa_threadx (Express Logic)
- @ref exa_ucos-ii (Micrium/SiLabs)
- @ref exa_uc-os2 (Micrium/SiLabs)
@section exa_ref_os Examples for Workstations (Windows, Linux, MacOS)
@ -419,7 +271,6 @@ The examples in the "workstation" directory are designed for workstations (runni
- @ref exa_emwin (SEGGER, a.k.a. uC/GUI by Micrium)
@section exa_ref_boards Examples by Development Board
The boards chosen for the examples are generally inexpensive and self-contained with minimal need for external hardware (such as external JTAG debuggers or power supplies). Also, all the selected boards provide a virtual COM port (ideally) or can be easily connected to a TTL-to-USB serial converter cable for @ref comp_qs "QS software tracing" output.
@ -430,83 +281,94 @@ You can hover the mouse cursor over the <span class="board"></span>&nbsp;&nbsp;
@subsection exa_ref_arm-cm ARM Cortex-M Boards
@anchor EK-TM4C123GXL
![EK-TM4C123GXL (TivaC LaunchPad)](bd_EK-TM4C123GXL.jpg)
@image html bd_EK-TM4C123GXL.jpg
@image latex bd_EK-TM4C123GXL.jpg width=2.5in
@caption{EK-TM4C123GXL (TivaC LaunchPad)}
- @ref arm-cm_blinky_ek-tm4c123gxl (QV, QK kernels; ARM-KEIL, GNU-ARM, IAR-EWARM toolchains)
- @ref arm-cm_dpp_ek-tm4c123gxl (QV, QK, QXK kernels; ARM-KEIL, GNU-ARM, IAR-EWARM toolchains)
- @ref freertos_dpp_ek-tm4c123gxl (FreeRTOS kernel; ARM-KEIL, GNU-ARM, IAR-EWARM toolchains)
- @ref freertos_dpp_nucleo-h743zi (FreeRTOS kernel; ARM-KEIL, GNU-ARM, IAR-EWARM toolchains)
- @ref threadx_dpp_ek-tm4c123gxl (ThreadX kernel; IAR-EWARM toolchain)
- @ref ucos-ii_dpp_ek-tm4c123gxl (uC/OS-II kernel; ARM-KEIL, GNU-ARM, IAR-EWARM toolchains)
- @ref uc-os2_dpp_ek-tm4c123gxl (uC/OS-II kernel; ARM-KEIL, GNU-ARM, IAR-EWARM toolchains)
@anchor EFM32-SLSTK3401A
![EFM32-SLSTK3401A](bd_EFM32-SLSTK3401A.jpg)
@image html bd_EFM32-SLSTK3401A.jpg
@image latex bd_EFM32-SLSTK3401A.jpg width=4.5in
@caption{EFM32-SLSTK3401A (Pearl-Gecko)}
- @ref arm-cm_blinky_efm32-slstk3401a (QV, QK kernels; ARM-KEIL, GNU-ARM, IAR-EWARM toolchains)
- @ref arm-cm_dpp_efm32-slstk3401a (QV, QK, QXK kernels; ARM-KEIL, GNU-ARM, IAR-EWARM toolchains)
- @ref arm-cm_game_efm32-slstk3401a (QV, QK kernels; ARM-KEIL, GNU-ARM, IAR-EWARM toolchains; <a href="https://www.state-machine.com/qtools/qwin.html"><b>QWin-GUI emulation</b></a>)
@anchor mbed-LPC1768
![mbed-LPC1768](bd_mbed-LPC1768.jpg)
@image html bd_mbed-LPC1768.jpg
@image latex bd_mbed-LPC1768.jpg width=2.5in
@caption{mbed-LPC1768}
- @ref arm-cm_dpp_mbed-lpc1768 (QV, QK kernels; ARM-KEIL, GNU-ARM, IAR-EWARM toolchains)
@anchor NUCLEO-L053R8
![NUCLEO-L053R8](bd_NUCLEO-L053R8.jpg)
@image html bd_NUCLEO-L053R8.jpg
@image latex bd_NUCLEO-L053R8.jpg width=2.5in
@caption{NUCLEO-L053R8}
- @ref arm-cm_dpp_nucleo-l053r8 (QV, QK, QXK kernels; ARM-KEIL, GNU-ARM, IAR-EWARM toolchains)
@anchor NUCLEO-L152RE
![NUCLEO-L152RE](bd_NUCLEO-L152RE.jpg)
@image html bd_NUCLEO-L152RE.jpg
@image latex bd_NUCLEO-L152RE.jpg width=2.4in
@caption{NUCLEO-L152RE}
- @ref arm-cm_dpp_nucleo-l152re (QV, QK kernels; ARM-KEIL, GNU-ARM, IAR-EWARM toolchains)
- @ref ucos-ii_dpp_nucleo-l053r8 (uC/OS-II kernel; ARM-KEIL, IAR-EWARM toolchains)
- @ref uc-os2_dpp_nucleo-l053r8 (uC/OS-II kernel; ARM-KEIL, IAR-EWARM toolchains)
@anchor exa_EK-LM3S6965
![EK-LM3S6965](bd_EK-LM3S6965.jpg)
@anchor EK-LM3S6965
@image html bd_EK-LM3S6965.jpg
@image latex bd_EK-LM3S6965.jpg width=2.0in
@caption{EK-LM3S6965}
- @ref lwip_ek-lm3s6965 (**LwIP TCP/IP**; QV, QK kernels; ARM-KEIL, GNU-ARM, IAR-EWARM toolchains)
@anchor NUCLEO-H743ZI
![NUCLEO-H743ZI](bd_NUCLEO-H743ZI.jpg)
@image html bd_NUCLEO-H743ZI.jpg
@image latex bd_NUCLEO-H743ZI.jpg width=4.5in
@caption{NUCLEO-H743ZI}
- @ref arm-cm_dpp_nucleo-h743zi (QV, QK, QXK kernels; ARM-KEIL, GNU-ARM, IAR-EWARM toolchains)
- @ref freertos_dpp_nucleo-h743zi (FreeRTOS kernel; ARM-KEIL, GNU-ARM, IAR-EWARM toolchains)
@anchor STM32F4-Discovery
![STM32F4-Discovery](bd_STM32F4-Discovery.jpg)
@image html bd_STM32F4-Disco.jpg
@image latex bd_STM32F4-Disco.jpg width=2.8in
@caption{STM32F4-Discovery}
- @ref arm-cm_dpp_stm32f4-discovery (QV, QK, QXK kernels; ARM-KEIL, GNU-ARM, IAR-EWARM toolchains)
- @ref embos_dpp_stm32f429-discovery (embOS kernel; IAR-EWARM toolchain)
- @ref threadx_dpp_stm32f429-discovery (ThreadX kernel; IAR-EWARM toolchain)
@anchor STM32F746G-Discovery
![STM32F746G-Discovery](bd_STM32F746G-Disco.jpg)
@image html bd_STM32F746G-Disco.jpg
@image latex bd_STM32F746G-Disco.jpg width=4.75in
@caption{STM32F746G-Discovery}
- @ref arm-cm_dpp_stm32f746g-disco (QV, QK, QXK kernels; ARM-KEIL, GNU-ARM, IAR-EWARM toolchains)
- @ref freertos_dpp_stm32f746g-disco (FreeRTOS kernel; ARM-KEIL, GNU-ARM, IAR-EWARM toolchains)
@subsection exa_ref_arm-cr ARM Cortex-R Boards:
@anchor LAUNCHXL2-TMS57012
![LAUNCHXL2-TMS57012](bd_LAUNCHXL2-TMS57012.jpg)
@image html bd_LAUNCHXL2-TMS57012.jpg
@image latex bd_LAUNCHXL2-TMS57012.jpg width=4.0in
@caption{LAUNCHXL2-TMS57012}
- @ref arm-cr_blinky_launchxl2-tms57012 (QV, QK kernels; CCS-TI-ARM, IAR-EWARM toolchains)
- @ref arm-cr_dpp_launchxl2-tms57012 (QV, QK kernels; CCS-TI-ARM, IAR-EWARM toolchains)
@subsection exa_ref_arm7-9 ARM7 Boards:
@anchor AT91SAM7S-EK
![AT91SAM7S-EK](bd_AT91SAM7S-EK.jpg)
- @ref arm7-9_dpp_at91sam7s-ek (QV, QK kernels; IAR-EWARM toolchains)
@subsection exa_ref_msp430 MSP430 Boards:
@anchor MSP-EXP430F5529LP
![MSP-EXP430F5529LP](bd_MSP-EXP430F5529LP.jpg)
@image html bd_MSP-EXP430F5529LP.jpg
@image latex bd_MSP-EXP430F5529LP.jpg width=3.5in
@caption{MSP-EXP430F5529LP}
- @ref msp430_blinky_msp-exp430f5529lp (QV, QK kernels; CCS=430, IAR-EW430 toolchains)
- @ref msp430_dpp_msp-exp430f5529lp (QV, QK kernels; CCS=430, IAR-EW430 toolchains)
@ -532,16 +394,12 @@ You can hover the mouse cursor over the <span class="board"></span>&nbsp;&nbsp;
- ARM Cortex-R
- @ref arm-cr_blinky_launchxl2-tms57012 <a class="preview board" href="bd_LAUNCHXL2-TMS57012.jpg" title="LAUNCHXL2-TMS57012"></a>
- @ref arm-cr_dpp_launchxl2-tms57012 <a class="preview board" href="bd_LAUNCHXL2-TMS57012.jpg" title="LAUNCHXL2-TMS57012"></a>
- ARM7 / ARM9
- @ref arm7-9_dpp_at91sam7s-ek <a class="preview board" href="bd_AT91SAM7S-EK.jpg" title="AT91SAM7S-EK"></a>
- MSP430
- @ref msp430_blinky_msp-exp430f5529lp <a class="preview board" href="bd_MSP-EXP430F5529LP.jpg" title="MSP-EXP430F5529LP"></a>
- @ref msp430_dpp_msp-exp430f5529lp <a class="preview board" href="bd_MSP-EXP430F5529LP.jpg" title="MSP-EXP430F5529LP"></a>
@section exa_ref_vendor Examples by MCU Vendor
- Atmel
- @ref arm7-9_dpp_at91sam7s-ek <a class="preview board" href="bd_AT91SAM7S-EK.jpg" title="AT91SAM7S-EK"></a>
- NXP
- @ref arm-cm_dpp_mbed-lpc1768 <a class="preview board" href="bd_mbed-LPC1768.jpg" title="mbed-LPC1768"></a>
- Silicon Labs
@ -561,5 +419,7 @@ You can hover the mouse cursor over the <span class="board"></span>&nbsp;&nbsp;
- @ref arm-cr_dpp_launchxl2-tms57012 <a class="preview board" href="bd_LAUNCHXL2-TMS57012.jpg" title="LAUNCHXL2-TMS57012"></a>
- @ref lwip_ek-lm3s6965 <a class="preview board" href="bd_EK-LM3S6965.jpg" title="EK-LM3S6965"></a>
@next{exa_native}
@ifnot LATEX
@nav_next{exa_native}
@endif
*/

31
doxygen/exa_mware.dox
View File

@ -13,34 +13,37 @@
/*##########################################################################*/
/*! @page lwip_ek-lm3s6965 lwIP on EK-LM3S6965
@image html bd_EK-LM3S6965.jpg EK-LM3S6965 board
@image html bd_EK-LM3S6965.jpg
@image latex bd_EK-LM3S6965.jpg width=2.0in
@caption{EK-LM3S6965}
lwIP example for Texas Instruments EK-LM3S6965 (Cortex-M3) with GNU-ARM and IAR-ARM toolsets.
@image html bd_EK-LM3S6965_lwip.jpg QP-lwIP on EK-LM3S6965
@n@n
@image html bd_EK-LM3S6965_lwip.jpg
@image latex bd_EK-LM3S6965_lwip.jpg width=2.0in
@caption{QP-lwIP on EK-LM3S6965}
<br>
@section lwip_AN Application Note: QP and lwIP TCP/IP Stack
The [Application Note](https://www.state-machine.com/doc/AN_QP_and_lwIP.pdf) describes how to use the lightweight TCP/IP stack called lwIP with the QP real-time embedded frameworks.
[![Application Note: QP and lwIP TCP/IP](AN-QL.png)](https://www.state-machine.com/doc/AN_QP_and_lwIP.pdf)
@htmlonly
<div class="caption">
Application Note: QP and lwIP TCP/IP Stack
</div>
@endhtmlonly
@image html AN-QL.png
@image latex AN-QL.png width=2in
@caption{Application Note: QP and lwIP TCP/IP}
@next{ exa_emwin}
@ifnot LATEX
@nav_next{exa_emwin}
@endif
*/
/*##########################################################################*/
/*! @page exa_emwin emWin Embedded GUI
<p>The <a href="https://www.state-machine.com/doc/AN_QP_emWin.pdf" target="_blank" class="extern"><strong>Application Note "QP and emWin Embedded GUI"</strong></a> describes how to use QP&trade; with the <a href="https://www.segger.com/emwin.html" target="_blank" class="extern">emWin&trade; Embedded GUI from SEGGER</a> and also <a href="https://www.micrium.com/rtos/gui/" target="_blank" class="extern">&micro;C/GUI from Micrium</a>, which technically are the same products.
</p>
@image html emWin_demo.jpg QP-emWin demo (DPP) running on Windows
The <a href="https://www.state-machine.com/doc/AN_QP_emWin.pdf" target="_blank" class="extern"><strong>Application Note "QP and emWin Embedded GUI"</strong></a> describes how to use QP&trade; with the <a href="https://www.segger.com/emwin.html" target="_blank" class="extern">emWin&trade; Embedded GUI from SEGGER</a> and also <a href="https://www.micrium.com/rtos/gui/" target="_blank" class="extern">&micro;C/GUI from Micrium</a>, which technically are the same products.
@image html emWin_demo.jpg
@image latex emWin_demo.jpg width=4.0in
@caption{QP-emWin demo (DPP) running on Windows}
To demonstrate the working examples, this Application Note uses the emWin Simulation on Windows, which is available for a <a href="https://www.segger.com/downloads/emwin" target="_blank" class="extern">free download from the SEGGER</a> (requires registration). You need only a Windows-based PC to execute the examples provided in this Application Note. Additionally, you'd need Microsoft Visual Studio 2013 (could be the free Express Edition) or higher to re-build and debug the provided examples.

223
doxygen/exa_native.dox
View File

@ -1,8 +1,7 @@
/*##########################################################################*/
/*! @page exa_native Native Examples (Built-in Kernels)
<p>The QP/C framework contains real-time kernels (@ref comp_qv and @ref comp_qk), so it can run natively ("bare-metal") on single-chip microcontrollers, completely replacing a traditional RTOS. Click on the following links to see examples for the specified built-in kernels:
</p>
The QP/C framework contains real-time kernels (@ref comp_qv and @ref comp_qk), so it can run natively ("bare-metal") on single-chip microcontrollers, completely replacing a traditional RTOS. Click on the following links to see examples for the specified built-in kernels:
- @subpage exa_qv
- @subpage exa_qk
@ -20,8 +19,10 @@ Click on the following links to see examples for the specified CPU architectures
/*##########################################################################*/
/*! @page exa_qv QV Kernel (Non-Preemptive, Priority-Based, Non-Blocking)
@note
@ifnot LATEX
@remark
You can hover the mouse cursor over the <span class="board"></span>&nbsp;&nbsp; icon in the list below to see the picture of the board.
@endif
- @ref arm-cm_blinky_ek-tm4c123gxl <a class="preview board" href="bd_EK-TM4C123GXL.jpg" title="EK-TM4C123GXL"></a>
- @ref arm-cm_blinky_efm32-slstk3401a <a class="preview board" href="bd_EFM32-SLSTK3401A.jpg" title="EFM32-SLSTK3401A"></a>
@ -34,18 +35,19 @@ You can hover the mouse cursor over the <span class="board"></span>&nbsp;&nbsp;
- @ref arm-cm_dpp_nucleo-h743zi <a class="preview board" href="bd_NUCLEO-H743ZI.jpg" title="STM32 NUCLEO-H743ZI"></a>
- @ref arm-cm_dpp_nucleo-l552ze <a class="preview board" href="bd_NUCLEO-L552ZE.jpg" title="STM32 NUCLEO-L552ZE Q"></a>
- @ref arm-cm_game_efm32-slstk3401a <a class="preview board" href="bd_EFM32-SLSTK3401A.jpg" title="EFM32-SLSTK3401A"></a>
- @ref arm-cm_low-power <a class="preview board" href="bd_EK-TM4C123GXL.jpg" title="EK-TM4C123GXL"></a>
- @ref tut_low <a class="preview board" href="bd_EK-TM4C123GXL.jpg" title="EK-TM4C123GXL"></a>
- @ref arm-cr_blinky_launchxl2-tms57012 <a class="preview board" href="bd_LAUNCHXL2-TMS57012.jpg" title="LAUNCHXL2-TMS57012"></a>
- @ref arm-cr_dpp_launchxl2-tms57012 <a class="preview board" href="bd_LAUNCHXL2-TMS57012.jpg" title="LAUNCHXL2-TMS57012"></a>
- @ref arm7-9_dpp_at91sam7s-ek <a class="preview board" href="bd_AT91SAM7S-EK.jpg" title="AT91SAM7S-EK"></a>
- @ref msp430_blinky_msp-exp430f5529lp <a class="preview board" href="bd_MSP-EXP430F5529LP.jpg" title="MSP-EXP430F5529LP"></a>
- @ref msp430_dpp_msp-exp430f5529lp <a class="preview board" href="bd_MSP-EXP430F5529LP.jpg" title="MSP-EXP430F5529LP"></a>
*/
/*##########################################################################*/
/*! @page exa_qk QK Kernel (Preemptive, Run-To-Completion/Non-Blocking)
@note
@ifnot LATEX
@remark
You can hover the mouse cursor over the <span class="board"></span>&nbsp;&nbsp; icon in the list below to see the picture of the board.
@endif
- @ref arm-cm_blinky_ek-tm4c123gxl <a class="preview board" href="bd_EK-TM4C123GXL.jpg" title="EK-TM4C123GXL"></a>
- @ref arm-cm_blinky_efm32-slstk3401a <a class="preview board" href="bd_EFM32-SLSTK3401A.jpg" title="EFM32-SLSTK3401A"></a>
@ -58,10 +60,9 @@ You can hover the mouse cursor over the <span class="board"></span>&nbsp;&nbsp;
- @ref arm-cm_dpp_stm32f4-discovery <a class="preview board" href="bd_STM32F4-Disco.jpg" title="STM32F4-Discovery"></a>
- @ref arm-cm_dpp_nucleo-h743zi <a class="preview board" href="bd_NUCLEO-H743ZI.jpg" title="STM32 NUCLEO-H743ZI"></a>
- @ref arm-cm_dpp_nucleo-l552ze <a class="preview board" href="bd_NUCLEO-L552ZE.jpg" title="STM32 STM32 NUCLEO-L552ZE Q"></a>
- @ref arm-cm_low-power <a class="preview board" href="bd_EK-TM4C123GXL.jpg" title="EK-TM4C123GXL"></a>
- @ref tut_low <a class="preview board" href="bd_EK-TM4C123GXL.jpg" title="EK-TM4C123GXL"></a>
- @ref arm-cr_blinky_launchxl2-tms57012 <a class="preview board" href="bd_LAUNCHXL2-TMS57012.jpg" title="LAUNCHXL2-TMS57012"></a>
- @ref arm-cr_dpp_launchxl2-tms57012 <a class="preview board" href="bd_LAUNCHXL2-TMS57012.jpg" title="LAUNCHXL2-TMS57012"></a>
- @ref arm7-9_dpp_at91sam7s-ek <a class="preview board" href="bd_AT91SAM7S-EK.jpg" title="AT91SAM7S-EK"></a>
- @ref msp430_blinky_msp-exp430f5529lp <a class="preview board" href="bd_MSP-EXP430F5529LP.jpg" title="MSP-EXP430F5529LP"></a>
- @ref msp430_dpp_msp-exp430f5529lp <a class="preview board" href="bd_MSP-EXP430F5529LP.jpg" title="MSP-EXP430F5529LP"></a>
@ -69,22 +70,26 @@ You can hover the mouse cursor over the <span class="board"></span>&nbsp;&nbsp;
/*##########################################################################*/
/*! @page exa_qxk QXK Kernel (Preemptive, Run-To-Completion/Blocking)
@note
@ifnot LATEX
@remark
You can hover the mouse cursor over the <span class="board"></span>&nbsp;&nbsp; icon in the list below to see the picture of the board.
@endif
- @ref arm-cm_dpp_ek-tm4c123gxl <a class="preview board" href="bd_EK-TM4C123GXL.jpg" title="EK-TM4C123GXL"></a>
- @ref arm-cm_dpp_efm32-slstk3401a <a class="preview board" href="bd_EFM32-SLSTK3401A.jpg" title="EFM32-SLSTK3401A"></a>
- @ref arm-cm_dpp_stm32f4-discovery <a class="preview board" href="bd_STM32F4-Disco.jpg" title="STM32F4-Discovery"></a>
- @ref arm-cm_dpp_nucleo-l552ze <a class="preview board" href="bd_NUCLEO-L552ZE.jpg" title="STM32 NUCLEO-L552ZE Q"></a>
- @ref arm-cm_dpp_nucleo-h743zi <a class="preview board" href="bd_NUCLEO-H743ZI.jpg" title="STM32 NUCLEO-H743ZI"></a>
- @ref arm-cm_low-power <a class="preview board" href="bd_EK-TM4C123GXL.jpg" title="EK-TM4C123GXL"></a>
- @ref tut_low <a class="preview board" href="bd_EK-TM4C123GXL.jpg" title="EK-TM4C123GXL"></a>
*/
/*##########################################################################*/
/*! @page exa_arm-cm ARM Cortex-M (Cortex-M0/M0+/M3/M4/M7/M33)
@note
@ifnot LATEX
@remark
You can hover the mouse cursor over the <span class="board"></span>&nbsp;&nbsp; icon in the list below to see the picture of the board.
@endif
- @subpage arm-cm_blinky_ek-tm4c123gxl <a class="preview board" href="bd_EK-TM4C123GXL.jpg" title="EK-TM4C123GXL"></a>
- @subpage arm-cm_blinky_efm32-slstk3401a <a class="preview board" href="bd_EFM32-SLSTK3401A.jpg" title="EFM32-SLSTK3401A"></a>
@ -97,30 +102,26 @@ You can hover the mouse cursor over the <span class="board"></span>&nbsp;&nbsp;
- @subpage arm-cm_dpp_nucleo-h743zi <a class="preview board" href="bd_NUCLEO-H743ZI.jpg" title="STM32 NUCLEO-H743ZI"></a>
- @subpage arm-cm_dpp_nucleo-l552ze <a class="preview board" href="bd_NUCLEO-L552ZE.jpg" title="STM32 NUCLEO-L552ZE"></a>
- @subpage arm-cm_game_efm32-slstk3401a <a class="preview board" href="bd_EFM32-SLSTK3401A.jpg" title="EFM32-SLSTK3401A"></a>
- @subpage arm-cm_low-power <a class="preview board" href="bd_EK-TM4C123GXL.jpg" title="EK-TM4C123GXL"></a>
- @ref tut_low <a class="preview board" href="bd_EK-TM4C123GXL.jpg" title="EK-TM4C123GXL"></a>
*/
/*##########################################################################*/
/*! @page exa_arm-cr ARM Cortex-R
@note
@ifnot LATEX
@remark
You can hover the mouse cursor over the <span class="board"></span>&nbsp;&nbsp; icon in the list below to see the picture of the board.
@endif
- @subpage arm-cr_blinky_launchxl2-tms57012 <a class="preview board" href="bd_LAUNCHXL2-TMS57012.jpg" title="LAUNCHXL2-TMS57012"></a>
- @subpage arm-cr_dpp_launchxl2-tms57012 <a class="preview board" href="bd_LAUNCHXL2-TMS57012.jpg" title="LAUNCHXL2-TMS57012"></a>
*/
/*##########################################################################*/
/*! @page exa_arm7-9 ARM7/ARM9 ("classic" ARM)
@note
You can hover the mouse cursor over the <span class="board"></span>&nbsp;&nbsp; icon in the list below to see the picture of the board.
- @subpage arm7-9_dpp_at91sam7s-ek <a class="preview board" href="bd_AT91SAM7S-EK.jpg" title="AT91SAM7S-EK"></a>
*/
/*##########################################################################*/
/*! @page exa_msp430 MSP430 ("classic" MSP430 and "extended" MSP430x)
@note
@ifnot LATEX
@remark
You can hover the mouse cursor over the <span class="board"></span>&nbsp;&nbsp; icon in the list below to see the picture of the board.
@endif
- @subpage msp430_blinky_msp-exp430f5529lp <a class="preview board" href="bd_MSP-EXP430F5529LP.jpg" title="MSP-EXP430F5529LP"></a>
@ -130,13 +131,11 @@ You can hover the mouse cursor over the <span class="board"></span>&nbsp;&nbsp;
/*##########################################################################*/
/*! @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
This example implements the @ref blinky "Blinky sample application" on the EK-TM4C123GLX board (ARM Cortex-M4F).
@image html bd_EK-TM4C123GXL.jpg
@image latex bd_EK-TM4C123GXL.jpg width=2.5in
@caption{EK-TM4C123GXL (TivaC LaunchPad)}
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:
@ -180,25 +179,30 @@ The Blinky example is located in the directory <span class="img folder">qpc/exam
@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)
@image html bd_EK-TM4C123GXL.jpg
@image latex bd_EK-TM4C123GXL.jpg width=2.5in
@caption{EK-TM4C123GXL (TivaC LaunchPad)}
@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
@image html blinky_win32.png
@image latex blinky_win32.png width=4.5in
@caption{Blinky emulation running in a Windows console}
@next{arm-cm_blinky_efm32-slstk3401a}
@ifnot LATEX
@nav_next{arm-cm_blinky_efm32-slstk3401a}
@endif
*/
/*##########################################################################*/
/*! @page arm-cm_blinky_efm32-slstk3401a Blinky on EFM32-SLSTK3401A
@tableofcontents
This example implements the @ref blinky "Blinky sample application" on the EFM32-SLSTK3401A board (ARM Cortex-M4F).
<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
@image html bd_EFM32-SLSTK3401A.jpg
@image latex bd_EFM32-SLSTK3401A.jpg width=4.5in
@caption{EFM32-SLSTK3401A (Pearl-Gecko)}
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:
@ -232,7 +236,6 @@ The Blinky example is located in the directory <span class="img folder">qpc/exam
@endcode
@section arm-cm_blinky_efm32-slstk3401a_feat Features Demonstrated
- cooperative QV kernel
+ with ARM-KEIL toolchain
@ -253,19 +256,22 @@ Once programmed into the board, the example blinks the on-board LED about once a
@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
@image html blinky_win32.png
@image latex blinky_win32.png width=4.5in
@caption{Blinky emulation running in a Windows console}
@next{arm-cm_dpp_ek-tm4c123gxl}
@ifnot LATEX
@nav_next{arm-cm_dpp_ek-tm4c123gxl}
@endif
*/
/*##########################################################################*/
/*! @page arm-cm_dpp_ek-tm4c123gxl DPP on EK-TM4C123GXL
@tableofcontents
This example implements the @ref dpp "Dining Philosophers Problem" sample application on the EK-TM4C123GLX board (ARM Cortex-M4F).
<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
@image html bd_EK-TM4C123GXL.jpg
@image latex bd_EK-TM4C123GXL.jpg width=2.5in
@caption{EK-TM4C123GXL (TivaC LaunchPad)}
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:
@ -357,14 +363,14 @@ The application also demonstrates <a href="https://www.state-machine.com/qtools/
/*##########################################################################*/
/*! @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
@image html bd_EFM32-SLSTK3401A.jpg
@image latex bd_EFM32-SLSTK3401A.jpg width=4.5in
@caption{EFM32-SLSTK3401A (Pearl-Gecko)}
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:
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 srs_qv "cooperative QV kernel", the @ref srs_qk "preemptive QK kernel", and the @ref srs_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{c}
qpc/ // QP/C installation directory
@ -432,7 +438,6 @@ The DPP example is located in the directory <span class="img folder">qpc/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://www.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.
@ -440,27 +445,33 @@ The application also demonstrates <a href="https://www.state-machine.com/qtools/
/*##########################################################################*/
/*! @page arm-cm_dpp_mbed-lpc1768 DPP on mbed-LPC1768
@image html bd_mbed-LPC1768.jpg mbed-LPC1768 board
@image html bd_mbed-LPC1768.jpg
@image latex bd_mbed-LPC1768.jpg width=2.5in
@caption{mbed-LPC1768}
Dining Philosophers Problem (DPP) example for NXP LPC1768 MCU (Cortex-M3) with GNU-ARM toolchain.
@image html mbed-LPC1768_button.jpg Adding External Button to mbed-LPC1768
@n
@n
@image html under_construction.jpg
@image html mbed-LPC1768_button.jpg
@image latex mbed-LPC1768_button.jpg width=3.0in
@captionAdding External Button to mbed-LPC1768{}
@image html under-constr.png
@image latex under-constr.png width=1in
*/
/*##########################################################################*/
/*! @page arm-cm_dpp_nucleo-l053r8 DPP on STM32 NUCLEO-L053R8
@image html bd_NUCLEO-L053R8.jpg NUCLEO-L053R8 board
@image html bd_NUCLEO-L053R8.jpg
@image latex bd_NUCLEO-L053R8.jpg width=2.5in
@caption{NUCLEO-L053R8}
@ref dpp "Dining Philosophers Problem (DPP)" example for STM32 NUCLEO-L053R8 MCU (Cortex-M0+).
Demonstrated built-in kernels:
- cooperative @ref qv with ARM-Clang, ARM-Keil, GNU-ARM (Makefile and Atollic TRUEstudio), and IAR-ARM toolchains
- preemptive, run-to-completion @ref qk with ARM-Clang, ARM-Keil, GNU-ARM, and IAR-ARM toolchains
- dual-mode (run-to-completion/blocking) @ref qxk with ARM-Clang, ARM-Keil, GNU-ARM, and IAR-ARM toolchains
- cooperative @ref srs_qv with ARM-Clang, ARM-Keil, GNU-ARM (Makefile and Atollic TRUEstudio), and IAR-ARM toolchains
- preemptive, run-to-completion @ref srs_qk with ARM-Clang, ARM-Keil, GNU-ARM, and IAR-ARM toolchains
- dual-mode (run-to-completion/blocking) @ref srs_qxk with ARM-Clang, ARM-Keil, GNU-ARM, and IAR-ARM toolchains
Features:
@ -472,13 +483,15 @@ Features:
/*##########################################################################*/
/*! @page arm-cm_dpp_nucleo-l152re DPP on STM32 NUCLEO-L152RE
@image html bd_NUCLEO-L152RE.jpg NUCLEO-L152RE board
@image html bd_NUCLEO-L152RE.jpg
@image latex bd_NUCLEO-L152RE.jpg width=2.4in
@caption{NUCLEO-L152RE}
@ref dpp "Dining Philosophers Problem (DPP)" example for STM32 NUCLEO-L152RE MCU (Cortex-M3).
Demonstrated built-in kernels:
- cooperative @ref qv with ARM-Clang, ARM-Keil, GNU-ARM, and IAR-ARM toolchains
- preemptive, run-to-completion @ref qk with ARM-Clang, ARM-Keil, GNU-ARM, and IAR-ARM toolchains
- cooperative @ref srs_qv with ARM-Clang, ARM-Keil, GNU-ARM, and IAR-ARM toolchains
- preemptive, run-to-completion @ref srs_qk with ARM-Clang, ARM-Keil, GNU-ARM, and IAR-ARM toolchains
Features:
@ -492,12 +505,14 @@ Features:
The @ref dpp "DPP example" for STM32F4-Discovery board is located directory <span class="img folder">examples/arm-cm/dpp_stm32f4-discovery</span>.
![STM32F4-Discovery board](bd_STM32F4-Disco.jpg)
@image html bd_STM32F4-Disco.jpg
@image latex bd_STM32F4-Disco.jpg width=2.8in
@caption{STM32F4-Discovery}
Demonstrated built-in kernels:
- cooperative @ref qv with ARM-Keil, GNU-ARM, and IAR-ARM toolchains
- preemptive, run-to-completion @ref qk with ARM-Keil, GNU-ARM, and IAR-ARM toolchains
- dual-mode (run-to-completion/blocking) @ref qxk with ARM-Keil, GNU-ARM, and IAR-ARM toolchains
- cooperative @ref srs_qv with ARM-Keil, GNU-ARM, and IAR-ARM toolchains
- preemptive, run-to-completion @ref srs_qk with ARM-Keil, GNU-ARM, and IAR-ARM toolchains
- dual-mode (run-to-completion/blocking) @ref srs_qxk with ARM-Keil, GNU-ARM, and IAR-ARM toolchains
Features:
@ -522,7 +537,9 @@ VDD | VCC
GND | GND
</center>
![STM32F4-Discovery board connected to RS232 level shifter](bd_STM32F4-Disco_RS232.jpg)
@image html bd_STM32F4-Disco_RS232.jpg
@image latex bd_STM32F4-Disco_RS232.jpg width=3.5in
@caption{STM32F4-Discovery board connected to RS232 level shifter}
The output is generated at 115200 baud rate.
@ -534,20 +551,24 @@ qspy -cCOM1
The actual COM port number might be different on your Windows machine. Please check the Device Manager to find the COM port number.
@next{arm-cm_dpp_nucleo-l552ze}
@ifnot LATEX
@nav_next{arm-cm_dpp_nucleo-l552ze}
@endif
*/
/*##########################################################################*/
/*! @page arm-cm_dpp_nucleo-h743zi DPP on STM32 NUCLEO-H743ZI
![STM32 NUCLEO-H743ZI](bd_NUCLEO-H743ZI.jpg)
@image html bd_NUCLEO-H743ZI.jpg
@image latex bd_NUCLEO-H743ZI.jpg width=4.5in
@caption{NUCLEO-H743ZI}
@ref dpp "Dining Philosophers Problem (DPP)" example for STM32 NUCLEO-H743ZI MCU (Cortex-M7).
Demonstrated built-in kernels:
- cooperative @ref qv with ARM-Clang, ARM-Keil, GNU-ARM (Makefile and Atollic TRUEstudio), and IAR-ARM toolchains
- preemptive, run-to-completion @ref qk with ARM-Clang, ARM-Keil, GNU-ARM, and IAR-ARM toolchains
- dual-mode (run-to-completion/blocking) @ref qxk with ARM-Clang, ARM-Keil, GNU-ARM, and IAR-ARM toolchains
- cooperative @ref srs_qv with ARM-Clang, ARM-Keil, GNU-ARM (Makefile and Atollic TRUEstudio), and IAR-ARM toolchains
- preemptive, run-to-completion @ref srs_qk with ARM-Clang, ARM-Keil, GNU-ARM, and IAR-ARM toolchains
- dual-mode (run-to-completion/blocking) @ref srs_qxk with ARM-Clang, ARM-Keil, GNU-ARM, and IAR-ARM toolchains
Features:
- multiple active objects, including 5 instances of the same AO class (Philo)
@ -558,16 +579,18 @@ Features:
*/
/*##########################################################################*/
/*! @page arm-cm_dpp_nucleo-l552ze DPP on STM32 STM32 NUCLEO-L552ZE Q
/*! @page arm-cm_dpp_nucleo-l552ze DPP on STM32 NUCLEO-L552ZE Q
![STM32 NUCLEO-L552ZE Q](bd_NUCLEO-L552ZE.jpg)
@image html bd_NUCLEO-L552ZE.jpg
@image latex bd_NUCLEO-L552ZE.jpg width=3.5in
@caption{STM32 NUCLEO-L552ZE Q}
@ref dpp "Dining Philosophers Problem (DPP)" example for STM32 NUCLEO-L552ZE Q (Cortex-M33).
Demonstrated built-in kernels:
- cooperative @ref qv with ARM-Clang, ARM-Keil, GNU-ARM (Makefile and Atollic TRUEstudio), and IAR-ARM toolchains
- preemptive, run-to-completion @ref qk with ARM-Clang, ARM-Keil, GNU-ARM, and IAR-ARM toolchains
- dual-mode (run-to-completion/blocking) @ref qxk with ARM-Clang, ARM-Keil, GNU-ARM, and IAR-ARM toolchains
- cooperative @ref srs_qv with ARM-Clang, ARM-Keil, GNU-ARM (Makefile and Atollic TRUEstudio), and IAR-ARM toolchains
- preemptive, run-to-completion @ref srs_qk with ARM-Clang, ARM-Keil, GNU-ARM, and IAR-ARM toolchains
- dual-mode (run-to-completion/blocking) @ref srs_qxk with ARM-Clang, ARM-Keil, GNU-ARM, and IAR-ARM toolchains
Features:
- multiple active objects, including 5 instances of the same AO class (Philo)
@ -580,48 +603,50 @@ Features:
/*##########################################################################*/
/*! @page arm-cm_game_efm32-slstk3401a "Fly 'n' Shoot" Game on EFM32-SLSTK3401A
@image html bd_EFM32-SLSTK3401A.jpg EFM32-SLSTK3401A board
@image html bd_EFM32-SLSTK3401A.jpg
@image latex bd_EFM32-SLSTK3401A.jpg width=4.5in
@caption{EFM32-SLSTK3401A (Pearl-Gecko)}
"Fly 'n' Shoot" game example for Silicon Labs Pearl Gecko MCU (Cortex-M4F), ARM (MDK-ARM), GNU-ARM, IAR EWARM toolchains.
@image html game_win32.jpg Game emulation running in Windows GUI
@n
@n
@image html under_construction.jpg
@image html qwin_ani.gif "Fly 'n' Shoot game running on Windows"
@image latex qwin_static.jpg "Fly 'n' Shoot game running on Windows"
@image html under-constr.png
@image latex under-constr.png width=0.93in
*/
/*##########################################################################*/
/*! @page arm-cr_blinky_launchxl2-tms57012 Blinky on LAUNCHXL2-TMS57012
@image html bd_LAUNCHXL2-TMS57012.jpg LAUNCHXL2-TMS57012
@image html bd_LAUNCHXL2-TMS57012.jpg
@image latex bd_LAUNCHXL2-TMS57012.jpg width=4.0in
@caption{LAUNCHXL2-TMS57012}
@ref blinky "Blinky" example for LAUNCHXL2-TMS57012 MCU (Cortex-R, Hercules) with IAR-ARM and TI toolchains.
@image html under_construction.jpg
@image html under-constr.png
@image latex under-constr.png width=0.93in
*/
/*##########################################################################*/
/*! @page arm-cr_dpp_launchxl2-tms57012 DPP on LAUNCHXL2-TMS57012
@image html bd_LAUNCHXL2-TMS57012.jpg LAUNCHXL2-TMS57012
@image html bd_LAUNCHXL2-TMS57012.jpg
@image latex bd_LAUNCHXL2-TMS57012.jpg width=4.0in
@caption{LAUNCHXL2-TMS57012}
Dining Philosophers Problem (DPP) example for LAUNCHXL2-TMS57012 MCU (Cortex-R, Hercules) with IAR-ARM and TI toolchains.
@image html under_construction.jpg
@image html under-constr.png
@image latex under-constr.png width=0.93in
*/
/*##########################################################################*/
/*! @page arm7-9_dpp_at91sam7s-ek DPP on AT91SAM7S-EK
@image html bd_AT91SAM7S-EK.jpg AT91SAM7S-EK board
Dining Philosophers Problem (DPP) example for Atmel AT91SAM7S MCU (ARM7) with GNU-ARM toolchain.
@image html under_construction.jpg
*/
/*##########################################################################*/
/*! @page msp430_blinky_msp-exp430f5529lp Blinky on MSP-EXP430F5529LP
@image html bd_MSP-EXP430F5529LP.jpg MSP-EXP430F5529LP board
@image html bd_MSP-EXP430F5529LP.jpg
@image latex bd_MSP-EXP430F5529LP.jpg width=2.5in
@caption{MSP-EXP430F5529LP}
Simple Blinky example for MSP-EXP430F5529LP with CCS-430 and IAR-430 toolchains. The application blinks the LED1 (P1.0) once per second. The LED2 is rapidly toggled from the idle callback, which results in a "glow" with intensity proportional to the frequency of calling the idle callback.
@ -633,7 +658,9 @@ The simple Blinky application does NOT support the Spy build configuration. Plea
/*##########################################################################*/
/*! @page msp430_dpp_msp-exp430f5529lp DPP on MSP-EXP430F5529LP
@image html bd_MSP-EXP430F5529LP.jpg MSP-EXP430F5529LP board
@image html bd_MSP-EXP430F5529LP.jpg
@image latex bd_MSP-EXP430F5529LP.jpg width=2.5in
@caption{MSP-EXP430F5529LP}
DPP example for MSP-EXP430F5529LP with CCS-430 and IAR-430 toolchains. The application blinks the LED1 (P1.0) when a Philosopher gets a permission to "eat". The LED2 is rapidly toggled from the idle callback, which results in a "glow" with intensity proportional to the frequency of calling the idle callback.
@ -643,8 +670,8 @@ This example demonstrates the QS software tracing output in the Spy build config
The QS trace date requires the following setting of the QSPY host utility
@verbatim
qspy -cCOM_PORT -O2 -F2 -E1 -P1 -B1
qspy -c <COM#> -O2 -F2 -E1 -P1 -B1
@endverbatim
where `COM_PORT` denotes the Virtual COM port, which you can find out in the Device Manager.
where `<COM#>` denotes the Virtual COM port, which you can find out in the Device Manager.
*/

30
doxygen/exa_os.dox
View File

@ -1,7 +1,5 @@
/*! @page exa_os Examples for Workstations (Windows/POSIX)
@tableofcontents
<p>The examples in the <span class="img folder">qpc/examples/workstation</span> directory are designed for workstations (running Windows, Linux, or MacOS). Currently, the following examples are provided:
</p>
@ -37,11 +35,14 @@ All examples in the <span class="img folder">qpc/examples/workstation</span> dir
On Windows, the **make** utility and the GNU GCC toolchain (**MinGW**) are provided in the [<b>QTools collection</b>](https://www.state-machine.com/qtools), which is available for a separate download. The code can be also built with other tools as well, such as the Microsoft Visual Studio 2013 and newer.
@n
![Blinky example on Windows (QP linked from a library)](blinky_win32.png)
@n
![Blinky example on Linux (QP built from sources)](blinky_posix.png)
@image html blinky_win32.png
@image latex blinky_win32.png width=4.0in
@caption{Blinky example on Windows}
<br>
@image html blinky_posix.png
@image latex blinky_posix.png width=4.0in
@caption{Blinky example on Linux}
@section exa_os-qv Single-Threaded and Multi-Threaded QP/C Ports
@ -102,7 +103,6 @@ make CONF=rel clean
The object files and the executable is located in the <span class="img folder">build_rel</span> directory.
@subsection exa_os-spy Spy Configuration
This configuration is built with the QP's Q-SPY trace functionality. The QP/Spy output is performed by a TCP/IP socket and requires launching the QSPY host application with the -t option. To build this configuration, type:
@ -125,12 +125,16 @@ The Spy build configuration requires launching the [QSPY host utility](https://w
@remark
Only specific examples support the Spy build configuration. The examples that don't support it, will report an error or will fail the linking stage.
@image html dpp_win.png
@image latex dpp_win.png width=5.0in
@caption{DPP with QSPY example on Windows (QSPY running in a separate command-prompt)}
@n
![DPP with QSPY example on Windows (QSPY running in a separate command-prompt)](dpp_win.png)
@n
![DPP with QSPY example on Linux (QSPY running in a separate terminal)](dpp_posix.png)
<br>
@image html dpp_posix.png
@image latex dpp_posix.png width=6.0in
@caption{DPP with QSPY example on Linux (QSPY running in a separate command-prompt)}
@next{exa_mware}
@ifnot LATEX
@nav_next{exa_mware}
@endif
*/

25
doxygen/exa_qutest.dox
View File

@ -1,7 +1,5 @@
/*! @page exa_qutest Examples for QUTest Unit Testing Harness
@tableofcontents
<p>The examples in the <span class="img folder">qpc/examples/qutest</span> directory demonstrate how to test embedded code with the [<b>QUTest</b>](https://www.state-machine.com/qtools/qutest.html) unit testing harness. Currently, the following examples are provided:
</p>
@ -14,10 +12,8 @@
- <span class="img folder">unity_mock</span> &mdash; Comparison of a advanced testing (mocking) with Unity and QUTest
@section exa_qutest-dir General Code Organization
The projects within the <span class="img folder">examples/qutest</span> directory have the customary structure used for testing. The production code to be tested is located in the <span class="img folder">src</span> sub-directory. The testing code is located in the <span class="img folder">test_...</span> sub-folder(s). The following directory tree illustrates the structure for the `dpp` example:
The projects within the <span class="img folder">examples/qutest</span> directory have the customary structure used for testing. The production code to be tested is located in the <span class="img folder">src</span> sub-directory. The testing code is located in the <span class="img folder">test_~~~</span> sub-folder(s). The following directory tree illustrates the structure for the `dpp` example:
<ul class="tag">
<li><span class="img folder">examples/</span>
@ -88,7 +84,7 @@ The projects within the <span class="img folder">examples/qutest</span> director
</li>
</ul>
</ul>
<li><span class="img folder">.../</span> &mdash; Other QUTest examples...
<li><span class="img folder">~~~/</span> &mdash; Other QUTest examples~~~
</li>
<li><span class="img folder">target_efm32/</span> &mdash; Code for the **embedded target** (EFM32) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <span class="tag">D</span>
</li>
@ -120,9 +116,11 @@ As usual in Test-Driven Development (TDD), the provided <span class="img file_ma
@subsection exa_qutest_host Host Computers
Typically, you start testing on your host computer. Before building/running the code, you need to open a terminal window and launch the [QSPY host application](https://www.state-machine.com/qtools/qspy.html) with the `-t` [command-line option](https://www.state-machine.com/qtools/qspy.html#qspy_command).
Next, you open another terminal window, change directory to the <span class="img folder">test_...</span> folder of interest, and type `make`. This will build the application and run the tests (Python), as shown in the screen shot below:
Next, you open another terminal window, change directory to the <span class="img folder">test_~~~</span> folder of interest, and type `make`. This will build the application and run the tests (Python), as shown in the screen shot below:
![Testing on the host (Python)](qutest_py.png)
@image html qutest_py.png
@image latex qutest_py.png width=6.5in
@caption{Testing on the host (Python)}
@subsection exa_qutest_target Embedded Targets
@ -130,10 +128,13 @@ The QUTest testing system allows you also to easily test the code directly on th
To test the code on an embedded board, you need to connect the board to the host computer and launch the and launch the [QSPY host application](https://www.state-machine.com/qtools/qspy.html) with the `-c COM<n>` [command-line option](https://www.state-machine.com/qtools/qspy.html#qspy_command), where `<n>` is the specific COM port number on your host that the board is using.
Next, you open another terminal window, change directory to the <span class="img folder">test_...</span> folder of interest, and type `make -f make_tm4c123`. This will build the application and run the tests (Python), as shown in the screen shot below:
Next, you open another terminal window, change directory to the <span class="img folder">test_~~~</span> folder of interest, and type `make -f make_tm4c123`. This will build the application and run the tests (Python), as shown in the screen shot below:
![Testing on the TM4C123 embedded target (Python)](qutest_tm4c123_py.png)
@image html qutest_tm4c123_py.png
@image latex qutest_tm4c123_py.png width=6.5in
@caption{Testing on the TM4C123 embedded target (Python)}
@next{exa_os}
@ifnot LATEX
@nav_next{exa_os}
@endif
*/

436
doxygen/exa_rtos.dox
View File

@ -6,12 +6,15 @@ The main purpose of integrating QP/C with conventional RTOSes is to enable you t
- @subpage exa_embos (directory <span class="img folder">examples/embos/</span>)
- @subpage exa_freertos (directory <span class="img folder">examples/freertos/</span>)
- @subpage exa_threadx (directory <span class="img folder">examples/threadx/</span>)
- @subpage exa_ucos-ii (directory <span class="img folder">examples/ucos-ii/</span>)
- @subpage exa_uc-os2 (directory <span class="img folder">examples/uc-os2/</span>)
- @subpage exa_zephyr (directory <span class="img folder">examples/zephyr/</span>)
@note
You do **not** need to use a third-party RTOS just to achieve preemptive multitasking with QP/C. The framework contains a selection of built-in real-time kernels, such as the cooperative @ref qv "QV kernel", the preemptive non-blocking @ref qk "QK kernel", and the preemptive, dual-mode, blocking @ref qxk "QXK kernel". Specifically, the QXK kernel 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.
You do **not** need to use a third-party RTOS just to achieve preemptive multitasking with QP/C. The framework contains a selection of built-in real-time kernels, such as the cooperative @ref srs_qv "QV kernel", the preemptive non-blocking @ref srs_qk "QK kernel", and the preemptive, dual-mode, blocking @ref srs_qxk "QXK kernel". Specifically, the QXK kernel 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.
@next{exa_embos examples}
@ifnot LATEX
@nav_next{exa_embos}
@endif
*/
/*##########################################################################*/
@ -25,14 +28,18 @@ The QP/C examples for SEGGER embOS are as follows:
@note
You can hover the mouse cursor over the <span class="board"></span>&nbsp;&nbsp; icon in the list below to see the picture of the board.
@next{embos_dpp_nucleo-h743zi}
@ifnot LATEX
@nav_next{embos_dpp_nucleo-h743zi}
@endif
*/
/*##########################################################################*/
/*! @page embos_dpp_nucleo-h743zi DPP on NUCLEO-H743ZI
The @ref dpp "DPP example" for embOS on NUCLEO-H743ZI board is located directory <span class="img folder">examples/embos/arm-cm/dpp_nucleo-h743zi</span>.
@image html bd_NUCLEO-H743ZI.jpg NUCLEO-H743ZI
@image html bd_NUCLEO-H743ZI.jpg
@image latex bd_NUCLEO-H743ZI.jpg width=4.5in
@caption{NUCLEO-H743ZI}
@ref dpp "Dining Philosophers Problem (DPP)" example for NUCLEO-H743ZI MCU (Cortex-M7).
@ -65,7 +72,9 @@ qspy -c COM4
The actual COM port number might be different on your Windows machine. Please check the Device Manager to find the COM port number.
@next{exa_freertos examples}
@ifnot LATEX
@nav_next{exa_freertos}
@endif
*/
/*##########################################################################*/
@ -82,12 +91,16 @@ The QP/C examples for FreeRTOS are as follows:
@note
You can hover the mouse cursor over the <span class="board"></span>&nbsp;&nbsp; icon in the list below to see the picture of the board.
@next{exa_os examples}
@ifnot LATEX
@nav_next{exa_os}
@endif
*/
/*##########################################################################*/
/*! @page freertos_dpp_ek-tm4c123gxl DPP on EK-TM4C123GXL
@image html bd_EK-TM4C123GXL.jpg EK-TM4C123GXL board
@image html bd_EK-TM4C123GXL.jpg
@image latex bd_EK-TM4C123GXL.jpg width=2.5in
@caption{EK-TM4C123GXL (TivaC LaunchPad)}
@ref dpp "DPP example" for @ref freertos "FreeRTOS" on Texas Instruments TivaC123GXL MCU (Cortex-M4F) with the following toolchains:
- ARM-Keil
@ -107,12 +120,16 @@ Demonstrated features:
- QP/Spy input over the virtual COM port (bi-directional Spy) (Spy build configuration)
@next{freertos_dpp_stm32f746g-disco examples}
@ifnot LATEX
@nav_next{freertos_dpp_stm32f746g-disco}
@endif
*/
/*##########################################################################*/
/*! @page freertos_dpp_stm32f746g-disco DPP on STM32F746G-Discovery
@image html bd_STM32F746G-Disco.jpg STM32F746G-Discovery
@image html bd_STM32F746G-Disco.jpg
@image latex bd_STM32F746G-Disco.jpg width=4.75in
@caption{STM32F746G-Discovery}
@ref dpp "DPP example" for @ref freertos "FreeRTOS" on STM32F746G-Discovery MCU (Cortex-M7) with the following toolchains:
- ARM-Keil
@ -131,13 +148,16 @@ Demonstrated features:
- QP/Spy output over the virtual COM port (Spy build configuration)
- QP/Spy input over the virtual COM port (bi-directional Spy) (Spy build configuration)
@next{freertos_dpp_nucleo-h743zi}
@ifnot LATEX
@nav_next{freertos_dpp_nucleo-h743zi}
@endif
*/
/*##########################################################################*/
/*! @page freertos_dpp_nucleo-h743zi DPP on NUCLEO-H743ZI
@image html bd_NUCLEO-H743ZI.jpg NUCLEO-H743ZI
@image html bd_NUCLEO-H743ZI.jpg
@image latex bd_NUCLEO-H743ZI.jpg width=4.5in
@caption{NUCLEO-H743ZI}
@ref dpp "Dining Philosophers Problem (DPP)" example for NUCLEO-H743ZI MCU (Cortex-M7).
@ -146,12 +166,16 @@ Features:
- [QP/Spy software tracing](https://www.state-machine.com/qtools/qpspy.html) using the virtual COM-port
- bi-directional [QP/Spy](https://www.state-machine.com/qtools/qs.html#qs_rx) (sending commands to the target)
@next{freertos_start-stop_nucleo-h743zi}
@ifnot LATEX
@nav_next{freertos_start-stop_nucleo-h743zi}
@endif
*/
/*##########################################################################*/
/*! @page freertos_start-stop_nucleo-h743zi Start-Stop on NUCLEO-H743ZI
@image html bd_NUCLEO-H743ZI.jpg NUCLEO-H743ZI
@image html bd_NUCLEO-H743ZI.jpg
@image latex bd_NUCLEO-H743ZI.jpg width=4.5in
@caption{NUCLEO-H743ZI}
Start-Stop example for NUCLEO-H743ZI MCU (Cortex-M7) demonstrates staring and stopping active objects multiple times
during the runtime, as opposed to starting AOs only at the beginning.
@ -164,7 +188,10 @@ The start-stop application consists of two AOs:
- the Worker AO is NOT started at the beginning, but instead it is instantiated and started by the Launcher AO.
![Launcher and Worker state machines](start-stop.png)
@image html start-stop.png
@image latex start-stop.png width=5.0in
@caption{Launcher and Worker state machines}
The actual visible work is performed by the Worker AO, which blinks the yellow LED (LD1) on the NUCLEO-H743ZI board. After blinking the LED five times, the Worker AO publishes turns the blue LED (LD2), publishes the DONE event and stops itself (by calling QP::QActive::stop() on itself).
@ -181,7 +208,7 @@ Because this application is intended for embedded real-time systems, it does not
It is possible to use the standard **new** and **delete** operators with the standard heap, or some customized memory allocation (overloaded new/delete). This goes beyond the scope of this example.
**Supported Toolchains** @n
**Supported Toolchains**<br>
This example contains sub-directories for building it with various toolchains. The following toolchains are supported:
- ARM-Keil MDK
@ -191,7 +218,7 @@ This example contains sub-directories for building it with various toolchains. T
Please refer to the README.txt files in these sub-directories for more information about building and running the examples.
**QP/Spy Support** @n
**QP/Spy Support**<br>
This example demonstrates the [QP/Spy software tracing](https://www.state-machine.com/qtools/qpspy.html) in the **Spy build configuration**. The QP/Spy uses the virtual COM port provided by the NUCLEO-H743ZI board. To see the QP/Spy output, you need to launch the qspy host utility, as follows (Windows command prompt):
@verbatim
@ -201,7 +228,7 @@ qspy -u -c COM4
where COM4 is the particular virtual serial port registered by your NUCLEO board. You need to adjust the COM port number for your machine.
**Programming the NUCLEO Board** @n
**Programming the NUCLEO Board**<br>
The NUCLEO boards appear as a USB-flash drive in the file system. Programming of the board is done by simply copying the binary into
thy flash drive letter.
@ -218,7 +245,9 @@ copy dbg\start-stop.bin E:
- [QP/Spy software tracing](https://www.state-machine.com/qtools/qpspy.html) using the virtual COM-port
- bi-directional [QP/Spy](https://www.state-machine.com/qtools/qs.html#qs_rx) (sending commands to the target)
@next{exa_threadx examples}
@ifnot LATEX
@nav_next{exa_threadx}
@endif
*/
/*##########################################################################*/
@ -232,12 +261,16 @@ The QP/C examples for ThreadX (Express Logic) are as follows:
@note
You can hover the mouse cursor over the <span class="board"></span>&nbsp;&nbsp; icon in the list below to see the picture of the board.
@next{exa_ucos-ii examples}
@ifnot LATEX
@nav_next{exa_uc-os2}
@endif
*/
/*##########################################################################*/
/*! @page threadx_dpp_ek-tm4c123gxl DPP on EK-TM4C123GXL
@image html bd_EK-TM4C123GXL.jpg "EK-TM4C123GXL (TivaC LaunchPad) board"
@image html bd_EK-TM4C123GXL.jpg
@image latex bd_EK-TM4C123GXL.jpg width=2.5in
@caption{EK-TM4C123GXL (TivaC LaunchPad)}
@ref dpp "DPP example" for ThreadX on Texas Instruments TivaC123GXL MCU (Cortex-M4F) with the following toolchain:
- IAR-ARM
@ -247,22 +280,24 @@ Demonstrated features:
- QP/Spy output over the virtual COM port (Spy build configuration)
- QP/Spy input over the virtual COM port (bi-directional Spy) (Spy build configuration)
@next{threadx_dpp_stm32f429-discovery examples}
@ifnot LATEX
@nav_next{threadx_dpp_stm32f429-discovery}
@endif
*/
/*##########################################################################*/
/*! @page threadx_dpp_stm32f429-discovery DPP on STM32F4-Discovery
The @ref dpp "DPP example" for ThreadX on STM32F4-Discovery board is located directory <span class="img folder">examples/threadx/arm-cm/dpp_stm32f429-discovery</span>.
@image html bd_STM32F4-Discovery.jpg "STM32F4-Discovery board"
@image html bd_STM32F4-Disco.jpg
@image latex bd_STM32F4-Disco.jpg width=2.8in
@caption{STM32F4-Discovery}
The sub-directory <span class="img folder">iar</span> contains the workspace and project file that you can open in IAR EWARM IDE.
After you load the DPP example into the STM32F4-Discovery board, the application should start blinking the 4 on-board LEDs. You can press the User button (blue) to PAUSE the philosophers for as long as the button is depressed. The philosophers resume dining when you release the User button. (In the PAUSED state the Table active object stops granting permissions to eat, so eventually all philosophers end in the "hungry" state.)
@section threadx_dpp_stm32f429-discovery_qs QS Software Tracing
The DPP example for ThreadX on STM32F4-Discovery board provides the "Spy" build configuration, which outputs the QS (Quantum Spy) software tracing data through USART2. To get the data out of the board, you need to connect the TTL/RS232 converter as follows:
@ -276,7 +311,9 @@ VDD | VCC
GND | GND
</center>
@image html bd_STM32F4-Discovery_RS232.jpg STM32F4-Discovery board connected to RS232 level shifter
@image html bd_STM32F4-Disco.jpg
@image latex bd_STM32F4-Disco.jpg width=2.8in
@caption{STM32F4-Discovery}
The output is generated at 115200 baud rate.
@ -288,43 +325,360 @@ qspy -cCOM1
The actual COM port number might be different on your Windows machine. Please check the Device Manager to find the COM port number.
@next{exa_ucos-ii examples}
@ifnot LATEX
@nav_next{exa_uc-os2}
@endif
*/
/*##########################################################################*/
/*! @page exa_ucos-ii uC/OS-II
/*! @page exa_uc-os2 uC-OS2
The QP/C examples for uC/OS-II are as follows:
The QP/C examples for uC-OS2 are as follows:
- ARM Cortex-M
- @subpage ucos-ii_dpp_ek-tm4c123gxl (Cortex-M4F) <a class="preview board" href="bd_EK-TM4C123GXL.jpg" title="EK-TM4C123GXL"></a><br>(ARM-CLANG, GNU-ARM and IAR EWARM toolsets)
- @subpage ucos-ii_dpp_nucleo-l053r8 (Cortex-M0+) <a class="preview board" href="bd_NUCLEO-L053R8.jpg" title="NUCLEO-L053R8"></a><br>(ARM-CLANG, GNU-ARM, and IAR EWARM toolsets)
- @subpage uc-os2_dpp_ek-tm4c123gxl (Cortex-M4F) <a class="preview board" href="bd_EK-TM4C123GXL.jpg" title="EK-TM4C123GXL"></a><br>(ARM-CLANG, GNU-ARM and IAR EWARM toolsets)
- @subpage uc-os2_dpp_nucleo-l053r8 (Cortex-M0+) <a class="preview board" href="bd_NUCLEO-L053R8.jpg" title="NUCLEO-L053R8"></a><br>(ARM-CLANG, GNU-ARM, and IAR EWARM toolsets)
@note
You can hover the mouse cursor over the <span class="board"></span>&nbsp;&nbsp; icon in the list below to see the picture of the board.
@next{exa_os examples}
@ifnot LATEX
@nav_next{exa_os}
@endif
*/
/*##########################################################################*/
/*! @page ucos-ii_dpp_ek-tm4c123gxl DPP on EK-TM4C123GXL
/*! @page uc-os2_dpp_ek-tm4c123gxl DPP on EK-TM4C123GXL
@image html bd_EK-TM4C123GXL.jpg "EK-TM4C123GXL board"
@image html bd_EK-TM4C123GXL.jpg
@image latex bd_EK-TM4C123GXL.jpg width=2.5in
@caption{EK-TM4C123GXL (TivaC LaunchPad)}
DPP example for Texas Instruments TivaC123GXL MCU (Cortex-M4F) and ARM-CLANG, GNU-ARM and IAR EWARM toolsets.
@image html under_construction.jpg
@image html under-constr.png
@image latex under-constr.png width=1in
@next{ucos-ii_dpp_nucleo-l053r8 examples}
@ifnot LATEX
@nav_next{uc-os2_dpp_nucleo-l053r8}
@endif
*/
/*##########################################################################*/
/*! @page ucos-ii_dpp_nucleo-l053r8 DPP on STM32-NUCLEO-L053R8
/*! @page uc-os2_dpp_nucleo-l053r8 DPP on STM32-NUCLEO-L053R8
@image html bd_NUCLEO-L053R8.jpg "STM32-NUCLEO-L053R8 board"
@image html bd_NUCLEO-L053R8.jpg
@image latex bd_NUCLEO-L053R8.jpg width=2.5in
@caption{NUCLEO-L053R8}
DPP example for STM32 L053R8 MCU (Cortex-M0+) and ARM-CLANG, GNU-ARM and IAR EWARM toolsets.
@image html under_construction.jpg
@image html under-constr.png
@image latex under-constr.png width=1in
@next{exa_os examples}
@ifnot LATEX
@nav_next{exa_zephyr}
@endif
*/
/*##########################################################################*/
/*! @page exa_zephyr Zephyr
The QP/C examples for Zephyr are as follows:
- @subpage zephyr_blinky
- @subpage zephyr_dpp
@ifnot LATEX
@nav_next{zephyr_blinky}
@endif
*/
/*##########################################################################*/
/*! @page zephyr_blinky Blinky
The "Blinky" example blinks an on-board LED once per second. The blinking is done by an Active Object (Blinky) with a state machine. The example directory contains the following files:
@verbatim
<qpc>/examples/zephyr/blinky
|
+-src/ - project sources
| |
| +-bsp.h
| +-bsp.c
| +-blinky.h
| +-blinky.c
| +-main.c
|
+-CMakeLists.txt - project files
+-prj.conf - project config
+-README.md
@endverbatim
@section zephyr_blinky-build Building and Running
- Linux:
@verbatim
[1] cd <qpc>/examples/zephyr/blinky
[2] source ~/zephyrproject/zephyr/zephyr-env.sh
[3] west build -b <board>
[3a] west build -b nucleo_h743zi
[3b] west build -b nucleo_l053r8
~~~
[4] west flush
@endverbatim
`[1]` Open a terminal in the Blinky example directory.<br>
`[2]` If Zephyr project is not in your path, you might need to source the `zephyr-env.sh` shell script.<br>
`[3]` build the example project, where `<board>` is any of the boards supported by Zepyr. The example has been tested with the following boards:<br>
`[3a]` nucleo_h743zi (ARM Cortex-M7)<br>
`[3b]` nucleo_l053r8 (ARM Cortex-M0+)<br>
`[4]` flash the board
@remark
The example has been tested with the following boards:
@image html bd_NUCLEO-L053R8.jpg
@image latex bd_NUCLEO-L053R8.jpg width=2.5in
@caption{NUCLEO-L053R8}
<br>
@image html bd_NUCLEO-H743ZI.jpg
@image latex bd_NUCLEO-H743ZI.jpg width=4.5in
@caption{NUCLEO-H743ZI}
@note
The example should also work with most boards supported by Zephyr.
@section zephyr_blinky-output Sample Output
Once flashed to the board, the application also produces ASCII output to the serial terminal (if supported by the board):
@verbatim
*** Booting Zephyr OS build v2.6.0-rc2-88-g3d39f72a88b3 ***
BSP_ledOff
QF_onStartup
BSP_ledOn
BSP_ledOff
BSP_ledOn
BSP_ledOff
@endverbatim
@section zephyr_blinky-limits Limitations
The simple Blinky example does not support the QS software tracing.
@ifnot LATEX
@nav_next{zephyr_dpp}
@endif
*/
/*##########################################################################*/
/*! @page zephyr_dpp DPP
DPP example with multiple active objects.
@verbatim
<qpc>/examples/zephyr/dpp
|
+-src/ - project sources
| |
| +-bsp.h
| +-bsp.c
| +-dpp.h
| +-philo.c
| +-table.c
| +-main.c
|
+-CMakeLists.txt - project files
+-prj.conf - project config
+-README.md
@endverbatim
@section zephyr_dpp-build Building and Running
- Linux:
@verbatim
[1] cd <qpc>/examples/zephyr/dpp
[2] source ~/zephyrproject/zephyr/zephyr-env.sh
[3] west build -b <board>
[3a] west build -b nucleo_h743zi
[3b] west build -b nucleo_l053r8
~~~
[4] west flush
@endverbatim
`[1]` Open a terminal in the DPP example directory.<br>
`[2]` If Zephyr project is not in your path, you might need to source the `zephyr-env.sh` shell script.<br>
`[3]` build the example project, where `<board>` is any of the boards supported by Zepyr. The example has been tested with the following boards:<br>
`[3a]` nucleo_h743zi (ARM Cortex-M7)<br>
`[3b]` nucleo_l053r8 (ARM Cortex-M0+)<br>
`[4]` flash the board
@remark
The example has been tested with the following boards:
@image html bd_NUCLEO-L053R8.jpg
@image latex bd_NUCLEO-L053R8.jpg width=2.5in
@caption{NUCLEO-L053R8}
<br>
@image html bd_NUCLEO-H743ZI.jpg
@image latex bd_NUCLEO-H743ZI.jpg width=4.5in
@caption{NUCLEO-H743ZI}
@note
The example should also work with most boards supported by Zephyr.
@section zephyr_dpp-output Sample Output
Once flashed to the board, the application also produces ASCII output to the serial terminal (if supported by the board):
@verbatim
*** Booting Zephyr OS build v2.6.0-rc2-88-g3d39f72a88b3 ***
Philo[4]->thinking
Philo[3]->eating
Philo[1]->thinking
Philo[0]->eating
Philo[4]->hungry
Philo[3]->thinking
Philo[2]->eating
Philo[1]->hungry
Philo[0]->thinking
Philo[4]->eating
Philo[3]->hungry
Philo[0]->hungry
Philo[4]->thinking
Philo[0]->eating
Philo[2]->thinking
Philo[3]->eating
Philo[4]->hungry
Philo[2]->hungry
Philo[3]->thinking
Philo[2]->eating
Philo[0]->thinking
@endverbatim
@section zephyr_dpp-qpspy Using the QP/SPY Software Tracing
The @ref zephyr "QP/C Zephyr port" supports the
[QSPY Software Tracing](https://www.state-machine.com/qtools/qpspy.html)
option and will add the appropriate macros and files to build the "QSPY"
configuration.
If you wish to enable "QSPY" you can provide the option "QSPY"
in the command-line for the build. For example:
@verbatim
west build -b nucleo_h743zi -- -DQSPY=ON
@endverbatim
@note
The QP/Spy software tracing uses the Zephyr's console UART. This means that the Zephyr `printk()` facility cannot be used while QP/Spy is configured.
If yo have built the example with QP/Spy, you might want to watch the QP/Spy output.
@section zephyr_dpp-qspy The QSPY Host Utility
To receive the QP/Spy software tracing output you need to run a special [qspy host application](https://www.state-machine.com/qtools/qspy.html).
@note
You might need to build the `qspy` host utility on your Linux machine. The QSPY utility is available in
[QTools collection](https://github.com/QuantumLeaps/qtools/tree/master/qspy).
To launch the `qspy` host utility, open a separate terminal and run
@verbatim
qspy -c <serial-port>
```
specific example:
```
qspy -c /dev/ttyACM0
@endverbatim
@subsection @section zephyr_dpp-qs-output QSPY Output Example
After resetting the board, you should see output similar to the following:
@verbatim
########## Trg-RST QP-Ver=701,Build=220810_150847
Obj-Dict 0x20003154->QS_RX
Obj-Dict 0x20000680->AO_Table
Obj-Dict 0x20000180->AO_Philo[0]
Obj-Dict 0x20000280->AO_Philo[1]
Obj-Dict 0x20000380->AO_Philo[2]
Obj-Dict 0x20000480->AO_Philo[3]
Obj-Dict 0x20000580->AO_Philo[4]
Obj-Dict 0x0000A52C->timerID
Usr-Dict 00000100->PHILO_STAT
Usr-Dict 00000101->PAUSED_STAT
Usr-Dict 00000102->COMMAND_STAT
Usr-Dict 00000103->CONTEXT_SW
Obj-Dict 0x20003054->EvtPool1
Obj-Dict 0x20000180->Philo_inst[0]
Obj-Dict 0x2000026C->Philo_inst[0].m_timeEvt
Obj-Dict 0x20000280->Philo_inst[1]
Obj-Dict 0x2000036C->Philo_inst[1].m_timeEvt
Obj-Dict 0x20000380->Philo_inst[2]
Obj-Dict 0x2000046C->Philo_inst[2].m_timeEvt
Obj-Dict 0x20000480->Philo_inst[3]
Obj-Dict 0x2000056C->Philo_inst[3].m_timeEvt
Obj-Dict 0x20000580->Philo_inst[4]
Obj-Dict 0x2000066C->Philo_inst[4].m_timeEvt
Fun-Dict 0x00008929->Philo_initial
Fun-Dict 0x0000890F->Philo_thinking
Fun-Dict 0x00008917->Philo_hungry
Fun-Dict 0x0000891F->Philo_eating
Sig-Dict 00000004,Obj=0x00000000->TIMEOUT_SIG
0000000327 AO-Subsc Obj=Philo_inst[0],Sig=00000005,Obj=0x20000180
0000000327 AO-Subsc Obj=Philo_inst[0],Sig=00000009,Obj=0x20000180
===RTC===> St-Init Obj=Philo_inst[0],State=0x00009B1B->Philo_thinking
===RTC===> St-Entry Obj=Philo_inst[0],State=Philo_thinking
0000000328 Init===> Obj=Philo_inst[0],State=Philo_thinking
0000000334 AO-Subsc Obj=Philo_inst[1],Sig=00000005,Obj=0x20000280
0000000334 AO-Subsc Obj=Philo_inst[1],Sig=00000009,Obj=0x20000280
===RTC===> St-Init Obj=Philo_inst[1],State=0x00009B1B->Philo_thinking
===RTC===> St-Entry Obj=Philo_inst[1],State=Philo_thinking
0000000334 Init===> Obj=Philo_inst[1],State=Philo_thinking
0000000340 AO-Subsc Obj=Philo_inst[2],Sig=00000005,Obj=0x20000380
0000000340 AO-Subsc Obj=Philo_inst[2],Sig=00000009,Obj=0x20000380
===RTC===> St-Init Obj=Philo_inst[2],State=0x00009B1B->Philo_thinking
===RTC===> St-Entry Obj=Philo_inst[2],State=Philo_thinking
0000000340 Init===> Obj=Philo_inst[2],State=Philo_thinking
0000000346 AO-Subsc Obj=Philo_inst[3],Sig=00000005,Obj=0x20000480
0000000346 AO-Subsc Obj=Philo_inst[3],Sig=00000009,Obj=0x20000480
===RTC===> St-Init Obj=Philo_inst[3],State=0x00009B1B->Philo_thinking
===RTC===> St-Entry Obj=Philo_inst[3],State=Philo_thinking
0000000346 Init===> Obj=Philo_inst[3],State=Philo_thinking
0000000352 AO-Subsc Obj=Philo_inst[4],Sig=00000005,Obj=0x20000580
0000000352 AO-Subsc Obj=Philo_inst[4],Sig=00000009,Obj=0x20000580
===RTC===> St-Init Obj=Philo_inst[4],State=0x00009B1B->Philo_thinking
===RTC===> St-Entry Obj=Philo_inst[4],State=Philo_thinking
0000000352 Init===> Obj=Philo_inst[4],State=Philo_thinking
Obj-Dict 0x20000680->Table::inst
Sig-Dict 00000006,Obj=0x00000000->DONE_SIG
Sig-Dict 00000005,Obj=0x00000000->EAT_SIG
Sig-Dict 00000007,Obj=0x00000000->PAUSE_SIG
Sig-Dict 00000008,Obj=0x00000000->SERVE_SIG
Sig-Dict 00000009,Obj=0x00000000->TEST_SIG
Sig-Dict 00000011,Obj=0x20000680->HUNGRY_SIG
0000000370 AO-Subsc Obj=Table::inst,Sig=DONE_SIG
0000000370 AO-Subsc Obj=Table::inst,Sig=PAUSE_SIG
0000000370 AO-Subsc Obj=Table::inst,Sig=SERVE_SIG
0000000371 AO-Subsc Obj=Table::inst,Sig=TEST_SIG
0000000371 PHILO_STAT 0 thinking
0000000371 PHILO_STAT 1 thinking
0000000371 PHILO_STAT 2 thinking
0000000371 PHILO_STAT 3 thinking
@endverbatim
@ifnot LATEX
@nav_next{exa_os}
@endif
*/

175
doxygen/gen/metrics.txt Normal file
View File

@ -0,0 +1,175 @@
@code{.c}
================================================
NLOC CCN token PARAM length location
------------------------------------------------
3 1 16 1 3 QHsm_state@409-411@..\include\qep.h
3 1 15 1 3 QEQueue_getNFree@306-308@..\include\qequeue.h
3 1 15 1 3 QEQueue_getNMin@323-325@..\include\qequeue.h
3 1 21 1 3 QEQueue_isEmpty@342-344@..\include\qequeue.h
5 2 33 1 8 QPSet_setEmpty@245-252@..\include\qf.h
4 3 44 1 7 QPSet_isEmpty@255-261@..\include\qf.h
4 3 44 1 7 QPSet_notEmpty@264-270@..\include\qf.h
8 3 95 2 11 QPSet_hasElement@273-283@..\include\qf.h
11 3 105 2 14 QPSet_insert@286-299@..\include\qf.h
12 3 117 2 15 QPSet_remove@302-316@..\include\qf.h
6 3 56 1 9 QPSet_findMax@319-327@..\include\qf.h
3 1 27 1 3 QActive_getPrio@782-784@..\include\qf.h
6 1 20 2 6 QF_psInit@1412-1417@..\include\qf.h
3 1 20 1 3 QEvt_refCtr_inc_@180-182@..\include\qf_pkg.h
3 1 20 1 3 QEvt_refCtr_dec_@189-191@..\include\qf_pkg.h
14 3 67 1 14 QS_rxPut@863-876@..\include\qs.h
7 1 33 3 7 QHsm_reservedEvt_@90-96@..\src\qf\qep_hsm.c
18 3 101 2 24 QHsm_isIn@103-126@..\src\qf\qep_hsm.c
22 4 125 2 31 QHsm_childState@129-159@..\src\qf\qep_hsm.c
12 2 57 2 14 QHsm_ctor@162-175@..\src\qf\qep_hsm.c
7 1 29 2 7 QHsm_top@178-184@..\src\qf\qep_hsm.c
51 8 360 3 77 QHsm_init_@187-263@..\src\qf\qep_hsm.c
101 15 631 3 154 QHsm_dispatch_@266-419@..\src\qf\qep_hsm.c
3 1 16 1 3 QHsm_getStateHandler_@423-425@..\src\qf\qep_hsm.c
91 15 480 3 132 QHsm_tran_@429-560@..\src\qf\qep_hsm.c
14 3 79 3 17 QHsm_state_entry_@563-579@..\src\qf\qep_hsm.c
20 3 96 3 23 QHsm_state_exit_@582-604@..\src\qf\qep_hsm.c
15 3 69 2 16 QMsm_isInState@81-96@..\src\qf\qep_msm.c
3 1 17 1 3 QMsm_stateObj@99-101@..\src\qf\qep_msm.c
22 4 97 2 29 QMsm_childStateObj@104-132@..\src\qf\qep_msm.c
12 2 60 2 15 QMsm_ctor@135-149@..\src\qf\qep_msm.c
27 4 202 3 45 QMsm_init_@152-196@..\src\qf\qep_msm.c
117 19 728 3 168 QMsm_dispatch_@199-366@..\src\qf\qep_msm.c
3 1 18 1 3 QMsm_getStateHandler_@370-372@..\src\qf\qep_msm.c
55 9 317 3 68 QMsm_execTatbl_@376-443@..\src\qf\qep_msm.c
24 4 132 4 32 QMsm_exitToTranSource_@446-477@..\src\qf\qep_msm.c
45 6 243 3 54 QMsm_enterHistory_@480-533@..\src\qf\qep_msm.c
82 14 431 4 120 QActive_post_@70-189@..\src\qf\qf_actq.c
44 7 266 2 66 QActive_postLIFO_@194-259@..\src\qf\qf_actq.c
34 3 233 1 44 QActive_get_@264-307@..\src\qf\qf_actq.c
10 2 60 1 11 QF_getQueueMin@313-323@..\src\qf\qf_actq.c
16 2 79 2 20 QTicker_ctor@342-361@..\src\qf\qf_actq.c
10 1 45 3 11 QTicker_init_@364-374@..\src\qf\qf_actq.c
17 2 92 3 20 QTicker_dispatch_@377-396@..\src\qf\qf_actq.c
30 2 156 4 37 QTicker_post_@399-435@..\src\qf\qf_actq.c
8 1 30 2 9 QTicker_postLIFO_@438-446@..\src\qf\qf_actq.c
15 1 84 3 17 QActive_defer@65-81@..\src\qf\qf_defer.c
34 3 169 2 54 QActive_recall@86-139@..\src\qf\qf_defer.c
13 3 68 2 15 QActive_flushDeferred@144-158@..\src\qf\qf_defer.c
17 3 116 3 26 QF_poolInit@86-111@..\src\qf\qf_dyn.c
3 1 17 1 3 QF_poolGetMaxBlockSize@114-116@..\src\qf\qf_dyn.c
9 3 59 1 12 QF_getPoolMin@119-130@..\src\qf\qf_dyn.c
39 7 234 3 57 QF_newX_@133-189@..\src\qf\qf_dyn.c
30 4 188 1 46 QF_gc@192-237@..\src\qf\qf_dyn.c
20 2 99 2 28 QF_newRef_@240-267@..\src\qf\qf_dyn.c
11 2 67 1 15 QF_deleteRef_@270-284@..\src\qf\qf_dyn.c
32 5 233 4 50 QMPool_init@67-116@..\src\qf\qf_mem.c
45 5 241 3 72 QMPool_get@119-190@..\src\qf\qf_mem.c
19 3 117 3 26 QMPool_put@193-218@..\src\qf\qf_mem.c
8 1 35 2 13 QActive_psInit@73-85@..\src\qf\qf_ps.c
43 6 232 3 73 QActive_publish_@90-162@..\src\qf\qf_ps.c
18 5 111 2 24 QActive_subscribe@167-190@..\src\qf\qf_ps.c
18 5 111 2 27 QActive_unsubscribe@195-221@..\src\qf\qf_ps.c
19 5 130 1 24 QActive_unsubscribeAll@226-249@..\src\qf\qf_ps.c
10 2 46 2 10 QF_bzero@85-94@..\src\qf\qf_qact.c
16 2 72 2 23 QActive_ctor@101-123@..\src\qf\qf_qact.c
28 10 225 1 47 QActive_register_@128-174@..\src\qf\qf_qact.c
10 3 79 1 15 QActive_unregister_@179-193@..\src\qf\qf_qact.c
24 6 143 1 29 QF_LOG2@201-229@..\src\qf\qf_qact.c
14 2 84 3 14 QEQueue_init@67-80@..\src\qf\qf_qeq.c
57 8 301 4 76 QEQueue_post@83-158@..\src\qf\qf_qeq.c
36 5 199 3 46 QEQueue_postLIFO@161-206@..\src\qf\qf_qeq.c
38 4 219 2 48 QEQueue_get@209-256@..\src\qf\qf_qeq.c
16 2 79 2 35 QMActive_ctor@74-108@..\src\qf\qf_qmact.c
15 2 96 4 32 QTimeEvt_ctorX@78-109@..\src\qf\qf_time.c
33 8 225 3 59 QTimeEvt_armX@112-170@..\src\qf\qf_time.c
31 3 173 1 41 QTimeEvt_disarm@173-213@..\src\qf\qf_time.c
36 8 230 2 64 QTimeEvt_rearm@216-279@..\src\qf\qf_time.c
5 1 36 1 5 QTimeEvt_wasDisarmed@282-286@..\src\qf\qf_time.c
7 1 30 1 8 QTimeEvt_currCtr@289-296@..\src\qf\qf_time.c
69 7 380 2 110 QTimeEvt_tick_@299-408@..\src\qf\qf_time.c
14 3 75 1 16 QTimeEvt_noActive@411-426@..\src\qf\qf_time.c
21 2 112 1 31 QK_schedLock@74-104@..\src\qk\qk.c
20 4 118 1 33 QK_schedUnlock@107-139@..\src\qk\qk.c
11 3 101 1 23 QF_init@144-166@..\src\qk\qk.c
3 1 10 1 4 QF_stop@169-172@..\src\qk\qk.c
15 4 61 1 25 QF_run@175-199@..\src\qk\qk.c
25 3 156 7 34 QActive_start_@206-239@..\src\qk\qk.c
19 4 78 1 24 QK_sched_@244-267@..\src\qk\qk.c
65 17 384 1 112 QK_activate_@270-381@..\src\qk\qk.c
7 3 52 1 13 QF_init@73-85@..\src\qv\qv.c
3 1 10 1 4 QF_stop@88-91@..\src\qv\qv.c
39 10 197 1 77 QF_run@94-170@..\src\qv\qv.c
18 1 124 7 25 QActive_start_@177-201@..\src\qv\qv.c
23 3 131 1 34 QXK_schedLock@71-104@..\src\qxk\qxk.c
20 4 118 1 33 QXK_schedUnlock@107-139@..\src\qxk\qxk.c
11 3 101 1 23 QF_init@144-166@..\src\qxk\qxk.c
3 1 10 1 4 QF_stop@169-172@..\src\qxk\qxk.c
18 4 92 1 30 QF_run@175-204@..\src\qxk\qxk.c
29 5 178 7 42 QActive_start_@211-252@..\src\qxk\qxk.c
42 8 220 1 53 QXK_sched_@260-312@..\src\qxk\qxk.c
59 16 383 1 98 QXK_activate_@315-412@..\src\qxk\qxk.c
12 2 72 1 18 QXK_current@415-432@..\src\qxk\qxk.c
23 7 132 1 34 QXK_contextSw@436-469@..\src\qxk\qxk.c
13 2 104 1 23 QXK_threadExit_@476-498@..\src\qxk\qxk.c
10 2 64 2 13 QXMutex_init@74-86@..\src\qxk\qxk_mutex.c
81 11 724 2 138 QXMutex_lock@89-226@..\src\qxk\qxk_mutex.c
59 9 502 1 97 QXMutex_tryLock@229-325@..\src\qxk\qxk_mutex.c
78 12 670 1 135 QXMutex_unlock@328-462@..\src\qxk\qxk_mutex.c
9 1 51 3 11 QXSemaphore_init@73-83@..\src\qxk\qxk_sema.c
57 7 389 2 84 QXSemaphore_wait@86-169@..\src\qxk\qxk_sema.c
28 3 139 1 39 QXSemaphore_tryWait@172-210@..\src\qxk\qxk_sema.c
42 7 275 1 66 QXSemaphore_signal@213-278@..\src\qxk\qxk_sema.c
21 2 113 3 26 QXThread_ctor@74-99@..\src\qxk\qxk_xthr.c
21 4 195 1 38 QXThread_delay@102-139@..\src\qxk\qxk_xthr.c
14 2 68 1 16 QXThread_delayCancel@142-157@..\src\qxk\qxk_xthr.c
58 7 493 1 85 QXThread_queueGet@160-244@..\src\qxk\qxk_xthr.c
10 1 39 3 11 QXThread_init_@247-257@..\src\qxk\qxk_xthr.c
10 1 39 3 11 QXThread_dispatch_@260-270@..\src\qxk\qxk_xthr.c
31 7 216 7 52 QXThread_start_@273-324@..\src\qxk\qxk_xthr.c
100 15 527 4 138 QXThread_post_@327-464@..\src\qxk\qxk_xthr.c
8 1 30 2 9 QXThread_postLIFO_@467-475@..\src\qxk\qxk_xthr.c
5 1 49 1 7 QXThread_block_@478-484@..\src\qxk\qxk_xthr.c
8 3 56 1 8 QXThread_unblock_@487-494@..\src\qxk\qxk_xthr.c
20 3 157 3 39 QXThread_teArm_@497-535@..\src\qxk\qxk_xthr.c
11 2 46 1 13 QXThread_teDisarm_@538-550@..\src\qxk\qxk_xthr.c
33 file analyzed.
==============================================================
NLOC Avg.NLOC AvgCCN Avg.token function_cnt file
--------------------------------------------------------------
6 0.0 0.0 0.0 0 ..\include\qassert.h
133 3.0 1.0 16.0 1 ..\include\qep.h
33 3.0 1.0 17.0 3 ..\include\qequeue.h
226 6.6 2.4 60.1 9 ..\include\qf.h
15 3.0 1.0 20.0 2 ..\include\qf_pkg.h
19 0.0 0.0 0.0 0 ..\include\qk.h
25 0.0 0.0 0.0 0 ..\include\qmpool.h
8 0.0 0.0 0.0 0 ..\include\qpc.h
356 14.0 3.0 67.0 1 ..\include\qs.h
3 0.0 0.0 0.0 0 ..\include\qstamp.c
2 0.0 0.0 0.0 0 ..\include\qstamp.h
0 0.0 0.0 0.0 0 ..\include\qs_dummy.h
19 0.0 0.0 0.0 0 ..\include\qs_pkg.h
7 0.0 0.0 0.0 0 ..\include\qv.h
96 0.0 0.0 0.0 0 ..\include\qxk.h
359 31.5 5.1 182.5 11 ..\src\qf\qep_hsm.c
336 32.3 5.3 188.3 10 ..\src\qf\qep_msm.c
2 0.0 0.0 0.0 0 ..\src\qf\qf_act.c
258 27.9 3.8 154.7 9 ..\src\qf\qf_actq.c
69 20.7 2.3 107.0 3 ..\src\qf\qf_defer.c
138 18.4 3.1 111.4 7 ..\src\qf\qf_dyn.c
103 32.0 4.3 197.0 3 ..\src\qf\qf_mem.c
115 21.2 4.4 123.8 5 ..\src\qf\qf_ps.c
96 17.6 4.6 113.0 5 ..\src\qf\qf_qact.c
152 36.2 4.8 200.8 4 ..\src\qf\qf_qeq.c
18 16.0 2.0 79.0 1 ..\src\qf\qf_qmact.c
218 26.2 4.1 155.6 8 ..\src\qf\qf_time.c
187 22.4 4.8 127.5 8 ..\src\qk\qk.c
74 16.8 3.8 95.8 4 ..\src\qv\qv.c
261 23.0 5.0 140.1 11 ..\src\qxk\qxk.c
235 57.0 8.5 490.0 4 ..\src\qxk\qxk_mutex.c
143 34.0 4.5 213.5 4 ..\src\qxk\qxk_sema.c
325 24.4 3.8 156.0 13 ..\src\qxk\qxk_xthr.c
=============================================================================================================
No thresholds exceeded (cyclomatic_complexity > 20 or length > 500 or nloc > 1000000 or parameter_count > 10)
==========================================================================================
Total nloc Avg.NLOC AvgCCN Avg.token Fun Cnt Warning cnt Fun Rt nloc Rt
------------------------------------------------------------------------------------------
4037 24.2 4.2 149.1 126 0 0.00 0.00
@endcode

366
doxygen/gs.dox
View File

@ -1,42 +1,57 @@
/*! @page gs Getting Started
@nav{index,gs_get}
The following sections describe how to get started with QP&trade;/C quickly:
- @subpage gs_get
- @subpage gs_over
- @subpage gs_tut
The YouTube Video <a class="extern" target="_blank" href="https://youtu.be/O7ER6_VqIH0"><strong>Getting Started with QP&trade; Frameworks</strong></a> provides instructions on how to download, install and get started with QP quickly.
The YouTube Video <a class="extern" target="_blank" href="https://youtu.be/O7ER6_VqIH0">Getting Started with QP&trade; Frameworks</a> provides instructions on how to download, install and get started with QP quickly.
[![Video: Getting Started with QP&trade; Real-Time Embedded Framework](gs-video.jpg)](https://youtu.be/O7ER6_VqIH0)
@image html gs-video.jpg
@image latex gs-video.jpg width=4.5in
@caption{Video: Getting Started with QP&trade; Real-Time Embedded Framework}
@note
@htmlonly
<a href="modules.html" title="QP Cert-Pack"><img src="cert-pack.png" style="float:right; margin:0 20px 20px 0;"></img></a>
@endhtmlonly
Information about the QP/C functionality, architecture, design, and other aspects is provided in the [Certification Package](modules.html):
- @ref srs &mdash; QP/C functionality
- @ref sas &mdash; QP/C architecture
- @ref sds &mdash; QP/C design
- @ref misra &mdash; QP/C compliance with MISRA-C
@ifnot LATEX
@nav{index,gs_get}
@endif
*/
/*##########################################################################*/
/*! @page gs_get Downloading &amp; Installing QP&trade;/C
@tableofcontents
@nav{gs,gs_over}
@ifnot LATEX
@nav{gs,gs_tut}
@endif
@section gs_bundle Downloading QP&trade;/C in QP&trade;-Bundle
The most recommended way of obtaining QP&trade;/C&trade; is by downloading the @webref{#Downloads, <b>QP-bundle&trade;</b>}, which includes QP&trade;/C as well as other QP&trade; frameworks and also the @webref{products/qm, QM&trade; modeling tool} and the @webref{products/qtools, QTools&trade; collection}. The main advantage of obtaining QP&trade;/C bundled together like that is that you get all components, tools and examples ready to go.
[![QP-bundle Downloads](qp-bundle.png)](https://www.state-machine.com/#Downloads)
@image html qp-bundle.png
@image latex qp-bundle.png width=1.5in
@caption{QP-bundle Downloads}
@note
<a target="_blank" href="https://github.com/QuantumLeaps/qpc" title="QP&trade;/C on GitHub"><img style="float:right; clear:right;" src="img/github-corner.png"></a>
@htmlonly
<a target="_blank" href="https://github.com/QuantumLeaps/qpc" title="QP&trade;/C on GitHub"><img style="float:right; clear:right;" src="img/logo_github.png"></a>
@endhtmlonly
If you are allergic to installers and GUIs or don't have administrator privileges you can also **download and install QP&trade;/C separately** from the <a class="extern" target="_blank" href="https://github.com/QuantumLeaps/qpc"><b>QP&trade;/C GitHub repository</b></a>, as described in the next section.
@section gs_gh Downloading QP&trade;/C from GitHub
Go to the <a class="extern" href="https://github.com/QuantumLeaps/qpc/releases" target="_blank">QP&trade;/C <strong>release</strong> page on GitHub</a>, and choose the QP&trade;/C version number you wish to download. You should select the latest QP&trade;/C version, unless you have a very specific reason to go with an older release.
Inside the release directory (e.g., `6.9.3`), you need to choose the QP&trade;/C archive for your platform. QM&trade; is available for Windows (`qpc_<ver>-win32.zip`), Linux (`qpc_<ver>-linux64.zip`), and MacOS (`qm_<ver>-macx64.dmg`).
![QP&trade;/C downloads from GitHub](qpc_gh.jpg)
@image html qpc_gh.jpg
@image latex qpc_gh.jpg width=5.0in
@caption{<a class="extern" href="https://github.com/QuantumLeaps/qpc/releases" target="_blank">QP&trade;/C downloads from GitHub</a>}
@section gs_dir QP&trade;/C Installation Folder
The following annotated directory tree lists the top-level directories provided in the standard QP&trade;/C distribution.
<ul class="tag">
@ -56,96 +71,21 @@ The following annotated directory tree lists the top-level directories provided
</ul>
</ul>
@attention
The QP/C GitHub repository does not contain the `3rd_party` folder, which is needed to build the @ref exa "QP&trade;/C Examples". Therefore, it is highly **recommended** to download the latest [QP/C Release](https://github.com/QuantumLeaps/qpc/releases) as opposed to cloning the repo directly.
@remark
The standard QP&trade;/C distribution contains many @ref exa "Example Projects", which are specifically designed to help you learn to use QP&trade;/C and to serve you as starting points for your own projects.
The standard QP&trade;/C distribution contains the `examples` folder with many @ref exa "Example Projects", which are specifically designed to help you learn to use QP&trade;/C and to serve you as starting points for your own projects.
<br>
@nav{gs,gs_over}
*/
/*##########################################################################*/
/*! @page gs_over QP&trade;/C Overview
@nav{gs_get,gs_tut}
@tableofcontents
This section gives a quick, high-level overview of the QP&trade; framework and its context of use. The main purpose is to provide the links to the more detailed information available in this QP&trade;/C Manual.
@section gs_struct General System Structure
The block diagram below illustrates the general system architecture based on the QP&trade;/C framework:
![General system architecture based on QP&trade;/C](qp_comp.jpg)
@note
The following sections describe the system structure from top to bottom because this is the order most relevant for the development of **QP&trade; Applications**.
@section gs_app QP&trade; Application
The **QP&trade; Application** consists of event-driven @webref{active-object, Active Objects}. The application is not a part of QP&trade;, but rather is *derived* from the QP&trade; framework that supplies the @ref api "API" for building the application as well as runtime environment to execute it on an embedded target.
@sa
- @ref srs_app "Application Requirements"
- @ref exa "Application Examples"
@section gs_qep QEP State Machine Processor
The QEP component provides services related to event-driven **State Machines**. This is the most relevant QP&trade; layer for the application developers, because they spend most of their time elaborating the state machines of their Active Objects.
@sa
- @ref srs_evt "Event Requirements"
- @ref srs_sm "State Machine Overview &amp; Requirements"
- @ref sas_sm "State Machine Architecture"
- @ref sds_sm "State Machine Design &amp; Implementation"
@section gs_qf QF Active Object Framework
The QF component provides services related to **Active Objects** like: asynchronous event passing, queuing of events, publish-subscribe, time events, deterministic event pools for mutable events, etc. These services form the core of the QP&trade; framework, which provides the Run-To-Completion (RTC) execution context for the Active Objects and their internal state machines. The application developers often use the Active Object services in the *actions* executed by the state machines.
@sa
- @ref srs_ao "Active Object Overview &amp; Requirements"
- @ref sas_ao "Active Object Architecture"
- @ref sds_ao "Active Object Design &amp; Implementation"
@section gs_kernel Real-Time Kernels/RTOS/GPOS
The QP&trade; framework can run standalone with one of the provided built-in kernels or it can run on top of a traditional, 3rd-party RTOS, or on top of a general-purpose OS.
@subsubsection gs_kernel-builtin Built-in Real-Time Kernels
The QP&trade; framework contains a selection of built-in real-time kernels, such as:
- the cooperative QV kernel (see @ref srs_qv_intro "QV Kernel Theory of Operation"),
- the preemptive non-blocking QK kernel (see @ref srs_qk_intro "QK Kernel Theory of Operation"), and
- the preemptive, dual-mode, blocking QXK kernel (see @ref srs_qxk_intro "QXK Kernel Theory of Operation").
@subsection gs_kernel-rtos 3rd-Party RTOS Kernels
QP&trade; can also work with many 3rd-party RTOSes, such as:
- @ref embos "embOS (SEGGER)"
- @ref freertos "FreeRTOS (AWS)"
- @ref threadx "ThreadX (Microsoft)"
- @ref ucos-ii "uC/OS-II (Silicon Labs)"
@subsection gs_kernel-gpos General-Purpose Operating Systems
Finally, QP&trade; can also work with general-purpose operating systems, such as:
- @ref posix "POSIX (Linux, QNX, VxWorks, Integrity, etc.)"
- @ref win32 "Windows".
@section gs_qs QS Software Tracing
The QS component provides special instrumentation inside QP that can produce detailed information from the execution of the QP Application. This information, produced in live system can be valuable for debugging, fine-tuning and testing of the QP Applications.
@sa
- @ref srs_qs "Software Tracing Overview &amp; Requirements"
- @ref sas_qs "Software Tracing Architecture"
- @ref sds_qs "Software Tracing Design &amp; Implementation"
<br>
@nav{gs_get,gs_tut}
@ifnot LATEX
@nav{gs,gs_tut}
@endif
*/
/*##########################################################################*/
/*! @page gs_tut QP&trade;/C Tutorial
@tableofcontents
@nav{gs_over,tut_blinky}
@ifnot LATEX
@nav{gs_get,tut_blinky}
@endif
This Tutorial describes how to use the QP/C&trade; real-time embedded framework in a series of progressively advancing examples. The first example ("Blinky") uses only one Active Object with a simple non-hierarchical state machine. The following example ("DPP") demonstrates multiple, communicating Active Objects. Finally, the last example ("Fly'n'Shoot" game) demonstrates all features the QP&trade; framework. It is highly recommended to study the simpler examples before the more advanced ones, as the basic information won't be repeated in the later examples.
@ -163,23 +103,27 @@ Keeping this in mind, the provided @ref exa "QP&trade;/C application examples",
Only after convincing yourself that the example project works "as is", you can think about creating your own projects. At this point, the easiest and recommended way is to copy the existing working example project folder (such as the Blinky example) and rename it.
After copying the project folder, you still need to change the name of the project/workspace. The easiest and safest way to do this is to open the project/workspace in the corresponding IDE and use the Save As... option to save the project under a different name. (You can do this also with the @webref{products/qm, QM model file}, which you can open in QM and "Save As" a different model.)
After copying the project folder, you still need to change the name of the project/workspace. The easiest and safest way to do this is to open the project/workspace in the corresponding IDE and use the Save As~~~ option to save the project under a different name. (You can do this also with the @webref{products/qm, QM model file}, which you can open in QM and "Save As" a different model.)
@note
By copying and re-naming an existing, working project, as opposed to creating a new one
from scratch, you inherit the correct compiler and linker options an other project settings, which will help you get started much faster.
<br>
@nav{gs_over,tut_blinky}
@ifnot LATEX
@nav{gs_get,tut_blinky}
@endif
*/
/*##########################################################################*/
/*! @page tut_blinky Simple Blinky Application
@tableofcontents
@ifnot LATEX
@nav{gs_tut,tut_dpp}
@endif
The ultra-simple Blinky example is the embedded systems' equivalent of the venerable <i>"Hello World!"</i> program, that is, the simplest possible working QP&trade; application that does "something". In the case of Blinky, this "something" is blinking an LED at the rate of 1Hz, where an LED turns on and remains on for 0.5 seconds on then turns off and remains off for 0.5 seconds.
![Blinky on EK-TM4C123GLX (TivaC LaunchPad)](blinky_ek-tm4c123gxl.gif)
@image html blinky_ek-tm4c123gxl.gif
@image latex blinky_ek-tm4c123gxl.jpg width=2.0in
@caption{Blinky on EK-TM4C123GLX (TivaC LaunchPad)}
@note
The Blinky example is provided for other supported boards as well, not just TivaC LaunchPad. Please look for examples named <span class="img folder">dpp_<board-name></span> in the @ref exa "qpc/examples/examples" directory (e.g., `qpc/examples/arm-cm/blinky_ek-tm4c123gxl` for the EK-TM4C123GXL board (TivaC LaunchPad)).
@ -196,14 +140,19 @@ The ultra-simple Blinky application, which consists of just one active object n
The details of the Blinky application are describe in the Quantum Leaps Application Note @webref{doc/AN_Getting_Started_with_QP.pdf, Getting Started with QP&trade; Real-Time Embedded Frameworks}.
[![Application Note: Getting Started with QP&trade;](AN-getting_started.jpg)](https://www.state-machine.com/doc/AN_Getting_Started_with_QP.pdf)
@image html AN-getting_started.jpg
@image latex AN-getting_started.jpg width=2.0in
@caption{@webref{doc/AN_Getting_Started_with_QP.pdf, Getting Started with QP&trade; Real-Time Embedded Frameworks}}
@ifnot LATEX
@nav{gs_tut,tut_dpp}
@endif
*/
/*##########################################################################*/
/*! @page tut_dpp Dining Philosophers Problem (DPP)
@tableofcontents
@ifnot LATEX
@nav{tut_blinky,tut_game}
@endif
The Dining Philosophers Problem (DPP) example is an intermediate-level application with *multiple* active objects. It illustrates the following QP&trade; features, such as:
@ -222,22 +171,28 @@ The DPP example is provided for most supported boards as well as in the command-
The Dining Philosophers Problem (DPP) example is described in the @webref{doc/AN_DPP.pdf, Application Note: Dining Philosophers Problem (DPP) Example}.
[![Application Note: Dining Philosophers Problem (DPP) Example](AN_DPP.jpg)](https://www.state-machine.com/doc/AN_Fly-n-Shoot.pdf)
@image html AN_DPP.jpg
@image latex AN_DPP.jpg width=2.0in
@caption{@webref{doc/AN_DPP.pdf, Application Note: Dining Philosophers Problem (DPP) Example}}
@note
There is also a DPP variant that implements the "Philosophers" as passive "Orthogonal Components" of the "Table" active object. That DPP version is located in <span class="img folder">qpc/examples/examples/workstation/dpp-comp/</span>
<br>
@ifnot LATEX
@nav{tut_blinky,tut_game}
@endif
*/
/*##########################################################################*/
/*! @page tut_game "Fly 'n' Shoot" Game
@ifnot LATEX
@nav{tut_dpp,tut_low}
@endif
The "Fly 'n' shoot" game example is a moderately advanced application of a vintage computer game. It requires a LCD screen and push-buttons on the board.
![EFM32 Pearl-Gecko board](bd_EFM32-SLSTK3401A.jpg)
@image html bd_EFM32-SLSTK3401A.jpg
@image latex bd_EFM32-SLSTK3401A.jpg width=4.5in
@caption{EFM32 Pearl-Geckob}
"Fly 'n' shoot" game and illustrates the following QP&trade; features, such as:
@ -249,25 +204,31 @@ The "Fly 'n' shoot" game example is a moderately advanced application of a vint
- publish-subscribe event delivery;
- developing of embedded software on Windows (see also @webref{qtools/qwin.html,QWin&trade; GUI Prototyping Toolkit})
!["Fly 'n' Shoot" game running on Windows](qwin_ani.gif)
@image html qwin_ani.gif "Fly 'n' Shoot game running on Windows"
@image latex qwin_static.jpg "Fly 'n' Shoot game running on Windows" width=6in
The "Fly 'n' Shoot" game example is described in the @webref{doc/AN_Fly-n-Shoot.pdf, Application Note: Fly 'n' Shoot Game Example}.
The "Fly 'n' Shoot" game example is described in the @webref{doc/AN_Fly-n-Shoot.pdf,Application Note: Fly 'n' Shoot Game Example}.
[![Application Note: Fly 'n' Shoot Game Example](AN-game.jpg)](https://www.state-machine.com/doc/AN_Fly-n-Shoot.pdf)
[!["Fly'n'Shoot" game tutorial video](game-video.jpg)](https://youtu.be/h_u92uLssDo)
@image html AN-game.jpg "Application Note: Fly 'n' Shoot Game Example"
@image latex AN-game.jpg "Application Note: Fly 'n' Shoot Game Example" width=2in
<br>
@image html game-video.jpg
@image latex game-video.jpg width=5in
@caption{Fly'n'Shoot game tutorial video}
@ifnot LATEX
@nav{tut_dpp,tut_low}
@endif
*/
/*##########################################################################*/
/*! @page tut_low Low-Power Example
@tableofcontents
@nav{tut_game,srs}
@ifnot LATEX
@nav{tut_game,exa}
@endif
The main principle of low-power design for software is to keep the hardware in the most appropriate low-power sleep mode for as long as possible. Most commonly, the software enters a low-power sleep mode from the **idle callback** (a.k.a. "idle hook"), which is called when the software has nothing left to do and is waiting for an interrupt to deliver more work. The QP/C and QP/C++ Real-Time Embedded Frameworks (RTEFs) support the *idle callback* in all of the built-in real-time kernels, such as the cooperative @ref qv "QV kernel", the preemptive non-blocking @ref qk "QK kernel" and the preemptive blocking @ref qxk "QXK kernel". Also, such an *idle callback* is provided in all 3rd-party traditional RTOS kernels that QP/C/C++ have been @ref ports_rtos "ported to".
The main principle of low-power design for software is to keep the hardware in the most appropriate low-power sleep mode for as long as possible. Most commonly, the software enters a low-power sleep mode from the **idle callback** (a.k.a. "idle hook"), which is called when the software has nothing left to do and is waiting for an interrupt to deliver more work. The QP/C and QP/C++ Real-Time Embedded Frameworks (RTEFs) support the *idle callback* in all of the built-in real-time kernels, such as the cooperative @ref srs_qv "QV kernel", the preemptive non-blocking @ref srs_qk "QK kernel" and the preemptive blocking @ref srs_qxk "QXK kernel". Also, such an *idle callback* is provided in all 3rd-party traditional RTOS kernels that QP/C/C++ have been @ref ports_rtos "ported to".
@remark
Design for low-power is a broad subject that requires a holistic system approach to achieve a really long battery-powered operation. This example covers only certain *software-related* aspects of the problem.
@ -280,8 +241,10 @@ interrupt that occurs at a predetermined rate, typically between 10Hz and 1000Hz
While the system clock tick is very useful, it also has the unfortunate side effect of taking the processor out of a low power state as many as 1000 times per second regardless if real work needs to be done or not. This effect can have a significant negative impact on the power efficiency of the system.
![Additional power dissipation caused by the system clock tick](exa_low-power_tick.gif)
@image html exa_low-power_tick.png
@image latex exa_low-power_tick.png width=6.0in
@caption{Additional power dissipation caused by the system clock tick}
@subsection arm-cm_low_power_tickless The "Tickless Mode"
Some real-time kernels use the low-power optimization called the "tickless mode" (a.k.a. "tick supression" or "dynamic tick"). In this mode, instead of indiscriminately making the clock tick fire with a fixed period, the kernel adjusts the clock ticks *dynamically*, as needed. Specifically, after each clock tick the kernel re-calculates the time for the next clock tick and then sets the clock tick interrupt for the earliest timeout it has to wait for. So for example, if the shortest wait the kernel has to attend to is 300 milliseconds into the future, then the clock interrupt will be set for 300 milliseconds.
@ -299,7 +262,6 @@ The support for multiple static clock tick rates is much *simpler* than the "dyn
Yet the *multiple clock rates* can deliver similar low-power operation for the system, while keeping the QP framework much simpler and easier to certify than "tickless" kernels. The rest of this example explains how to use the multiple static clock rates in QP/C/C++ and shows how to leverage this feature to achieve low-power software design.
@section arm-cm_low_power_app The Low-Power Example Application
The low-power example is located in QP/C and QP/C++ distributions, in the directory with the following structure:
@ -339,8 +301,9 @@ The low-power example is located in QP/C and QP/C++ distributions, in the direct
@note
To focus the discussion, this example uses the **EK-TM4C123GXL** evaluation board (a.k.a. TivaC LaunchPad) with Cortex-M4 MCU. However, the general demonstrated principles apply to most modern microcontrollers.
<br>
![EK-TM4C123GXL evaluation board](bd_EK-TM4C123GXL_pins.jpg)
@image html bd_EK-TM4C123GXL.jpg
@image latex bd_EK-TM4C123GXL.jpg width=2.5in
@caption{EK-TM4C123GXL (TivaC LaunchPad}
@subsection arm-cm_low_power_behave Behavior
The the low-power example illustrates the use of two clock tick rates to toggle the LEDs available on the EK-TM4C123GXL board. After the application code is loaded to the board, the **Green-LED** starts blinking once per two seconds (a second on and a second off), while the **Red-LED** lights up and stays on. If no buttons on the board are pressed, the **Green-LED** stops blinking after 4 times. The **Red-LED** shows the **idle** condition, where the system is in a sleep mode.
@ -373,53 +336,40 @@ The behavior just described is designed for the slow human interaction with the
The following logic analyzer trace shows the behavior of the low-power application at the faster time scale. The explanation section immediately following the tarce explains the most interesting points:
![low-power application after pressing the SW1 button](exa_low-power_sig.png)
@image html exa_low-power_sig.png "low-power application after pressing the SW1 button"
@image latex exa_low-power_sig.png "low-power application after pressing the SW1 button"
<dl class="tag">
<dt>0</dt><dd>
The plot shows the logic-analyzer traces of the following signals (from the top): **SW1** button (active low), **Blinky1** (Blue-LED), **Blinky0** (Green-LED) and **Idle** (Red-LED). The Idle callback turns the **Red-LED** on when the system enters the low-power sleep mode and it turns the **Red-LED** off when the system is active.
</dd>
<dt>1</dt><dd>
At this time the **SW1** button is depressed, which triggers an interrupt that activates both the slow and the fast clock tick rates. The clock tick interrupts trigger toggling of the **Blinky0** (Green-LED) at the slower tick rate-0 and **Blinky1** (Blue-LED) at the faster tick rate-1.
</dd>
<dt>2</dt><dd>
The **Blinky1** (Blue-LED) stops toggling after 13 cycles. At this point also the **Idle** callback turns the **fast tick rate-1** off.
</dd>
<dt>3</dt><dd>
The **Blinky0** (Green-LED) stops toggling after 4 cycles.
</dd>
<dt>4</dt><dd>
The **Idle** callback turns the **slow tick rate-0** off. The system enters the low-power sleep mode without any clock ticks running and remains in this state until the **SW1** button is pressed again.
</dd>
</dl>
<div style="clear:both;"></div>
`[0]` The plot shows the logic-analyzer traces of the following signals (from the top): **SW1** button (active low), **Blinky1** (Blue-LED), **Blinky0** (Green-LED) and **Idle** (Red-LED). The Idle callback turns the **Red-LED** on when the system enters the low-power sleep mode and it turns the **Red-LED** off when the system is active.
@note
`[1]` At this time the **SW1** button is depressed, which triggers an interrupt that activates both the slow and the fast clock tick rates. The clock tick interrupts trigger toggling of the **Blinky0** (Green-LED) at the slower tick rate-0 and **Blinky1** (Blue-LED) at the faster tick rate-1.
`[2]` The **Blinky1** (Blue-LED) stops toggling after 13 cycles. At this point also the **Idle** callback turns the **fast tick rate-1** off.
`[3]` The **Blinky0** (Green-LED) stops toggling after 4 cycles.
`[4]` The **Idle** callback turns the **slow tick rate-0** off. The system enters the low-power sleep mode without any clock ticks running and remains in this state until the **SW1** button is pressed again.
@remark
The **Idle** line (Red-LED) goes down twice as fast as the changes in the state of the **Green-LED** or the **Blue-LED**. This is because the application uses timeouts of **2 clock ticks** for toggling these lines instead of just one clock tick, which then could be slower. This is not quite optimal for the energy dissipation (as the CPU is woken up twice as often as it needs to be), but it illustrates more accurately how the fixed clock rates work as well as the one-tick delay to enter the low-power sleep mode from the idle callback.
@subsection arm-cm_low_power_sm State Machines
The versions of this low-power example for the **QK** and **QV** kernels use two active objects **Blinky0** and **Blinky1**, which toggle the **Green-LED** at the slow tick rate 0, and the **Blue-LED** at the fast tick rate 1, respectively. The state machines of the Blinky0 and Blinky1 active objects are shown below:
![state machines Blinky0 and Blinky1 active objects](exa_low-power_sm.png)
@image html exa_low-power_sm.png
@image latex exa_low-power_sm.png width=4.0in
@caption{state machines Blinky0 and Blinky1 active objects}
<dl class="tag">
<dt>0</dt><dd>
The **Blinky0** state machine, in the entry action to the "active" state, calls `BSP_tickRate0_on()` to turn the tick rate-0 on. This is done *before* arming the time event `me->timeEvt0` that uses the clock rate-0.
</dd>
<dt>1</dt><dd>
Similarly, the **Blinky1** state machine, in the entry action to the "active" state, calls `BSP_tickRate1_on()` to turn the tick rate-1 on. This is done *before* arming the time event `me->timeEvt1` that uses the clock rate-1.
</dd>
</dl>
<div style="clear:both;"></div>
`[0]` The **Blinky0** state machine, in the entry action to the "active" state, calls `BSP_tickRate0_on()` to turn the tick rate-0 on. This is done *before* arming the time event `me->timeEvt0` that uses the clock rate-0.
`[1]` Similarly, the **Blinky1** state machine, in the entry action to the "active" state, calls `BSP_tickRate1_on()` to turn the tick rate-1 on. This is done *before* arming the time event `me->timeEvt1` that uses the clock rate-1.
@subsection arm-cm_low_power_xt Extended Thread (QXK)
The version of this low-power example for the **QXK** kernel uses one active object **Blinky0** (with the state machine shown above), but instead of the Blinky1 active object, the QXK version uses an eXtended thread (::QXThread) called **XBlinky1**, with the code shown below:
@code{c}
@code{.c}
#include "qpc.h"
#include "low_power.h"
#include "bsp.h"
@ -431,14 +381,14 @@ The version of this low-power example for the **QXK** kernel uses one active obj
QXThread XT_Blinky1;
QXSemaphore XSEM_sw1;
/*..........................................................................*/
/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~..*/
void XBlinky1_ctor(void) {
QXThread_ctor(&XT_Blinky1,
&XBlinky1_run, /* thread routine */
1U); /* associate the thread with tick rate-1 */
}
/*..........................................................................*/
/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~..*/
static void XBlinky1_run(QXThread * const me) {
bool isActive = false;
@ -463,19 +413,16 @@ The version of this low-power example for the **QXK** kernel uses one active obj
}
@endcode
<dl class="tag">
<dt>0</dt><dd> The **XBlinky1** extended thread emulates the states with the `isActive` flag. When the flag is not set (meaning that the system is not active), the thread waits (and blocks) on the global semaphore `XSEM_sw1`.
</dd>
<dt>1</dt><dd> After the semaphore is signalled (from the GPIO interrupt in the BSP), the **XBlinky1** extened thread calls `BSP_tickRate1_on()` to turn the tick rate-1 on. This is done *before* later calling QXThread_delay() function, which in case uses the clock rate-1.
</dd>
</dl>
<div style="clear:both;"></div>
`[0]` The **XBlinky1** extended thread emulates the states with the `isActive` flag. When the flag is not set (meaning that the system is not active), the thread waits (and blocks) on the global semaphore `XSEM_sw1`.
`[1]` After the semaphore is signalled (from the GPIO interrupt in the BSP), the **XBlinky1** extened thread calls `BSP_tickRate1_on()` to turn the tick rate-1 on. This is done *before* later calling QXThread_delay() function, which in case uses the clock rate-1.
@subsection arm-cm_low_power_idle The Idle Callback (QK/QXK)
The most important functionality in this low-power example is implemented in the **idle callback** located in the BSP (Board Support Package). The idle callback QK_onIdle() for the preemptive QK kernel and the idle callback QXK_onIdle() for the QXK kernel are almost identical and are explained in this section.
@code{c}
@code{.c}
[0] void QXK_onIdle(void) {
[1] QF_INT_DISABLE();
@ -502,46 +449,44 @@ The most important functionality in this low-power example is implemented in the
}
@endcode
<dl class="tag">
<dt>0</dt><dd> The idle callback for QK and QXK are called from the idle loop with interrupts enabled.
</dd>
<dt>1</dt><dd> Interrupts are disabled to access the shared bitmask `l_activeSet`, which stores the information about active clock rates and peripherals. This bitmask is shared between the idle callback and the application-level threads.
</dd>
<dt>2</dt><dd> If the SYSTICK timer is active (source of the tick-0 rate)...
</dd>
<dt>3</dt><dd> The `QF_noTimeEvtsActiveX(0)` function is called to check whether no time events are active at the clock rate-0.
> <b>NOTE:</b> The QF_noTimeEvtsActiveX() function is designed to be called from a critical section, which is the case here.
`[0]` The idle callback for QK and QXK are called from the idle loop with interrupts enabled.
</dd>
<dt>4</dt><dd> If both of these conditions hold, it is safe to turn the clock rate-0 off, which is done here.
</dd>
<dt>5</dt><dd> The bit indicating that SYSTICK timer is active is cleared in the `l_activeSet` bitmask.
</dd>
<dt>6</dt><dd> Simliarly, the bit corresponding to TIMER0 is checked in the `l_activeSet` bitmask.
</dd>
<dt>7</dt><dd> The `QF_noTimeEvtsActiveX(1)` function is called to check whether no time events are active at the clock rate-1.
</dd>
<dt>8-9</dt><dd> If both of these conditions hold, it is safe to turn the clock rate-1 off, which is done here.
</dd>
<dt>10</dt><dd> The bit indicating that TIMER0 timer is active is cleared in the `l_activeSet` bitmask.
</dd>
<dt>11</dt><dd> Interrupts are enabled, so the following code is no logner inside critical section
</dd>
<dt>12</dt><dd> The **Red-LED** is turned ON right before entering the low-power sleep mode
</dd>
<dt>13</dt><dd> The `__WFI()` instruction stops the CPU and enters the **low-power sleep mode**
</dd>
<dt>14</dt><dd> The **Red-LED** is turned off after waking up from the sleep mode
</dd>
</dl>
<div style="clear:both;"></div>
`[1]` Interrupts are disabled to access the shared bitmask `l_activeSet`, which stores the information about active clock rates and peripherals. This bitmask is shared between the idle callback and the application-level threads.
`[2]` If the SYSTICK timer is active (source of the tick-0 rate)~~~
`[3]` The `QF_noTimeEvtsActiveX(0)` function is called to check whether no time events are active at the clock rate-0.
@remark
The QF_noTimeEvtsActiveX() function is designed to be called from a critical section, which is the case here.
`[4]` If both of these conditions hold, it is safe to turn the clock rate-0 off, which is done here.
`[5]` The bit indicating that SYSTICK timer is active is cleared in the `l_activeSet` bitmask.
`[6]` Simliarly, the bit corresponding to TIMER0 is checked in the `l_activeSet` bitmask.
`[7]` The `QF_noTimeEvtsActiveX(1)` function is called to check whether no time events are active at the clock rate-1.
`[8-9]` If both of these conditions hold, it is safe to turn the clock rate-1 off, which is done here.
`[10]` The bit indicating that TIMER0 timer is active is cleared in the `l_activeSet` bitmask.
`[11]` Interrupts are enabled, so the following code is no logner inside critical section
`[12]` The **Red-LED** is turned ON right before entering the low-power sleep mode
`[13]` The `__WFI()` instruction stops the CPU and enters the **low-power sleep mode**
`[14]` The **Red-LED** is turned off after waking up from the sleep mode
@subsection arm-cm_low_power_idle-qv The Idle Callback (QV)
The idle callback QV_onIdle() for the cooperative QV kernel is slightly different, because it is called with interrupts **disabled**. The following listing shows the complete QV_onIdle() callback, with the most important points explained in the section below:
@code{c}
@code{.c}
[0] void QV_onIdle(void) { /* NOTE: called with interrupts DISABLED */
[1] if (((l_activeSet & (1U << SYSTICK_ACTIVE)) != 0U) /* rate-0 enabled? */
@ -566,20 +511,19 @@ The idle callback QV_onIdle() for the cooperative QV kernel is slightly differen
}
@endcode
<dl class="tag">
<dt>0</dt><dd> The idle callback for QV is called from the QV event-loop with interrupts **disabled**.
</dd>
<dt>1</dt><dd> The `l_activeSet` bitmask is tested right away, because interrupts are already disabled
</dd>
<dt>2</dt><dd> The `QF_noTimeEvtsActiveX(0)` function is called to check whether no time events are active at the clock rate-0.
`[0]` The idle callback for QV is called from the QV event-loop with interrupts **disabled**.
> <b>NOTE:</b> The QF_noTimeEvtsActiveX() function is designed to be called from a critical section, which is the case here.
`[1]` The `l_activeSet` bitmask is tested right away, because interrupts are already disabled
</dd>
<dt>3</dt><dd> The QV_CPU_SLEEP() macro enters **low-power sleep mode** with interrupts still disabled. This port-specific macro is designed to re-anable interrupts **atomically** with entering the sleep mode.
</dd>
</dl>
<div style="clear:both;"></div>
`[2]` The `QF_noTimeEvtsActiveX(0)` function is called to check whether no time events are active at the clock rate-0.
@nav{tut_game,srs}
@remark
The QF_noTimeEvtsActiveX() function is designed to be called from a critical section, which is the case here.
`[3]` The QV_CPU_SLEEP() macro enters **low-power sleep mode** with interrupts still disabled. This port-specific macro is designed to re-anable interrupts **atomically** with entering the sleep mode.
@ifnot LATEX
@nav{tut_game,exa}
@endif
*/

461
doxygen/history.dox
View File

File diff suppressed because it is too large Load Diff

BIN
doxygen/images/SM_calc.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 66 KiB

BIN
doxygen/images/an-oop_in_c.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 48 KiB

BIN
doxygen/images/an-oop_in_c.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 71 KiB

BIN
doxygen/images/arm-cm_int3bit.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 48 KiB

BIN
doxygen/images/arm-cm_int4bit.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 63 KiB

BIN
doxygen/images/bd_mbed-LPC1768.jpg
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 13 KiB

After

Width:  |  Height:  |  Size: 11 KiB

BIN
doxygen/images/bd_mbed-LPC1768_xyz.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 13 KiB

BIN
doxygen/images/blinky_ek-tm4c123gxl.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 21 KiB

BIN
doxygen/images/exa_low-power_sig-zoom.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 59 KiB

After

Width:  |  Height:  |  Size: 23 KiB

BIN
doxygen/images/exa_low-power_sig.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 24 KiB

BIN
doxygen/images/exa_low-power_sm.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 29 KiB

After

Width:  |  Height:  |  Size: 17 KiB

BIN
doxygen/images/exa_low-power_tick.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 10 KiB

BIN
doxygen/images/game.mp4
View File

Binary file not shown.

BIN
doxygen/images/github-star.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 25 KiB

BIN
doxygen/images/logo_embos.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.5 KiB

BIN
doxygen/images/logo_freertos.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 20 KiB

BIN
doxygen/images/logo_pclintplus.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 32 KiB

BIN
doxygen/images/logo_threadx.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.6 KiB

BIN
doxygen/images/logo_uc-os2.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 11 KiB

BIN
doxygen/images/logo_zephyr.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 9.9 KiB

BIN
doxygen/images/misra3.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 73 KiB

BIN
doxygen/images/oop-in-C.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 39 KiB

BIN
doxygen/images/qk_arm-cm.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 24 KiB

BIN
doxygen/images/qk_asynch.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 18 KiB

BIN
doxygen/images/qk_asynch.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

BIN
doxygen/images/qk_preempt.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 22 KiB

BIN
doxygen/images/qk_preempt.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB

BIN
doxygen/images/qk_stack-detail.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 34 KiB

BIN
doxygen/images/qk_synch.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 15 KiB

BIN
doxygen/images/qk_synch.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 10 KiB

BIN
doxygen/images/qp-prio.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.8 KiB

BIN
doxygen/images/qp-zephyr.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 24 KiB

BIN
doxygen/images/qp_classes.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 42 KiB

BIN
doxygen/images/qp_classes.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 26 KiB

BIN
doxygen/images/qpc_gh.jpg
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 91 KiB

After

Width:  |  Height:  |  Size: 102 KiB

BIN
doxygen/images/qutest_tcl.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 107 KiB

After

Width:  |  Height:  |  Size: 36 KiB

BIN
doxygen/images/qutest_tm4c123_py.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 42 KiB

After

Width:  |  Height:  |  Size: 18 KiB

BIN
doxygen/images/qutest_tm4c123_tcl.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 59 KiB

After

Width:  |  Height:  |  Size: 19 KiB

BIN
doxygen/images/qv.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 16 KiB

BIN
doxygen/images/qv.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 9.6 KiB

0
doxygen/images/game_win32.jpg → doxygen/images/qwin_static.jpg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 106 KiB

After

Width:  |  Height:  |  Size: 106 KiB

BIN
doxygen/images/qxk_classes.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 42 KiB

BIN
doxygen/images/qxk_classes.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 28 KiB

BIN
doxygen/images/qxk_ctx-switch.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 14 KiB

BIN
doxygen/images/qxk_ctx-switch.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.9 KiB

BIN
doxygen/images/start-stop.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 40 KiB

BIN
doxygen/images/under_construction.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 21 KiB

BIN
doxygen/images/v-model.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 154 KiB

BIN
doxygen/img/cert-pack.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 9.7 KiB

BIN
doxygen/img/github-corner.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 1.8 KiB

BIN
doxygen/img/github-qp.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 8.4 KiB

BIN
doxygen/img/help_dark.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 920 B

After

Width:  |  Height:  |  Size: 774 B

BIN
doxygen/img/help_light.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 965 B

After

Width:  |  Height:  |  Size: 705 B

3
doxygen/img/img.htm
View File

@ -7,6 +7,7 @@
<img src="logo_ql.png">
<img src="logo_github.png">
<img src="cert-pack.png">
<img src="splitbar.png">
<img src="AN.jpg">
<img src="AN_Coding_Standard.jpg">
@ -18,8 +19,6 @@
<img src="help_dark.png">
<img src="tree-view_linked.png">
<img src="tree-view_unlinked.png">
<img src="github-corner.png">
<img src="github-qp.png">
<img src="logo_qwin.jpg">
<img src="board.png">
<img src="checkboxoff.png">

BIN
doxygen/img/logo_github.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.7 KiB

After

Width:  |  Height:  |  Size: 2.9 KiB

BIN
doxygen/img/logo_ql-compact.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 20 KiB

177
doxygen/macros.h
View File

@ -1,177 +0,0 @@
/**
* @file
* @brief Various macros for configuring and porting QP/C
*/
/*! The preprocessor switch to disable checking assertions */
/**
* When defined, Q_NASSERT disables the following macros #Q_ASSERT,
* #Q_REQUIRE, #Q_ENSURE, #Q_INVARIANT, #Q_ERROR as well as
* #Q_ASSERT_ID, #Q_REQUIRE_ID, #Q_ENSURE_ID, #Q_INVARIANT_ID, and
* #Q_ERROR_ID do _not_ evaluate the test condition passed as the
* argument to these macros.
*
* @note The notable exceptions are the macros #Q_ALLEGE and
* #Q_ALLEGE_ID, that still evaluate the test condition, but do not
* report assertion failures when the switch #Q_NASSERT is defined.
*/
#define Q_NASSERT
/*! The preprocessor switch to activate the QS software tracing
* instrumentation in the code */
/**
* When defined, Q_SPY activates the QS software tracing instrumentation.
* When Q_SPY is not defined, the QS instrumentation in the code does
* not generate any code.
*/
#define Q_SPY
/*! The preprocessor switch to activate the QUTest unit testing
* instrumentation in the code */
/**
* @note
* This macro requires that #Q_SPY be defined as well.
*/
#define Q_UTEST
/*! The preprocessor switch to enable constructor in the ::QEvt class
* instrumentation in the code */
/**
* @rtr{RQP005}
*/
#define Q_EVT_CTOR
/*! This macro defines the type of the thread handle used for AOs */
#define QF_THREAD_TYPE void*
/*! This macro defines the type of the event-queue used for AOs */
#define QF_EQUEUE_TYPE QEQueue
/*! This macro defines the type of the OS-Object used for blocking
* the native ::QEQueue when the queue is empty */
/**
* @description
* This macro is used when ::QEQueue is used as the event-queue for AOs
* but also the AO queue must *block* when the queue is empty.
* In that case, #QF_OS_OBJECT_TYPE specifies the blocking mechanism.
* For examle, in the POSIX port, the blocking mechanism is a condition
* variable.
*/
#define QF_OS_OBJECT_TYPE pthread_cond_t
/*! Platform-dependent macro defining how QF should block the
* calling task when the QF native queue is empty */
/**
* @note This is just an example of QACTIVE_EQUEUE_WAIT_() for the QK-port
* of QF. QK never activates a task that has no events to process, so in
* this case the macro asserts that the queue is not empty. In other QF
* ports you need to define the macro appropriately for the underlying
* kernel/OS you're using.
*/
#define QACTIVE_EQUEUE_WAIT_(me_) \
(Q_ASSERT((me_)->eQueue.frontEvt != (QEvt *)0))
#if (QF_MAX_ACTIVE <= 8U)
#define QACTIVE_EQUEUE_SIGNAL_(me_) do { \
QPSet8_insert(&QK_readySet_, (me_)->prio); \
if (QK_intNest_ == 0U) { \
uint_fast8_t p = QK_schedPrio_(); \
if (p != 0U) { \
QK_sched_(p); \
} \
} \
} while (0)
#else
/*! Platform-dependent macro defining how QF should signal the
* active object task that an event has just arrived. */
/**
* The macro is necessary only when the native QF event queue is used.
* The signaling of task involves unblocking the task if it is blocked.
*
* @note QACTIVE_EQUEUE_SIGNAL_() is called from a critical section.
* It might leave the critical section internally, but must restore
* the critical section before exiting to the caller.
*
* @note This is just an example of QACTIVE_EQUEUE_SIGNAL_() for the
* QK-port of QF. In other QF ports you need to define the macro
* appropriately for the underlying kernel/OS you're using.
*/
#define QACTIVE_EQUEUE_SIGNAL_(me_) do { \
QPSet64_insert(&QK_readySet_, (me_)->prio); \
if (QK_intNest_ == 0U) { \
uint_fast8_t p = QK_schedPrio_(); \
if (p != 0U) { \
QK_sched_(p); \
} \
} \
} while (0)
#endif
/*! This macro defines the type of the event pool used in the QK kernel. */
/**
* @note This is a specific implementation for the QK-port of QF.
* In other QF ports you need to define the macro appropriately for
* the underlying kernel/OS you're using.
*/
#define QF_EPOOL_TYPE_ QMPool
/*! This macro enables calling the QK context-switch callback
* QK_onContextSw() */
#define QK_ON_CONTEXT_SW
/*! This macro enables calling the QXK context-switch callback
* QXK_onContextSw() */
#define QXK_ON_CONTEXT_SW
/*! Platform-dependent macro defining the event pool initialization */
/**
* @note
* This is an example implementation based on the native ::QMPool class.
* In other QF ports, the port might be using a memory pool from the
* underlying kernel/OS.
*/
#define QF_EPOOL_INIT_(p_, poolSto_, poolSize_, evtSize_) \
(QMPool_init(&(p_), (poolSto_), (poolSize_), (QMPoolSize)(evtSize_)))
/*! Platform-dependent macro defining how QF should obtain the
* event pool block-size */
/**
* @note This is a specific implementation for the QK-port of QF.
* In other QF ports you need to define the macro appropriately for
* the underlying kernel/OS you're using.
*/
#define QF_EPOOL_EVENT_SIZE_(p_) ((QEvtSize)(p_).blockSize)
/*! Platform-dependent macro defining how QF should obtain an event
* @a e_ from the event pool @a p_ with the free margin @a m_. */
/**
* @note
* This is an example implementation based on the native ::QMPool class.
* In other QF ports, the port might be using a memory pool from the
* underlying kernel/OS.
*/
#define QF_EPOOL_GET_(p_, e_, m_, qs_id_) \
((e_) = (QEvt *)QMPool_get(&(p_), (m_), (qs_id_)))
/*! Platform-dependent macro defining how QF should return an event
* @a e_ to the event pool @a p_ */
/**
* @note
* This is an example implementation based on the native ::QMPool class.
* In other QF ports, the port might be using a memory pool from the
* underlying kernel/OS.
*/
#define QF_EPOOL_PUT_(p_, e_, qs_id_) \
(QMPool_put(&(p_), (e_), (qs_id_)))
/*! Macro defined only for the internal QP implementation. It should
* be not defined for the application-level code
*/
#define QP_IMPL
/*! Macro that should be defined (typically on the compiler's command line)
in the Win32-GUI applications that use the @ref win32 or @ref win32-qv ports.
*/
#define WIN32_GUI

139
doxygen/main.dox
View File

@ -1,98 +1,121 @@
/*! @mainpage About QP&trade;/C
@image html qp_banner.jpg
/*! @mainpage Overview
<a target="_blank" href="https://github.com/QuantumLeaps/qpc" title="QP&trade;/C on GitHub"><img style="float:right; clear:right;" src="img/github-corner.png"></a>
@section ab_new What's new?
@image html qp_banner.jpg
@image latex qp_banner.jpg width=6.5in
@ifnot LATEX
@remark
<a target="_blank" href="https://github.com/QuantumLeaps/qpc" title="QP/C on GitHub"><img class="right" src="img/logo_github.png"></a>
@endif
@image{inline} latex logo_github.png width=1in
To check what's new in QP&trade;/C, please see @ref history "QP/C Revision History". You can also get the latest **QP&trade;/C code**, with the recent enhancements and bug fixes, from the <a class="extern" target="_blank" href="https://github.com/QuantumLeaps/qpc"><strong>GitHub QP&trade;/C repository</strong></a>.
<div style="clear:both"></div>
@section ab_about What is it?
@webref{products/qp, <strong>QP&trade;/C (Quantum Platform in C)</strong>} is a lightweight @webref{rtef, Real-Time Embedded Framework (RTEF)} for building modern, responsive and modular real-time embedded applications as systems of asynchronous event-driven @webref{active-object, active objects} (<a href="https://en.wikipedia.org/wiki/Actor_model">actors</a>). The QP&trade;/C RTEF is a member of a @webref{products/qp, larger family of real-time embedded frameworks (RTEFs)} consisting of QP&trade;/C and QP&trade;/C++ frameworks, which are strictly quality controlled, thoroughly documented, and available under @ref licensing "dual licensing model".
The behavior of active objects is specified in QP&trade;/C by means of @webref{fsm/#HSM, <strong>hierarchical state machines</strong>} (UML statecharts). The framework supports @ref sm "manual coding of UML state machines in C" as well as automatic code generation by means of the free @webref{products/qm, <strong>QM&trade; model-based design tool</strong>}.
@attention
To use QP&trade;/C effectively, you need to understand the @webref{category/concepts, <strong>key concepts</strong>} that underline the architecture of the framework and your applications based on the framework.
@section over_about What is it?
<b>QP&trade;/C Real-Time Embedded Framework (RTEF)</b> is a lightweight implementation of the @webref{active-object, Active Object model of computation} specifically tailored for real-time embedded (RTE) systems. QP is both a *software infrastructure* for building applications consisting of active objects (actors) and a *runtime environment* for executing the active objects in a deterministic fashion. Additionally, QP Framework supports @webref{fsm#HSM, Hierarchical State Machines} with which to specify the behavior of Active Objects @ref srs_ref "[ROOM:94], [UML 2.5],[Sutter:10]". You can think of the QP/C RTEF as a modern, truly *event-driven* real-time operating system (RTOS).
@section ab_goals What does it do?
The main goals of the QP&trade;/C framework are:
- to provide a reusable event-driven **architecture** based on @webref{active-object, active objects (actors)}, which is inherently **safer**, more extensible, and easier to understand than the usual *shared-state concurrency* based on a traditional Real-Time Operating System (RTOS).
- to provide a simple-to-use coding techniques for @webref{fsm/#HSM, hierarchical state machines}, with which to implement the behavior of active objects.
- to provide efficient and thread-safe asynchronous mechanisms for active objects to communicate, such as direct event passing and publish-subscribe.
- to provide event-driven timing services (time events).
- to provide a selection of built-in real-time kernels to run the QP applications, such as the cooperative @ref qv "QV kernel", the preemptive non-blocking @ref qk "QK kernel", and the preemptive blocking @ref qxk "QXK kernel".
- to provide testing support for applications based on software tracing (@ref qs "Q-Spy").
- to provide **unit testing** support for applications based on software tracing (@webref{qtools/qutest.html, <strong>QUTest&trade;</strong>}).
- to provide portability layer and ready-to-use ports to @ref ports_rtos "3rd-party RTOSes" and general purpose operating systems such as @ref posix "Linux" and @ref win32 "Windows".
- to provide a target for modeling and automatic code generation from the @webref{products/qm, <strong>QM&trade; modeling tool</strong>}.
@section over_goals What does it do?
The main objectives of the QP/C RTEF are:
- to provide a modern, event-driven model of concurrency based on the best practices of concurrent programming collectively known as the @webref{active-object, Active Object (Actor) model of computation}, which is inherently *safer* than the traditional "shared-state concurrency, mutual-exclusion, and blocking" approach based on a conventional Real-Time Operating System (RTOS);
- to provide an efficient, @ref tr "bidirectionally traceable" implementation of @webref{fsm#HSM, Hierarchical State Machines} for specifying the internal behavior of Active Objects;
- to provide a *higher-level of abstraction* closer to the problem domain than the "naked" RTOS threads;
- to provide the *right* abstractions for applying modern techniques like visual modeling, hierarchical state machines, and automatic code generation;
- to bridge the semantic gap between the higher level modeling concepts (such as UML) and the traditional programming languages like C or C++.
@section ab_special What's special about it?
The QP&trade;/C Real-Time Embedded Framework (RTEF) is a unique offering on the embedded software market. It provides a modern, reusable **architecture** of embedded applications, which combines object-orientation with the particular model of concurrency, known as @webref{active-object, <strong>active objects</strong>} (actors). This architecture is generally **safer**, more responsive and easier to understand than "free threading" with a traditional Real-Time Operating System (RTOS). It also provides sufficiently high level of abstraction and the right abstractions to effectively apply modeling and code generation to deeply embedded systems.
@subsection oop Object Orientation
Even though it is written in @ref misra "MISRA-compliant" ISO-C99, QP&trade;/C is fundamentally an **object-oriented** framework, which means that the framework itself and your applications derived from the framework are fundamentally composed of <a href="https://en.wikipedia.org/wiki/Class_(computer_programming)" target="_blank" class="extern">classes</a> and only classes can have @ref sm "state machines" associated with them.
@section over_special What's special about it?
The QP&trade;/C Real-Time Embedded Framework (RTEF) provides a modern, reusable **architecture** of embedded applications, which combines the model of concurrency, known as @webref{active-object, <strong>active objects</strong>} (actors) with @webref{fsm#HSM, Hierarchical State Machines}. This architecture is generally **safer**, more responsive and easier to understand than "free threading" with a traditional Real-Time Operating System (RTOS). It also provides sufficiently high level of abstraction and the *right* abstractions to effectively apply modeling and code generation to deeply embedded systems.
@note
If you program in C and object-oriented programming is new to you, please refer to the article and set of videos @webref{oop, "Object-Oriented Programming"}, which among others describes how you can implement the concepts of *classes*, *inheritance*, and *polymorphism* to portable ISO-C.
The most unique aspect of the QP&trade;/C RTEF is its @ref over_eff "tiny size and efficiency" suitable for embedded microcontrollers, such as MCUs based on ARM Cortex-M.
@subsection hsms Hierarchical State Machines
The behavior of active objects is specified in QP&trade;/C by means of @webref{fsm/#HSM, hierarchical state machines (UML statecharts)}. The framework supports @ref sm "manual coding of UML state machines in C" (or C++ in case of QP&trade;/C++) as well as fully **automatic code generation** by means of the free graphical @webref{products/qm, QM&trade; model-based design (MBD) tool}.
@subsection over_oop Object Orientation
Even though it is written in @ref misra "MISRA-compliant" ISO-C99, QP&trade;/C is fundamentally an **object-oriented** framework, which means that the framework itself and your applications derived from the framework are fundamentally composed of @ref sas_core "classes" and only classes can have @ref srs_sm "state machines" associated with them.
@remarks
State machines can be an incredibly powerful technique, but they require an event-driven **infrastructure** (framework) that provides, at a minimum: a run-to-completion (RTC) execution context for each state machine, queuing of events, and event-based timing services. This is really the pivotal point. Without an event-driven framework (like QP&trade;/C), state machines are like @webref{rtef, cars without an infrastructure of roads}.
@anchor oop
@remark
If you program in C and object-oriented programming is new to you, please refer to the article and set of videos @webref{oop, "Object-Oriented Programming"}, which among others describes how you can implement the concepts of *classes*, *inheritance*, and *polymorphism* to portable ISO-C.<br>
<br>
@ifnot LATEX
[![](oop-in-C.jpg)](https://www.state-machine.com/oop)
@endif
@image latex oop-in-C.jpg width=3.00in
@caption{Application Note: Object-Oriented Programming in C}
@subsection kernels Built-in Kernels
The QP&trade;/C framework can run on @ref exa_native "bare-metal single-chip microcontrollers", completely replacing a traditional RTOS. The framework contains a selection of built-in real-time kernels, such as the cooperative @ref qv "QV kernel", the preemptive non-blocking @ref qk "QK kernel", and the preemptive, dual-mode, blocking @ref qxk "QXK kernel". The QXK kernel <span class="highlight">provides all the features you might expect from a traditional <strong>RTOS kernel</strong></span> and has been specifically designed 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. @ref ports_native "Native QP ports" and ready-to-use @ref exa_native "examples" are provided for major @ref exa_ref_mcu "CPU families".
@subsection over_hsms Hierarchical State Machines
The behavior of active objects is specified in QP&trade;/C by means of @webref{fsm/#HSM, hierarchical state machines (UML statecharts)}. The framework supports manual coding of UML state machines in C as well as fully **automatic code generation** by means of the free graphical @webref{products/qm, QM&trade; model-based design (MBD) tool}.
@subsection light_fast Lightweight and Fast
Even though QP&trade;/C offers much higher level of abstraction than a traditional RTOS, it typically outperforms equivalent traditional RTOS offerings both in RAM/ROM footprint and in CPU efficiency. The specific measurements and results are reported in the following @webref{doc/AN_QP_Performance.pdf, Application Note: "QP Performance Tests and Results"}:
[![Application Note: "QP Performance Tests and Results"](an-qp_performance.png)](https://www.state-machine.com/doc/AN_QP_Performance.pdf)
@subsection over_kernels Built-in Kernels
The QP&trade;/C framework can run on @ref exa_native "bare-metal single-chip microcontrollers", completely replacing a traditional RTOS. The framework contains a selection of built-in real-time kernels, such as the cooperative @ref srs_qv "QV kernel", the preemptive non-blocking @ref srs_qk "QK kernel", and the preemptive, dual-mode, blocking @ref srs_qxk "QXK kernel". The QXK kernel <span class="highlight">provides all the features you might expect from a traditional <strong>RTOS kernel</strong></span> and has been specifically designed 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. @ref ports_native "Native QP ports" and ready-to-use @ref exa_native "examples" are provided for major @ref exa_ref_mcu "CPU families".
@subsection inter Interoperability
QP/C can also work with many traditional @ref exa_rtos "RTOSes" and @ref exa_os "general-purpose OSes" (such as Linux and Windows).
@subsection over_eff Size and Efficiency
Even though QP&trade;/C offers much higher level of abstraction than a traditional RTOS, it typically outperforms equivalent traditional RTOS applications both in RAM/ROM footprint and in CPU efficiency. The specific measurements and results are reported in the following @webref{doc/AN_QP_Performance.pdf, Application Note: "QP Performance Tests and Results"}:
@ifnot LATEX
[![](an-qp_performance.png)](https://www.state-machine.com/doc/AN_QP_Performance.pdf)
@endif
@image latex an-qp_performance.png width=1.5in
@caption{QP Performance Tests and Results}
@subsection over_inter Interoperability
QP/C can also work with many traditional @ref exa_rtos "Real-Time Operating Systems (RTOSes)" and @ref exa_os "general-purpose operating systems (GPOSes)" (such as Linux (POSIX) and Windows).
@subsection popular Popularity &amp; Maturity
@subsection over_trace Traceability
QP&trade;/C offers unprecedented, bidirectional @ref tr "traceability" among all work artifacts, which gives teams full visibility from requirements through architecture, design, source code, tests, and back again.
@subsection over_popular Popularity &amp; Maturity
With 20 years of continuous development, over @webref{customers#Customers, 350 commercial licensees}, and many times more open source users worldwide, the QP&trade; frameworks are the most popular such offering on the market. They power countless electronic products ranging from implantable medical devices to complex weapon systems.
@subsection use Widespread Use
@subsection over_use Widespread Use
The QP&trade; real-time embedded frameworks address high-reliability applications across a @webref{customers#Markets, wide variety of markets}, such as medical, consumer, IoT, defense, robotics, industrial, communication, transportation, semiconductor IP, and many others. In each of these application areas, the elegant software architecture and modern design philosophy of QP&trade; have distinct advantages.
@subsection psicc2 Books
The two editions of the book, @webref{psicc2, <strong>Practical Statecharts in C/C++</strong>} provide a detailed design study of the QP frameworks and explain the related concepts.
@subsection over_psicc2 Books
The two editions of the book, @webref{psicc2, <strong>Practical Statecharts in C/C++</strong>} provide a detailed design study of the QP&trade; frameworks and explain the related concepts.
[![Practical UML Statecharts in C/C++, 2nd Edition](psicc2.jpg)](https://www.state-machine.com/psicc2)
@ifnot LATEX
[![](psicc2.jpg)](https://www.state-machine.com/psicc2)
@endif
@image latex psicc2.jpg width=3.1in
@caption{Practical UML Statecharts in C/C++, 2nd Edition}
<br>
[![Practical Statecharts in C/C++, 1nd Edition](psicc1.jpg)](https://www.state-machine.com/psicc)
@ifnot LATEX
[![](psicc1.jpg)](https://www.state-machine.com/psicc)
@endif
@image latex psicc1.jpg width=4.5in
@caption{Practical Statecharts in C/C++, 1nd Edition}
@section licensing How is it licensed?
@section over_licensing How is it licensed?
QP&trade;/C is licensed under the sustainable @webref{licensing, dual licensing model}, in which both the open source software distribution mechanism and traditional closed source software distribution models are combined.
@note
If your company has a policy forbidding open source in your product, all QP frameworks can be @webref{licensing#Commercial, licensed commercially}, in which case you don't use any open source license and you do not violate your policy.
@subsection open-source Open Source Projects
@subsection over_open-source Open Source Projects
If you are developing and distributing **open source** applications under the GNU General Public License (GPL), as published by the Free Software Foundation, then you are free to use the Quantum Leaps software under the <a class="extern" target="_blank" href="https://www.gnu.org/copyleft/gpl.html">GPL version 3</a> of the License, or (at your option) any later version. Please note that GPL requires that all modifications to the original code as well as your application code (Derivative Works as defined in the Copyright Law) must also be released under the terms of the GPL open source license.
@subsection closed-source Closed Source Projects
@subsection over_closed-source Closed Source Projects
If you are developing and distributing traditional **closed source** applications, you can purchase one of @webref{licensing/#Commercial, Quantum Leaps commercial licenses}, which are specifically designed for users interested in retaining the proprietary status of their code. All Quantum Leaps commercial licenses expressly supersede the GPL open source license. This means that when you license Quantum Leaps software under a commercial license, you specifically do not use the software under the open source license and therefore you are not subject to any of its terms.
@section support How to get help?
@section over_support How to get help?
Please post any **technical questions** to the <a class="extern" target="_blank" href="https://sourceforge.net/p/qpc/discussion/668726"><strong>Free Support Forum</strong></a> hosted on SourceForge.net. Posts to this forum benefit the whole community and are typically answered the same day.
Direct **Commercial Support** is available to the commercial licensees. Every commercial license includes one year of Technical Support for the licensed software. The support term can be extended annually.
@ -103,15 +126,13 @@ Training and consulting services are also available from Quantum Leaps. Please r
The features of this online help and tips for using it are described in Section @ref help.
@section contact Contact Information
@section over_contact Contact Information
- Quantum Leaps Web site: @webref{,state-machine.com}
- Quantum Leaps licensing: @webref{licensing, state-machine.com/licensing}
- QP/QM on GitHub: <a class="extern" target="_blank" href="https://github.com/QuantumLeaps">github.com/QuantumLeaps</a>
- Quantum Leaps on GitHub: <a class="extern" target="_blank" href="https://github.com/QuantumLeaps">github.com/QuantumLeaps</a>
- e-mail: <a class="extern" target="_blank" href="mailto:info@state-machine.com">info@state-machine.com</a>
@next{gs}
@ifnot LATEX
@nav_next{gs}
@endif
*/

202
doxygen/make.bat
View File

@ -1,93 +1,109 @@
@echo off
:: ==========================================================================
:: Product: batch script for generating Doxygen documentation
:: Copyright (C) 2005 Quantum Leaps, LLC. All rights reserved.
::
:: SPDX-License-Identifier: GPL-3.0-or-later OR LicenseRef-QL-commercial
::
:: This software is dual-licensed under the terms of the open source GNU
:: General Public License version 3 (or any later version), or alternatively,
:: under the terms of one of the closed source Quantum Leaps commercial
:: licenses.
::
:: The terms of the open source GNU General Public License version 3
:: can be found at: <www.gnu.org/licenses/gpl-3.0>
::
:: The terms of the closed source Quantum Leaps commercial licenses
:: can be found at: <www.state-machine.com/licensing>
::
:: Redistributions in source code must retain this top-level comment block.
:: Plagiarizing this software to sidestep the license obligations is illegal.
::
:: Contact information:
:: <www.state-machine.com>
:: <info@state-machine.com>
:: ==========================================================================
@setlocal
@echo usage:
@echo make
@echo make -CHM
@echo make ...
:: Doxygen tool (adjust to your system) ......................................
@set DOXYGEN=doxygen
:: HTML Help tool (needed only with the -CHM option, (adjust to your system) .
@set HHC="C:\tools\HTML Help Workshop\hhc.exe"
:: Simple complexity metrics tool (adjust to your system) ...................
@set LIZARD=lizard
:: QP/C directory ............................................................
@set QPC=..
:: HTML outut directory ......................................................
@set HTML_OUT=%QPC%\html
:: Generate metrics.dox file...
@set METRICS_INP=%QPC%\include %QPC%\src -x %QPC%\src\qs\*
@set METRICS_OUT=metrics.dox
@echo /** @page metrics Code Metrics > %METRICS_OUT%
@echo.>> %METRICS_OUT%
@echo @code{cpp} >> %METRICS_OUT%
@echo Code Metrics >> %METRICS_OUT%
%LIZARD% -m -L500 -a10 -C20 -V %METRICS_INP% >> %METRICS_OUT%
@echo @endcode >> %METRICS_OUT%
@echo */ >> %METRICS_OUT%
:: Generate Doxygen Documentation...
if "%1"=="-CHM" (
@echo Generating HTML...
%DOXYGEN% Doxyfile-CHM
@echo Adding custom images...
xcopy img tmp\img\
@echo img\img.htm >> tmp\index.hhp
@echo Generating CHM...
%HHC% tmp\index.hhp
@echo.
@echo Cleanup...
@rmdir /S /Q tmp
@echo CHM file generated
) else (
@echo.
@echo Cleanup...
rmdir /S /Q %HTML_OUT%
@echo Generating HTML...
%DOXYGEN% Doxyfile%1
@echo Adding custom images...
xcopy img %HTML_OUT%\img\
xcopy /Y ..\..\ql-doxygen\jquery.js %HTML_OUT%
rem @qclean %HTML_OUT%
)
@endlocal
@echo off
:: ==========================================================================
:: Product: batch script for generating Doxygen documentation
:: Copyright (C) 2005 Quantum Leaps, LLC. All rights reserved.
::
:: SPDX-License-Identifier: GPL-3.0-or-later OR LicenseRef-QL-commercial
::
:: This software is dual-licensed under the terms of the open source GNU
:: General Public License version 3 (or any later version), or alternatively,
:: under the terms of one of the closed source Quantum Leaps commercial
:: licenses.
::
:: The terms of the open source GNU General Public License version 3
:: can be found at: <www.gnu.org/licenses/gpl-3.0>
::
:: The terms of the closed source Quantum Leaps commercial licenses
:: can be found at: <www.state-machine.com/licensing>
::
:: Redistributions in source code must retain this top-level comment block.
:: Plagiarizing this software to sidestep the license obligations is illegal.
::
:: Contact information:
:: <www.state-machine.com>
:: <info@state-machine.com>
:: ==========================================================================
@setlocal
@echo usage:
@echo make
@echo make -CHM
@echo make -LATEX
:: tools (adjust to your system)---------------------------------------------
:: Doxygen tool
@set DOXYGEN=doxygen
:: Simple complexity metrics tool (adjust to your system)
@set METRICS=lizard -m -L500 -a10 -C20 -V
:: HTML Help tool (needed only with the -CHM option) .
@set HHC="C:\tools\HTML Help Workshop\hhc.exe"
:: QP directory .............................................................
@set QP=..
:: Outut directories ........................................................
@set HTML_OUT=%QP%\html
IF "%1"=="-CERT" (
@set HTML_OUT=%QP%\cert-pack
)
@set LATEX_OUT=%QP%\latex
:: Generate metrics.dox file-------------------------------------------------
@set METRICS_INP=%QP%\include %QP%\src -x %QP%\src\qs\*
@set METRICS_OUT=gen\metrics.txt
@echo @code{.c}> %METRICS_OUT%
%METRICS% %METRICS_INP% >> %METRICS_OUT%
@echo @endcode>> %METRICS_OUT%
:: Generate Doxygen Documentation -------------------------------------------
if "%1"=="-CHM" (
@echo Generating HTML...
%DOXYGEN% Doxyfile-CHM
@echo Adding custom images...
xcopy img tmp\img\
@echo img\img.htm >> tmp\index.hhp
@echo Generating CHM...
%HHC% tmp\index.hhp
@echo.
@echo Cleanup...
@rmdir /S /Q tmp
@echo CHM file generated
) else if "%1"=="-LATEX" (
@echo.
@echo Cleanup...
rmdir /S /Q %LATEX_OUT%
@echo Generating LATEX...
%DOXYGEN% Doxyfile-LATEX
@echo Adding custom files...
xcopy img %LATEX_OUT%\img\
@cd %LATEX_OUT%
@call make.bat
) else (
@echo.
@echo Cleanup...
rmdir /S /Q %HTML_OUT%
@echo Generating HTML...
%DOXYGEN% Doxyfile%1
@echo Adding custom files...
xcopy img %HTML_OUT%\img\
xcopy /Y ..\..\ql-doxygen\jquery.js %HTML_OUT%
rem @qclean %HTML_OUT%
)
@endlocal

190
doxygen/metrics.dox
View File

@ -1,190 +0,0 @@
/** @page metrics Code Metrics
@code{cpp}
Code Metrics
================================================
NLOC CCN token PARAM length location
------------------------------------------------
3 1 19 1 3 QHsm_state@379-381@..\include\qep.h
3 1 16 1 3 QMsm_stateObj@470-472@..\include\qep.h
3 1 14 1 3 QEQueue_getNFree@186-188@..\include\qequeue.h
3 1 14 1 3 QEQueue_getNMin@201-203@..\include\qequeue.h
3 1 20 1 3 QEQueue_isEmpty@218-220@..\include\qequeue.h
3 1 15 1 3 QPSet_setEmpty@71-73@..\include\qpset.h
3 1 16 1 3 QPSet_isEmpty@76-78@..\include\qpset.h
3 1 16 1 3 QPSet_notEmpty@81-83@..\include\qpset.h
3 1 36 2 3 QPSet_hasElement@86-88@..\include\qpset.h
3 1 31 2 3 QPSet_insert@91-93@..\include\qpset.h
3 1 36 2 3 QPSet_remove@96-98@..\include\qpset.h
3 1 17 1 3 QPSet_findMax@103-105@..\include\qpset.h
4 1 27 1 4 QPSet_setEmpty@120-123@..\include\qpset.h
5 2 34 1 6 QPSet_isEmpty@126-131@..\include\qpset.h
5 2 34 1 6 QPSet_notEmpty@134-139@..\include\qpset.h
5 2 74 2 5 QPSet_hasElement@142-146@..\include\qpset.h
8 2 66 2 8 QPSet_insert@149-156@..\include\qpset.h
8 2 76 2 8 QPSet_remove@159-166@..\include\qpset.h
5 2 45 1 5 QPSet_findMax@171-175@..\include\qpset.h
6 1 23 1 15 Q_DEFINE_THIS_MODULE@45-59@..\src\qf\qep_hsm.c
5 1 31 3 5 QHsm_trig_@77-81@..\src\qf\qep_hsm.c
10 2 56 2 12 QHsm_ctor@142-153@..\src\qf\qep_hsm.c
48 8 357 2 73 QHsm_init_@173-245@..\src\qf\qep_hsm.c
5 1 32 2 5 QHsm_top@265-269@..\src\qf\qep_hsm.c
104 15 670 2 157 QHsm_dispatch_@292-448@..\src\qf\qep_hsm.c
95 15 500 2 133 QHsm_tran_@472-604@..\src\qf\qep_hsm.c
3 1 16 1 3 QHsm_getStateHandler_@608-610@..\src\qf\qep_hsm.c
16 3 107 2 23 QHsm_isIn@630-652@..\src\qf\qep_hsm.c
22 4 131 2 30 QHsm_childState@678-707@..\src\qf\qep_hsm.c
10 2 59 2 13 QMsm_ctor@115-127@..\src\qf\qep_msm.c
24 5 211 2 44 QMsm_init_@146-189@..\src\qf\qep_msm.c
122 23 847 2 185 QMsm_dispatch_@210-394@..\src\qf\qep_msm.c
3 1 18 1 3 QMsm_getStateHandler_@398-400@..\src\qf\qep_msm.c
52 9 328 2 65 QMsm_execTatbl_@425-489@..\src\qf\qep_msm.c
20 4 120 3 28 QMsm_exitToTranSource_@509-536@..\src\qf\qep_msm.c
41 6 236 2 50 QMsm_enterHistory_@557-606@..\src\qf\qep_msm.c
13 3 69 2 14 QMsm_isInState@624-637@..\src\qf\qep_msm.c
21 4 97 2 27 QMsm_childStateObj@658-684@..\src\qf\qep_msm.c
10 3 65 1 16 QF_add_@66-81@..\src\qf\qf_act.c
10 3 79 1 15 QF_remove_@99-113@..\src\qf\qf_act.c
7 2 46 2 7 QF_bzero@130-136@..\src\qf\qf_act.c
24 6 143 1 29 QF_LOG2@143-171@..\src\qf\qf_act.c
79 13 422 3 115 QActive_post_@88-202@..\src\qf\qf_actq.c
42 7 268 2 65 QActive_postLIFO_@223-287@..\src\qf\qf_actq.c
34 3 235 1 45 QActive_get_@312-356@..\src\qf\qf_actq.c
9 2 60 1 12 QF_getQueueMin@378-389@..\src\qf\qf_actq.c
14 2 78 2 18 QTicker_ctor@421-438@..\src\qf\qf_actq.c
7 2 39 2 10 QTicker_init_@445-454@..\src\qf\qf_actq.c
14 3 87 2 20 QTicker_dispatch_@461-480@..\src\qf\qf_actq.c
27 2 150 4 35 QTicker_post_@487-521@..\src\qf\qf_actq.c
5 1 30 2 5 QTicker_postLIFO_@524-528@..\src\qf\qf_actq.c
14 1 84 3 16 QActive_defer@72-87@..\src\qf\qf_defer.c
32 3 169 2 52 QActive_recall@112-163@..\src\qf\qf_defer.c
13 2 68 2 13 QActive_flushDeferred@182-194@..\src\qf\qf_defer.c
5 1 37 2 6 QEvt_ctor@63-68@..\src\qf\qf_dyn.c
15 3 117 3 24 QF_poolInit@108-131@..\src\qf\qf_dyn.c
37 7 234 3 55 QF_newX_@161-215@..\src\qf\qf_dyn.c
30 4 186 1 47 QF_gc@242-288@..\src\qf\qf_dyn.c
16 2 94 2 24 QF_newRef_@306-329@..\src\qf\qf_dyn.c
11 1 67 1 13 QF_deleteRef_@343-355@..\src\qf\qf_dyn.c
3 1 17 1 3 QF_poolGetMaxBlockSize@363-365@..\src\qf\qf_dyn.c
30 5 235 4 48 QMPool_init@83-130@..\src\qf\qf_mem.c
16 2 113 3 23 QMPool_put@155-177@..\src\qf\qf_mem.c
43 4 238 3 66 QMPool_get@213-278@..\src\qf\qf_mem.c
9 3 59 1 13 QF_getPoolMin@294-306@..\src\qf\qf_mem.c
5 1 35 2 10 QF_psInit@85-94@..\src\qf\qf_ps.c
37 5 211 3 64 QF_publish_@120-183@..\src\qf\qf_ps.c
16 5 113 2 22 QActive_subscribe@205-226@..\src\qf\qf_ps.c
16 5 113 2 25 QActive_unsubscribe@254-278@..\src\qf\qf_ps.c
19 5 134 1 24 QActive_unsubscribeAll@304-327@..\src\qf\qf_ps.c
14 2 71 2 21 QActive_ctor@60-80@..\src\qf\qf_qact.c
13 2 85 3 13 QEQueue_init@65-77@..\src\qf\qf_qeq.c
55 8 303 4 74 QEQueue_post@104-177@..\src\qf\qf_qeq.c
35 5 201 3 45 QEQueue_postLIFO@203-247@..\src\qf\qf_qeq.c
36 4 221 2 46 QEQueue_get@269-314@..\src\qf\qf_qeq.c
14 2 78 2 32 QMActive_ctor@68-99@..\src\qf\qf_qmact.c
66 7 368 1 98 QF_tickX_@89-186@..\src\qf\qf_time.c
14 3 75 1 17 QF_noTimeEvtsActiveX@203-219@..\src\qf\qf_time.c
13 2 99 4 30 QTimeEvt_ctorX@240-269@..\src\qf\qf_time.c
32 8 225 3 58 QTimeEvt_armX@302-359@..\src\qf\qf_time.c
31 3 173 1 41 QTimeEvt_disarm@381-421@..\src\qf\qf_time.c
34 8 230 2 62 QTimeEvt_rearm@445-506@..\src\qf\qf_time.c
5 1 36 1 5 QTimeEvt_wasDisarmed@531-535@..\src\qf\qf_time.c
7 1 30 1 8 QTimeEvt_currCtr@554-561@..\src\qf\qf_time.c
11 2 76 1 16 QF_init@65-80@..\src\qk\qk.c
3 1 10 1 4 QF_stop@99-102@..\src\qk\qk.c
6 2 26 1 8 initial_events@107-114@..\src\qk\qk.c
12 3 45 1 19 QF_run@125-143@..\src\qk\qk.c
21 5 144 7 31 QActive_start_@167-197@..\src\qk\qk.c
22 2 111 1 33 QK_schedLock@221-253@..\src\qk\qk.c
21 4 123 1 33 QK_schedUnlock@271-303@..\src\qk\qk.c
14 3 76 1 17 QK_sched_@320-336@..\src\qk\qk.c
61 16 353 1 105 QK_activate_@348-452@..\src\qk\qk.c
9 2 64 1 13 QF_init@66-78@..\src\qv\qv.c
3 1 10 1 4 QF_stop@97-100@..\src\qv\qv.c
39 9 197 1 76 QF_run@110-185@..\src\qv\qv.c
14 3 114 7 20 QActive_start_@209-228@..\src\qv\qv.c
14 2 108 1 22 QF_init@68-89@..\src\qxk\qxk.c
3 1 10 1 4 QF_stop@108-111@..\src\qxk\qxk.c
6 2 26 1 8 initial_events@116-123@..\src\qxk\qxk.c
12 3 45 1 20 QF_run@133-152@..\src\qxk\qxk.c
23 6 164 7 33 QActive_start_@177-209@..\src\qxk\qxk.c
23 3 130 1 34 QXK_schedLock@241-274@..\src\qxk\qxk.c
20 4 123 1 33 QXK_schedUnlock@297-329@..\src\qxk\qxk.c
47 7 268 1 65 QXK_sched_@345-409@..\src\qxk\qxk.c
73 16 474 1 128 QXK_activate_@421-548@..\src\qxk\qxk.c
12 2 72 1 18 QXK_current@551-568@..\src\qxk\qxk.c
16 4 113 2 25 QXMutex_init@80-104@..\src\qxk\qxk_mutex.c
69 12 542 2 110 QXMutex_lock@127-236@..\src\qxk\qxk_mutex.c
43 10 315 1 67 QXMutex_tryLock@259-325@..\src\qxk\qxk_mutex.c
64 16 502 1 111 QXMutex_unlock@347-457@..\src\qxk\qxk_mutex.c
8 1 49 3 10 QXSemaphore_init@72-81@..\src\qxk\qxk_sema.c
43 7 321 2 69 QXSemaphore_wait@107-175@..\src\qxk\qxk_sema.c
15 2 61 1 20 QXSemaphore_tryWait@192-211@..\src\qxk\qxk_sema.c
28 6 195 1 46 QXSemaphore_signal@233-278@..\src\qxk\qxk_sema.c
20 2 112 3 25 QXThread_ctor@105-129@..\src\qxk\qxk_xthr.c
8 2 38 3 11 QXThread_init_@136-146@..\src\qxk\qxk_xthr.c
8 2 38 3 11 QXThread_dispatch_@152-162@..\src\qxk\qxk_xthr.c
25 6 202 7 47 QXThread_start_@189-235@..\src\qxk\qxk_xthr.c
97 13 519 3 131 QXThread_post_@280-410@..\src\qxk\qxk_xthr.c
5 1 30 2 5 QXThread_postLIFO_@423-427@..\src\qxk\qxk_xthr.c
58 7 497 1 84 QXThread_queueGet@449-532@..\src\qxk\qxk_xthr.c
5 1 51 1 7 QXThread_block_@542-548@..\src\qxk\qxk_xthr.c
8 3 58 1 8 QXThread_unblock_@558-565@..\src\qxk\qxk_xthr.c
19 3 153 3 37 QXThread_teArm_@576-612@..\src\qxk\qxk_xthr.c
11 2 46 1 13 QXThread_teDisarm_@622-634@..\src\qxk\qxk_xthr.c
21 4 195 1 38 QXThread_delay@650-687@..\src\qxk\qxk_xthr.c
14 2 68 1 16 QXThread_delayCancel@699-714@..\src\qxk\qxk_xthr.c
13 2 106 1 23 QXK_threadRet_@727-749@..\src\qxk\qxk_xthr.c
37 file analyzed.
==============================================================
NLOC Avg.NLOC AvgCCN Avg.token function_cnt file
--------------------------------------------------------------
4 0.0 0.0 0.0 0 ..\include\qassert.h
108 3.0 1.0 17.5 2 ..\include\qep.h
28 3.0 1.0 16.0 3 ..\include\qequeue.h
93 0.0 0.0 0.0 0 ..\include\qf.h
20 0.0 0.0 0.0 0 ..\include\qk.h
21 0.0 0.0 0.0 0 ..\include\qmpool.h
8 0.0 0.0 0.0 0 ..\include\qpc.h
71 4.4 1.4 37.4 14 ..\include\qpset.h
238 0.0 0.0 0.0 0 ..\include\qs.h
3 0.0 0.0 0.0 0 ..\include\qstamp.c
2 0.0 0.0 0.0 0 ..\include\qstamp.h
0 0.0 0.0 0.0 0 ..\include\qs_dummy.h
9 0.0 0.0 0.0 0 ..\include\quit.h
5 0.0 0.0 0.0 0 ..\include\qv.h
23 0.0 0.0 0.0 0 ..\include\qxk.h
32 0.0 0.0 0.0 0 ..\include\qxthread.h
337 31.4 5.1 192.3 10 ..\src\qf\qep_hsm.c
346 34.0 6.3 220.6 9 ..\src\qf\qep_msm.c
59 12.8 3.5 83.2 4 ..\src\qf\qf_act.c
257 25.7 3.9 152.1 9 ..\src\qf\qf_actq.c
66 19.7 2.0 107.0 3 ..\src\qf\qf_defer.c
126 16.7 2.7 107.4 7 ..\src\qf\qf_dyn.c
105 24.5 3.5 161.2 4 ..\src\qf\qf_mem.c
103 18.6 4.2 121.2 5 ..\src\qf\qf_ps.c
16 14.0 2.0 71.0 1 ..\src\qf\qf_qact.c
146 34.8 4.8 202.5 4 ..\src\qf\qf_qeq.c
16 14.0 2.0 78.0 1 ..\src\qf\qf_qmact.c
211 25.2 4.1 154.5 8 ..\src\qf\qf_time.c
180 19.0 4.2 107.1 9 ..\src\qk\qk.c
73 16.2 3.8 96.2 4 ..\src\qv\qv.c
243 23.3 4.6 142.0 10 ..\src\qxk\qxk.c
199 48.0 10.5 368.0 4 ..\src\qxk\qxk_mutex.c
101 23.5 4.0 156.5 4 ..\src\qxk\qxk_sema.c
339 22.3 3.6 150.9 14 ..\src\qxk\qxk_xthr.c
19 0.0 0.0 0.0 0 ..\src\qf_pkg.h
30 0.0 0.0 0.0 0 ..\src\qs_pkg.h
16 0.0 0.0 0.0 0 ..\src\qxk_pkg.h
=========================================================================================================
!!!! Warnings (cyclomatic_complexity > 20 or length > 500 or nloc > 1000000 or parameter_count > 10) !!!!
================================================
NLOC CCN token PARAM length location
------------------------------------------------
122 23 847 2 185 QMsm_dispatch_@210-394@..\src\qf\qep_msm.c
==========================================================================================
Total nloc Avg.NLOC AvgCCN Avg.token Fun Cnt Warning cnt Fun Rt nloc Rt
------------------------------------------------------------------------------------------
3653 21.6 3.9 137.3 129 1 0.01 0.04
@endcode
*/

80
doxygen/modules.dox → doxygen/modules-unused.dox
View File

@ -1,3 +1,9 @@
/*! @defgroup qp QP
@brief
QP Framework
*/
/*##########################################################################*/
/*! @defgroup qep QEP
@brief
@ -34,11 +40,11 @@ QV is a simple **cooperative** kernel (previously called "Vanilla" kernel). This
The QV scheduler is described in Section 6.3.7 of the book ["Practical UML Statecharts in C/C++, 2nd Ed" (PSiCC2)](https://www.state-machine.com/psicc2/).
@section qv_overview QV Overview
The QV scheduler is engaged after every RTC step of any active object to choose the next active object to execute. The QV scheduler always chooses the highest-priority active object that has any events in its event queue. The QV scheduler then extracts the next event from this queue and dispatches it to the state machine associated with the active object. The state machine runs to completion, after which the QV scheduler runs and the cycle repeats.
![QV scheduler operation](qv.gif)
@image html qv.png "QV scheduler operation"
@image latex qv.png "QV scheduler operation"
Please note that because the state machines always return to the QV scheduler after each RTC step, a single stack can be used to process all state machines (memory-friendly architecture).
@ -47,9 +53,11 @@ The QV scheduler can also very easily detect when all event queues are empty, at
Given the simplicity, portability, and low-resource consumption, the QV scheduler is very attractive. It allows you to partition the problem into active objects and execute these active objects orderly. The thread-level response of this scheduler is the longest RTC step in the whole system, but because event-driven active objects don’t block, the RTC steps tend to be very short (typically just a few microseconds). Also, often you can break up longer RTC steps into shorter pieces, by posting an event to self and returning (“Reminder” state pattern). The self-posted event then triggers the continuation of longer processing.
@remarks
Sometimes it is not practical to break up long RTC steps, and consequently the thread-level response of the simple @ref qv "QV kernel" might be too slow. In this cases you need to use a *preemptive* kernel. The big advantage of preemptive kernel is that it effectively decouples high-priority thread from low-priority threads in the time domain. The timeliness of execution of high-priority thread is almost independent on the low-priority threads. But of course there is no such thing as a free lunch. Preemptive kernels open the whole new class of problems related to race conditions. So you need to be very careful about sharing any resources.
Sometimes it is not practical to break up long RTC steps, and consequently the thread-level response of the simple @ref srs_qv "QV kernel" might be too slow. In this cases you need to use a *preemptive* kernel. The big advantage of preemptive kernel is that it effectively decouples high-priority thread from low-priority threads in the time domain. The timeliness of execution of high-priority thread is almost independent on the low-priority threads. But of course there is no such thing as a free lunch. Preemptive kernels open the whole new class of problems related to race conditions. So you need to be very careful about sharing any resources.
@next{qk}
@ifnot LATEX
@nav_next{qk}
@endif
*/
/*##########################################################################*/
/*! @defgroup qk QK
@ -57,44 +65,45 @@ Sometimes it is not practical to break up long RTC steps, and consequently the t
@brief
Preemptive Run-To-Completion (Non-Blocking) Kernel
<p>The preemptive, non-blocking QK kernel is specifically designed to execute non-blocking active objects (see also [[PSiCC2](https://www.state-machine.com/psicc2/), Chapter 10]). QK runs active objects in the same way as prioritized interrupt controller (such as NVIC in ARM Cortex-M) runs interrupts using **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. <span class="highlight">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</span>.
</p>
The preemptive, non-blocking QK kernel is specifically designed to execute non-blocking active objects (see also [[PSiCC2](https://www.state-machine.com/psicc2/), Chapter 10]). QK runs active objects in the same way as prioritized interrupt controller (such as NVIC in ARM Cortex-M) runs interrupts using **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. <span class="highlight">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</span>.
@note
The non-blocking, run-to-completion, preemptive threads are known in the literature as "basic threads" (OSEK/AUTOSAR terminology), sometimes also called "fibers" (e.g., Q-Kernel) or "software interrupts" (e.g., TI-RTOS).
@section qk_overview QK Overview
The preemptive, run-to-completion (RTC) QK kernel breaks entirely with the endless-loop structure of the thread routines and instead uses threads structured as one-shot, discrete, run-to-completion functions, very much like ISRs [[PSiCC2](https://www.state-machine.com/psicc2/), Chapter 10]. In fact, the QK kernel views interrupts very much like threads of a “super-high” priority, except that interrupts are prioritized in hardware by the interrupt controller, whereas threads are prioritized in software by the RTC kernel.
As a fully preemptive multithreading kernel, QK must ensure that at all times the CPU executes the highest-priority thread (active object) that is ready to run. Fortunately, only two scenarios can lead to readying a higher-priority thread:
<ul class="tag">
<li><span class="tag">1</span>
When a lower-priority thread posts an event to a higher-priority thread, the kernel must immediately suspend the execution of the lower-priority thread and start the higher-priority thread. This type of preemption is called <b>synchronous preemption</b> because it happens synchronously with posting an event to the thread's event queue.
> NOTE: The stack usage shown in the bottom panel displays stack growing down (towards lower addresses), as it is the case in ARM Cortex-M.
</li>
</ul>
`[1]` When a lower-priority thread posts an event to a higher-priority thread, the kernel must immediately suspend the execution of the lower-priority thread and start the higher-priority thread. This type of preemption is called <b>synchronous preemption</b> because it happens synchronously with posting an event to the thread's event queue.
@note
The stack usage shown in the bottom panel displays stack growing down (towards lower addresses), as it is the case in ARM Cortex-M.
@anchor qk-synch-fig
@image html qk_synch.gif "Synchronous Preemption in QK"
@image html qk_synch.png
@image latex qk_synch.png width=5.0in
@caption{Synchronous Preemption in QK}
`[2]` When an interrupt posts an event to a higher-priority thread than the interrupted thread, upon completion of the ISR the kernel must start execution of the higher-priority thread instead of resuming the lower-priority thread. This type of preemption is called <b>asynchronous preemption</b> because it can happen asynchronously, any time interrupts are not explicitly disabled.
@note
The stack usage during asynchronous preemption on ARM Cortex-M is slightly simplified in the diagram below. A more detailed stack usage diagram is discussed later in the section explaining the @ref arm-cm_qk_port-asm_pendsv "Detailed stack allocation in QK for ARM Cortex-M".
<ul class="tag">
<li><span class="tag">2</span>
When an interrupt posts an event to a higher-priority thread than the interrupted thread, upon completion of the ISR the kernel must start execution of the higher-priority thread instead of resuming the lower-priority thread. This type of preemption is called <b>asynchronous preemption</b> because it can happen asynchronously, any time interrupts are not explicitly disabled.
> NOTE: The stack usage during asynchronous preemption on ARM Cortex-M is slightly simplified in the diagram below. A more detailed stack usage diagram is discussed later in the section explaining the @ref arm-cm_qk_port-asm_pendsv "Detailed stack allocation in QK for ARM Cortex-M".
</li>
</ul>
@anchor qk-asynch-fig
@image html qk_asynch.gif "Asynchronous Preemption in QK"
@image html qk_asynch.png
@image latex qk_asynch.png width=5.0in
@caption{Asynchronous Preemption in QK}
@note
A traditional RTOS kernel does not distinguish between the synchronous and asynchronous preemptions and makes all preemptions look like the more stack-intensive asynchronous preemptions. In contrast, a RTC kernel can implement synchronous preemption as a simple function call (to QK_activate_()), which is much more efficient than a full context-switch.
@next{qxk}
@ifnot LATEX
@nav_next{qxk}
@endif
*/
/*##########################################################################*/
/*! @defgroup qxk QXK
@ -102,9 +111,9 @@ A traditional RTOS kernel does not distinguish between the synchronous and async
@brief
Preemptive Dual-Mode (Run-to-Completion/Blocking) RTOS Kernel
QXK is a small, preemptive, priority-based, dual-mode **blocking** kernel that executes active objects like the @ref qk "QK kernel" (@ref qxk_basic "basic threads"), but can also execute traditional __blocking__ threads (@ref qxk_extended "extended threads"). In this respect, QXK behaves exactly like a __conventional RTOS__ (Real-Time Operating System).
QXK is a small, preemptive, priority-based, dual-mode **blocking** kernel that executes active objects like the @ref srs_qk "QK kernel" (@ref srs_qxk_basic "basic threads"), but can also execute traditional __blocking__ threads (@ref srs_qxk_extended "extended threads"). In this respect, QXK behaves exactly like 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. To this end, QXK is not only more efficient than running QP on top of a @ref ports_rtos "traditional 3rd-party RTOS" (because non-blocking @ref qxk_basic "basic threads" take far less stack space and CPU cycles for context switch than the much heavier @ref qxk_extended "extended threads"). But the biggest advantage of QXK is that it __protects__ the application-level code from inadvertent mixing of blocking calls inside the event-driven active objects. Specifically, QXK "knows" the type of the thread context (extended/basic) and asserts internally if a blocking call (e.g., semaphore-wait or a time-delay) is attempted in a basic thread (active object). This is something that a QP port to a @ref ports_rtos "conventional 3rd-party RTOS" cannot do, because such an RTOS runs all code (including active objects) in the context of havyweight extended threads.
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. To this end, QXK is not only more efficient than running QP on top of a @ref ports_rtos "traditional 3rd-party RTOS" (because non-blocking @ref srs_qxk_basic "basic threads" take far less stack space and CPU cycles for context switch than the much heavier @ref srs_qxk_extended "extended threads"). But the biggest advantage of QXK is that it __protects__ the application-level code from inadvertent mixing of blocking calls inside the event-driven active objects. Specifically, QXK "knows" the type of the thread context (extended/basic) and asserts internally if a blocking call (e.g., semaphore-wait or a time-delay) is attempted in a basic thread (active object). This is something that a QP port to a @ref ports_rtos "conventional 3rd-party RTOS" cannot do, because such an RTOS runs all code (including active objects) in the context of havyweight extended threads.
Currently, the QXK kernel has been ported to the following CPUs:
@ -124,13 +133,12 @@ Example illustrates: 6 active objects plus two extended threads, QXK blocking de
@section qxk_basic Basic Threads
QXK supports **basic**-threads (non-blocking, run-to-completion activations). The basic-threads all nest on the same stack (Main Stack Pointer in ARM Cortex-M), so the stack usage is reduced. The additional advantage of basic-threads is that switching from basic-thread to another basic-thread requires only @ref QXK_activate_() "activation" of the basic-thread, which is much simpler and faster than full context-switch required for @ref qxk_extended "extended"-threads that QXK also supports (see below).
QXK supports **basic**-threads (non-blocking, run-to-completion activations). The basic-threads all nest on the same stack (Main Stack Pointer in ARM Cortex-M), so the stack usage is reduced. The additional advantage of basic-threads is that switching from basic-thread to another basic-thread requires only @ref srs_qxk_activate_() "activation" of the basic-thread, which is much simpler and faster than full context-switch required for @ref srs_qxk_extended "extended"-threads that QXK also supports (see below).
@remarks
QXK adopts the "basic/exteded thread" terms from the <a class="extern" target="_blank" href="https://www.autosar.org">OSEK/AUTOSAR Operating System</a> specification. Other real-time kernels might use different terminology for similar concepts. For example, the <a class="extern" target="_blank" href="http://www.quasarsoft.com/">Q-Kernel</a> uses the term "fibers", while <a class="extern" target="_blank" href="http://www.ti.com/tool/TI-RTOS">TI-RTOS</a> uses the term "software interrupts" for concepts closely related to "basic threads".
@section qxk_extended Extended Threads
QXK supports **extended**-threads (blocking, typically structrued as endless loops). The extended-threads use private per-thread stacks, as in conventional RTOS kernels. Any switching from basic-to-extended thread or extended-to-extended thread requires full context switch.
@ -143,27 +151,21 @@ QXK is a unique dual-mode kernel on the market that supports interleaving the pr
@section qxk_classes Classes in QXK
The figure below shows the main classes introduced in the QXK kernel and their relation to the classes of the QP framework.
@image html qxk_classes.gif "Classes of the QXK dual-mode kernel"
@image html qxk_classes.png "Classes of the QXK dual-mode kernel"
@image latex qxk_classes.png "Classes of the QXK dual-mode kernel"
<ul class="tag">
<li><span class="tag">0</span> The abstract ::QActive class represents active objects in QP. This class contains the @c thread object of the underlying kernel (QXK thread-control-block in this case) as well as the event queue and the unique priority of the active object.
</li>
`[0]` The abstract ::QActive class represents active objects in QP. This class contains the @c thread object of the underlying kernel (QXK thread-control-block in this case) as well as the event queue and the unique priority of the active object.
<li><span class="tag">1</span> The ::QXThread class represents the extended (blocking) threads of the QXK kernel. It inherits ::QActive, so that extended-threads can be treated as active objects internally in the framework. However, the extended-threads **do not implement state machines**. Instead, the data fields used for storing the current state in active objects are re-used to store the private stack of the extended-thread. The ::QXThread class also contains the @c timeEvt object (see ::QTimeEvt) for generating timeouts when the extended-thread is blocked.
</li>
`[1]` The ::QXThread class represents the extended (blocking) threads of the QXK kernel. It inherits ::QActive, so that extended-threads can be treated as active objects internally in the framework. However, the extended-threads **do not implement state machines**. Instead, the data fields used for storing the current state in active objects are re-used to store the private stack of the extended-thread. The ::QXThread class also contains the @c timeEvt object (see ::QTimeEvt) for generating timeouts when the extended-thread is blocked.
<li><span class="tag">2</span> The ::QXMutex class represents the **priority-ceiling mutex** of the QXK kernel. The mutex can block and can be used only in the extended-threads (in case they share resources that need to be protected). The mutex is recursive, meaning that it can be locked multiple times from the same extended thread (but it needs to be unlocked equal number of times).
</li>
`[2]` The ::QXMutex class represents the **priority-ceiling mutex** of the QXK kernel. The mutex can block and can be used only in the extended-threads (in case they share resources that need to be protected). The mutex is recursive, meaning that it can be locked multiple times from the same extended thread (but it needs to be unlocked equal number of times).
<li><span class="tag">3</span> The ::QXSemaphore class represents the **counting semaphore** of the QXK kernel. The semaphore can be waited on only in the extended-threads and the QXK kernel would assert if an active object thread would attempt to wait on a semaphore. On the other hand, a semaphore can be signaled from anywhere in the code, including active objects and ISRs.
</li>
</ul>
`[3]` The ::QXSemaphore class represents the **counting semaphore** of the QXK kernel. The semaphore can be waited on only in the extended-threads and the QXK kernel would assert if an active object thread would attempt to wait on a semaphore. On the other hand, a semaphore can be signaled from anywhere in the code, including active objects and ISRs.
@note
The main takeaway from the QXK class diagram is QXK's **optimal, tight integration** with the QP framework. The QXK kernel 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 @ref ports_rtos "3rd-party RTOS kernels" to run QP applications.
@section qxk_features QXK Feature Summary
As you can see in the list below, <span class="highlight">QXK provides most features you might expect of a traditional blocking **RTOS** kernel and is <strong>recommended</strong> as the preferred RTOS kernel for QP applications</span> that need to mix active objects with traditional blocking code.
@ -212,7 +214,7 @@ As you can see in the list below, <span class="highlight">QXK provides most feat
> NOTE: This feature is only supported on CPUs that allow selective interrupt disabling, such as ARM Cortex-M3/M4 (but not ARM Cortex-M0/M0+);
<li><span class="bullet">&gt;</span> @ref qxk_tls "Thread-Local Storage" for all threads (basic threads and extended threads).
<li><span class="bullet">&gt;</span> @ref srs_qxk_tls "Thread-Local Storage" for all threads (basic threads and extended threads).
</li>
</ul>

8
doxygen/notes.txt Normal file
View File

@ -0,0 +1,8 @@
main.dox
@note
<a href="https://www.state-machine.com/products/qp#CERT" title="QP Cert-Pack"><img class="right" src="cert-pack.png"></img></a>
The @webref{products/qp#CERT,QP Certification Pack} provides:
- @ref srs "Software Requirements Specification" with a good @ref srs_over "overview" of the QP/C Framework
- @ref sas "Software Architecture Specification" with concise description of QP/C @ref sas_core "architecture"
- @ref sds "Software Design Specification" with detailed description of the QP/C @ref sds "design".

246
doxygen/ports.dox
View File

@ -5,121 +5,171 @@ The QP/C framework can be easily adapted to various operating systems, processor
The QP/C distribution contains many QP/C ports, which are organized into the three categories:
- @subpage ports_native "Native Ports" adapt QP/C to run on bare-metal processors "natively", using one of the built-in kernels (@ref qv "QV", @ref qk "QK", or @ref qxk "QXK")
- @subpage ports_lint (generic C compiler) QP/C "port" to the PC-Lint Plus static analysis tool (a "compiler")
- @subpage ports_native "Native Ports" adapt QP/C to run on bare-metal processors "natively", using one of the built-in kernels (@ref srs_qv "QV", @ref srs_qk "QK", or @ref srs_qxk "QXK")
- @subpage ports_rtos "3rd-Party RTOS Ports" adapt QP/C to run on top of a 3rd-Party Real-Time Operating System (RTOS)
- @subpage ports_os "3rd-Party OS Ports" adapt QP/C to run on top of a 3rd-Party Operating System (OS), such as @ref win32 "Windows" or @ref posix "Linux".
@section ports_code Port Code Structure
Starting with QP/C release 5.4.0, **all** available ports are bundled into the QP/C download, as opposed to being distributed as separate QP Development Kits (QDKs). The main benefit is of this approach is that it greatly reduces chances of mistakes in combining the mainline QP/C code with various QDKs. The downside is that the QP/C distribution becomes quite large and that ports cannot be added or updated independently from the QP/C baseline code.
All ports are located in sub-directories of the <span class="img folder">ports</span> top-level folder, with the hierarchical organization outlined below:
<ul class="tag">
<li><span class="img folder">ports/</span>
</li>
<ul class="tag">
<li><span class="img folder">arm-cm/</span> &mdash; Native ports for ARM-Cortex-M (bare-metal) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <span class="tag">A</span>
</li>
<ul class="tag">
<li><span class="img folder">qk/</span> &mdash; Port to the @ref qk "preemptive QK kernel"
</li>
<ul class="tag">
<li><span class="img folder">arm</span> &mdash; Port to ARM-KEIL toolset
</li>
<li><span class="img folder">gnu</span> &mdash; Port to GNU toolset
</li>
<li><span class="img folder">iar</span> &mdash; Port to IAR toolset
</li>
<li><span class="img folder">ti</span> &mdash; Port to TI/CCS toolset
</li>
</ul>
<li><span class="img folder">qv/</span> &mdash; Port to the @ref qv "cooperative QV kernel"
</li>
<ul class="tag">
<li><span class="img folder">arm</span> &mdash; Port to ARM-KEIL toolset
</li>
<li><span class="img folder">gnu</span> &mdash; Port to GNU toolset
</li>
<li><span class="img folder">iar</span> &mdash; Port to IAR toolset
</li>
<li><span class="img folder">ti</span> &mdash; Port to TI/CCS toolset
</li>
</ul>
<li><span class="img folder">qxk/</span> &mdash; Port to the @ref qxk "blocing QXK kernel"
</li>
<ul class="tag">
<li><span class="img folder">arm</span> &mdash; Port to ARM-KEIL toolset
</li>
<li><span class="img folder">gnu</span> &mdash; Port to GNU toolset
</li>
<li><span class="img folder">iar</span> &mdash; Port to IAR toolset
</li>
<li><span class="img folder">ti</span> &mdash; Port to TI/CCS toolset
</li>
</ul>
</ul>
<br>
@code{.c}
qpc/ // QP/C installation directory
+---ports/ // ports directory
| |
| [1]--arm-cm/ // ports for ARM Cortex-M
| | +---qk/ // ports for preemptive QK kernel
| | | +---armclang/ // port with ARM-Clang (Compiler Version 6) toolchain
| | | +---gnu/ // port with GNU-ARM toolchain
| | | +---iar/ // port with IAR toolchain
| | +---qv/ // ports for cooperative QV kernel
| | \---qxk/ // ports for dual-mode QXK kernel
| |
| [2]--freertos/ // ports for FreeRTOS (3rd-party RTOS)
| |
| [3]--win32/ // port to Win32 (multithreaded)
| | +---Debug/ // Debug build configuration for VC++ toolset
| | +---Release/ // Release build configuration for VC++ toolset
| | +---QSpy/ // Spy build configuration for VC++ toolset
| | +---dbg/ // Debug build configuration for GNU toolset
| | +---rel/ // Release build configuration for GNU toolset
| | \---spy/ // Spy build configuration for GNU toolset
| |
| [4]--win32-qv/ // port to Win32 (single-threaded)
| |
| [5]--posix/ // port to POSIX (multithreaded)
| |
| [6]--posix-qv/ // port to POSIX (single-threaded)
@endcode
<li><span class="img folder">ucos-ii/</span> &mdash; Port to uCOS-II (3rd-party RTOS) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <span class="tag">B</span>
</li>
<ul class="tag">
<li><span class="img folder">arm-cm</span> &mdash; Port to ARM-Cortex-M
</li>
<ul class="tag">
<li><span class="img folder">arm</span> &mdash; build with ARM toolset
</li>
<li><span class="img folder">iar</span> &mdash; build with IAR toolset
</li>
</ul>
</ul>
`[1]` **Native Ports** are located in sub-directories named after the CPU architecture, such as <span class="img folder">arm-cm</span> for ARM Cortex-M. Under that directory, the sub-directories <span class="img folder">qk</span> and <span class="img folder">qv</span> contain ports for the @ref comp_qk "QK" and @ref comp_qv "QV" kernels, respectively.
<li><span class="img folder">win32/</span> &mdash; Port to Win32 (Windows) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <span class="tag">C</span>
</li>
<ul class="tag">
<li><span class="img folder">Debug/</span> &mdash; Debug build configuration for VC++ toolset
</li>
<li><span class="img folder">dbg/</span> &mdash; Debug build configuration for MinGW toolset
</li>
<li><span class="img folder">Release/</span> &mdash; Release build configuration for VC++ toolset
</li>
<li><span class="img folder">rel/</span> &mdash; Release build configuration for MinGW toolset
</li>
<li><span class="img folder">QSpy/</span> &mdash; Spy build configuration for VC++ toolset
</li>
<li><span class="img folder">spy/</span> &mdash; Spy build configuration for MinGW toolset
</li>
</ul>
`[2]` **Ports for 3rd-party RTOS** are located in sub-directories named after the RTOS, such as <span class="img folder">uc-os2</span> for uc-os2 RTOS. Under that directory, the sub-directories, such as <span class="img folder">arm-cm</span>, contain examples for the specified CPU architecture, such as ARM Cortex-M here.
<li><span class="img folder">posix/</span> &mdash; Port to POSIX (e.g., Linux) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <span class="tag">C</span>
</li>
<ul class="tag">
<li><span class="img folder">dbg/</span> &mdash; Debug build configuration for GNU toolset
</li>
<li><span class="img folder">rel/</span> &mdash; Release build configuration for GNU toolset
</li>
<li><span class="img folder">spy/</span> &mdash; Spy build configuration for GNU toolset
</li>
</ul>
</ul>
</ul>
`[3]` **Ports for 3rd-party OS** are located in sub-directories named after the OS, such as <span class="img folder">win32</span> for the Win32 API (Windows OS). (NOTE: The builds for desktop operating systems, such as Windows or Linux contain the pre-build QP libraries for the Debug, Release, and Spy build configurations).
<ul class="tag">
<li><span class="tag">A</span> **Native Ports** are located in sub-directories named after the CPU architecture, such as <span class="img folder">arm-cm</span> for ARM Cortex-M. Under that directory, the sub-directories <span class="img folder">qk</span> and <span class="img folder">qv</span> contain ports for the @ref comp_qk "QK" and @ref comp_qv "QV" kernels, respectively.
</li>
<li><span class="tag">B</span> **Ports for 3rd-party RTOS** are located in sub-directories named after the RTOS, such as <span class="img folder">ucos-ii</span> for uCOS-II RTOS. Under that directory, the sub-directories, such as <span class="img folder">arm-cm</span>, contain examples for the specified CPU architecture, such as ARM Cortex-M here.
</li>
<li><span class="tag">C</span> **Ports for 3rd-party OS** are located in sub-directories named after the OS, such as <span class="img folder">win32</span> for the Win32 API (Windows OS). (NOTE: The builds for desktop operating systems, such as Windows or Linux contain the pre-build QP libraries for the Debug, Release, and Spy build configurations).
</li>
</ul>
@note
Because the QP distribution contains *all* ports, the number of sub-directories and files in the <span class="img folder">ports</span> folder may seem daunting. However, knowing the structure of the <span class="img folder">ports</span> folder, you can simply **delete** the sub-directories that are not interesting to you.
@next{ports_native}
@ifnot LATEX
@nav_next{ports_lint}
@endif
*/
/*##########################################################################*/
/*! @page ports_lint PC-Lint-Plus
@image html pc-lint-plus.png "PC-Lint Plus"
@image latex pc-lint-plus.png "PC-Lint Plus" width=2in
The QP/C distribution contains a "port" to <a href="https://pclintplus.com" target="_blank" class="extern"><b>PC-Lint-Plus</b></a> static analysis tool from <a href="https://www.vector.com" target="_blank" class="extern">Vector</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-Plus port" allows you to statically analyze the QP/C source code and facilitates static analysis of your **application code** based on QP/C.
The QP/C "port" to PC-Lint-Plus is located in the directory <span class="img folder">qpc/ports/lint-plus</span> and includes also lint configuration files, as well as an example of "linting" application code in the directory <span class="img folder">qpc/examples/arm-cm/dpp_ek-tm4c123gxl/lint-plus</span>. The following listing describes the most important files in these three directories.
<br>
@code{.c}
qpc/ // QP/C installation directory
+---ports/ // ports directory
| +---lint-plus/ // "port" to PC-Lint-Plus
| | +---16bit/ // "port" to 16-bit CPUs
| | | +-cpu.lnt // Lint options for a 16-bit CPU
| | | \-stdint.h // Standard exact-width integers for a 16-bit CPU
| | +---32bit/ // "port" to 16-bit CPUs
| | | +-cpu.lnt // Lint options for a 32-bit CPU
| | | \-stdint.h // Standard exact-width integers for a 32-bit CPU
| | +---qk/ // port with the QK kernel
| | +---qv/ // port with the QV kernel
| | +---qxk/ // port with the QXK kernel
| |
| | au-ds.lnt // Dan Saks recommendations
| | au-misra3.lnt // MISRA-C:2012 compliance checks
| | au-misra3-amd1.lnt // MISRA-C:2012-Amendment-1 additional checks
| | au-misra3-amd2.lnt // MISRA-C:2012-Amendment-2 additional checks
| | qpc.lnt // PC-Lint-Plus options for applications
| | std.lnt // Standard PC-Lint-Plus settings recommended by Quantum Leaps
| | lin.bat // Batch file to invoke PC-Lint-Plus to run analysis of QP/C code
| | options.lnt // PC/Lint-Plus options for "linting" QP/C source code
| | lint_qf.log // PC/Lint-Plus output for the QEP/QF components of QP/C
| | lint_qs.log // PC/Lint-Plus output for the QS component of QP/C
| | lint_qv.log // PC/Lint-Plus output for the QV component of QP/C
| | lint_qk.log // PC/Lint-Plus output for the QK component of QP/C
| | lint_qxk.log // PC/Lint-Plus output for the QXK component of QP/C
| | qep_port.h // QEP component "port" to a "generic C compiler"
| | stdbool.h // Standard Boolean type and constants for a "generic C compiler"
|
+---examples/ // examples directory (application)
| +---arm-cm/ // examples for ARM Cortex-M
| | +---dpp_ek-tm4c123gxl/ // DPP example on the EK-TM4C123GLX board
| | | +---lint-plus/ // directory for linting the application
| | |
| | | lin.bat // Batch to run PC-Lint-Plus analysis of application code
| | | options.lnt // PC-Lint-Plus 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-plus</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-Plus 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 `PCLP_DIR` at the top of the batch file, to the PC-Lint-Plus installation directory on your computer.
@remarks
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 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-Plus guidelines, the `lin.bat` uses two option files: the `qpc.lnt` configuration file discussed before and the `options.lnt` configuration file that covers all deviations from the MISRA-C rules **within the QP/C source code**. These deviations are intentionally localized to QP/C code and are independent from your **application-level** code. In other words, a MISRA-C deviation present in the QP/C code does **not** mean that such deviation is somehow allowed or its detection is somehow suppressed in the **application-level** code. This is because the the `options.lnt` configuration file for internals of QP/C is **not** used to "lint" the application-level code.
@section lint_app Linting QP/C Application Code
The QP/C baseline code contains an example of MISRA-C compliance checking with PC-Lint-Plus: 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-plus</span>. The PC-Lint-Plus analysis is very simple and requires invoking the **lin.bat** file.
@note
In order to execute the **lin.bat** file on your system, you might need to adjust the symbol `PCLP_DIR` at the top of the batch file, to the PC-Lint-Plus installation directory on your computer. You
The `lint-plus` subdirectory contains also the local version of the `options.lnt` configuration file with the PC-Lint-Plus options specific to linting the application. Here, you might include linting options for your specific compiler, as described in the "PC-Lint-Plus Manual", Chapter 2 "Installation and Configuration".
@section lint_options Structure of PC-Lint-Plus Options for QP/C
PC-Lint-Plus has several places where it reads its currently valid options:
- From special PC-Lint-Plus 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-Plus option files used for "linting" QP/C follows the <a href="http://www.gimpel.com" target="_blank" class="extern">Gimpel Software</a> guidelines for configuring PC-Lint-Plus (See Section 2 "Configuration" in the *PC-Lint-Plus 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-Plus 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-Plus "port" files description, the directory <span class="img folder">qpc/include</span>, contains the PC-Lint-Plus 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-Plus accomplishes both inclusion of QP/C header files and PC-Lint-Plus options.
Note that the `qpc/include` directory contains all PC-Lint-Plus option files used in "linting" the code, including the standard MISRA-C:2012 `au-misr3.lnt` option file as well as Dan Saks' recommendations `au-ds.lnt`, which are copied from the PC-Lint-Plus distribution. This design freezes the lint options for which the compliance has been checked.
@subsection lint_std_lnt The std.lnt option file
According to the Gimpel Software *PC-Lint-Plus 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-Plus 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
@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:2012 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:2012 rules.
At the same time, the **qpc.lnt** option file has been very carefully designed not to suppress any MISRA-C:2012 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:2012 rule checks that PC-Lint-Plus is capable of performing.
@remarks
For example, for reasons explained in Section 5.10 of the <a href="https://www.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:2012 advisory Rule 4.9 and which PC-Lint-Plus checks with the warning 9026. However, instead of suppressing this warning globally (with the -e9096 directive), the qpc.lnt option file suppresses warning 9096 only for the specific QP function-like macros that are visible to the application level. So specifically, the qpc.lnt file contains directives `-esym(9026, 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.
@ifnot LATEX
@nav_next{ports_native}
@endif
*/

1063
doxygen/ports_arm-cm.dox
View File

File diff suppressed because it is too large Load Diff

151
doxygen/ports_native.dox
View File

@ -1,7 +1,6 @@
/*##########################################################################*/
/*! @page ports_native Native (Bare-Metal) Ports
- @subpage lint (generic C compiler)
- @subpage arm-cm (Cortex-M0/M0+/M3/M4/M4/M7)
- @ref arm-cm_qv (ARM-CLANG, ARM-KEIL, GNU-ARM, IAR-ARM )
- @ref arm-cm_qk (ARM-CLANG, ARM-KEIL, GNU-ARM, IAR-ARM)
@ -16,148 +15,46 @@
- @ref msp430_qv (TI-CCS, IAR toolchains)
- @ref msp430_qk (TI-CCS, IAR toolchains)
*/
/*##########################################################################*/
/*! @page lint PC-Lint-Plus
@tableofcontents
<p>The QP/C distribution contains a "port" to <a href="https://www.gimpel.com" target="_blank" class="extern"><b>PC-Lint-Plus</b></a> static analysis tool from <a href="https://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-Plus 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-Plus is located in the directory <span class="img folder">qpc/ports/lint-plus</span> and includes also lint configuration files, as well as an example of "linting" application code in the directory <span class="img folder">qpc/examples/arm-cm/dpp_ek-tm4c123gxl/lint-plus</span>. The following listing describes the most important files in these three directories.
@code{.x}
qpc\ - QP/C installation directory
+-ports/ - QP/C ports directory
| +-lint-plus/ - QP/C "port" to PC-Lint-Plus
| | +-16bit/ - QP/C++ "port" to 16-bit CPUs
| | | +-cpu.lnt - Lint options for a 16-bit CPU
| | | +-stdint.h - Standard exact-width integers for a 16-bit CPU
| | +-32bit/ - QP/C++ "port" to 32-bit CPUs
| | | +-cpu.lnt - Lint options for a 32-bit CPU
| | | +-stdint.h - Standard exact-width integers for a 32-bit CPU
| | +-qk/ - QP/C port with the QK kernel
| | +-qv/ - QP/C port with the QV kernel
| | +-qxk/ - QP/C port with the QXK kernel
| | +-au-ds.lnt - Dan Saks recommendations
| | +-au-misra3.lnt - MISRA-C:2012 compliance checks
| | +-au-misra3-amd1.lnt - MISRA-C:2012-Amendment-1 additional checks
| | +-qpc.lnt - PC-Lint-Plus options for QP/C applications
| | +-std.lnt - Standard PC-Lint-Plus settings recommended by Quantum Leaps
| | +-lin.bat - Batch file to invoke PC-Lint-Plus to run analysis of QP/C code
| | +-options.lnt - PC/Lint-Plus options for "linting" QP/C source code
| | +-lint_qf.log - PC/Lint-Plus output for the QEP/QF components of QP/C
| | +-lint_qs.log - PC/Lint-Plus output for the QS component of QP/C
| | +-lint_qv.log - PC/Lint-Plus output for the QV component of QP/C
| | +-lint_qk.log - PC/Lint-Plus output for the QK component of QP/C
| | +-lint_qxk.log - PC/Lint-Plus output for the QXK component of QP/C
| | +-qep_port.h - QEP component "port" to a "generic C compiler"
| | +-stdbool.h - Standard Boolean type and constants for a "generic 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-plus\ - directory for linting the application
| | | | +-lin.bat - Batch to run PC-Lint-Plus analysis of application code
| | | | +-options.lnt - PC-Lint-Plus 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-plus</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-Plus 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 `PCLP_DIR` at the top of the batch file, to the PC-Lint-Plus installation directory on your computer.
@remarks
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 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-Plus guidelines, the `lin.bat` uses two option files: the `qpc.lnt` configuration file discussed before and the `options.lnt` configuration file that covers all deviations from the MISRA-C rules **within the QP/C source code**. These deviations are intentionally localized to QP/C code and are independent from your **application-level** code. In other words, a MISRA-C deviation present in the QP/C code does **not** mean that such deviation is somehow allowed or its detection is somehow suppressed in the **application-level** code. This is because the the `options.lnt` configuration file for internals of QP/C is **not** used to "lint" the application-level code.
@section lint_app Linting QP/C Application Code
The QP/C baseline code contains an example of MISRA-C compliance checking with PC-Lint-Plus: 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-plus</span>. The PC-Lint-Plus analysis is very simple and requires invoking the **lin.bat** file.
@note
In order to execute the **lin.bat** file on your system, you might need to adjust the symbol `PCLP_DIR` at the top of the batch file, to the PC-Lint-Plus installation directory on your computer. You
The `lint-plus` subdirectory contains also the local version of the `options.lnt` configuration file with the PC-Lint-Plus options specific to linting the application. Here, you might include linting options for your specific compiler, as described in the "PC-Lint-Plus Manual", Chapter 2 "Installation and Configuration".
@section lint_options Structure of PC-Lint-Plus Options for QP/C
PC-Lint-Plus has several places where it reads its currently valid options:
- From special PC-Lint-Plus 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-Plus option files used for "linting" QP/C follows the <a href="http://www.gimpel.com" target="_blank" class="extern">Gimpel Software</a> guidelines for configuring PC-Lint-Plus (See Section 2 "Configuration" in the *PC-Lint-Plus 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-Plus 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-Plus "port" files description, the directory <span class="img folder">qpc/include</span>, contains the PC-Lint-Plus 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-Plus accomplishes both inclusion of QP/C header files and PC-Lint-Plus options.
Note that the `qpc/include` directory contains all PC-Lint-Plus option files used in "linting" the code, including the standard MISRA-C:2012 `au-misr3.lnt` option file as well as Dan Saks' recommendations `au-ds.lnt`, which are copied from the PC-Lint-Plus distribution. This design freezes the lint options for which the compliance has been checked.
@subsection lint_std_lnt The std.lnt option file
According to the Gimpel Software *PC-Lint-Plus 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-Plus 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
@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:2012 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:2012 rules.
At the same time, the **qpc.lnt** option file has been very carefully designed not to suppress any MISRA-C:2012 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:2012 rule checks that PC-Lint-Plus is capable of performing.
@remarks
For example, for reasons explained in Section 5.10 of the <a href="https://www.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:2012 advisory Rule 4.9 and which PC-Lint-Plus checks with the warning 9026. However, instead of suppressing this warning globally (with the -e9096 directive), the qpc.lnt option file suppresses warning 9096 only for the specific QP function-like macros that are visible to the application level. So specifically, the qpc.lnt file contains directives `-esym(9026, 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}
@ifnot LATEX
@nav_next{arm-cm}
@endif
*/
/*##########################################################################*/
/*! @page arm-cr ARM Cortex-R
@image html under_construction.jpg
The QP/C/C++ ports and examples for ARM Cortex-R are described in the Quantum Leaps Application Note @webref{doc/AN_QP_and_ARM-Cortex-R.pdf, QP and ARM Cortex-R}.
@section arm-cr_qk Preemptive QK Kernel
@image html AN-QL.png
@image latex AN-QL.png width=2.0in
@caption{[Application Note: "QP and ARM Cortex-R"](https://www.state-machine.com/doc/AN_QP_and_ARM-Cortex-R.pdf)}
@includelineno ports/arm-cr/qk/gnu/qk_port.h
@section arm-cr_qv Cooperative QV Kernel
@next{arm7-9}
@ifnot LATEX
@nav_next{arm7-9}
@endif
*/
/*##########################################################################*/
/*! @page arm7-9 ARM7/ARM9
@image html under_construction.jpg
The QP/C/C++ ports and examples for ARM7/ARM9 are described in the Quantum Leaps Application Note @webref{doc/AN_QP_and_ARM-Cortex-R.pdf, QP and ARM7/ARM9}.
@section arm7-9_qk Preemptive QK Kernel
@image html AN-QL.png
@image latex AN-QL.png width=2.0in
@caption{[Application Note: "QP and ARM7/ARM9"](https://www.state-machine.com/doc/AN_QP_and_ARM7_ARM9-GNU.pdf)}
@includelineno ports/arm7-9/qk/gnu/qk_port.s
@section arm7-9_qv Cooperative QV Kernel
@next{msp430}
@ifnot LATEX
@nav_next{msp430}
@endif
*/
/*##########################################################################*/
/*! @page msp430 MSP430
@image html under_construction.jpg
The QP/C/C++ ports and examples for MSP430 are described in the Quantum Leaps Development Kit @webref{doc/QDK_MSP430-CCS.pdf, QP and MSP430 with CCS} and @webref{doc/QDK_MSP430-IAR.pdf, QP and MSP430 with IAR}.
@section msp430_qk Preemptive QK Kernel
@section msp430_qv Cooperative QV Kernel
@image html AN-QL.png
@image latex AN-QL.png width=2.0in
@caption{[Application Note: "QP and MSP430-CCS"](https://www.state-machine.com/doc/QDK_MSP430-CCS.pdf)}
@image html AN-QL.png
@image latex AN-QL.png width=2.0in
@caption{[Application Note: "QP and MSP430-IAR"](https://www.state-machine.com/doc/QDK_MSP430-IAR.pdf)}
*/

2
doxygen/ports_os.dox
View File

@ -49,7 +49,7 @@ The standard QP/C distribution contains the POSIX port and @ref exa_os.
/*##########################################################################*/
/*! @page win32-qv Win32-QV (Windows with QV)
<p>The QP/C/C++ ports and examples for Windows with single-thread (like the @ref qv "QV cooperative kernel") are described in the Quantum Leaps Application Note <a class="extern" target="_blank" href="https://www.state-machine.com/doc/AN_QP_and_Win32.pdf"><strong>QP and Win32 (Windows)</strong></a>.
<p>The QP/C/C++ ports and examples for Windows with single-thread (like the @ref srs_qv "QV cooperative kernel") are described in the Quantum Leaps Application Note <a class="extern" target="_blank" href="https://www.state-machine.com/doc/AN_QP_and_Win32.pdf"><strong>QP and Win32 (Windows)</strong></a>.
</p>
@htmlonly

206
doxygen/ports_rtos.dox
View File

@ -10,7 +10,7 @@ Another reason you might be interested in running QP/C on top of a conventional
You do **not** need to use a traditional RTOS just to achieve preemptive multitasking with QP. The @ref comp_qk "preemptive QK kernel", available as part of the QP package, supports preemptive priority-based multitasking and is fully compatible with Rate Monotonic Scheduling to achieve guaranteed, hard real-time performance. The preemptive, run-to-completion QK kernel perfectly matches the run-to-completion execution semantics of active objects, yet it is simpler, faster, and more efficient than any traditional blocking kernel.
@attention
QP/C 6.x includes a small, preemptive, priority-based, @ref qxk "dual-mode blocking QXK kernel" that executes active objects like the QK kernel (@ref qxk_basic "basic threads"), but can also execute traditional blocking threads (@ref qxk_extended "extended threads"). In this respect, QXK behaves exactly like a conventional RTOS. The QXK kernel is recommended as the preferred RTOS kernel for applications that need to mix active objects with traditional blocking code. Due to the tight and optimal integration between QXK and the rest of QP, QXK offers better performance and smaller memory footprint than any @ref ports_rtos "QP port to a 3rd-party RTOS". Additionally, QXK is already included in QP, so you avoid additional licensing costs of 3rd-party kernels.
QP/C 6.x includes a small, preemptive, priority-based, @ref srs_qxk "dual-mode blocking QXK kernel" that executes active objects like the QK kernel (@ref srs_qxk_basic "basic threads"), but can also execute traditional blocking threads (@ref srs_qxk_extended "extended threads"). In this respect, QXK behaves exactly like a conventional RTOS. The QXK kernel is recommended as the preferred RTOS kernel for applications that need to mix active objects with traditional blocking code. Due to the tight and optimal integration between QXK and the rest of QP, QXK offers better performance and smaller memory footprint than any @ref ports_rtos "QP port to a 3rd-party RTOS". Additionally, QXK is already included in QP, so you avoid additional licensing costs of 3rd-party kernels.
The QP/C framework can work with virtually any traditional real-time operating
@ -20,35 +20,40 @@ system (RTOS). The currently supported 3rd-party RTOS kernels are:
- @subpage freertos
- @subpage threadx
- @subpage uc-os2
- @subpage zephyr
- <a href="https://www.erika-enterprise.com" target="_blank" class="extern">OSEK/VDX RTOS ERIKA Enterprise</a>
Combined with a conventional RTOS, QP/C takes full advantage of the multitasking capabilities of the RTOS by executing each active object in a separate RTOS task. The QP/C Platform Abstraction Layer (PAL) includes an abstract RTOS interface to enable integration between QP/C and the underlying RTOS. Specifically, the PAL allows adapting most message queue variants as event queues of active objects as well as most memory partitions as QP/C event pools.
@next{embos}
@ifnot LATEX
@nav_next{embos}
@endif
*/
/*##########################################################################*/
/*! @page embos embOS
<p>The QP/C/C++ ports and examples for embOS are described in the Quantum Leaps Application Note @webref{doc/AN_RTOS-embOS.pdf, QP and embOS}.
</p>
@image html logo_embos.png
@image latex logo_embos.png width=1.5in
@caption{SEGGER embOS}
@htmlonly
<div class="image">
<a target="_blank" href="https://www.state-machine.com/doc/AN_RTOS-embOS.pdf"><img border="0" src="img/AN.jpg" title="Download PDF"></a>
<div class="caption">
Application Note: QP and embOS
</div>
</div>
@endhtmlonly
The QP/C/C++ ports and examples for embOS are described in the Quantum Leaps Application Note @webref{doc/AN_RTOS-embOS.pdf, QP and embOS}.
@next{freertos}
@image html AN-QL.png
@image latex AN-QL.png width=2.0in
@caption{[Application Note: "QP and embOS"](https://www.state-machine.com/doc/AN_RTOS-embOS.pdf)}
@ifnot LATEX
@nav_next{freertos}
@endif
*/
/*##########################################################################*/
/*! @page freertos FreeRTOS
@tableofcontents
@image html logo_freertos.png
@image latex logo_freertos.png width=2.5in
@caption{FreeRTOS}
@section freertos_about About the QP Port to FreeRTOS
The <span class="img folder">ports/freertos/</span> directory contains a generic platform-independent QP/C port to <a href="https://freertos.org" target="_blank" class="extern">FreeRTOS kernel</a> (version 10). The provided QP port to FreeRTOS has been designed *generically* to rely exclusively on the existing FreeRTOS API. This means that the port should run without changes on any CPU/compiler platform supported by FreeRTOS.
@ -57,7 +62,7 @@ The QP-FreeRTOS port works as follows:
- The QP port uses the [static memory allocation of FreeRTOS](https://freertos.org/Static_Vs_Dynamic_Memory_Allocation.html). This requires the FreeRTOS configuration to define the [configSUPPORT_STATIC_ALLOCATION](https://freertos.org/a00110.html#configSUPPORT_STATIC_ALLOCATION)
- Each QP active object executes in a separate FreeRTOS task and requires a private stack space.
- Each QP active object executes in a separate FreeRTOS task (`StaticTask_t`) and requires a private stack space.
- The task-level critical section used in QF and QS is based on the FreeRTOS APIs `taskENTER_CRITICAL()`/`taskEXIT_CRITICAL()`.
@ -69,9 +74,7 @@ The QP-FreeRTOS port works as follows:
The design of FreeRTOS requires the use of special "FromISR" API inside ISRs, which imposes the requirement to also provide the "FromISR" variants of the QP APIs, such as `QACTIVE_POST_FROM_ISR()`, `QF_PUBLISH_FROM_ISR()`, etc. These "FromISR" QP APIs must be used inside ISRs instead of the task-level APIs (`QACTIVE_POST()`, `QF_PUBLISH()`, etc.) and conversely, they cannot be used inside tasks and active objects. Unfortunately, FreeRTOS provides no generic way to enforce the proper API use via assertions.
- The QP port uses the native event queue (::QEQueue) for active object event queues and internally calls the FreeRTOS API `xTaskNotifyGive()` to notify an active object when an event is posted to its event queue.
- The QP port internally calls the FreeRTOS API `ulTaskNotifyTake(pdTRUE, portMAX_DELAY)` to block an active object task when it waits for posting an event.
- The QP port uses the FreeRTOS message queue (`StaticQueue_t`) for active object event queues.
- The QP port uses the native QF memory pool (::QMPool) to implement event pools.
@ -79,37 +82,36 @@ The design of FreeRTOS requires the use of special "FromISR" API inside ISRs, wh
@section freertos_examples Example Code
The QP port to FreeRTOS comes with examples located in the directory `qpc/examples/freertos/`. Currently, the examples are provided for the following boards and development toolchains:
The QP port to FreeRTOS comes with examples located in the directory `qpc/examples/freertos`. Currently, the examples are provided for the following boards and development toolchains:
- EK-TM4C123GXL (ARM Cortex-M4F), ARM-KEIL, GNU-ARM, IAR-ARM
- STM32F746G-Discovery (ARM Cortex-M7), ARM-KEIL, GNU-ARM, IAR-ARM
@subsection freertos_isr Writing ISRs for QP/FreeRTOS
The provided examples show how to write regular "kernel-aware" ISRs as well as "kernel-unaware" ISRs for QP/FreeRTOS. (See also the FreeRTOS documentation for [configMAX_SYSCALL_INTERRUPT_PRIORITY](https://www.freertos.org/a00110.html#kernel_priority).
Here is an example of a regular "kernel-aware" ISR (note the use of the "FromISR" QP APIs"):
Here is an example of a regular "kernel-aware" ISR (note the use of the `FromISR` suffix in the QP APIs):
@code{c}
@code{.c}
/* NOTE: only the "FromISR" API variants are allowed in the ISRs! */
void GPIOPortA_IRQHandler(void) {
BaseType_t xHigherPriorityTaskWoken = pdFALSE;
/* for testing... */
/* for testing~~~ */
QACTIVE_POST_FROM_ISR(AO_Table,
Q_NEW_FROM_ISR(QEvt, MAX_PUB_SIG),
&xHigherPriorityTaskWoken,
&l_GPIOPortA_IRQHandler);
/* the usual end of FreeRTOS ISR... */
/* the usual end of FreeRTOS ISR~~~ */
portEND_SWITCHING_ISR(xHigherPriorityTaskWoken);
}
@endcode
Here is an example of a "kernel-unaware" ISR (See also the FreeRTOS documentation for [configMAX_SYSCALL_INTERRUPT_PRIORITY](https://www.freertos.org/a00110.html#kernel_priority):
Here is an example of a "kernel-unaware" ISR (See also the FreeRTOS documentation for [configMAX_SYSCALL_INTERRUPT_PRIORITY](https://www.freertos.org/a00110.html#kernel_priority) ):
@code{c}
@code{.c}
/*
* ISR for receiving bytes from the QSPY Back-End
* NOTE: This ISR is "kernel-unaware" meaning that it does not interact with
@ -132,7 +134,7 @@ void UART0_IRQHandler(void) {
@subsection freertos_hook Writing FreeRTOS Hooks Running in ISR Context
FreeRTOS provides "hooks" that are user functions that execute in the ISR context (e.g., `vApplicationTickHook()`). Such ISR-level functions are closely related to ISRs and should also use exclusively only the "FromISR" APIs. Here is an example of the `vApplicationTickHook()`:
@code{c}
@code{.c}
/* NOTE: only the "FromISR" API variants are allowed in vApplicationTickHook */
void vApplicationTickHook(void) {
BaseType_t xHigherPriorityTaskWoken = pdFALSE;
@ -149,7 +151,7 @@ void vApplicationTickHook(void) {
@subsection freertos_ao Starting Active Objects in QP/FreeRTOS
As mentioned in the @ref freertos_about "FreeRTOS port summary", the QP port to FreeRTOS uses the [static memory allocation of FreeRTOS](https://freertos.org/Static_Vs_Dynamic_Memory_Allocation.html). This means that all memory for an active object, including the private queue buffer and the private **stack** for the the associated FreeRTOS task must be allocated by the user. Here is an example code that starts an active object:
@code{c}
@code{.c}
int main() {
. . .
static QEvt const *tableQueueSto[N_PHILO];
@ -170,38 +172,40 @@ int main() {
}
@endcode
@next{threadx}
@ifnot LATEX
@nav_next{threadx}
@endif
*/
/*##########################################################################*/
/*! @page threadx ThreadX
<p>The QP/C/C++ ports and examples for ThreadX are described in the Quantum Leaps Application Note @webref{doc/AN_RTOS-ThreadX.pdf, QP and ThreadX}.
</p>
@image html logo_threadx.jpg
@image latex logo_threadx.jpg width=3.0in
@caption{ThreadX (Azure RTOS)}
@htmlonly
<div class="image">
<a target="_blank" href="https://www.state-machine.com/doc/AN_RTOS-ThreadX.pdf"><img border="0" src="img/AN.jpg" title="Download PDF"></a>
<div class="caption">
Application Note: QP and ThreadX
</div>
</div>
@endhtmlonly
The QP/C/C++ ports and examples for ThreadX (now Azure RTOS) are described in the Quantum Leaps Application Note @webref{doc/AN_RTOS-ThreadX.pdf, QP and ThreadX}.
@next{uc-os2}
@image html AN-QL.png
@image latex AN-QL.png width=2.0in
@caption{[Application Note: "QP and ThreadX"](https://www.state-machine.com/doc/AN_RTOS-ThreadX.pdf)}
@ifnot LATEX
@nav_next{uc-os2}
@endif
*/
/*##########################################################################*/
/*! @page uc-os2 uC-OS
/*! @page uc-os2 uC-OS2
@image html logo_uc-os2.jpg
@image latex logo_uc-os2.jpg width=2.0in
@caption{uC-OS2}
@section uc-os2_about About the QP Port to uC-OS2
This directory contains a generic platform-independent QP/C port to uC-OS2 V2.92.
Typically, you should not need to change the files in this directory to adapt the QP-uC-OS2 port on any CPU/Compiler to which uC-OS2 has been ported, because all the CPU and compiler specifics are handled by the uC-OS2 RTOS.
@note
Currently, the port has been tested only on ARM Cortex-M3 and M4F.
@section uc-os2_source uC-OS2 Source and ARM Cortex-M3/M4 Ports
The uC-OS2 V2.92 source code and ports are located in `3rd_party/uc-os2`. Please make sure to read about uC-OS2 licensing in the README file found in this directory.
@ -223,6 +227,86 @@ However, this port can also be used as a library, in which case you need to buil
@subsection uc-os2_build QP Source Files Needed in this QP Port
Whether you use this QP port as source files or as a library, it is important to note that not all QP source files should be included. Here is the list of QP source files needed:
@code{.c}
qpc/
+-src/
| | +-qf/
| | | +-qep_hsm.c
| | | +-qep_msm.c
| | | +-qf_act.c
| | | +-qf_actq.c // NOT included (implemented in uC-OS2)
| | | +-qf_defer.c
| | | +-qf_dyn.c
| | | +-qf_mem.c // NOT included (implemented in uC-OS2)
| | | +-qf_ps.c
| | | +-qf_qeq.c
| | | +-qf_qmact.c
| | | +-qf_time.c
| |
| | +-qs/
| | | +-qs.c // included only in the Spy build configuration
| | | +-qs_fp.c // included only in the Spy build configuration
|
+-ports
| +-uc-os2
| | +-qf_port.c
|
@endcode
@note
Specifically, the QP source files qf_actq.c and qf_mem.c must **NOT** be included in the build, because this functionality is taken from uC-OS2.
The QP/C/C++ ports and examples for uC-OS2 are described in the Quantum Leaps Application Note @webref{doc/AN_RTOS-uCOS2.pdf, QP and uC-OS2}.
@image html AN-QL.png
@image latex AN-QL.png width=2.0in
@caption{[Application Note: QP and uC-OS2](https://www.state-machine.com/doc/AN_RTOS-uCOS2.pdf)}
@ifnot LATEX
@nav_next{zephyr}
@endif
*/
/*##########################################################################*/
/*! @page zephyr Zephyr
@image html logo_zephyr.jpg
@image latex logo_zephyr.jpg width=2.0in
@caption{Zephyr Project}
@section zephyr_about About the QP Port to Zephyr
This directory contains a generic platform-independent QP/C port to the [Zephyr RTOS](https://zephyrproject.org).
Typically, you should not need to change the files in this directory to adapt the QP-Zephyr port on any CPU/Compiler to which Zephyr has been ported, because all the CPU and compiler specifics are handled by the Zephyr RTOS.
The QP-Zephyr port works as follows:
- The critical section used in this port is based on `k_spin_lock()/k_spin_unlock()` Zephyr API. This is the modern Zephyr critical section API, which is ready for SMP (symmetric multiprocessing).
- Each QP active object executes in a separate Zephyr thread (`struct k_thread`) and requires a private stack space.
@note
As demonstrated in the @ref exa_zephyr "provided examples", the private stacks for active objects in this port must be allocated with the Zephyr `K_THREAD_STACK_DEFINE()` macro. Also, the stack size passed to QACTIVE_START() must be calculated with the Zephyr `K_THREAD_STACK_SIZEOF()` macro. Failure to use these macros can lead to memory corruption in the application.
- The active object event queue is implemented with the Zephyr message queue (`struct k_msgq`).
@note
The Zephyr message queue currently supports only the FIFO policy and does NOT support the LIFO policy. For that reason, the QActive_postLIFO_() implementation in this port uses the FIFO policy. A feature request has been filed in the Zephyr project for adding the LIFO policy, so perhaps this can be improved, if the feature is added.
- The QP port uses Zephyr scheduler locking (`k_sched_lock()/k_sched_unlock()`), which locks all threads indiscriminately. Currently Zephyr does not provide a selective scheduler locking.
- The QP port uses the native QF memory pool (::QMPool) to implement event pools.
- The QP port does not mandate any specific method to manage the QP time events, but the provided examples use the Zephyr timer (`struct k_timer`) to tick periodically and invoke QF_TICK_X().
@subsection zephyr_build QP Source Files Needed in this QP Port
It is important to note that **NOT** all QP source files should be included. Here is the list of QP source files needed:
@verbatim
qpc/
+-src/
@ -230,38 +314,36 @@ qpc/
| | | +-qep_hsm.c
| | | +-qep_msm.c
| | | +-qf_act.c
| | | +-qf_actq.c - NOT included (implemented in uC-OS2)
| | | +-qf_actq.c - NOT included (implemented in Zephyr)
| | | +-qf_defer.c
| | | +-qf_dyn.c
| | | +-qf_mem.c - NOT included (implemented in uC-OS2)
| | | +-qf_mem.c
| | | +-qf_ps.c
| | | +-qf_qeq.c
| | | +-qf_qmact.c
| | | +-qf_time.c
| |
| | +-qs/
| | | +-qs.c - included only in the Spy build configuration
| | | +-qs_fp.c - included only in the Spy build configuration
| | | +-qs.c - included only in the Spy build configuration
| | | +-qs_fp.c - included only in the Spy build configuration
|
+-ports
| +-uc-os2
| | +-qf_port.c
| +-zephyr
| | +-qep_port.h
| | +-qf_port.h
| | +-qf_port.c - implementation of the Zephyr port
| | +-qs_port.h
|
@endverbatim
@note
Specifically, the QP source files qf_actq.c and qf_mem.c must **NOT** be included in the build, because this functionality is taken from uC-OS2.
Specifically, the QP source files qf_actq.c must **NOT** be included in the build, because this functionality is taken from Zephyr.
The QP/C/C++ ports and examples for uC-OS2 are described in the Quantum Leaps Application Note @webref{doc/AN_RTOS-uCOS2.pdf, QP and uC-OS2}.
@htmlonly
<div class="image">
<a target="_blank" href="https://www.state-machine.com/doc/AN_RTOS-uCOS2.pdf"><img border="0" src="img/AN.jpg" title="Download PDF"></a>
<div class="caption">
Application Note: QP and uC-OS2
</div>
</div>
@endhtmlonly
@section zephyr_exa Examples for the Zephyr port
The example projects for this port are located in @ref exa_zephyr "examples/zephyr".
@next{ports_os}
@ifnot LATEX
@nav_next{ports_os}
@endif
*/

88
doxygen/rsm.bat
View File

@ -1,44 +1,44 @@
@echo off
:: ==========================================================================
:: Product: QP/C script for running MSquared Resource Standard Metrics (RSM)
:: Last Updated for Version: 5.5.0
:: Date of the Last Update: 2015-09-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:
:: https://state-machine.com
:: mailto:info@state-machine.com
:: ==========================================================================
setlocal
set RCMHOME="C:\tools\MSquared\M2 RSM"
set RSM_OUTPUT=qpc_metrics.txt
set RSM_INPUT=..\include\*.h ..\source\*.h ..\source\*.c
%RCMHOME%\rsm.exe -fd -n -xNOCOMMAND -xNOCONFIG -u"File cfg rsm_qpc.cfg" %RSM_INPUT% > %RSM_OUTPUT%
endlocal
@echo off
:: ==========================================================================
:: Product: QP/C script for running MSquared Resource Standard Metrics (RSM)
:: Last Updated for Version: 5.5.0
:: Date of the Last Update: 2015-09-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:
:: https://state-machine.com
:: mailto:info@state-machine.com
:: ==========================================================================
setlocal
set RCMHOME="C:\tools\MSquared\M2 RSM"
set RSM_OUTPUT=qpc_metrics.txt
set RSM_INPUT=..\include\*.h ..\source\*.h ..\source\*.c
%RCMHOME%\rsm.exe -fd -n -xNOCOMMAND -xNOCONFIG -u"File cfg rsm_qpc.cfg" %RSM_INPUT% > %RSM_OUTPUT%
endlocal

32
doxygen/rsm_qpc.cfg
View File

@ -1,7 +1,7 @@
# ==========================================================================
# Product: Configuration file for MSquared Resource Standard Metrics (RSM)
# Last Updated for Version: 5.2.0
# Date of the Last Update: Dec 20, 2013
# ==========================================================================
# Product: Configuration file for MSquared Resource Standard Metrics (RSM)
# Last Updated for Version: 5.2.0
# Date of the Last Update: Dec 20, 2013
#
# Q u a n t u m L e a P s
# ---------------------------
@ -31,7 +31,7 @@
# Quantum Leaps Web sites: http://www.quantum-leaps.com
# http://www.state-machine.com
# e-mail: info@quantum-leaps.com
# ==========================================================================
# ==========================================================================
####################################################################
# RSM Operational Configuration ####################################
@ -87,7 +87,7 @@ C# File Extensions : cs
Java File Extensions : java
# Other files are not officially supported by RSM
# but lines will be counted as LOC
Other File Extensions :
Other File Extensions :
# When analyzing *.h files, treat header files as
# both C and C++. If you use separate extensions for C++ and
@ -136,7 +136,7 @@ Wrap long names in reports : Yes
# are to be created. The path must be a location with write
# permissions. RSM will create work files in the current
# directory if no path is specified.
Work file location path :
Work file location path :
# When processing code line differentials, ignore
# blank line changes in the code.
@ -261,7 +261,7 @@ Maximum Function Name Length : 32
# Emit a quality notice when a file does not contain
# the specified key string.
Quality Notice 21 : No
RSM KEY String :
RSM KEY String :
# RSM Quality Notices For Stability and Maintainability ################
@ -492,13 +492,13 @@ Min. Class/Struct LOC content analysis : 10
# or interface white space percentage is less than
# the specified minimum.
Quality Notice 16 : Yes
Minimum Function Whitespace Percent : 10.00
Minimum Function Whitespace Percent : 10.00
# Quality Notice No. 17
# Emit a quality notice when function comment line
# percentage is less than the specified minimum.
Quality Notice 17 : No
Minimum Function Comment Line Percent : 10.00
Minimum Function Comment Line Percent : 10.00
# Quality Notice No. 18
# Emit a quality notice when the eLOC within a
@ -517,14 +517,14 @@ Minimum Function lLOC : 0
# Emit a quality notice when class/struct comment line
# percentage is less than the specified minimum.
Quality Notice 31 : Yes
Minimum Class/Struct Comment Percent : 10.00
Minimum Class/Struct Comment Percent : 10.00
# Quality Notice No. 46
# Emit a quality notice when function, struct, class
# or interface blank line percentage is less than the
# specified minimum.
Quality Notice 46 : No
Minimum Function Blank Line Percent : 10.00
Minimum Function Blank Line Percent : 10.00
# Quality Notice No. 51
# Emit a quality notice when a function
@ -553,20 +553,20 @@ Quality Notice 54 : Yes
# percentage is less than the specified minimum.
# Consider setting Notice 30 to No.
Quality Notice 19 : Yes
Minimum File Whitespace Percent : 10.00
Minimum File Whitespace Percent : 10.00
A TAB is equivalent to n space : 2
# Quality Notice No. 20
# Emit a quality notice when file comment line
# percentage is less than the specified minimum.
Quality Notice 20 : Yes
Minimum File Comment Line Percent : 10.00
Minimum File Comment Line Percent : 10.00
# Quality Notice No. 47
# Emit a quality notice when file blank line
# percentage is less than the specified minimum.
Quality Notice 47 : No
Minimum File Blank Line Percent : 10.00
Minimum File Blank Line Percent : 10.00
# Quality Notice No. 57
# Emit a quality notice when RSM skip lines conditions
@ -579,7 +579,7 @@ Quality Notice 57 : No
Quality Notice 58 : No
# RSM Quality Notices Miscellaneous ####################################
# Quality Notice No. 25
# Deprecated in Version 6.70
# See settings under language extensions.

2
doxygen/snippets/qa_run.c
View File

@ -10,7 +10,7 @@ static void __cdecl run(void *me) { /* the exact signature for _beginthread */
} while (((QActive *)me)->prio > (uint8_t)0);
QActive_unsubscribeAll((QActive *)me); /* unsubscribe from all signals */
QF_remove_((QActive *)me); /* remove this object from any subscriptions */
QActive_unregister_((QActive *)me); /* un-register this active object */
_endthread(); /* cleanup after the thead and close the thread handle */
}

4
doxygen/snippets/qep_qfsm_use.c
View File

@ -8,14 +8,14 @@ static Bomb l_bomb; /* an instance of Bomb HSM */
int main() {
Bomb_ctor(&l_bomb); /* Bomb "constructor" invokes QFsm_ctor() */
QMSM_INIT(&l_bomb.super, (QEvt *)0); /* trigger initial transition */
QHSM_INIT(&l_bomb.super, (QEvt *)0); /* trigger initial transition */
for (;;) { /* event loop */
QEvt e;
. . .
/* wait for the next event and assign it to the event object e */
. . .
QMSM_DISPATCH(&l_bomb.super, &e); /* dispatch e */
QHSM_DISPATCH(&l_bomb.super, &e); /* dispatch e */
}
return 0; /* never reached, needed for some compilers */
}

4
doxygen/snippets/qep_qhist.c
View File

@ -4,7 +4,7 @@ typedef struct {
QStateHandler hist_doorClosed; /* history of doorClosed */
} ToastOven;
/*..........................................................*/
/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~.*/
static QState ToastOven_doorClosed(ToastOven * const me,
QEvt const * const e)
{
@ -19,7 +19,7 @@ static QState ToastOven_doorClosed(ToastOven * const me,
}
return status;
}
/*..........................................................*/
/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~.*/
static QState ToastOven_doorOpen(ToastOven * const me,
QEvt const * const e)
{

4
doxygen/snippets/qep_qhsm_use.c
View File

@ -8,14 +8,14 @@ static Calc Calc_inst; /* an instance of Calc SM */
int main() {
Calc_ctor(&Calc_inst); /* Calc "constructor" invokes QHsm_ctor() */
QMSM_INIT(&Calc_inst.super, (QEvt *)0); /* trigger initial transition */
QHSM_INIT(&Calc_inst.super, (QEvt *)0); /* trigger initial transition */
for (;;) { /* event loop */
QEvt e;
. . .
/* wait for the next event and assign it to the event object e */
. . .
QMSM_DISPATCH(&Calc_inst.super, &e); /* dispatch e */
QHSM_DISPATCH(&Calc_inst.super, &e); /* dispatch e */
}
return 0;
}

4
doxygen/snippets/qep_qinit.c
View File

@ -1,4 +1,4 @@
/* initial pseudostate of the Bomb FSM ....................................*/
/* initial pseudostate of the Bomb FSM ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
QState Bomb_initial(Bomb * const me, QEvt const * const e) {
Q_REQUIRE(e != (QEvt *)0); /* initialization event expected */
Bomb_updateState(me, "top-INIT");
@ -8,7 +8,7 @@ QState Bomb_initial(Bomb * const me, QEvt const * const e) {
return Q_TRAN(&Bomb_setting); /* <--- initial transition */
}
/* state handler function for the Calc HSM ................................*/
/* state handler function for the Calc HSM ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~..*/
QState Calc_on(Calc * const me, QEvt const * const e) {
QState status;
switch (e->sig) {

26
doxygen/snippets/qf_main.c
View File

@ -1,4 +1,6 @@
#include "qpc.h"
#include "dpp.h"
#include "bsp.h"
Q_DEFINE_THIS_FILE
@ -7,30 +9,36 @@ int main(void) {
QF_init(); /* initialize the framework and the underlying RT kernel */
BSP_init(); /* initialize the BSP */
/* init publish-subscribe... */
/* initialize publish-subscribe~~~ */
static QSubscrList l_subscrSto[MAX_PUB_SIG];
QF_psInit(l_subscrSto, Q_DIM(l_subscrSto));
/* initialize event pools... */
/* initialize event pools~~~ */
static QF_MPOOL_EL(TableEvt) l_smlPoolSto[2*N_PHILO]; /* small pool */
QF_poolInit(l_smlPoolSto, sizeof(l_smlPoolSto), sizeof(l_smlPoolSto[0]));
/* start the active objects... */
/* start the active objects~~~ */
Philo_ctor(); /* instantiate all Philosopher active objects */
static QEvt const *l_philoQueueSto[N_PHILO][N_PHILO];
for (uint8_t n = 0U; n < N_PHILO; ++n) {
QACTIVE_START(AO_Philo[n], (uint8_t)(n + 1),
l_philoQueueSto[n], Q_DIM(l_philoQueueSto[n]),
(void *)0, 0U, (QEvt *)0);
QACTIVE_START(AO_Philo[n],
Q_PRIO(n + 1U, N_PHILO), /* QF-priority/preemption-threshold */
l_philoQueueSto[n], /* event queue storage */
Q_DIM(l_philoQueueSto[n]),/* event queue length [events] */
(void *)0, /* stack storage (not used) */
0U, /* stack size [bytes] (not used) */
(void *)0); /* initialization parameter (not used) */
}
Table_ctor(); /* instantiate the Table active object */
static QEvt const *l_tableQueueSto[N_PHILO];
QACTIVE_START(AO_Table, (uint8_t)(N_PHILO + 1),
l_tableQueueSto, Q_DIM(l_tableQueueSto),
(void *)0, 0U, (QEvt *)0);
QACTIVE_START(AO_Table,
N_PHILO + 1U , /* QF-priority/preemption-threshold */
l_tableQueueSto, Q_DIM(l_tableQueueSto),
(void *)0, 0U,
(void *)0);
return QF_run(); /* run the QF application, QF_run() does not return */
}

Some files were not shown because too many files have changed in this diff Show More