qp_config.hpp

Go to the documentation of this file.

/*!@file
@code_uid{qp_config.hpp, Sample @QPX configuration file}
@code_litem{Details}
This an example of a @QPX configuration file with the explanation
of the available configuration macros. The `qp_config.hpp` file is
required for every @QPX Application.
 
@attention
The `qp_config.hpp` file is required for every @QPX Application.
 
@remark
Some of the configuration macros listed in this file apply only
to specific @QPX ports.
 
@code_litem{Configuration Wizard support}
The `qp_config.hpp` header files provided in the various @ref exa "@QPX examples"
are formatted to support the "Configuration Wizard" editor available in some IDEs
(e.g., KEIL uVision). The screen shot below shows how to edit `qp_config.hpp`
in that mode.
 
@image html  qp_config.png
@image latex qp_config.png width=5in
 
@code_fw_trace
- @tr{DVR_QP_MP2_D5_7_2}: <i>Directive 5.7.2(Advisory): Section of code should not be "commented out"</i>
@endcode_uid
*/
#ifndef QP_CONFIG_HPP_
#define QP_CONFIG_HPP_
 
//------------------------------------------------------------------------------
/*!
@code_uid{#QP_API_VERSION, QP Framework API backwards-compatibility version}
@code_litem{Details}
QP API backwards compatibility with the @QPX API version.
Lower `QP_API_VERSION` values enable backwards compatibility
with lower (older) QP API versions.
 
- 0   =>  maximum supported compatibility
- 580 => QP 5.8.0 or newer
- 660 => QP 6.6.0 or newer
- 691 => QP 6.9.1 or newer
- 700 => QP 7.0.0 or newer
- 9999 => Latest QP API only (minimum compatibility)
 
For example, `QP_API_VERSION==691` will enable the compatibility
layer with QP version 6.9.1 and newer, but not older than 6.9.1.
`QP_API_VERSION==0` enables the maximum currently supported
backwards compatibility. Conversely, `QP_API_VERSION==9999` means
that no backwards compatibility layer should be enabled.
Default: 0 (All supported)
@endcode_uid
*/
#define QP_API_VERSION 0
 
//------------------------------------------------------------------------------
/*!
@code_uid{#Q_UNSAFE, Disable the QP Functional Safety (FuSa) Subsystem}
@code_litem{Details}
Defining the macro #Q_UNSAFE (in the application-specific qp_config.h header file)
disables most of the QP FuSa Subsystem, affecting the following facilities:
- Software assertions as a recommended technique
  (called Failure Assertion Programming (FAP) in IEC 61508)
- Software Self-Monitoring Safety Functions, which encompasses such techniques:
  + @ref ssr-qp_dim-dis "Duplicate Inverse Storage" for critical variables
  + @ref ssr-qp_cfm-lbound "Fixed Upper Loop Bound" for all loops
  + @ref ssr-qp_cfm-icf "Invalid Control Flow" for all unreachable code paths
 
The intent of the #Q_UNSAFE macro is to support verification (during development)
that assertions (and more generally, Safety Functions) have _no side effects_
on the primary functionalityare and are truly independent from the nominal
flow of control.
 
However, quite specifically, the #Q_UNSAFE macro should _not_ be used to permanently
disable the @QPX FuSa Subsystem in the final, production release of the @QPX
Application, especially in the context of a safety-related system.
 
@attention
Disabling QP FuSa Subsystem (by defining the macro #Q_UNSAFE) in the final production
release, _contradicts_ the most fundamental principles of functional safety and
is __not allowed__ in safety-related applications.
 
@endcode_uid
*/
#define Q_UNSAFE
 
//------------------------------------------------------------------------------
// <h>QF Framework
// <i>Active Object framework
 
/*!
@code_uid{#QF_MAX_ACTIVE,Maximum # Active Objects in the system (1..64)}
@code_litem{Details}
Defines the maximum # Active Objects that %QP Framework can manage at any time.
- Minimum: 1
- Default: 32
- Maximum: 64 (inclusive)
@endcode_uid
*/
#define QF_MAX_ACTIVE  32U
 
/*!
@code_uid{::QF_MAX_EPOOL,Maximum # event pools in the system (0..15)}
@code_litem{Details}
- Minimum: 0 -- no event pools at all
- Default: 3
- Maximum: 15 (inclusive)
@endcode_uid
*/
#define QF_MAX_EPOOL 3U
 
/*!
@code_uid{::QF_MAX_TICK_RATE,Maximum # clock tick rates in the system (0..15)}
@code_litem{Details}
- Minimum: 0 -- no time events at all
- Default: 1
- Maximum: 15 (inclusive)
@endcode_uid
*/
#define QF_MAX_TICK_RATE 1U
 
