qp_config.hpp

Go to the documentation of this file.

/*!@file
@code_uid{qp_config.h,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 optional and does not need to be provided (see the description of
the #QP_CONFIG macro below). In that case, all the listed configuration
macros will be set at their __default__ values.
 
@attention
The `qp_config.hpp` configuration file takes effect only when the
command-line macro #QP_CONFIG is defined.
 
 
Also, if the `qp_config.hpp` file is provided and enabled (by defining
the command-line macro #QP_CONFIG), but any of the listed configuration
macros is not defined in the provided file, the __default__ value
will be used.
 
@note
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
 
@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` disables QP FuSa Subsystem, which
consists of the following facilities:
- Software assertions as a recommended technique
  (called Failure Assertion Programming (FAP) in IEC 61508)
- Software Self-Monitoring (SSM), 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
  + @ref ssr-qp_mpu-mem "Hardware Memory Isolation" by means of Memory Protection Unit (MPU)
  + @ref ssr-qp_dim-hwm "High Watermark" in event queues
  + @ref ssr-qp_dim-hwm "High Watermark" in event pools
  + @ref ssr-qp_dim-sover "Stack Overflow" detection in QP Applications
  + @ref ssr-qp_dim-spaint "Stack Painting" in QP Applications
  + @ref ssr-qp_dim-null "NULL-Pointer Dereferencing" protection in QP Applications
 
Default: undefined
 
@attention
Disabling QP FuSa Subsystem (by defining the macro `Q_UNSAFE`), especially
in the final production release, __CONTRADICTS__ the most fundamental
principles of functional safety and is __NOT recommended__.
 
@endcode_uid
*/
#define Q_UNSAFE
 
//------------------------------------------------------------------------------
// <h>QEP Event Processor
// <i>Events and state machines.
 
/*!
@code_uid{::Q_SIGNAL_SIZE,Size of the ::QEvt signal [bytes]}
@code_litem{Details}
This macro controls the dynamic range of event signals.
- 1U => 1 byte (up to 255 signals)
- 2U => 2 bytes (up to 65535 signals) (default)
- 4U => 4 bytes (up to 4G signals)
@endcode_uid
*/
#define Q_SIGNAL_SIZE  2U
 
// </h>
 
//------------------------------------------------------------------------------
// <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 (QS_CTR_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_