mirror of
https://github.com/QuantumLeaps/qpcpp.git
synced 2025-01-28 06:02:56 +08:00
226 lines
17 KiB
Plaintext
226 lines
17 KiB
Plaintext
/*! @page ports Ports
|
|
|
|
@section ports_gen General Comments
|
|
The QP/C++ framework can be easily adapted to various operating systems, processor architectures, and compilers. Adapting the QP/C++ software is called porting and the QP/C++ framework has been designed from the ground up to make porting easy.
|
|
|
|
The QP/C++ distribution contains many QP/C++ ports, which are organized into the three categories:
|
|
|
|
- @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 qv "QV", @ref qk "QK", or @ref 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> <a href="files.html">top-level folder</a>, 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> — Native ports for ARM-Cortex-M (bare-metal) <span class="tag">A</span>
|
|
</li>
|
|
<ul class="tag">
|
|
<li><span class="img folder">qk/</span> — Port to the @ref qk "preemptive QK kernel"
|
|
</li>
|
|
<ul class="tag">
|
|
<li><span class="img folder">arm</span> — Port to ARM-KEIL toolset
|
|
</li>
|
|
<li><span class="img folder">gnu</span> — Port to GNU toolset
|
|
</li>
|
|
<li><span class="img folder">iar</span> — Port to IAR toolset
|
|
</li>
|
|
<li><span class="img folder">ti</span> — Port to TI/CCS toolset
|
|
</li>
|
|
</ul>
|
|
<li><span class="img folder">qv/</span> — Port to the @ref qv "cooperative QV kernel"
|
|
</li>
|
|
<ul class="tag">
|
|
<li><span class="img folder">arm</span> — Port to ARM-KEIL toolset
|
|
</li>
|
|
<li><span class="img folder">gnu</span> — Port to GNU toolset
|
|
</li>
|
|
<li><span class="img folder">iar</span> — Port to IAR toolset
|
|
</li>
|
|
<li><span class="img folder">ti</span> — Port to TI/CCS toolset
|
|
</li>
|
|
</ul>
|
|
<li><span class="img folder">qxk/</span> — Port to the @ref qxk "blocking QXK kernel"
|
|
</li>
|
|
<ul class="tag">
|
|
<li><span class="img folder">arm</span> — Port to ARM-KEIL toolset
|
|
</li>
|
|
<li><span class="img folder">gnu</span> — Port to GNU toolset
|
|
</li>
|
|
<li><span class="img folder">iar</span> — Port to IAR toolset
|
|
</li>
|
|
</ul>
|
|
</ul>
|
|
|
|
<li><span class="img folder">uc-os2/</span> — Port to uc-os2 (3rd-party RTOS) <span class="tag">B</span>
|
|
</li>
|
|
<ul class="tag">
|
|
<li><span class="img folder">arm-cm</span> — Port to ARM-Cortex-M
|
|
</li>
|
|
<ul class="tag">
|
|
<li><span class="img folder">arm</span> — build with ARM toolset
|
|
</li>
|
|
<li><span class="img folder">iar</span> — build with IAR toolset
|
|
</li>
|
|
</ul>
|
|
</ul>
|
|
|
|
<li><span class="img folder">win32/</span> — Port to Win32 (Windows) <span class="tag">C</span>
|
|
</li>
|
|
<ul class="tag">
|
|
<li><span class="img folder">Debug/</span> — Debug build configuration for VC++ toolset
|
|
</li>
|
|
<li><span class="img folder">dbg/</span> — Debug build configuration for MinGW toolset
|
|
</li>
|
|
<li><span class="img folder">Release/</span> — Release build configuration for VC++ toolset
|
|
</li>
|
|
<li><span class="img folder">rel/</span> — Release build configuration for MinGW toolset
|
|
</li>
|
|
<li><span class="img folder">QSpy/</span> — Spy build configuration for VC++ toolset
|
|
</li>
|
|
<li><span class="img folder">spy/</span> — Spy build configuration for MinGW toolset
|
|
</li>
|
|
</ul>
|
|
|
|
<li><span class="img folder">posix/</span> — Port to POSIX (e.g., Linux) <span class="tag">C</span>
|
|
</li>
|
|
<ul class="tag">
|
|
<li><span class="img folder">dbg/</span> — Debug build configuration for GNU toolset
|
|
</li>
|
|
<li><span class="img folder">rel/</span> — Release build configuration for GNU toolset
|
|
</li>
|
|
<li><span class="img folder">spy/</span> — Spy build configuration for GNU toolset
|
|
</li>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
<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">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>
|
|
|
|
<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.
|
|
|
|
@nav_next{ports_lint}
|
|
*/
|
|
/*##########################################################################*/
|
|
/*! @page ports_lint PC-Lint-Plus
|
|
|
|
|
|
|
|
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++.
|
|
|
|
The QP/C++ "port" to PC-Lint-Plus is located in the directory <span class="img folder">qpcpp/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">qpcpp/examples/arm-cm/dpp_ek-tm4c123gxl/lint-plus</span>. The following listing describes the most important files in these three directories.
|
|
|
|
@code{.x}
|
|
qpcpp\ - 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
|
|
| | | | +-cstdint - 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
|
|
| | | | +-cstdint - 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-misra-cpp.lnt - MISRA-C++:2008 compliance 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.hpp - QEP component "port" to 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_qpcpp Linting the QP/C++ Source Code
|
|
The directory <span class="img folder">qpcpp/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 `qpcpp.lnt` configuration file discussed before and the `options.lnt` configuration file that covers all deviations from the AUTOSAR-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">qpcpp/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 exactly 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">qpcpp/include</span> and <span class="img folder">qpcpp/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">qpcpp/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 `-iqpcpp/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++:2008 `au-misra-cpp.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 `qpcpp/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_qpcpp_lnt The qpcpp.lnt option file
|
|
The most important file for "linting" QP/C++ applications is the **qpcpp.lnt** option file. This file handles all deviations from the MISRA-C++:2008 rules, which might arise at the application-level code from the use of the QP/C++ framework. In other words, the **qpcpp.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++:2008 rules.
|
|
|
|
At the same time, the **qpcpp.lnt** option file has been very carefully designed not to suppress any MISRA-C++:2008 rule checking outside the very specific context of the QP/C++ API. In other words, the qpcpp.lnt option file still supports 100% of the MISRA-C++:2008 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-Cpp_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++:2008 Rule 16-0-4 and which PC-Lint-Plus checks with the warning 9026. However, instead of suppressing this warning globally (with the -e9096 directive), the qpcpp.lnt option file suppresses warning 9096 only for the specific QP function-like macros that are visible to the application level. So specifically, the `qpcpp.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.
|
|
|
|
@nav_next{ports_native}
|
|
*/
|