ra8_hw_intrinsics.h File Reference

Shared CPU-intrinsic seam for the HAL drivers (host/target split). More...

#include <stdint.h>

Include dependency graph for ra8_hw_intrinsics.h:

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

Go to the source code of this file.

Functions
static void	ra8_hw_wfi (void)
	Wait For Interrupt: place the core in low-power wait.
static void	ra8_hw_dsb (void)
	Data Synchronisation Barrier (full system).
static void	ra8_hw_isb (void)
	Instruction Synchronisation Barrier (full system).
static void	ra8_hw_nop (void)
	No-operation used to pad a calibrated busy-wait.
static void	ra8_hw_irq_enable (void)
	Enable maskable interrupts (clear PRIMASK).
static void	ra8_hw_irq_disable (void)
	Disable maskable interrupts (set PRIMASK).
static void	ra8_hw_wait_for_reset (void)
	Barrier-then-spin used after requesting a system reset.

Detailed Description

Shared CPU-intrinsic seam for the HAL drivers (host/target split).

Tag

[Ring 3 / HAL] {World: S}

One documented home for the bare Armv8-M CPU primitives that several HAL peripheral drivers need but that a host unit-test build cannot execute: wfi, the dsb / isb barriers, the nop used to pad calibrated busy-waits, the cpsie i / cpsid i global-interrupt gate, and the post-reset spin that never returns on silicon.

