QP/C  8.0.0
Real-Time Embedded Framework
Loading...
Searching...
No Matches
qsafe.h File Reference

QP Functional Safety (FuSa) Subsystem. More...

Go to the source code of this file.

Macros

#define QF_CRIT_STAT
 
#define QF_CRIT_ENTRY()   ((void)0)
 
#define QF_CRIT_EXIT()   ((void)0)
 
#define Q_ASSERT_INCRIT(id_, expr_)    ((expr_) ? ((void)0) : Q_onError(&Q_this_module_[0], (id_)))
 
#define Q_ERROR_INCRIT(id_)    (Q_onError(&Q_this_module_[0], (id_)))
 
#define Q_ASSERT_ID(id_, expr_)
 
#define Q_ERROR_ID(id_)
 
#define Q_ASSERT(expr_)   Q_ASSERT_ID(__LINE__, (expr_))
 
#define Q_ERROR()   Q_ERROR_ID(__LINE__)
 
#define Q_REQUIRE_ID(id_, expr_)   Q_ASSERT_ID((id_), (expr_))
 
#define Q_REQUIRE(expr_)   Q_ASSERT(expr_)
 
#define Q_REQUIRE_INCRIT(id_, expr_)   Q_ASSERT_INCRIT((id_), (expr_))
 
#define Q_ENSURE_ID(id_, expr_)   Q_ASSERT_ID((id_), (expr_))
 
#define Q_ENSURE(expr_)   Q_ASSERT(expr_)
 
#define Q_ENSURE_INCRIT(id_, expr_)   Q_ASSERT_INCRIT((id_), (expr_))
 
#define Q_INVARIANT_ID(id_, expr_)   Q_ASSERT_ID((id_), (expr_))
 
#define Q_INVARIANT(expr_)   Q_ASSERT(expr_)
 
#define Q_INVARIANT_INCRIT(id_, expr_)   Q_ASSERT_INCRIT((id_), (expr_))
 
#define Q_ASSERT_STATIC(expr_)   extern char Q_static_assert_[(expr_) ? 1 : -1]
 
#define Q_NORETURN   _Noreturn void
 
#define Q_DIM(array_)   (sizeof(array_) / sizeof((array_)[0U]))
 

Typedefs

typedef int int_t
 

Functions

Q_NORETURN Q_onError (char const *const module, int_t const id)
 

Detailed Description

QP Functional Safety (FuSa) Subsystem.

This header file is part of the QP Functional Safety (FuSa) Subsystem and contains the following facilities:

  • Software assertions (Failure Assertion Programming (FAP) in IEC 61508)
  • Software Self-Monitoring (SSM) techniques:
    • Duplicate Inverse Storage for critical variables
    • Fixed Upper Loop Bound for all loops
    • Invalid Control Flow for all unreachable code paths
    • Hardware Memory Isolation by means of Memory Protection Unit (MPU)
    • High Watermark in event queues
    • High Watermark in event pools
    • Stack Overflow detection in QP Applications
    • Stack Painting in QP Applications
    • NULL-Pointer Dereferencing protection in QP Applications
Note
This header file can be used in C, C++, and mixed C/C++ programs.
Attention
The preprocessor switch Q_UNSAFE disables the QP Functional Safety System. However, it is generally NOT RECOMMENDED, especially in the production code. Instead, the failure callback Q_onError() should be very carefully designed, implemented, and tested in various failure modes.

Definition in file qsafe.h.

Macro Definition Documentation

◆ QF_CRIT_STAT

#define QF_CRIT_STAT

Definition at line 46 of file qsafe.h.

◆ QF_CRIT_ENTRY

#define QF_CRIT_ENTRY ( )    ((void)0)

Definition at line 50 of file qsafe.h.

◆ QF_CRIT_EXIT

#define QF_CRIT_EXIT ( )    ((void)0)

Definition at line 54 of file qsafe.h.

◆ Q_ASSERT_INCRIT

#define Q_ASSERT_INCRIT ( id_,
expr_ )    ((expr_) ? ((void)0) : Q_onError(&Q_this_module_[0], (id_)))

General-purpose assertion with user-specified ID number (in critical section)

Parameters
[in]id_ID number (unique within the module) of the assertion
[in]expr_Boolean expression to check
Attention
This macro must be called inside already established critical section. The evaluation of the expression expr_ as well as calling of Q_onError() happens inside that critical section.
The assertion expression (expr_) must be possibly simple, have no side effects, and quick to evaluate because the evaluation happens inside a critical section. Also, the expression must NOT call any functions that might use critical sections inside (because this would cause nesting of critical sections, which might not be supported).

Backward Traceability

  • DVP_QP_MC4_D04_09A (false-positive)

Definition at line 64 of file qsafe.h.

◆ Q_ERROR_INCRIT

#define Q_ERROR_INCRIT ( id_)     (Q_onError(&Q_this_module_[0], (id_)))

