Error Handling

Overview

The error handling system provides a centralized way to define, report, and handle errors. It can be added to any application by enabling the CONFIG_NTURT_ERR Kconfig option.

Core concepts

  • Severity Levels: Errors are categorized into different severity levels in err_sev.

  • Error Codes: Each error is identified by a unique error code defined using ERR_DEFINE, which does not need to be contiguous.

  • Callbacks: Modules can register callbacks via ERR_CALLBACK_DEFINE to be called when an error is reported (set or cleared). The callbacks may be optionally registered with filters to specify which errors they should handle using ERR_FILTER_CODE or ERR_FILTER_SEV.

Runtime Behavior

  • Initialization: During system initialization, reported errors are deferred until CONFIG_NTURT_ERR_CB_DISPATCH_PRIORITY is reached. This allows error callbacks from modules not yet initialized to be processed later.

  • Order of Callback Dispatch: At CONFIG_NTURT_ERR_CB_DISPATCH_PRIORITY initialization priority, errors defined with ERR_FLAG_SET are first processed, followed by the same order errors were reported.

    Warning

    Since the error callbacks are deferred, during callback dispatch, handlers may observe future errors that were reported after the current error was set.

  • Execution Context: Error callbacks are executed in the same context of the thread that reported the error, and they are reentrant and thread-safe.

Usage

Defining Errors

Use ERR_DEFINE to define one error. For example:

ERR_DEFINE(my_error, 0x01, ERR_SEV_FATAL, "My error occurred");

Errors may also be defined with additional flags to control their behavior, those include:

  • ERR_FLAG_SET: Indicates that the error is set after initialization.

  • ERR_FLAG_DISABLED: Indicates that the error is disabled and setting or clearing the error will not have any effect.

Reporting Errors

Use err_report() to report an error using its code:

err_report(0x01, true);  // set the error
err_report(0x01, false); // clear the error

Handling Errors

Use the ERR_CALLBACK_DEFINE to define a callback to handle errors in event-driven fasion. For example:

static void my_error_handler(uint32_t errcode, bool set, void* user_data) {
    // handle the error
}

ERR_CALLBACK_DEFINE(my_error_handler, NULL);

You can also filter which errors the callback should handle using ERR_FILTER_CODE or ERR_FILTER_SEV:

ERR_CALLBACK_DEFINE(my_error_handler, NULL, ERR_FILTER_CODE(0x01));

// or

ERR_CALLBACK_DEFINE(my_error_handler, NULL, ERR_FILTER_SEV(ERR_SEV_FATAL));

When two filters are specified, they are combined using logical AND, meaning the callback will only be invoked if both conditions are met.

Errors may also be polled using err_is_set() or ERR_FOREACH_SET to iterate over all currently set errors.

API Reference

group Error

Error passing and handling support.

Defines

ERR_FLAG_DISABLED

Flag indicating the error is disabled, meaning setting or clearing the error will not have any effect.

ERR_FLAG_SET

Flag indicating the error is set. Can also be used in ERR_DEFINE to define an error that will be set after initialization.

ERR_FLAG_SEV_MASK

Flag mask indicating the severity of the error.

ERR_DEFINE(_name, _errcode, _serverity, _desc, ...)

Define an error.

Parameters:

  • _name – [in] Name of the error.

  • _errcode – [in] Code of the error.

  • _serverity – [in] Serverity of the error, must be one of err_sev.

  • _desc – [in] Description of the error.

  • ... – [in] Optional flags of the error, multiple flags can be specified by using the bitwise OR operator (|).

ERR_FILTER_CODE(...)

Error filter for error codes.

Parameters:

  • ... – [in] Error codes to filter.

ERR_FILTER_SEV(...)

Error filter for severities.

Parameters:

  • ... – [in] Severities to filter.

ERR_CALLBACK_DEFINE_NAMED(_name, _handler, _user_data, ...)

Same as ERR_CALLBACK_DEFINE, but with a custom name for the callback.

ERR_CALLBACK_DEFINE(handler, user_data, ...)

Define an error callback.

Note

Since the name of the callback is derived from the name of handler , if the same handler is used for multiple callbacks, ERR_CALLBACK_DEFINE_NAMED can be used instead to prevent linker errors.

Parameters:

  • handler – [in] Handler of the error.

  • user_data – [in] Pointer to custom data for the callback.

  • ... – [in] Optional filters for the error callback. If multiple filters are specified, they are applied in the “and” manner.

ERR_FOREACH_SET(item)

Iterate over all set errors.

Parameters:

  • item – [out] Error pointer to the set errors, NULL if the loop exits normally or no errors are set.

Typedefs

typedef void (*err_handler_t)(uint32_t errcode, bool set, void *user_data)

Error handler type.

Param errcode:

[in] Code of the error.

Param set:

[in] True if the error is set, false if the error is cleared.

Param user_data:

[inout] Pointer to custom user data for the callback provided by ERR_CALLBACK_DEFINE.

Enums

enum err_sev

Error severity.

Values:

enumerator ERR_SEV_INFO = BIT(0)

Info serverity, the system operates normally.

enumerator ERR_SEV_WARN = BIT(1)

Warning serverity, the system may continue running.

enumerator ERR_SEV_FATAL = BIT(2)

Fatal serverity, the system must stop.

enum err_filter_type

Error filter type.

Values:

enumerator ERR_FILTER_TYPE_INVALID = 0

Invalid filter, internal use only.

enumerator ERR_FILTER_TYPE_CODE = 1

Filter for error codes.

enumerator ERR_FILTER_TYPE_SEV = 2

Filter for severities.

Functions

void err_report(uint32_t errcode, bool set)

Set or clear error.

Parameters:

  • errcode – [in] Error code to set or clear.

  • set – [in] True to set error, false to clear error.

bool err_is_set(uint32_t errcode)

Check if the error is set.

Parameters:

  • errcode – [in] Error code to check.

Returns:

true if the error is set, false otherwise.

struct err
#include <nturt/err/err.h>

Error.

Public Functions

TAILQ_ENTRY (err) next

List entry of the error.

Public Members

uint32_t errcode

Code of the error.

const char *name

String representation of the error.

const char *desc

Description of the error.

struct err_filter
#include <nturt/err/err.h>

Error filter for error callbacks.

Public Members

enum err_filter_type type

Type of the filter.

size_t size

Number of elements in the filter.

uint32_t *errcodes

Error codes to filter.

uint32_t *serverities

Severities to filter.

struct err_callback
#include <nturt/err/err.h>

Error callback.

Public Members

err_handler_t handler

Error handler.

void *user_data

User data for the callback functions.

size_t size

Number of error filters.

struct err_filter *filters

Array of error filters.