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

This graph shows which files directly or indirectly include 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], __LINE__)
	Assertion for a wrong path through the code. More...

#define	Q_ERROR_ID(id_) Q_onAssert(&Q_this_module_[0], (id_))
	Assertion with user-specified assertion-id for a wrong path. More...

#define	Q_NORETURN void
	no-return function specifier 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_STATIC(test_) extern int_t Q_assert_static[(test_) ? 1 : -1]
	Static (compile-time) assertion. More...

#define	Q_ASSERT_COMPILE(test_) Q_ASSERT_STATIC(test_)

#define	Q_DIM(array_) (sizeof(array_) / sizeof((array_)[0U]))
	Helper macro to calculate static dimension of a 1-dim `array_`. More...

Typedefs
typedef char	char_t
	typedef for character strings. More...

typedef int	int_t
	typedef for assertions-ids and line numbers in assertions. More...

Functions
Q_NORETURN	Q_onAssert (char_t const *const module, int_t const 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.

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 104 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 120 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_t const *const module, int_t const location)

Callback function invoked in case of any assertion failure.

Definition: qutest.c:437

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

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 155 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 171 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 186 of file qassert.h.

◆ Q_ERROR

#define Q_ERROR ( ) Q_onAssert(&Q_this_module_[0], __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 195 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.

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 211 of file qassert.h.

◆ Q_NORETURN

#define Q_NORETURN void

no-return function specifier

Definition at line 223 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 268 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 279 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 287 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 298 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 308 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 319 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.

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 331 of file qassert.h.

◆ Q_ASSERT_COMPILE

#define Q_ASSERT_COMPILE ( test_ ) Q_ASSERT_STATIC(test_)

Definition at line 334 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 337 of file qassert.h.

Typedef Documentation

◆ char_t

typedef char char_t

typedef for character strings.

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: This typedef specifies character type for exclusive use in character strings. Use of this type, rather than plain 'char', is in compliance with the MISRA-C 2004 Rules 6.1(req), 6.3(adv).

Definition at line 77 of file qassert.h.

◆ int_t

typedef int int_t

typedef for assertions-ids and line numbers in assertions.

Description: 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 2004 Rules 6.1(req), 6.3(adv).

Definition at line 86 of file qassert.h.

Function Documentation

◆ Q_onAssert()

Q_NORETURN Q_onAssert	(	char_t const *const	module,
		int_t const	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]	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 437 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

◆ char_t

◆ int_t

Function Documentation

◆ Q_onAssert()