Assertions and Argument Checking¶

LVGL provides two sets of macros for validating conditions at runtime: assertions and argument checking. This page explains when and how to use each within LVGL's codebase.

Overview¶

Feature	LV_ASSERT	LV_CHECK_ARG
Purpose	Catch programming errors	Validate runtime input
On failure	Halts (LV_ASSERT_HANDLER)	Configurable action
Log level	Error	Warning
Recovery possible	No	Yes / Maybe
Typical use	Internal invariants	API input validation

Use assertions for conditions that indicate bugs in the code—situations that should never happen if the code is correct.

Use argument checking for conditions that might legitimately fail at runtime (e.g., user-provided input, resource availability) and require graceful handling.

Assertions¶

Assertions check for programming errors and halt the program when they fail. They are typically enabled only in debug builds and may be disabled in release builds.

Configuration¶

Enable assertions in lv_conf.h:

LV_USE_ASSERT_NULL - Check for NULL pointers
LV_USE_ASSERT_MALLOC - Check for failed memory allocations
LV_USE_ASSERT_MEM_INTEGRITY - Check memory integrity

Configure the assert handler with LV_ASSERT_HANDLER. The default behavior is while(1); which halts the program.

Usage¶

LV_ASSERT

Basic assertion with the condition stringified in the log message:

LV_ASSERT(pi > 0);

LV_ASSERT_MSG

Assertion with a plain string message:

LV_ASSERT_MSG(pi > 0, "pi should be positive");

LV_ASSERT_FORMAT_MSG

Assertion with a printf-style format message:

LV_ASSERT_FORMAT_MSG(pi > 0, ": was %f", pi);

Specialized Assertions¶

LV_ASSERT_NULL

Check that a pointer is not NULL:

LV_ASSERT_NULL(obj);

LV_ASSERT_MALLOC

Check that a memory allocation succeeded:

void * buf = lv_malloc(size);
LV_ASSERT_MALLOC(buf);

LV_ASSERT_MEM_INTEGRITY

Check that LVGL's memory pool is not corrupted:

LV_ASSERT_MEM_INTEGRITY();

Argument Checking¶

The LV_CHECK_ARG macro provides a flexible approach for validating function arguments at runtime: it logs a warning and allows you to specify a recovery action (such as returning from a function or continuing with a fallback).

This macro is useful for:

Input validation at the start of functions
Checking preconditions without halting the program
Defensive programming with graceful error handling
Logging invariant violations that may not be critical but should be noted

Configuration¶

In lv_conf.h:

LV_USE_CHECK_ARG - Set to 1 to enable, 0 to disable. When disabled, all LV_CHECK_ARG calls compile to nothing.
LV_CHECK_ARG_ASSERT_ON_FAIL - Set to 1 to also call LV_ASSERT_HANDLER on failure (before the action is executed).

The macro uses the Logging system to output warnings. Make sure logging is enabled by setting LV_USE_LOG to 1.

Usage¶

LV_CHECK_ARG

Takes a condition, an action to execute on failure, and optional printf-style arguments for the log message:

void draw_to_display(lv_obj_t * display, int len)
{
    /* Return early if display is NULL */
    LV_CHECK_ARG(display != NULL, return, ": display must be provided");

    /* Return -1 if len is invalid, logging the actual value */
    LV_CHECK_ARG(len % 2 == 0, return, ": need even data points, but got %d", (int)len);
}

int get_width(lv_obj_t * obj)
{
    /* Return -1 if obj is NULL */
    LV_CHECK_ARG(obj != NULL, return -1, "tried to get width of NULL object");
    /* ... */
}

The condition is stringified and included in the log message, so you can see exactly what check failed. Only supply a format string and arguments if you want to include additional context beyond the condition itself.

Using break as the action in a loop:

for(int i = 0; i < count; i++) {
    LV_CHECK_ARG(data[i] != NULL, break, ": NULL at index %d", i);
    /* ... */
}

Macros Reference¶

Assertions¶

Macro	Description
`LV_ASSERT`	Assert condition; on failure log and halt
`LV_ASSERT_MSG`	Assert with plain string message
`LV_ASSERT_FORMAT_MSG`	Assert with printf-style format message
`LV_ASSERT_NULL`	Assert pointer is not NULL (if enabled)
`LV_ASSERT_MALLOC`	Assert allocation succeeded (if enabled)
`LV_ASSERT_MEM_INTEGRITY`	Assert memory pool integrity (if enabled)

Argument Checking¶

Macro	Description
`LV_CHECK_ARG`	Check condition; on failure log and execute action