ra8_error_handler.h File Reference

Centralised fatal-error sink. More...

#include <stdint.h>

Include dependency graph for ra8_error_handler.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
void	ra8_fatal_error (const char *tag, const char *message, uint32_t err)
	Report a fatal error, log it, and halt.

Detailed Description

Centralised fatal-error sink.

ra8_fatal_error() is the single entry point for "stop running and alert the developer". Every RA8_ASSERT and every RA8_ERROR_CHECK that fails eventually lands here.

The default behaviour is:

1. Mask all interrupts.
2. Emit a log line on the default backend.
3. If a debugger is attached, __BKPT(0).
4. Loop in __WFI forever.

The loop is deliberate: we do not want to reset silently because that erases the state the developer needs to diagnose the fault. Field deployments can override ra8_fatal_error() with a weak symbol to add a watchdog reset.

Copyright

Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Definition in file ra8_error_handler.h.

Function Documentation

ra8_fatal_error()

void ra8_fatal_error	(	const char *	tag,
		const char *	message,
		uint32_t	err )

Report a fatal error, log it, and halt.

Parameters

[in]	tag	Short tag describing the source ("ASSERT", "ERROR_CHECK", "HARDFAULT", ...).
[in]	message	String literal describing the failure.
[in]	err	Error code classifying the failure (may be 0 for plain assertion failures).

Note

Never returns.

Warning

Do not call from time-critical ISR paths unless you accept that the system will not come back.

Report a fatal error, log it, and halt.

Disables interrupts, emits a best-effort error line plus the numeric err code, then traps via BKPT and an infinite loop (or __builtin_trap on the off-target host so unit tests fail loudly instead of spinning forever).

Parameters

[in]	tag	NUL-terminated module/component tag.
[in]	message	NUL-terminated short failure description.
[in]	err	Numeric error code (typically a ra8_err_t value).

Precondition

tag and message are non-NULL, NUL-terminated.

Interrupt state is recoverable from disabled (we never return).

Postcondition

Interrupts are masked.

Function does not return; control is trapped or loops forever.

Note

Weak symbol; downstream apps may override with a richer halt path.

Since

0.1.0

Definition at line 133 of file ra8_error_handler.c.

References internal_bkpt(), internal_disable_irq(), internal_wfi(), ra8_log_error, and ra8_log_error_val.

Referenced by _sbrk().