zassert.h

Go to the documentation of this file.

/*
 * Copyright (c) 2026 Måns Ansgariusson <mansgariusson@gmail.com>
 *
 * SPDX-License-Identifier: Apache-2.0
 */
#ifndef ZEPHYR_INCLUDE_SYS_ZASSERT_H_
#define ZEPHYR_INCLUDE_SYS_ZASSERT_H_
 
#include <stdarg.h>
 
#include <zephyr/sys/util_macro.h>
#include <zephyr/toolchain.h>

 
/*
 * Granular, per-source-file assertions.
 *
 * ZASSERT_MODULE() opts a scope into the module-aware ZASSERT() macro. The
 * resulting assertion level is a compile-time constant, so disabled assertions
 * (and, below ZASSERT_LEVEL_VERBOSE, the message and its arguments) are folded away by
 * the optimizer. An individual file may set its level explicitly, overriding the
 * module default.
 *
 * For headers and inline functions, place ZASSERT_MODULE() inside the function
 * body so the selection does not leak into the includer, or use ZASSERT_TERSE(),
 * ZASSERT_NORMAL() or ZASSERT_VERBOSE() for an assertion with a fixed level.
 */

#define ZASSERT_LEVEL_OFF     0
#define ZASSERT_LEVEL_TERSE   1
#define ZASSERT_LEVEL_NORMAL  2
#define ZASSERT_LEVEL_VERBOSE 3
 
#ifdef __cplusplus
extern "C" {
#endif

#ifndef CONFIG_ASSERT_TEST
FUNC_NORETURN
#endif
__printf_like(4, 5)
void zassert_fail(const char *cond, const char *file, unsigned int line, const char *fmt, ...);

#ifndef CONFIG_ASSERT_TEST
FUNC_NORETURN
#endif
void zassert_post_action(const char *file, unsigned int line);

__printf_like(1, 0)
void zassert_vprint(const char *fmt, va_list ap);
 

static inline __printf_like(1, 2) void zassert_print(const char *fmt, ...)
{
        va_list ap;
 
        va_start(ap, fmt);
        zassert_vprint(fmt, ap);
        va_end(ap);
}
 
#ifdef __cplusplus
}
#endif
 
/* @cond INTERNAL_HIDDEN */
/* Level of a named Kconfig module: CONFIG_ASSERT_MODULE_<module>_LEVEL. */
#define ZASSERT_IMPL_MODULE_LEVEL(module) UTIL_CAT(UTIL_CAT(CONFIG_ASSERT_MODULE_, module), _LEVEL)
 
/*
 * ZASSERT_MODULE(module)        -> CONFIG_ASSERT_MODULE_<module>_LEVEL
 * ZASSERT_MODULE(module, level) -> explicit level
 */
#define ZASSERT_IMPL_LEVEL_RESOLVE(...) \
        GET_ARG_N(2, __VA_ARGS__, ZASSERT_IMPL_MODULE_LEVEL(GET_ARG_N(1, __VA_ARGS__)), _)
 
#ifndef CONFIG_ASSERT
#define ZASSERT_IMPL(_level, _test, ...)
#define ZASSERT_IMPL_MODULE(...)
#else
#define ZASSERT_IMPL(_level, _test, ...)                                                \
        do {                                                                            \
                if ((_level) != ZASSERT_LEVEL_OFF && unlikely(!(_test))) {              \
                        switch ((_level)) {                                             \
                        case ZASSERT_LEVEL_VERBOSE:                                     \
                                zassert_fail(Z_STRINGIFY(_test), __FILE__, __LINE__,    \
                                             COND_CODE_1(IS_EMPTY(__VA_ARGS__),         \
                                                         (NULL), (__VA_ARGS__)));       \
                                break;                                                  \
                        case ZASSERT_LEVEL_NORMAL:                                      \
                                zassert_fail(NULL, __FILE__, __LINE__, NULL);           \
                                break;                                                  \
                        case ZASSERT_LEVEL_TERSE:                                       \
                                zassert_fail(NULL, NULL, 0, NULL);                      \
                                break;                                                  \
                        default: /* ZASSERT_LEVEL_OFF */                                \
                                break;                                                  \
                        }                                                               \
                }                                                                       \
        } while (false)
 
#define ZASSERT_IMPL_MODULE(...)                                                                \
        BUILD_ASSERT((ZASSERT_IMPL_LEVEL_RESOLVE(__VA_ARGS__)) >= ZASSERT_LEVEL_OFF &&          \
                             (ZASSERT_IMPL_LEVEL_RESOLVE(__VA_ARGS__)) <= ZASSERT_LEVEL_VERBOSE,\
                     "Invalid assert level");                                                   \
        static const int zassert_impl_level __unused =                                          \
                IS_ENABLED(CONFIG_ASSERT) ? (ZASSERT_IMPL_LEVEL_RESOLVE(__VA_ARGS__))           \
                                           : ZASSERT_LEVEL_OFF
 
#endif /* ifndef CONFIG_ASSERT */
#define ZASSERT_IMPL_LEVEL(_level, _test, ...)                                                  \
        do {                                                                                    \
                BUILD_ASSERT((_level) >= ZASSERT_LEVEL_OFF && (_level) <= ZASSERT_LEVEL_VERBOSE,\
                             "Invalid assert level");                                           \
                ZASSERT_IMPL(_level, _test, ##__VA_ARGS__);                                     \
        } while (false)
/* @endcond */

#define ZASSERT_TERSE(_test, ...) ZASSERT_IMPL_LEVEL(ZASSERT_LEVEL_TERSE, (_test), ##__VA_ARGS__)

#define ZASSERT_NORMAL(_test, ...) ZASSERT_IMPL_LEVEL(ZASSERT_LEVEL_NORMAL, (_test), ##__VA_ARGS__)

#define ZASSERT_VERBOSE(_test, ...) \
        ZASSERT_IMPL_LEVEL(ZASSERT_LEVEL_VERBOSE, (_test), ##__VA_ARGS__)

#define ZASSERT_MODULE(...) ZASSERT_IMPL_MODULE(__VA_ARGS__)
#define ZASSERT(_test, ...) ZASSERT_IMPL(zassert_impl_level, _test, ##__VA_ARGS__)

 
#endif /* ZEPHYR_INCLUDE_SYS_ZASSERT_H_ */