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

Macros
#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]))

Typedefs
typedef int	int_t

Functions
Q_NORETURN	Q_onAssert (char const *const module, int_t const location)

Detailed Description

Date: Last updated on: 2021-12-23

Version: Last updated for: Version 7.0.0, 2022-04-30

Definition in file qassert.h.

Macro Definition Documentation

◆ 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_onAssert

Q_NORETURN Q_onAssert(char const *const module, int_t const location)

Definition: qutest.c:480

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

#define Q_NORETURN void

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

#define Q_ASSERT_COMPILE ( test_ ) Q_ASSERT_STATIC(test_)

Definition at line 304 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_

Definition at line 307 of file qassert.h.

Typedef Documentation

◆ int_t

typedef int 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.

Function Documentation

◆ Q_onAssert()

Q_NORETURN Q_onAssert	(	char const *const	module,
		int_t const	location
	)

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.

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ Q_DEFINE_THIS_FILE

◆ Q_DEFINE_THIS_MODULE

◆ Q_ASSERT

◆ Q_ASSERT_ID

◆ Q_ALLEGE

◆ Q_ALLEGE_ID

◆ Q_ERROR

◆ Q_ERROR_ID

◆ Q_NORETURN

◆ Q_REQUIRE

◆ Q_REQUIRE_ID

◆ Q_ENSURE

◆ Q_ENSURE_ID

◆ Q_INVARIANT

◆ Q_INVARIANT_ID

◆ Q_ASSERT_STATIC

◆ Q_ASSERT_COMPILE

◆ Q_DIM

Typedef Documentation

◆ int_t

Function Documentation

◆ Q_onAssert()