Assertion with user-specified ID for a wrong path through the code (in critical section)

Parameters
[in]id_ID number (unique within the module) of the assertion
Attention
This macro must be called inside already established critical section. The call to Q_onError() happens inside that critical section.

Backward Traceability

  • DVP_QP_MC4_D04_09A (false-positive)

Definition at line 68 of file qsafe.h.

◆ Q_ASSERT_ID

#define Q_ASSERT_ID ( id_,
expr_ )
Value:
do { \
QF_CRIT_STAT \
QF_CRIT_ENTRY(); \
(expr_) ? ((void)0) : Q_onError(&Q_this_module_[0], (id_)); \
QF_CRIT_EXIT(); \
} while (false)
Q_NORETURN Q_onError(char const *const module, int_t const id)

General-purpose assertion with user-specified ID number.

Evaluates the Boolean expression expr_ and does nothing else when it evaluates to 'true'. However, when expr_ evaluates to 'false', the Q_ASSERT_ID() macro calls the no-return function Q_onError().

Parameters
[in]id_ID number (unique within the module) of the assertion
[in]expr_Boolean expression to check
Attention
This macro uses critical section and the evaluation of the expression expr_ as well as calling of Q_onError() happens inside the critical section.
The assertion expression (expr_) must be possibly simple, have no side effects, and quick to evaluate because the evaluation happens inside a critical section. Also, the expression must NOT call any functions that might use critical sections inside (because this would cause nesting of critical sections, which might not be supported).

Backward Traceability

  • DVP_QP_MC4_D04_09A (false-positive)

Definition at line 72 of file qsafe.h.

◆ Q_ERROR_ID

#define Q_ERROR_ID ( id_)
Value:
do { \
QF_CRIT_STAT \
QF_CRIT_ENTRY(); \
Q_onError(&Q_this_module_[0], (id_)); \
QF_CRIT_EXIT(); \
} while (false)

Assertion with user-specified ID for a wrong path through the code

Calls the Q_onError() callback if ever executed. This assertion takes the user-supplied parameter id_ to identify the location of this assertion within the file. This avoids the volatility of using line numbers, which change whenever a line of code is added or removed upstream from the assertion.

Parameters
[in]id_ID number (unique within the module) of the assertion

Backward Traceability

  • DVP_QP_MC4_D04_09A (false-positive)

Definition at line 80 of file qsafe.h.

◆ Q_ASSERT

#define Q_ASSERT ( expr_)    Q_ASSERT_ID(__LINE__, (expr_))

General-purpose assertion (with LINE used as location in the file)

Equivalent to Q_ASSERT_ID(), except it uses LINE to identify the assertion within a file.

Parameters
[in]expr_Boolean expression to check

Backward Traceability

  • DVP_QP_MC4_D04_09A (false-positive)

Definition at line 116 of file qsafe.h.

◆ Q_ERROR

#define Q_ERROR ( )    Q_ERROR_ID(__LINE__)

Assertion for a wrong path through the code

Calls the Q_onError() callback if ever executed.

Note
This macro identifies the problem location with the line number, which might change as the code is modified.

Backward Traceability

  • DVP_QP_MC4_D04_09A (false-positive)

Definition at line 119 of file qsafe.h.

◆ Q_REQUIRE_ID

#define Q_REQUIRE_ID ( id_,
expr_ )   Q_ASSERT_ID((id_), (expr_))

Assertion for checking preconditions (with user-specified ID number).

Equivalent to Q_ASSERT_ID(), except the name provides a better documentation of the intention of this assertion.

Parameters
[in]id_ID number (unique within the module) of the assertion
[in]expr_Boolean expression

Backward Traceability

  • DVP_QP_MC4_D04_09A (false-positive)

Definition at line 122 of file qsafe.h.

◆ Q_REQUIRE

#define Q_REQUIRE ( expr_)    Q_ASSERT(expr_)

Assertion for checking preconditions (based on LINE).

Equivalent to Q_ASSERT(), except the name provides a better documentation of the intention of this assertion.

Parameters
[in]expr_Boolean expression

Backward Traceability

  • DVP_QP_MC4_D04_09A (false-positive)

Definition at line 125 of file qsafe.h.

◆ Q_REQUIRE_INCRIT

#define Q_REQUIRE_INCRIT ( id_,
expr_ )   Q_ASSERT_INCRIT((id_), (expr_))

Assertion for checking preconditions (in critical section)

Equivalent to Q_ASSERT_INCRIT(), except the name provides a better documentation of the intention of this assertion.

Parameters
[in]id_ID number (unique within the module) of the assertion
[in]expr_Boolean expression

Backward Traceability

  • DVP_QP_MC4_D04_09A (false-positive)

Definition at line 128 of file qsafe.h.

◆ Q_ENSURE_ID

#define Q_ENSURE_ID ( id_,
expr_ )   Q_ASSERT_ID((id_), (expr_))

Assertion for checking postconditions (with user-specified ID number).

