QP/C  5.9.7
qassert.h File Reference

Customizable and memory-efficient assertions for embedded systems. More...

Go to the source code of this file.

Macros

#define Q_DEFINE_THIS_FILE   static char_t const Q_this_module_[] = __FILE__;
 Define the file name (with __FILE__) for assertions in this file. More...
 
#define Q_DEFINE_THIS_MODULE(name_)   static char_t const Q_this_module_[] = name_;
 Define the user-specified module name for assertions in this file. More...
 
#define Q_ASSERT(test_)
 General purpose assertion. More...
 
#define Q_ASSERT_ID(id_, test_)
 General purpose assertion with user-specified assertion-id. More...
 
#define Q_ALLEGE(test_)   Q_ASSERT(test_)
 General purpose assertion that always evaluates the test_ expression. More...
 
#define Q_ALLEGE_ID(id_, test_)   Q_ASSERT_ID((id_), (test_))
 General purpose assertion with user-specified assertion-id that always evaluates the test_ expression. More...
 
#define Q_ERROR()   Q_onAssert(&Q_this_module_[0], (int_t)__LINE__)
 Assertion for a wrong path through the code. More...
 
#define Q_ERROR_ID(id_)   Q_onAssert(&Q_this_module_[0], (int_t)(id_))
 Assertion with user-specified assertion-id for a wrong path. More...
 
#define Q_REQUIRE(test_)   Q_ASSERT(test_)
 Assertion for checking preconditions. More...
 
#define Q_REQUIRE_ID(id_, test_)   Q_ASSERT_ID((id_), (test_))
 Assertion for checking preconditions with user-specified assertion-id. More...
 
#define Q_ENSURE(test_)   Q_ASSERT(test_)
 Assertion for checking postconditions. More...
 
#define Q_ENSURE_ID(id_, test_)   Q_ASSERT_ID((id_), (test_))
 Assertion for checking postconditions with user-specified assertion-id. More...
 
#define Q_INVARIANT(test_)   Q_ASSERT(test_)
 Assertion for checking invariants. More...
 
#define Q_INVARIANT_ID(id_, test_)   Q_ASSERT_ID((id_), (test_))
 Assertion for checking invariants with user-specified assertion-id. More...
 
#define Q_ASSERT_COMPILE(test_)   extern int_t Q_assert_compile[(test_) ? 1 : -1]
 Compile-time assertion. More...
 

Functions

void Q_onAssert (char_t const *const module, int_t location)
 Callback function invoked in case of any assertion failure. More...
 

Detailed Description

Customizable and memory-efficient assertions for embedded systems.

Definition in file qassert.h.

Macro Definition Documentation

◆ Q_DEFINE_THIS_FILE

#define Q_DEFINE_THIS_FILE   static char_t const Q_this_module_[] = __FILE__;

Define the file name (with __FILE__) for assertions in this file.

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.
Description
Macro to be placed at the top of each C/C++ module to define the single instance of the file name string to be used in reporting assertions in this module.
Note
The file name string literal is defined by means of the standard preprocessor macro __FILE__. However, please note that, depending on the compiler, the __FILE__ macro might contain the whole path name to the file, which might be inconvenient to log assertions.
This macro should not be terminated by a semicolon.
See also
Q_DEFINE_THIS_MODULE()

Definition at line 85 of file qassert.h.

◆ Q_DEFINE_THIS_MODULE

#define Q_DEFINE_THIS_MODULE (   name_)    static char_t const Q_this_module_[] = name_;

Define the user-specified module name for assertions in this file.

Description
Macro to be placed at the top of each C/C++ module to define the single instance of the module name string to be used in reporting assertions in this module. This macro takes the user-supplied parameter name_ instead of __FILE__ to precisely control the name of the module.
Parameters
[in]name_string constant representing the module name
Note
This macro should not be terminated by a semicolon.

Definition at line 101 of file qassert.h.

◆ Q_ASSERT

#define Q_ASSERT (   test_)
Value:
((test_) \
? (void)0 : Q_onAssert(&Q_this_module_[0], (int_t)__LINE__))
void Q_onAssert(char_t const *const module, int_t location)
Callback function invoked in case of any assertion failure.
int int_t
typedef for line numbers in assertions and return from QF_run()
Definition: qep.h:72

General purpose assertion.

Description
Makes sure the test_ parameter is TRUE. Calls the Q_onAssert() callback if the test_ expression evaluates to FALSE. This macro identifies the assertion location within the file by means of the standard __LINE__ macro.
Parameters
[in]test_Boolean expression
Note
the test_ is not evaluated if assertions are disabled with the Q_NASSERT switch.

Definition at line 117 of file qassert.h.

◆ Q_ASSERT_ID

#define Q_ASSERT_ID (   id_,
  test_ 
)
Value:
((test_) \
? (void)0 : Q_onAssert(&Q_this_module_[0], (int_t)(id_)))
void Q_onAssert(char_t const *const module, int_t location)
Callback function invoked in case of any assertion failure.
int int_t
typedef for line numbers in assertions and return from QF_run()
Definition: qep.h:72