This header is the single divergence point (issue #293). On the arm-none-eabi target each primitive is a static inline that expands to exactly the inline asm the drivers used before – so the shipping code is byte-for-byte unchanged and, critically, the calibrated nop pads stay inline (no per-iteration call overhead skews the delay). On the host build (RA8_OFF_TARGET defined) this header declares the primitives extern and their host-safe bodies (wfi -> return, dsb/isb -> compiler barrier, nop -> no-op, irq gate -> no-op, reset spin -> return) live in ONE translation unit, tests/mocks/src/ra8_host_asm_stub.c. The test harness therefore owns the whole host model and the driver .c files carry no #ifdef RA8_OFF_TARGET of their own; the gate scripts/checks/check_no_driver_asm_guard.py keeps it that way.

Note

The barriers are Arm architectural instructions (Armv8-M ARM), not RA8D2 peripheral registers, so no Hardware User's Manual citation applies to them.

Copyright

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

Since

0.1.0

Definition in file ra8_hw_intrinsics.h.

Function Documentation

ra8_hw_dsb()

void ra8_hw_dsb ( void )

inlinestatic

Data Synchronisation Barrier (full system).

Issues dsb 0xF (SY), stalling the core until every prior explicit memory access – including the MMIO writes that precede it – has completed. On the host this collapses to a compiler barrier because ordinary host RAM needs no hardware ordering.

Precondition

Placed after an MMIO write that must retire before the next step.

Running on the Cortex-M85 target or the host stub.

Postcondition

All earlier explicit memory accesses have completed.

No general-purpose register is modified.

Note

ISR-safe; touches no driver state.

Since

0.1.0

Definition at line 81 of file ra8_hw_intrinsics.h.

Referenced by internal_mpsm_issue(), internal_ra8_cache_maintain_range(), internal_ra8_cache_setway_all(), internal_wait_for_interrupt(), ra8_cache_dcache_enable(), ra8_cache_icache_disable(), ra8_cache_icache_enable(), ra8_cache_icache_invalidate_all(), ra8_eth_gwca_default_send(), and ra8_mpu_apply_boot_map().

ra8_hw_irq_disable()

void ra8_hw_irq_disable ( void )

inlinestatic

Disable maskable interrupts (set PRIMASK).

Issues cpsid i so subsequent maskable IRQs pend until re-enabled. On the host this is a no-op for the same reason as ra8_hw_irq_enable.

Precondition

Opening a critical section that must not be pre-empted.

Running on the Cortex-M85 target or the host stub.

Postcondition

Maskable interrupt delivery is disabled (PRIMASK = 1).

No general-purpose register is modified.

Note

ISR-safe; touches no driver state.

Since

0.1.0

Definition at line 162 of file ra8_hw_intrinsics.h.

Referenced by ra8_isr_globals_disable().

ra8_hw_irq_enable()

void ra8_hw_irq_enable ( void )

inlinestatic

Enable maskable interrupts (clear PRIMASK).

Issues cpsie i so maskable IRQs may dispatch again. On the host this is a no-op because the test harness dispatches interrupts through the ra8_fake_irq seam rather than the core's PRIMASK.

Precondition

A prior ra8_hw_irq_disable opened the critical section.

Running on the Cortex-M85 target or the host stub.

Postcondition

Maskable interrupt delivery is enabled (PRIMASK = 0).

No general-purpose register is modified.

Note

ISR-safe; touches no driver state.

Since

0.1.0

Definition at line 143 of file ra8_hw_intrinsics.h.

Referenced by ra8_isr_globals_enable().

ra8_hw_isb()

void ra8_hw_isb ( void )

inlinestatic

Instruction Synchronisation Barrier (full system).

Issues isb 0xF, flushing the pipeline so instructions fetched after it observe context changes established by a preceding enable/invalidate sequence. On the host this collapses to a compiler barrier because there is no pipeline to flush.

Precondition

Placed after a system-control write that affects fetch or execution.

Running on the Cortex-M85 target or the host stub.

Postcondition

The pipeline is flushed; later instructions see the new context.

No general-purpose register is modified.

Note

ISR-safe; touches no driver state.

Since

0.1.0

Definition at line 102 of file ra8_hw_intrinsics.h.

Referenced by internal_ra8_cache_maintain_range(), internal_ra8_cache_setway_all(), ra8_cache_dcache_enable(), ra8_cache_icache_disable(), ra8_cache_icache_enable(), ra8_cache_icache_invalidate_all(), and ra8_mpu_apply_boot_map().

ra8_hw_nop()

void ra8_hw_nop ( void )

inlinestatic

No-operation used to pad a calibrated busy-wait.

Emits a single nop so the compiler cannot fold a calibrated delay loop away on the target, and stays inline so the delay calibration holds. On the host it is a no-op call: the loop still runs but each iteration costs nothing, and there is no timing requirement to meet.

Precondition

Called from the body of a statically-bounded delay loop.

Running on the Cortex-M85 target or the host stub.

Postcondition

One nominal instruction slot has elapsed (target) or nothing (host).

No general-purpose register is modified.

Note

ISR-safe; touches no driver state.

Since

0.1.0

Definition at line 123 of file ra8_hw_intrinsics.h.

Referenced by internal_busy_wait_us(), internal_busy_wait_us(), and internal_wait_5_gtclk().

ra8_hw_wait_for_reset()

void ra8_hw_wait_for_reset ( void )

inlinestatic

Barrier-then-spin used after requesting a system reset.

On silicon a dsb guarantees the reset-request store retires, then the core spins forever until the reset actually lands – the function never returns and control must not fall through into the caller's tail. On the host it returns immediately so a unit test can inspect the register write it just staged.

Precondition

The reset-request register (e.g. AIRCR.SYSRESETREQ) was just written.

Running on the Cortex-M85 target or the host stub.

Postcondition

The pending reset store has retired (target) before the core spins.

Never returns on target; returns at once on the host.

Note

ISR context is irrelevant: the core is on its way down.

Since

0.1.0

Definition at line 184 of file ra8_hw_intrinsics.h.

Referenced by ra8_reset_software_reset().

ra8_hw_wfi()

void ra8_hw_wfi ( void )

inlinestatic

Wait For Interrupt: place the core in low-power wait.

Issues the Armv8-M wfi instruction with a memory clobber so no prior memory access is reordered past the sleep. On the host this returns immediately (the stub cannot halt an x86 test binary).

Precondition

Sleep-mode configuration registers have already been written.

Called with the intended wake source armed.

Postcondition

The core has slept until a wake event (target) or returned at once (host).

No general-purpose register is modified.

Note

ISR-safe; touches no driver state.

Since

0.1.0

Definition at line 60 of file ra8_hw_intrinsics.h.

Referenced by internal_wait_for_interrupt(), and internal_wfi().