Bounded wait-flag primitives for RA8D2 HAL drivers. More...

#include <stdint.h>
#include "ra8_err.h"

Include dependency graph for ra8_hw_err.h:

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

Enumerations
enum	ra8_hw_err_budget_t : uint32_t { k_ra8_hw_budget_short = 0x00000400U , k_ra8_hw_budget_medium = 0x00004000U , k_ra8_hw_budget_long = 0x00040000U , k_ra8_hw_budget_xlong = 0x00400000U }
	Default polling budgets for ra8_hw_wait_flag_*. More...

Functions
static ra8_err_t	ra8_hw_wait_flag_set8 (volatile const uint8_t *reg, uint8_t mask, uint32_t budget)
	Spin until (*reg & mask) != 0 or budget runs out.
static ra8_err_t	ra8_hw_wait_flag_clear8 (volatile const uint8_t *reg, uint8_t mask, uint32_t budget)
	Spin until (*reg & mask) == 0 or budget runs out.
static ra8_err_t	ra8_hw_wait_flag_set32 (volatile const uint32_t *reg, uint32_t mask, uint32_t budget)
	Spin until (*reg & mask) != 0 or budget runs out.
static ra8_err_t	ra8_hw_wait_flag_clear32 (volatile const uint32_t *reg, uint32_t mask, uint32_t budget)
	Spin until (*reg & mask) == 0 or budget runs out.

Detailed Description

Bounded wait-flag primitives for RA8D2 HAL drivers.

Tag: [Ring 3 / HAL] {World: S} (header-only)

Ring 3 / HAL substrate. Header-only because every helper here is a single short loop that the compiler should inline at the call site – making them static inline keeps the symbol weight to zero in the cross-build.

Driver code on the RA8D2 is full of "spin until this status bit changes" sequences:

SCI: poll TDRE before each TDR write
IIC: poll BBSY before issuing START
GPT: poll TCR.SE before reading the count
CGC: poll OSCSF.* for oscillator stabilisation
RTC: poll RWAIT for register-update lockout

Every one of those loops needs:

A statically provable upper bound (NASA Power of 10 Rule 2).
An ra8_err_t return so callers can propagate the timeout via RA8_RETURN_ON_ERROR.
Optional cycle-friendly behaviour on the target (a wfe hint, or just a memory barrier so the compiler does not hoist the load out of the loop).

The four helpers below cover every flavour the existing 29 driver shells need:

ra8_hw_wait_flag_set8 – 8-bit register, wait until a mask reads as set.
ra8_hw_wait_flag_clear8 – 8-bit register, wait until a mask reads as clear.
ra8_hw_wait_flag_set32 – 32-bit register, wait set.
ra8_hw_wait_flag_clear32 – 32-bit register, wait clear.

Each takes a pointer to a volatile register, a mask, and a spin budget. The spin budget is a uint32_t so callers can pick from a typed enum without needing yet another wrapper.

On success the helper returns k_ra8_ok. On budget exhaustion it returns k_ra8_err_hw_timeout. There is no other failure mode.

The implementation does NOT issue __WFE, __DSB or any other Cortex-M intrinsic – those are bring-up-time decisions that belong in the calling driver. The barrier here is just the volatile qualifier on the register pointer, which is sufficient to keep the compiler from hoisting the load.

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

Definition in file ra8_hw_err.h.

Enumeration Type Documentation

◆ ra8_hw_err_budget_t

enum ra8_hw_err_budget_t : uint32_t

Default polling budgets for ra8_hw_wait_flag_*.

Drivers SHOULD use one of these named budgets rather than inventing their own integer literal. Each value is set so that a worst-case Cortex-M85 at 1 GHz spends a comfortable margin over the longest documented stabilisation time for the relevant peripheral, multiplied by ~4 for safety.

k_ra8_hw_budget_short ~1 us at 1 GHz – bus handshakes
k_ra8_hw_budget_medium ~10 us – TX FIFO drain
k_ra8_hw_budget_long ~100 us – oscillator wait
k_ra8_hw_budget_xlong ~1 ms – PLL relock

Enumerator
k_ra8_hw_budget_short	RA8 hw budget short.
k_ra8_hw_budget_medium	RA8 hw budget medium.
k_ra8_hw_budget_long	RA8 hw budget long.
k_ra8_hw_budget_xlong	RA8 hw budget xlong.

Definition at line 171 of file ra8_hw_err.h.

Function Documentation

◆ ra8_hw_wait_flag_clear32()

ra8_err_t ra8_hw_wait_flag_clear32	(	volatile const uint32_t *	reg,
		uint32_t	mask,
		uint32_t	budget )

inlinestatic

Spin until (*reg & mask) == 0 or budget runs out.

Parameters

[in]	reg	Pointer to the volatile 32-bit register to poll.
[in]	mask	Bit mask to test for "clear".
[in]	budget	Spin budget.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	The flag was observed as clear within the budget.
k_ra8_err_hw_timeout	The budget ran out without the flag observed.
k_ra8_err_null_ptr	reg was NULL.

Precondition: reg is non-NULL.; budget > 0.

Postcondition: No hardware state is modified.; On success, the latest read returned the mask clear.

Note: Inline. Not thread-safe.

Since: 0.1.0

See implementation.

Definition at line 351 of file ra8_hw_err.h.

