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

Customizable and memory-efficient Design by Contract (DbC) for embedded systems. More...

Go to the source code of this file.

Macros

#define Q_ASSERT_ID(id_, expr_)
 
#define Q_ERROR_ID(id_)   Q_onAssert(&Q_this_module_[0], (id_))
 
#define Q_ALLEGE_ID(id_, expr_)   Q_ASSERT_ID((id_), (expr_))
 
#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_ENSURE_ID(id_, expr_)   Q_ASSERT_ID((id_), (expr_))
 
#define Q_ENSURE(expr_)   Q_ASSERT(expr_)
 
#define Q_INVARIANT_ID(id_, expr_)   Q_ASSERT_ID((id_), (expr_))
 
#define Q_INVARIANT(expr_)   Q_ASSERT(expr_)
 
#define Q_ALLEGE(expr_)   Q_ALLEGE_ID(__LINE__, (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_onAssert (char const *module, int_t location)
 

Detailed Description

Note
This header file can be used in C, C++, and mixed C/C++ programs.
The preprocessor switch Q_NASSERT disables checking assertions. However, it is generally not advisable to disable assertions, especially in the production code. Instead, the assertion handler Q_onAssert() should be very carefully designed and tested.

Definition in file qassert.h.

Macro Definition Documentation

◆ Q_ASSERT_ID

#define Q_ASSERT_ID (   id_,
  expr_ 
)
Value:
((expr_) \
? ((void)0) : Q_onAssert(&Q_this_module_[0], (id_)))
Q_NORETURN Q_onAssert(char const *module, int_t location)
Definition: qutest.c:109

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_onAssert().

Parameters
[in]id_ID number (unique within the module) of the assertion
[in]expr_Boolean expression to check
Attention
When assertions are disabled (by defining the Q_NASSERT macro), the Q_ASSERT_ID() macro expands to nothing, and consequently the Boolean expression expr_ is not evaluated and the callback function Q_onAssert() is not called.
Traceability

Definition at line 103 of file qassert.h.

◆ Q_ERROR_ID

#define Q_ERROR_ID (   id_)    Q_onAssert(&Q_this_module_[0], (id_))

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

Calls the Q_onAssert() 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
Note
Does noting if assertions are disabled with the Q_NASSERT switch.
Traceability

Definition at line 124 of file qassert.h.

◆ Q_ALLEGE_ID

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

General purpose assertion with user-specified ID number that always evaluates the expr_ expression.

Like the Q_ASSERT_ID() macro, except it always evaluates the expr_ expression even when assertions are disabled with the Q_NASSERT macro. However, when the Q_NASSERT macro is defined, the Q_onAssert() callback is not called, even if expr_ evaluates to FALSE.

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

Definition at line 143 of file qassert.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
Traceability

Definition at line 209 of file qassert.h.

◆ Q_ERROR

#define Q_ERROR ( )    Q_ERROR_ID(__LINE__)

Assertion for a wrong path through the code

Calls the Q_onAssert() callback if ever executed.

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

Definition at line 224 of file qassert.h.

◆ Q_REQUIRE_ID

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

Assertion for checking preconditions.

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
Traceability

Definition at line 239 of file qassert.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
Traceability

Definition at line 253 of file qassert.h.

◆ Q_ENSURE_ID

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

Assertion for checking postconditions.

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 265 of file qassert.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
Traceability

Definition at line 279 of file qassert.h.

◆ Q_INVARIANT_ID

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

Assertion for checking invariants.

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
Traceability

Definition at line 294 of file qassert.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
Traceability

Definition at line 308 of file qassert.h.

◆ Q_ALLEGE

#define Q_ALLEGE (   expr_)    Q_ALLEGE_ID(__LINE__, (expr_))

General purpose assertion with user-specified ID number that always evaluates the expr_ expression.

Equivalent to Q_ALLEGE_ID(), except it identifies the problem location with the line number __LINE__, which might change as the code is modified.

Parameters
[in]expr_Boolean expression to check
Traceability

Definition at line 323 of file qassert.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().
Traceability

Definition at line 344 of file qassert.h.

◆ Q_NORETURN

#define Q_NORETURN   _Noreturn void

No-return function specifier for the Q_onAssert() callback function.

If the Q_NORETURN macro is undefined, the default definition uses the C99 specifier _Noreturn.

Note
The Q_NORETURN macro can be defined in the QP port (typically in qep_port.h or qep_port.hpp). If such definition is porvided the default won't be used.
Traceability

Definition at line 362 of file qassert.h.

◆ Q_DIM

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

Helper macro to calculate static dimension of a 1-dim array_

Parameters
array_1-dimensional array
Returns
The length of the array (number of elements it can hold)
Traceability

Definition at line 424 of file qassert.h.

Typedef Documentation

◆ int_t

typedef int int_t

typedef for assertions-ids and line numbers in assertions.

This typedef specifies integer type for exclusive use in assertions. Use of this type, rather than plain 'int', is in compliance with the MISRA-C:2012 Directive 4.6 (Advisory).

Definition at line 374 of file qassert.h.

Function Documentation

◆ Q_onAssert()

Q_NORETURN Q_onAssert ( char const *  module,
int_t  location 
)

Callback function invoked in case of an assertion failure.

This callback function needs to be defined in the application to perform any corrective action after a non-recoverable error has been detected. The Q_onAssert() function is the last line of defense after the system failure and its implementation shouild be very carefully designed and tested under various fault conditions, including but not limited to: stack overflow, stack corruption, or calling Q_onAssert() from an interrupt.

Parameters
[in]modulename of the file/module in which the assertion failed (constant, zero-terminated C string)
[in]locationlocation 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 assertion failure does not make sense.
Note
During debugging, Q_onAssert() is an ideal place to put a breakpoint. For deployment, tt is typically a bad idea to implement Q_onAssert() 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() and Q_ALLEGE_ID() as well as: Q_ASSERT(), Q_ERROR(), Q_REQUIRE(), Q_ENSURE(), Q_INVARIANT(), and Q_ALLEGE().

Definition at line 109 of file qutest.c.