General purpose assertion with user-specified assertion-id.

Description
Makes sure the test_ parameter is TRUE. Calls the Q_onAssert() callback if the test_ evaluates to FALSE. 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
[in]test_Boolean expression
Note
the test_ expression is not evaluated if assertions are disabled with the Q_NASSERT switch.

Definition at line 136 of file qassert.h.

◆ Q_ALLEGE

#define Q_ALLEGE (   test_)    Q_ASSERT(test_)

General purpose assertion that always evaluates the test_ expression.

Description
Like the Q_ASSERT() macro, except it always evaluates the test_ 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 test_ evaluates to FALSE.
Parameters
[in]test_Boolean expression (always evaluated)
See also
Q_ALLEGE_ID

Definition at line 152 of file qassert.h.

◆ Q_ALLEGE_ID

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

General purpose assertion with user-specified assertion-id that always evaluates the test_ expression.

Description
Like the Q_ASSERT_ID() macro, except it always evaluates the test_ 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 test_ evaluates to FALSE.
Parameters
[in]id_ID number (unique within the module) of the assertion
[in]test_Boolean expression

Definition at line 167 of file qassert.h.

◆ Q_ERROR

#define Q_ERROR ( )    Q_onAssert(&Q_this_module_[0], (int_t)__LINE__)

Assertion for a wrong path through the code.

Description
Calls the Q_onAssert() callback if ever executed.
Note
Does noting if assertions are disabled with the Q_NASSERT switch.

Definition at line 176 of file qassert.h.

◆ Q_ERROR_ID

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

Assertion with user-specified assertion-id for a wrong path.

Description
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.

Definition at line 192 of file qassert.h.

◆ Q_REQUIRE

#define Q_REQUIRE (   test_)    Q_ASSERT(test_)

Assertion for checking preconditions.

Description
This macro is equivalent to Q_ASSERT, except the name provides a better documentation of the intention of this assertion.
Parameters
[in]test_Boolean expression

Definition at line 243 of file qassert.h.

◆ Q_REQUIRE_ID

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

Assertion for checking preconditions with user-specified assertion-id.

Description
Equivalent to Q_ASSERT_ID, except the macro name provides a better documentation of the intention of this assertion.
Parameters
[in]id_ID number (unique within the module) of the assertion
[in]test_Boolean expression

Definition at line 254 of file qassert.h.

◆ Q_ENSURE

#define Q_ENSURE (   test_)    Q_ASSERT(test_)

Assertion for checking postconditions.

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

Parameters
[in]test_Boolean expression

Definition at line 262 of file qassert.h.

◆ Q_ENSURE_ID

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

Assertion for checking postconditions with user-specified assertion-id.

Description
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]test_Boolean expression

Definition at line 273 of file qassert.h.

◆ Q_INVARIANT

#define Q_INVARIANT (   test_)    Q_ASSERT(test_)

Assertion for checking invariants.

Description
Equivalent to Q_ASSERT, except the macro name provides a better documentation of the intention of this assertion.
Parameters
[in]test_Boolean expression

Definition at line 283 of file qassert.h.

◆ Q_INVARIANT_ID

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

Assertion for checking invariants with user-specified assertion-id.

Description
Equivalent to Q_ASSERT_ID, except the macro name provides a better documentation of the intention of this assertion.
Parameters
[in]id_ID number (unique within the module) of the assertion
[in]test_Boolean expression

Definition at line 294 of file qassert.h.

◆ Q_ASSERT_COMPILE

#define Q_ASSERT_COMPILE (   test_)    extern int_t Q_assert_compile[(test_) ? 1 : -1]

Compile-time assertion.

Description
This type of assertion deliberately causes a compile-time error when the test_ 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]test_Compile-time Boolean expression

Definition at line 306 of file qassert.h.

Function Documentation

◆ Q_onAssert()

void Q_onAssert ( char_t const *const  module,
int_t  location 
)

Callback function invoked in case of any assertion failure.

Description
This is an application-specific callback function needs to be defined in the application to perform the clean system shutdown and perhaps a reset.
Parameters
[in]modulename of the file/module in which the assertion failed (constant, zero-terminated C string)
[in]loclocation of the assertion within the module. This could be a line number or a user-specified ID-number.
Note
This callback function should not return, as continuation after an assertion failure does not make sense.
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.
It is typically a bad idea to implement Q_onAssert() as an endless loop that ties up the CPU. During debuggin, Q_onAssert() is an ideal place to put a breakpoint.

Called by the following macros: Q_ASSERT, Q_REQUIRE, Q_ENSURE, Q_ERROR, Q_ALLEGE as well as Q_ASSERT_ID, Q_REQUIRE_ID, Q_ENSURE_ID, Q_ERROR_ID, and Q_ALLEGE_ID.