//------------------------------------------------------------------------------
/*!
@code_uid{QEVT_PAR_INIT(), Event parameter initialization (RAII) for dynamic events}
@code_litem{Details}
When defined, the macro activates initialization of event parameters while
creating dynamic events. This could be use for Resource Acquisition Is
Initialization (__RAII__) for dynamic events.
 
Default: undefined
 
@sa
- Q_NEW()
- Q_NEW_X()
- QP::QEvt::init()
@endcode_uid
*/
#define QEVT_PAR_INIT
 
//------------------------------------------------------------------------------
/*!
@code_uid{#QACTIVE_CAN_STOP, Enable the Active Object stop API}
@code_litem{Details}
When defined, enable Active Object stop API (Not recommended)
 
Default: undefined
@endcode_uid
*/
#define QACTIVE_CAN_STOP
 
//------------------------------------------------------------------------------
/*!
@code_uid{#Q_XTOR, Enable the virtual destructor in the QP::QAsm base class}
@code_litem{Details}
When defined, the macro #Q_XTOR enables the virtual destructor in the QP::QAsm base
class and all its subclasses: QP::QHsm, QP::QMsm, QP::QActive, QP::QMActive, etc.
 
@note
The virtual destructor is not enabled by default because such a destructor tends
to pull in the `delete` operator, which then must be linked from a standard library.
This is undesirable in many embedded systems.
 
Default: undefined
 
@sa
- QP::QAsm::~QAsm()
@endcode_uid
*/
#define Q_XTOR
 
//------------------------------------------------------------------------------
/*!
@code_uid{#QF_EVENT_SIZ_SIZE, Maximum size of dynamic events managed by QP}
@code_litem{Details}
This macro controls the maximum size of dynamic events managed by %QP Framework.
- 1U => 1 byte dynamic range (event size up to 255 bytes)
- 2U => 2 byte dynamic range (event size up to 65535 bytes) (default)
 
Default: 2 byte dynamic range (64K bytes maximum event size)
*/
#define QF_EVENT_SIZ_SIZE   2U
 
//------------------------------------------------------------------------------
/*!
@code_uid{::QF_TIMEEVT_CTR_SIZE,Time event counter size}
@code_litem{Details}
This macro controls the dynamic range of timeouts allowed in QP::QTimeEvt.
The timeouts are counted in tick _of the associated_ clock tick rate.
- 1U => 1 byte (timeouts of up to 255 ticks)
- 2U => 2 bytes (timeouts of up to 65535 ticks)
- 4U => 4 bytes (timeouts of up to 2^32 ticks) (default)
 
Default: 4 bytes (2^32 dynamic range)
@endcode_uid
*/
#define QF_TIMEEVT_CTR_SIZE 4U
 
//------------------------------------------------------------------------------
/*!
@code_uid{#QF_EQUEUE_CTR_SIZE, Event queue counter size}
@code_litem{Details}
This macro controls the maximum number of events that QP::QEQueue can hold
- 1U => 1 byte (maximum 255 events) (default)
- 2U => 2 bytes (maximum 65535 events)
 
Default: 1 (maximum 255 events in a queue)
@endcode_uid
*/
#define QF_EQUEUE_CTR_SIZE  1U
 
//------------------------------------------------------------------------------
/*!
@code_uid{#QF_MPOOL_CTR_SIZE, Memory pool counter size (QF_MPOOL_CTR_SIZE)}
@code_litem{Details}
This macro controls the maximum number of memory blocks that QP::QMPool can hold
- 1U => 1 byte (up to 255 memory blocks)
- 2U => 2 bytes (up to 65535 memory blocks) (default)
- 2U => 2 bytes (up to 2^32 memory blocks)
 
Default: 2 bytes (up to 65535 memory blocks maximum in a pool)
@endcode_uid
*/
#define QF_MPOOL_CTR_SIZE 2U
 
//------------------------------------------------------------------------------
/*!
@code_uid{#QF_MPOOL_SIZ_SIZE, Memory block size (QF_MPOOL_SIZ_SIZE)}
@code_litem{Details}
This macro controls the maximum size of memory blocks that QP::QMPool can hold.
- 1U => 1 byte dynamic range (event size up to 255 bytes)
- 2 U=> 2 byte dynamic range (event size up to 65535 bytes) (default)
 
Default: 2 byte dynamic range (64K bytes maximum block size)
@endcode_uid
*/
#define QF_MPOOL_SIZ_SIZE 2U
 
//==============================================================================
// QS Software Tracing
// Target-resident component of QP/Spy software tracing system
// (tracing instrumentation and command-input).
 