Equivalent to Q_ASSERT_ID(), except the name provides a better documentation of the intention of this assertion.

Parameters
[in]id_ID number (unique within the module) of the assertion
[in]expr_Boolean expression

Definition at line 131 of file qsafe.h.

◆ Q_ENSURE

#define Q_ENSURE ( expr_)    Q_ASSERT(expr_)

Assertion for checking postconditions.

Equivalent to Q_ASSERT(), except the name provides a better documentation of the intention of this assertion.

Parameters
[in]expr_Boolean expression

Backward Traceability

  • DVP_QP_MC4_D04_09A (false-positive)

Definition at line 134 of file qsafe.h.

◆ Q_ENSURE_INCRIT

#define Q_ENSURE_INCRIT ( id_,
expr_ )   Q_ASSERT_INCRIT((id_), (expr_))

Assertion for checking postconditions (in critical section)

Equivalent to Q_ASSERT_INCRIT(), except the name provides a better documentation of the intention of this assertion.

Parameters
[in]id_ID number (unique within the module) of the assertion
[in]expr_Boolean expression

Backward Traceability

  • DVP_QP_MC4_D04_09A (false-positive)

Definition at line 137 of file qsafe.h.

◆ Q_INVARIANT_ID

#define Q_INVARIANT_ID ( id_,
expr_ )   Q_ASSERT_ID((id_), (expr_))

Assertion for checking invariants (with user-specified ID number).

Equivalent to Q_ASSERT_ID(), except the name provides a better documentation of the intention of this assertion.

Parameters
[in]id_ID number (unique within the module) of the assertion
[in]expr_Boolean expression

Backward Traceability

  • DVP_QP_MC4_D04_09A (false-positive)

Definition at line 140 of file qsafe.h.

◆ Q_INVARIANT

#define Q_INVARIANT ( expr_)    Q_ASSERT(expr_)

Assertion for checking invariants.

Equivalent to Q_ASSERT(), except the name provides a better documentation of the intention of this assertion.

Parameters
[in]expr_Boolean expression

Backward Traceability

  • DVP_QP_MC4_D04_09A (false-positive)

Definition at line 143 of file qsafe.h.

◆ Q_INVARIANT_INCRIT

#define Q_INVARIANT_INCRIT ( id_,
expr_ )   Q_ASSERT_INCRIT((id_), (expr_))

Definition at line 146 of file qsafe.h.

◆ Q_ASSERT_STATIC

#define Q_ASSERT_STATIC ( expr_)    extern char Q_static_assert_[(expr_) ? 1 : -1]

Static (compile-time) assertion.

This type of assertion deliberately causes a compile-time error when the expr_ Boolean expression evaluates to FALSE. The macro exploits the fact that in C/C++ a dimension of an array cannot be negative. The compile-time assertion has no runtime side effects.

Parameters
[in]expr_Compile-time Boolean expression
Note
The static assertion macro is provided for backwards compatibility with older C standards. Newer C11 supports _Static_assert(), which should be used instead of Q_ASSERT_STATIC().

Backward Traceability

  • DVP_QP_MC4_D04_09A (false-positive)

Definition at line 149 of file qsafe.h.

◆ Q_NORETURN

#define Q_NORETURN   _Noreturn void

Definition at line 153 of file qsafe.h.

◆ Q_DIM

#define Q_DIM ( array_)    (sizeof(array_) / sizeof((array_)[0U]))

Definition at line 168 of file qsafe.h.

Typedef Documentation

◆ int_t

typedef int int_t

Definition at line 158 of file qsafe.h.

Function Documentation

◆ Q_onError()

Q_NORETURN Q_onError ( char const *const module,
int_t const id )

Callback function invoked after detecting an error (part of QP Functional Safety (FuSa) Subsystem).

This callback function needs to be defined in the application to perform any corrective action after an unrecoverable error has been detected. The Q_onError() function is the last line of defense after the system failure and its implementation should be very carefully designed and tested under various fault conditions, including but not limited to: stack overflow/corruption, calling Q_onError() from an ISR or other hardware exception, etc.

Parameters
[in]modulename of the file/module in which the assertion failed (constant, zero-terminated C string)
[in]idID of the assertion within the module. This could be a line number or a user-specified ID-number.
Returns
This callback function should not return (see Q_NORETURN), as continuation after an unrecoverable error makes no sense.
Attention
Q_onError() must be called within a critical section (typically with interrupts disabled).
Note
During debugging, Q_onError() is an ideal place to put a breakpoint. For deployment, it is NOT RECOMMENDED to implement Q_onError() as an endless loop that ties up the CPU (denial of service).

Called by the following: Q_ASSERT_ID(), Q_ERROR_ID(), Q_REQUIRE_ID(), Q_ENSURE_ID(), Q_INVARIANT_ID() as well as: Q_ASSERT(), Q_ERROR(), Q_REQUIRE(), Q_ENSURE(), and Q_INVARIANT().