References k_ra8_err_hw_timeout, k_ra8_err_null_ptr, and k_ra8_ok.

Referenced by internal_lin_wait_break_done(), internal_mdio_drain(), internal_set_global_mode(), internal_set_vscr_not_high_v(), internal_tas_learn_entry(), internal_wait_fifo_reset_clear(), internal_wait_ssirst_clear(), priv_ra8_canfd_internal_set_channel_mode(), ra8_dotf_run_self_test(), ra8_eth_gwca_reload_queue(), ra8_etha_read_tas_entry(), ra8_vin_capture_disarm(), and ra8_xspi_calibrate_dqs().

◆ ra8_hw_wait_flag_clear8()

ra8_err_t ra8_hw_wait_flag_clear8	(	volatile const uint8_t *	reg,
		uint8_t	mask,
		uint32_t	budget )

inlinestatic

Spin until (*reg & mask) == 0 or budget runs out.

Parameters

[in]	reg	Pointer to the volatile 8-bit register to poll.
[in]	mask	Bit mask to test for "clear".
[in]	budget	Spin budget. See ra8_hw_err_budget_t.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	The flag was observed as clear.
k_ra8_err_hw_timeout	Budget exhausted.
k_ra8_err_null_ptr	reg was NULL.

Precondition: reg is non-NULL.; budget > 0.

Postcondition: No hardware state is modified.; On success, the most recent read returned mask clear.

Note: Inline. Not thread-safe.

Since: 0.1.0

See implementation.

Definition at line 262 of file ra8_hw_err.h.

References k_ra8_err_hw_timeout, k_ra8_err_null_ptr, and k_ra8_ok.

Referenced by internal_route_sciclk(), internal_wait_canfdcksrdy(), internal_wait_cksrdy(), internal_wait_octacksrdy(), internal_wait_pdctreswm_clear(), internal_wait_usb60cksrdy(), internal_wait_usbcksrdy(), priv_ra8_cgc_wait_oscsf_clear(), and ra8_ulpt_stop().

◆ ra8_hw_wait_flag_set32()

ra8_err_t ra8_hw_wait_flag_set32	(	volatile const uint32_t *	reg,
		uint32_t	mask,
		uint32_t	budget )

inlinestatic

Spin until (*reg & mask) != 0 or budget runs out.

Parameters

[in]	reg	Pointer to the volatile 32-bit register to poll.
[in]	mask	Bit mask to test for "set".
[in]	budget	Spin budget.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	The flag was observed as set within the budget.
k_ra8_err_hw_timeout	The budget ran out without the flag observed.
k_ra8_err_null_ptr	reg was NULL.

Precondition: reg is non-NULL.; budget > 0.

Postcondition: No hardware state is modified.; On success, the latest read returned the mask set.

Note: Inline. Not thread-safe.

Since: 0.1.0

See implementation.

Definition at line 309 of file ra8_hw_err.h.

References k_ra8_err_hw_timeout, k_ra8_err_null_ptr, and k_ra8_ok.

Referenced by internal_set_global_mode(), internal_target_wait_spsr(), internal_wait_spsr(), internal_wait_status_bit(), internal_wait_tx_end(), ra8_eth_coma_bringup(), ra8_eth_gwca_axi_init(), ra8_etha_tas_ram_reset(), ra8_sci_getc_polling(), ra8_sci_lin_wait_break(), ra8_sci_putc_polling(), and ra8_sci_spi_xfer8().

◆ ra8_hw_wait_flag_set8()

ra8_err_t ra8_hw_wait_flag_set8	(	volatile const uint8_t *	reg,
		uint8_t	mask,
		uint32_t	budget )

inlinestatic

Spin until (*reg & mask) != 0 or budget runs out.

Parameters

[in]	reg	Pointer to the volatile 8-bit register to poll. Must not be NULL.
[in]	mask	Bit mask within *reg to test for "set". Must be non-zero or the function returns immediately with success.
[in]	budget	Maximum loop iterations before declaring a timeout. Pass one of the k_ra8_hw_budget_* values.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	The flag was observed as set within the budget.
k_ra8_err_hw_timeout	The budget ran out without the flag being observed.
k_ra8_err_null_ptr	reg was NULL.

Precondition: reg is non-NULL.; budget > 0.

Postcondition: No hardware state is modified.; On success, the most recent read returned mask set.

Note: Inline. Thread safety: not thread-safe (the caller must hold whatever lock the register requires).

Since: 0.1.0

NASA Power of 10 Compliance:

Rule 2: budget is a fixed upper bound, supplied by the caller.
Rule 5: 2 preconditions, 2 postconditions.

See implementation.

Definition at line 219 of file ra8_hw_err.h.

References k_ra8_err_hw_timeout, k_ra8_err_null_ptr, and k_ra8_ok.

Referenced by internal_route_sciclk(), internal_wait_canfdcksrdy(), internal_wait_cksrdy(), internal_wait_octacksrdy(), internal_wait_usb60cksrdy(), internal_wait_usbcksrdy(), and priv_ra8_cgc_wait_oscsf_set().

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ ra8_hw_err_budget_t

Function Documentation

◆ ra8_hw_wait_flag_clear32()

◆ ra8_hw_wait_flag_clear8()

◆ ra8_hw_wait_flag_set32()

◆ ra8_hw_wait_flag_set8()