//------------------------------------------------------------------------------
/*!
@code_uid{#QS_TIME_SIZE, QS timestamp size (QS_TIME_SIZE)}
@code_litem{Details}
This macro controls the dynamic range of timestamp produced by QS software tracing.
- 1U => 1 byte (timestamp wraps around at 255 )
- 2U => 2 bytes (timestamp wraps around at 65535)
- 4U => 4 bytes (timestamp wraps around at 2^32) (default)
 
Default: 4 bytes (2^32 dynamic range)
@sa
- QP::QSTimeCtr
- QP::QS::onGetTime()
@endcode_uid
*/
#define QS_TIME_SIZE 4U
 
//------------------------------------------------------------------------------
/*!
@code_uid{#QS_CTR_SIZE, QS buffer counter size}
@code_litem{Details}
This macro controls the maximum number of bytes held in the QS TX/RX buffers.
- 1U => 1 byte (maximum 255 bytes)
- 2U => 2 bytes (maximum 65535 bytes) (default)
- 4U => 4 bytes (maximum 2^32 bytes)
 
Default: 2 bytes (maximum 65535 bytes in QS buffers)
@endcode_uid
*/
#define QS_CTR_SIZE 2U
 
//==============================================================================
/*!
@code_uid{#QF_ON_CONTEXT_SW, Enable context switch callback WITHOUT QS}
@code_litem{Details}
When defined, enables context switch callback QF_onContextSw() in the built-in
kernels (QV, QK, QXK).
 
Default: undefined
@endcode_uid
*/
#define QF_ON_CONTEXT_SW
 
//------------------------------------------------------------------------------
/*!
@code_uid{#QF_MEM_ISOLATE, Enable MPU memory isolation}
@code_litem{Details}
When defined, enables  memory isolation (requires MPU)
@note
Implies ::QF_ON_CONTEXT_SW (i.e., ::QF_ON_CONTEXT_SW gets defined)
@endcode_uid
*/
#define QF_MEM_ISOLATE
// </c>
 
//------------------------------------------------------------------------------
/*!
@code_uid{#QK_USE_IRQ_NUM, Use IRQ handler for QK return-from-preemption in ARM Cortex-M}
@code_litem{Details}
If #QK_USE_IRQ_NUM macro is defined, it specifies the IRQ number in ARM Cortex-M
to be used as the exception for return-from-preemption in the QK kernel.
 
This macro should be defined only if the NMI handler is utilized in the project.
The specified IRQ number must be otherwise unused.
 
Default: undefined
 
@sa
Requires defining the macro #QK_USE_IRQ_HANDLER
@endcode_uid
*/
#define QK_USE_IRQ_NUM      31
 
/*!
@code_uid{#QK_USE_IRQ_HANDLER, Use IRQ handler for QK return-from-preemption in ARM Cortex-M}
@code_litem{Details}
If #QK_USE_IRQ_HANDLER macro is defined, it specifies the IRQ handler name
in ARM Cortex-M to be used as the exception for return-from-preemption
in the QK kernel.
 
This macro should be defined only if the NMI handler is utilized in the project.
The specified IRQ handler must be otherwise unused.
 
@sa
Requires defining the macro #QK_USE_IRQ_NUM
@endcode_uid
*/
#define QK_USE_IRQ_HANDLER  Reserved31_IRQHandler
 
//------------------------------------------------------------------------------
/*!
@code_uid{#QXK_USE_IRQ_NUM, Use IRQ handler for QXK return-from-preemption in ARM Cortex-M}
@code_litem{Details}
If #QXK_USE_IRQ_NUM macro is defined, it specifies the IRQ number in ARM Cortex-M
to be used as the exception for return-from-preemption in the QXK kernel.
 
This macro should be defined only if the NMI handler is utilized in the project.
The specified IRQ number must be otherwise unused.
 
Default: undefined
 
@sa
Requires defining the macro #QXK_USE_IRQ_HANDLER
@endcode_uid
*/
#define QXK_USE_IRQ_NUM      31
 
/*!
@code_uid{#QXK_USE_IRQ_HANDLER, Use IRQ handler for QK return-from-preemption in ARM Cortex-M}
@code_litem{Details}
If #QXK_USE_IRQ_HANDLER macro is defined, it specifies the IRQ handler name
in ARM Cortex-M to be used as the exception for return-from-preemption
in the QK kernel.
 
This macro should be defined only if the NMI handler is utilized in the project.
The specified IRQ handler must be otherwise unused.
 
Default: undefined
 
@sa
Requires defining the macro #QXK_USE_IRQ_NUM
@endcode_uid
*/
#define QXK_USE_IRQ_HANDLER  Reserved31_IRQHandler
 
#endif // QP_CONFIG_HPP_