Module based assert handling

Macros
#define	ZASSERT_LEVEL_OFF   0
	Assertions are disabled and compiled out.
#define	ZASSERT_LEVEL_TERSE   1
	Assertions are checked; No additional information is reported.
#define	ZASSERT_LEVEL_NORMAL   2
	Assertions are checked; only the failing location is reported.
#define	ZASSERT_LEVEL_VERBOSE   3
	Assertions are checked; condition, location and message are reported.
#define	ZASSERT_TERSE(_test, ...)
	Assertion that reports only a fixed banner (no location or message).
#define	ZASSERT_NORMAL(_test, ...)
	Assertion that reports only the failing location.
#define	ZASSERT_VERBOSE(_test, ...)
	Assertion that reports the condition, location and optional message.
#define	ZASSERT_MODULE(...)
	Select the Kconfig-defined assertion module used by ZASSERT() in this file.
#define	ZASSERT(_test, ...)
	Module-aware assertion.

Functions
FUNC_NORETURN void	zassert_fail (const char *cond, const char *file, unsigned int line, const char *fmt,...)
	Report a failed assertion and take terminal action.
FUNC_NORETURN void	zassert_post_action (const char *file, unsigned int line)
	Terminal action taken on assertion failure.
void	zassert_vprint (const char *fmt, va_list ap)
	Emit assertion text (va_list form).
static void	zassert_print (const char *fmt,...)
	Emit assertion text (printf like), routed through zassert_vprint().

Detailed Description

Macro Definition Documentation

ZASSERT

#define ZASSERT	(		_test,
			... )

#include <zassert.h>

Value:

ZASSERT_IMPL(zassert_impl_level, _test, ##__VA_ARGS__)

Module-aware assertion.

Gated by the level from ZASSERT_MODULE() in this file. At ZASSERT_LEVEL_TERSE only a fixed "ASSERTION FAIL" banner is reported. At ZASSERT_LEVEL_NORMAL the failing location is added. At ZASSERT_LEVEL_VERBOSE the stringified condition and the optional message and its arguments are also compiled in and printed.

Parameters

_test	Condition to check. A fatal error is raised if it is false.
...	Optional message format string followed by its arguments. May be omitted when the check is self-explanatory.

ZASSERT_LEVEL_NORMAL

#define ZASSERT_LEVEL_NORMAL   2

#include <zassert.h>

Assertions are checked; only the failing location is reported.

ZASSERT_LEVEL_OFF

#define ZASSERT_LEVEL_OFF   0

#include <zassert.h>

Assertions are disabled and compiled out.

ZASSERT_LEVEL_TERSE

#define ZASSERT_LEVEL_TERSE   1

#include <zassert.h>

Assertions are checked; No additional information is reported.

ZASSERT_LEVEL_VERBOSE

#define ZASSERT_LEVEL_VERBOSE   3

#include <zassert.h>

Assertions are checked; condition, location and message are reported.

ZASSERT_MODULE

#define ZASSERT_MODULE

(

...

)

#include <zassert.h>

Value:

ZASSERT_IMPL_MODULE(__VA_ARGS__)

Select the Kconfig-defined assertion module used by ZASSERT() in this file.

Must be placed at file scope before any use of ZASSERT() in the translation unit. Every file that uses ZASSERT() must select a module.

Parameters

...

The assertion module name (an UPPERCASE identifier) followed by an optional explicit level. The module's default level is taken from the Kconfig symbol CONFIG_ASSERT_MODULE_<module>_LEVEL, which must exist (the name is pasted verbatim, so it must match). An optional second argument (ZASSERT_LEVEL_OFF, ZASSERT_LEVEL_TERSE, ZASSERT_LEVEL_NORMAL or ZASSERT_LEVEL_VERBOSE) overrides the module default for this file.

Note

CONFIG_ASSERT is the master switch: when it is disabled every module is forced to ZASSERT_LEVEL_OFF, regardless of the module default or an explicit level.

ZASSERT_NORMAL

#define ZASSERT_NORMAL	(		_test,
			... )

#include <zassert.h>

Value:

ZASSERT_IMPL_LEVEL(ZASSERT_LEVEL_NORMAL, (_test), ##__VA_ARGS__)

Assertion that reports only the failing location.

Parameters

_test	Condition to check. A fatal error is raised if it is false.
...	Ignored optional message format string and arguments.

ZASSERT_TERSE

#define ZASSERT_TERSE	(		_test,
			... )

#include <zassert.h>

Value:

ZASSERT_IMPL_LEVEL(ZASSERT_LEVEL_TERSE, (_test), ##__VA_ARGS__)

Assertion that reports only a fixed banner (no location or message).

Parameters

_test	Condition to check. A fatal error is raised if it is false.
...	Ignored optional message format string and arguments.

ZASSERT_VERBOSE

#define ZASSERT_VERBOSE	(		_test,
			... )

#include <zassert.h>

Value:

ZASSERT_IMPL_LEVEL(ZASSERT_LEVEL_VERBOSE, (_test), ##__VA_ARGS__)

Assertion that reports the condition, location and optional message.

Parameters

_test	Condition to check. A fatal error is raised if it is false.
...	Optional message format string followed by its arguments.

Function Documentation

zassert_fail()

FUNC_NORETURN void zassert_fail	(	const char *	cond,
		const char *	file,
		unsigned int	line,
		const char *	fmt,
			... )

#include <zassert.h>

Report a failed assertion and take terminal action.

Weak, overridable.

Consolidates the entire assertion cold path into a single out-of-line call: the default implementation prints the location (and, when fmt is non-NULL, the user message) and then invokes zassert_post_action(). Overriding this is the single surface for capturing or redirecting the whole assertion output.

Parameters

cond	Stringified failing condition.
file	Source file of the failing assertion.
line	Source line of the failing assertion.
fmt	Optional user message format string, or NULL when none.
...	Arguments for fmt.

zassert_post_action()

FUNC_NORETURN void zassert_post_action	(	const char *	file,
		unsigned int	line )

#include <zassert.h>

Terminal action taken on assertion failure.

Weak, overridable.

zassert_print()

void zassert_print ( const char * fmt, ... )

inlinestatic

#include <zassert.h>

Emit assertion text (printf like), routed through zassert_vprint().

Parameters

fmt	Message format string.
...	Arguments for fmt.

zassert_vprint()

void zassert_vprint	(	const char *	fmt,
		va_list	ap )

#include <zassert.h>

Emit assertion text (va_list form).

Weak, overridable.

The single primitive through which all assertion output flows: the default zassert_fail() and zassert_print() route their text here. Override it to capture or redirect every assertion message from one place.

Parameters

fmt	Message format string.
ap	Arguments for fmt.