libopencm3
A free/libre/open-source firmware library for various ARM Cortex-M3 microcontrollers.
Debugging

Macros and functions to aid in debugging. More...

Collaboration diagram for Debugging:

Macros

#define CM3_LIKELY(expr)   (__builtin_expect(!!(expr), 1))
 
#define cm3_assert(expr)
 Check if assertion is true. More...
 
#define cm3_assert_not_reached()   cm3_assert_failed()
 Check if unreachable code is reached. More...
 

Functions

void cm3_assert_failed (void)
 Called on a failed assertion. More...
 
void cm3_assert_failed_verbose (const char *file, int line, const char *func, const char *assert_expr)
 Called on a failed assertion with verbose messages enabled. More...
 

Detailed Description

Macros and functions to aid in debugging.

Version
1.0.0
Date
25 September 2012

Two preprocessor defines control the behavior of assertion check macros in this module. They allow the choice between generated code size and ease of debugging.

If NDEBUG is defined, all assertion checks are disabled and macros do not generate any code.

If CM3_ASSERT_VERBOSE is defined, information regarding the position of assertion checks will be stored in the binary, allowing for more informative error messages, but also significantly increased code size. As default assertion checks do not use this information it is only useful if the application linked with libopencm3 defines its own cm3_assert_failed_verbose() implementation.

LGPL License Terms libopencm3 License

Macro Definition Documentation

◆ cm3_assert

#define cm3_assert (   expr)
Value:
do { \
if (CM3_LIKELY(expr)) { \
(void)0; \
} else { \
cm3_assert_failed(); \
} \
} while (0)
#define CM3_LIKELY(expr)
Definition: assert.h:53

Check if assertion is true.

If NDEBUG macro is defined, this macro generates no code. Otherwise cm3_assert_failed() or cm3_assert_failed_verbose() is called if assertion is false.

The purpose of this macro is to aid in debugging libopencm3 and applications using it. It can be used for example to check if function arguments are within expected ranges and stop execution in case an unexpected state is reached.

Parameters
exprexpression to check

Definition at line 86 of file assert.h.

◆ cm3_assert_not_reached

#define cm3_assert_not_reached ( )    cm3_assert_failed()

Check if unreachable code is reached.

If NDEBUG macro is defined, this macro generates code for an infinite loop. Otherwise cm3_assert_failed() or cm3_assert_failed_verbose() is called if the macro is ever reached.

The purpose of this macro is to aid in debugging libopencm3 and applications using it. It can be used for example to stop execution if an unreachable portion of code is reached.

Definition at line 102 of file assert.h.

◆ CM3_LIKELY

#define CM3_LIKELY (   expr)    (__builtin_expect(!!(expr), 1))

Definition at line 53 of file assert.h.

Function Documentation

◆ cm3_assert_failed()

void cm3_assert_failed ( void  )

Called on a failed assertion.

Halts execution in an infinite loop. This function never returns.

Defined as a weak symbol, so applications can define their own implementation. Usually, a custom implementation of this function should report an error in some way (print a message to a debug console, display, LED, ...) and halt execution or reboot the device.

Definition at line 22 of file assert.c.

Referenced by cm3_assert_failed_verbose().

Here is the caller graph for this function:

◆ cm3_assert_failed_verbose()

void cm3_assert_failed_verbose ( const char *  file,
int  line,
const char *  func,
const char *  assert_expr 
)

Called on a failed assertion with verbose messages enabled.

Halts execution in an infinite loop. This function never returns.

Defined as a weak symbol, so applications can define their own implementation. Usually, a custom implementation of this function should report an error in some way (print a message to a debug console, display, LED, ...) and halt execution or reboot the device.

Parameters
fileFile name where the failed assertion occurred
lineLine number where the failed assertion occurred
funcName of the function where the failed assertion occurred
assert_exprExpression that evaluated to false (can be NULL)

Definition at line 27 of file assert.c.

References cm3_assert_failed().

Here is the call graph for this function: