Customizable and memory-efficient assertions for embedded systems.
More...
Go to the source code of this file.
|
#define | Q_DEFINE_THIS_FILE static char const Q_this_module_[] = __FILE__; |
|
#define | Q_DEFINE_THIS_MODULE(name_) static char const Q_this_module_[] = name_; |
|
#define | Q_ASSERT(test_) |
|
#define | Q_ASSERT_ID(id_, test_) |
|
#define | Q_ALLEGE(test_) Q_ASSERT(test_) |
|
#define | Q_ALLEGE_ID(id_, test_) Q_ASSERT_ID((id_), (test_)) |
|
#define | Q_ERROR() Q_onAssert(&Q_this_module_[0], __LINE__) |
|
#define | Q_ERROR_ID(id_) Q_onAssert(&Q_this_module_[0], (id_)) |
|
#define | Q_NORETURN void |
|
#define | Q_REQUIRE(test_) Q_ASSERT(test_) |
|
#define | Q_REQUIRE_ID(id_, test_) Q_ASSERT_ID((id_), (test_)) |
|
#define | Q_ENSURE(test_) Q_ASSERT(test_) |
|
#define | Q_ENSURE_ID(id_, test_) Q_ASSERT_ID((id_), (test_)) |
|
#define | Q_INVARIANT(test_) Q_ASSERT(test_) |
|
#define | Q_INVARIANT_ID(id_, test_) Q_ASSERT_ID((id_), (test_)) |
|
#define | Q_ASSERT_STATIC(test_) extern int_t Q_assert_static[(test_) ? 1 : -1] |
|
#define | Q_ASSERT_COMPILE(test_) Q_ASSERT_STATIC(test_) |
|
#define | Q_DIM(array_) (sizeof(array_) / sizeof((array_)[0U])) |
|
- Date
- Last updated on: 2021-12-23
- Version
- Last updated for: Version 7.0.0, 2022-04-30
Definition in file qassert.h.
◆ Q_DEFINE_THIS_FILE
#define Q_DEFINE_THIS_FILE static char const Q_this_module_[] = __FILE__; |
Define the file name (with __FILE__
) for assertions in this file
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 87 of file qassert.h.
◆ Q_DEFINE_THIS_MODULE
#define Q_DEFINE_THIS_MODULE |
( |
|
name_ | ) |
static char const Q_this_module_[] = name_; |
Define the user-specified module name for assertions in this file.
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 102 of file qassert.h.
◆ Q_ASSERT
#define Q_ASSERT |
( |
|
test_ | ) |
|
Value: ((test_) \
? (
void)0 :
Q_onAssert(&Q_this_module_[0], __LINE__))
Q_NORETURN Q_onAssert(char const *const module, int_t const location)
General purpose assertion.
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], (id_)))
General purpose assertion with user-specified assertion-id.
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 135 of file qassert.h.
◆ Q_ALLEGE
#define Q_ALLEGE |
( |
|
test_ | ) |
Q_ASSERT(test_) |
General purpose assertion that always evaluates the test_
expression.
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 150 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.
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 164 of file qassert.h.
◆ Q_ERROR
#define Q_ERROR |
( |
| ) |
Q_onAssert(&Q_this_module_[0], __LINE__) |
Assertion for a wrong path through the code.
Calls the Q_onAssert() callback if ever executed.
- Note
- Does noting if assertions are disabled with the Q_NASSERT switch.
Definition at line 172 of file qassert.h.
◆ Q_ERROR_ID
#define Q_ERROR_ID |
( |
|
id_ | ) |
Q_onAssert(&Q_this_module_[0], (id_)) |
Assertion with user-specified assertion-id for a wrong path
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 187 of file qassert.h.
◆ Q_NORETURN
no-return function specifier
Definition at line 199 of file qassert.h.
◆ Q_REQUIRE
#define Q_REQUIRE |
( |
|
test_ | ) |
Q_ASSERT(test_) |
Assertion for checking preconditions.
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 242 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.
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 252 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 261 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.
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 271 of file qassert.h.
◆ Q_INVARIANT
#define Q_INVARIANT |
( |
|
test_ | ) |
Q_ASSERT(test_) |
Assertion for checking invariants.
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 280 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.
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 290 of file qassert.h.
◆ Q_ASSERT_STATIC
#define Q_ASSERT_STATIC |
( |
|
test_ | ) |
extern int_t Q_assert_static[(test_) ? 1 : -1] |
Static (compile-time) assertion.
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 301 of file qassert.h.
◆ Q_ASSERT_COMPILE
◆ Q_DIM
#define Q_DIM |
( |
|
array_ | ) |
(sizeof(array_) / sizeof((array_)[0U])) |
Helper macro to calculate static dimension of a 1-dim array_
Definition at line 307 of file qassert.h.
◆ int_t
- 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.
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 Dir 4.6 (adv).
Definition at line 70 of file qassert.h.
◆ Q_onAssert()
Callback function invoked in case of any assertion failure.
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] | module | name of the file/module in which the assertion failed (constant, zero-terminated C string) |
[in] | location | location 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.
Definition at line 480 of file qutest.c.