PAL Error Handling

Topics
	ESP32 error implementation

Macros
#define	PAL_ERR_TO_NAME(err)
	Convert a pal_err_t code to its human-readable name.
#define	PAL_CHECK(x, tag, msg)
	Macro that evaluates an expression and call a return if the result is different from PAL_OK.
#define	PAL_CHECK_COND(cond, tag, msg)
	Macro that evaluates a boolean condition and call a return if the result is false.

Typedefs
typedef int	pal_err_t

Functions
static const char *	_pal_err_to_name (pal_err_t err)
	Convert a pal_err_t code to its human-readable name.

Error Codes
#define	PAL_OK   0
	Operation completed successfully.
#define	PAL_FAIL   -1
	Generic failure.
#define	PAL_ERR_NO_MEM   -2
	Memory allocation failed.
#define	PAL_ERR_INVALID_ARG   -3
	One or more arguments are invalid.
#define	PAL_ERR_INVALID_STATE   -4
	The current state does not permit this operation.
#define	PAL_ERR_INVALID_SIZE   -5
	A size value is out of the valid range.
#define	PAL_ERR_NOT_FOUND   -6
	Requested resource was not found.
#define	PAL_ERR_NOT_SUPPORTED   -7
	Operation or feature is not supported.
#define	PAL_ERR_TIMEOUT   -8
	Operation timed out.
#define	PAL_ERR_INVALID_CRC   -9
	CRC check failed.
#define	PAL_ERR_NOT_FINISHED   -10
	Operation has not finished yet.
#define	PAL_ERR_NOT_ALLOWED   -11
	Operation is not permitted in the current context.

Detailed Description

Copyright

Copyright (c) 2026 Adrien Chevrier. Under AGPL-3.0-or-later license.

Platform-agnostic error codes and checking macros. On ESP32 targets, the type and constants are aliased to their esp_err_t equivalents via pal_err_esp.h so that PAL error values are directly interchangeable with ESP-IDF return values.

Macro Definition Documentation

PAL_CHECK

#define PAL_CHECK	(		x,
			tag,
			msg )

Value:

    do {                                                        \
        pal_err_t __;                                           \
        if ((__ = (x)) != PAL_OK) {                             \
            PAL_LOGE(tag, "%s (%s)", msg, PAL_ERR_TO_NAME(__)); \
            return __;                                          \
        }                                                       \
    } while (0)

Macro that evaluates an expression and call a return if the result is different from PAL_OK.

Logs an error message including the error name before calling a return statement with the obtained result.

Parameters

[in]	x	Expression that evaluates to a pal_err_t.
[in]	tag	Logging tag string.
[in]	msg	Human-readable message to log on failure.

PAL_CHECK_COND

#define PAL_CHECK_COND	(		cond,
			tag,
			msg )

Value:

    do {                                \
        if (!(cond)) {                  \
            PAL_LOGE(tag, msg);         \
            return PAL_ERR_INVALID_ARG; \
        }                               \
    } while (0)

Macro that evaluates a boolean condition and call a return if the result is false.

Logs an error message before calling a return statement with PAL_ERR_INVALID_ARG as result.

Parameters

[in]	cond	Boolean condition that must be true to continue.
[in]	tag	Logging tag string.
[in]	msg	Human-readable message to log when cond is false.

PAL_ERR_INVALID_ARG

#define PAL_ERR_INVALID_ARG   -3

One or more arguments are invalid.

PAL_ERR_INVALID_CRC

#define PAL_ERR_INVALID_CRC   -9

CRC check failed.

PAL_ERR_INVALID_SIZE

#define PAL_ERR_INVALID_SIZE   -5

A size value is out of the valid range.

PAL_ERR_INVALID_STATE

#define PAL_ERR_INVALID_STATE   -4

The current state does not permit this operation.

PAL_ERR_NO_MEM

#define PAL_ERR_NO_MEM   -2

Memory allocation failed.

PAL_ERR_NOT_ALLOWED

#define PAL_ERR_NOT_ALLOWED   -11

Operation is not permitted in the current context.

PAL_ERR_NOT_FINISHED

#define PAL_ERR_NOT_FINISHED   -10

Operation has not finished yet.

PAL_ERR_NOT_FOUND

#define PAL_ERR_NOT_FOUND   -6

Requested resource was not found.

PAL_ERR_NOT_SUPPORTED

#define PAL_ERR_NOT_SUPPORTED   -7

Operation or feature is not supported.

PAL_ERR_TIMEOUT

#define PAL_ERR_TIMEOUT   -8

Operation timed out.

PAL_ERR_TO_NAME

#define PAL_ERR_TO_NAME

(

err

)

Value:

_pal_err_to_name(err)

Convert a pal_err_t code to its human-readable name.

Parameters

[in]

err

Error code to convert.

Returns

A constant string with the error name, or "unknown" if the code is not recognized.

PAL_FAIL

#define PAL_FAIL   -1

Generic failure.

PAL_OK

#define PAL_OK   0

Operation completed successfully.

Typedef Documentation

pal_err_t

typedef int pal_err_t

Function Documentation

_pal_err_to_name()

static const char * _pal_err_to_name ( pal_err_t err )

inlinestatic

Convert a pal_err_t code to its human-readable name.

Parameters

[in]

err

Error code to convert.

Returns

A constant string with the error name, or "unknown" if the code is not recognized.

Warning

This function shall not be used because it may be overridden by a plateform-specific implementation. Use the macro PAL_ERR_TO_NAME(err) instead.