Inter-Processor Communication (IPC) HAL driver – transfer API. More...

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

Include dependency graph for ra8_ipc_xfer.h:

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

Functions
ra8_err_t	ra8_ipc_init (const ra8_ipc_config_t *cfg)
	Initialise one IPC channel.
ra8_err_t	ra8_ipc_deinit (uint8_t channel)
	Tear down one IPC channel.
ra8_err_t	ra8_ipc_reset_fifo (uint8_t channel)
	Issue a CLR.RST on one channel without altering callbacks.
ra8_err_t	ra8_ipc_set_event_mask (uint8_t channel, uint32_t mask)
	Update the event-mask filter for an already-initialized channel.
ra8_err_t	ra8_ipc_channel_for_send (ra8_ipc_core_id_t core, uint8_t pair, uint8_t *out_channel)
	Pick the channel id this core writes to.
ra8_err_t	ra8_ipc_channel_for_recv (ra8_ipc_core_id_t core, uint8_t pair, uint8_t *out_channel)
	Pick the channel id this core reads from.
ra8_err_t	ra8_ipc_send_event (uint8_t channel, ra8_ipc_irq_event_id_t event_id)
	Generate a maskable IRQ event on the peer core.
ra8_err_t	ra8_ipc_clear_event (uint8_t channel, ra8_ipc_irq_event_id_t event_id)
	Clear one received IRQ event line on the local core.
ra8_err_t	ra8_ipc_send_message (uint8_t channel, uint32_t message)
	Push one 32-bit word into the channel TX FIFO.
ra8_err_t	ra8_ipc_send_message_retry (uint8_t channel, uint32_t message, uint16_t max_retries)
	Bounded-retry variant of ra8_ipc_send_message.
ra8_err_t	ra8_ipc_send_burst (uint8_t channel, const uint32_t data, uint32_t count, uint32_t out_written)
	Push up to count words into the channel TX FIFO.
ra8_err_t	ra8_ipc_recv_message (uint8_t channel, uint32_t *out_msg)
	Pop one 32-bit word from the channel RX FIFO.
ra8_err_t	ra8_ipc_recv_message_retry (uint8_t channel, uint32_t *out_msg, uint16_t max_retries)
	Bounded-retry variant of ra8_ipc_recv_message.
ra8_err_t	ra8_ipc_recv_burst (uint8_t channel, uint32_t out_data, uint32_t capacity, uint32_t out_read)
	Drain up to capacity words from the channel RX FIFO.
ra8_err_t	ra8_ipc_get_status (uint8_t channel, uint32_t *out_sta)
	Read the raw channel status register.
ra8_err_t	ra8_ipc_clear_status (uint8_t channel, uint32_t mask)
	Clear selected status bits on a channel.
ra8_err_t	ra8_ipc_clear_errors (uint8_t channel)
	Clear RERR + FERR on the channel.
ra8_err_t	ra8_ipc_can_send (uint8_t channel, bool *out_can_send)
	Predicate: would ra8_ipc_send_message succeed right now?
ra8_err_t	ra8_ipc_has_data (uint8_t channel, bool *out_has_data)
	Predicate: would ra8_ipc_recv_message succeed right now?
ra8_err_t	ra8_ipc_get_attribution (uint8_t channel, ra8_ipc_attr_t *out_attr)
	Read the security / privilege attribution for one channel.
ra8_err_t	ra8_ipc_get_nmi_attribution (uint8_t unit, ra8_ipc_attr_t *out_attr)
	Read the attribution for one NMI unit.
ra8_err_t	ra8_ipc_get_sem_attribution (ra8_ipc_sem_attr_group_t group, ra8_ipc_attr_t *out_attr)
	Read the attribution for an IPCSEM group.
ra8_err_t	ra8_ipc_can_access (uint8_t channel, ra8_ipc_attr_t const required, bool out_can_access)
	Predicate: does this core's attribution allow writing the channel?

Detailed Description

Inter-Processor Communication (IPC) HAL driver – transfer API.

Tag: [Ring 3 / HAL] {World: NS}

Lifecycle, channel-pair convention helpers, send / receive (single and burst), status / error inspection, and security / privilege attribution prototypes for the RA8D2 IPC mailbox driver. Split out of ra8_ipc.h so each header stays within the repository file-size budget; ra8_ipc.h re-includes this header so existing consumers are unaffected.

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

Since: 0.1.0

Definition in file ra8_ipc_xfer.h.

Function Documentation

◆ ra8_ipc_can_access()

ra8_err_t ra8_ipc_can_access	(	uint8_t	channel,
		ra8_ipc_attr_t const *	required,
		bool *	out_can_access )

nodiscard

Predicate: does this core's attribution allow writing the channel?

Reads IPCSAR / IPCPAR for the channel and compares against the core's expected security / privilege state. The driver does not know the running core's state directly – the caller passes a desired required attribution and the function returns true if the channel matches.

Parameters

[in]	channel	Channel id 0..3.
[in]	required	Desired attribution.
[out]	out_can_access	Receives true on a match.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Predicate evaluated.
k_ra8_err_invalid_arg	channel >= 4.
k_ra8_err_null_ptr	out_can_access was NULL.

Precondition: out_can_access non-NULL.; Channel attribution registers are accessible.

Postcondition: *out_can_access reflects (live attr == required).; No registers are mutated.

Note: Thread safety: re-entrant; pure read.

Since: 0.1.0

Definition at line 689 of file ra8_ipc.c.

References k_ra8_ok, ra8_ipc_attr_t::privileged, RA8_CHECK_NULL_PTR, ra8_ipc_get_attribution(), s_tag, and ra8_ipc_attr_t::secure.

◆ ra8_ipc_can_send()

ra8_err_t ra8_ipc_can_send	(	uint8_t	channel,
		bool *	out_can_send )

nodiscard

Predicate: would ra8_ipc_send_message succeed right now?

Parameters

[in]	channel	Channel id 0..3.
[out]	out_can_send	Receives true if FIFO has at least one free slot.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Predicate evaluated.
k_ra8_err_invalid_arg	channel >= 4.
k_ra8_err_null_ptr	out_can_send was NULL.

Precondition: Channel was initialized.; out_can_send non-NULL.

Postcondition: No registers are mutated.; *out_can_send reflects !STA.FULL.

Note: Thread safety: re-entrant; pure read.

Since: 0.1.0

Definition at line 608 of file ra8_ipc.c.

References internal_ra8_ipc_get_regs(), k_ra8_err_invalid_arg, k_ra8_ipc_sta_mask_full, k_ra8_ok, RA8_CHECK_NULL_PTR, s_tag, and r_ipc_channel_regs_t::STA.

◆ ra8_ipc_channel_for_recv()

ra8_err_t ra8_ipc_channel_for_recv	(	ra8_ipc_core_id_t	core,
		uint8_t	pair,
		uint8_t *	out_channel )

nodiscard

Pick the channel id this core reads from.

Mirror of ra8_ipc_channel_for_send: CPU0 receives through IPC0 (channels 0/1); CPU1 receives through IPC1 (channels 2/3).

Parameters

[in]	core	Local CPU id.
[in]	pair	Pair within the unit (0 -> _0, 1 -> _1).
[out]	out_channel	Receives the resolved channel id 0..3.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Resolved successfully.
k_ra8_err_null_ptr	out_channel was NULL.
k_ra8_err_invalid_arg	core or pair out of range.

Precondition: out_channel non-NULL.; core in {k_ra8_ipc_core_cpu0, k_ra8_ipc_core_cpu1}.

Postcondition: On success, *out_channel < 4.; Hardware state untouched.

Note: Thread safety: re-entrant (pure computation).

See also: ra8_ipc_channel_for_send

Since: 0.1.0

Definition at line 331 of file ra8_ipc.c.

References k_ra8_err_invalid_arg, k_ra8_ipc_channel_count, k_ra8_ipc_core_cpu0, k_ra8_ipc_core_cpu1, k_ra8_ok, RA8_CHECK_NULL_PTR, and s_tag.

◆ ra8_ipc_channel_for_send()

ra8_err_t ra8_ipc_channel_for_send	(	ra8_ipc_core_id_t	core,
		uint8_t	pair,
		uint8_t *	out_channel )

nodiscard

Pick the channel id this core writes to.

Encodes the channel-pair convention from HUM Ch 3.1 p 204: CPU0 (M85) sends through IPC1 (channels 2/3); CPU1 (M33) sends through IPC0 (channels 0/1). The pair argument selects between the two channels owned by each unit.

Parameters

[in]	core	Local CPU id.
[in]	pair	Channel pair within the unit (0 -> _0, 1 -> _1).
[out]	out_channel	Receives the resolved channel id 0..3.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Resolved successfully.
k_ra8_err_null_ptr	out_channel was NULL.
k_ra8_err_invalid_arg	core or pair out of range.

Precondition: out_channel non-NULL.; core in {k_ra8_ipc_core_cpu0, k_ra8_ipc_core_cpu1}.

Postcondition: On success, *out_channel < 4.; Hardware state untouched.

Note: Thread safety: re-entrant (pure computation).

See also: ra8_ipc_channel_for_recv

Since: 0.1.0

Definition at line 311 of file ra8_ipc.c.

References k_ra8_err_invalid_arg, k_ra8_ipc_channel_count, k_ra8_ipc_core_cpu0, k_ra8_ipc_core_cpu1, k_ra8_ok, RA8_CHECK_NULL_PTR, and s_tag.

◆ ra8_ipc_clear_errors()

ra8_err_t ra8_ipc_clear_errors ( uint8_t channel )

nodiscard

Clear RERR + FERR on the channel.

Parameters

[in] channel Channel id 0..3.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Errors cleared.
k_ra8_err_invalid_arg	channel >= 4.

Precondition: Channel was initialized.; Caller observed (or expects) STA.RERR or STA.FERR to be set.

Postcondition: STA.RERR == 0 and STA.FERR == 0 on next read.; No other STA bits are disturbed.

Note: Thread safety: re-entrant per channel.

See also: ra8_ipc_clear_status

Since: 0.1.0

Definition at line 596 of file ra8_ipc.c.

References r_ipc_channel_regs_t::CLR, internal_ra8_ipc_get_regs(), k_ra8_err_invalid_arg, k_ra8_ipc_clr_mask_fclr, k_ra8_ipc_clr_mask_rclr, and k_ra8_ok.

◆ ra8_ipc_clear_event()

ra8_err_t ra8_ipc_clear_event	(	uint8_t	channel,
		ra8_ipc_irq_event_id_t	event_id )

nodiscard

Clear one received IRQ event line on the local core.

Parameters

[in]	channel	Channel id 0..3 (call from the receive side).
[in]	event_id	IRQ event line 0..7 to acknowledge.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Bit cleared.
k_ra8_err_invalid_arg	channel >= 4 or event_id > 7.

Precondition: This core observed the IPCnIRQm interrupt for channel.; ra8_ipc_init previously enabled the channel.

Postcondition: STA.IRQn reads 0 on the next register fetch.; No pending CLR write remains for this event line.

Note: Thread safety: re-entrant per channel.

See also: ra8_ipc_send_event

Since: 0.1.0

Definition at line 376 of file ra8_ipc.c.

References r_ipc_channel_regs_t::CLR, internal_ra8_ipc_get_regs(), k_ra8_err_invalid_arg, k_ra8_ipc_channel_count, k_ra8_ipc_irq_event_count, k_ra8_ok, RA8_CHECK_NULL_PTR, and s_tag.

◆ ra8_ipc_clear_status()

ra8_err_t ra8_ipc_clear_status	(	uint8_t	channel,
		uint32_t	mask )

nodiscard

Clear selected status bits on a channel.

Parameters

[in]	channel	Channel id 0..3.
[in]	mask	Bitmask of ra8_ipc_event_t flags to clear.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Mask written.
k_ra8_err_invalid_arg	channel >= 4.

Precondition: Channel was initialized.; mask only contains bits drawn from ra8_ipc_event_t.

Postcondition: Bits requested in mask read back as 0 on next get_status.; No other STA bits are disturbed.

Note: Thread safety: re-entrant per channel.

See also: ra8_ipc_get_status

Since: 0.1.0

Definition at line 580 of file ra8_ipc.c.

References r_ipc_channel_regs_t::CLR, internal_ra8_ipc_event_to_clr(), internal_ra8_ipc_get_regs(), k_ra8_err_invalid_arg, k_ra8_ipc_channel_count, k_ra8_ok, RA8_CHECK_NULL_PTR, and s_tag.

◆ ra8_ipc_deinit()

ra8_err_t ra8_ipc_deinit ( uint8_t channel )

nodiscard

Tear down one IPC channel.

Clears the channel STA register (cancels every IRQn / RDY / FULL / RERR / FERR bit) and resets the FIFO via CLR.RST so the next ra8_ipc_init starts from a known state. Also drops every per-event line callback registered via ra8_ipc_attach_event_handler.

Parameters

[in] channel Channel id 0..3.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Channel cleared.
k_ra8_err_invalid_arg	channel >= 4.

Precondition: ra8_ipc_init was previously called for this channel.; Caller is in single-threaded shutdown context.

Postcondition: Channel STA reads zero on a real device.; FIFO is empty (RDY = 0, FULL = 0).

Note: Thread safety: not thread-safe.

See also: ra8_ipc_init

Since: 0.1.0

Definition at line 261 of file ra8_ipc.c.

References ra8_ipc_channel_state_t::active, r_ipc_channel_regs_t::CLR, ra8_ipc_irq_slot_t::ctx, ra8_ipc_channel_state_t::event_mask, ra8_ipc_irq_slot_t::fn, internal_ra8_ipc_get_regs(), k_ra8_err_invalid_arg, k_ra8_ipc_channel_count, k_ra8_ipc_clr_mask_fclr, k_ra8_ipc_clr_mask_irq_all, k_ra8_ipc_clr_mask_rclr, k_ra8_ipc_clr_mask_rst, k_ra8_ipc_irq_event_count, k_ra8_ok, ra8_ipc_channel_state_t::per_event, RA8_CHECK_NULL_PTR, s_ipc_channels, and s_tag.

◆ ra8_ipc_get_attribution()

ra8_err_t ra8_ipc_get_attribution	(	uint8_t	channel,
		ra8_ipc_attr_t *	out_attr )

nodiscard

Read the security / privilege attribution for one channel.

Decodes the matching SAIPCIRn / PAIPCIRn bits in IPCSAR / IPCPAR (HUM Ch 3.2.1 p 207, Ch 3.2.2 p 208). Useful for the secondary core to confirm it has access to the channel before issuing a register write that the SAU / IDAU would silently drop.

Parameters

[in]	channel	Channel id 0..3.
[out]	out_attr	Receives secure and privileged flags.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Attribution read.
k_ra8_err_invalid_arg	channel >= 4.
k_ra8_err_null_ptr	out_attr was NULL.

Precondition: IPCSAR / IPCPAR are mapped (CPSCU window).; out_attr non-NULL.

Postcondition: out_attr->secure reflects SAIPCIRn (1 = non-secure).; out_attr->privileged reflects PAIPCIRn (1 = unprivileged).

Note: Thread safety: re-entrant; pure read.

Since: 0.1.0

Definition at line 637 of file ra8_ipc.c.

References k_ra8_err_invalid_arg, k_ra8_ipc_attr_shift_ir_base, k_ra8_ipc_channel_count, k_ra8_ok, ra8_ipc_attr_t::privileged, RA8_CHECK_NULL_PTR, ra8_ipc_ipcpar(), ra8_ipc_ipcsar(), s_tag, and ra8_ipc_attr_t::secure.

Referenced by ra8_ipc_can_access().

◆ ra8_ipc_get_nmi_attribution()

ra8_err_t ra8_ipc_get_nmi_attribution	(	uint8_t	unit,
		ra8_ipc_attr_t *	out_attr )

nodiscard

Read the attribution for one NMI unit.

IPCSAR.SAIPCNMI[0..1] and IPCPAR.PAIPCNMI[0..1] live at bits 8/9 of their respective registers (HUM Ch 3.2.1 p 205-207). Provided so the NMI-injection code can pre-flight before issuing IPCnNMISET writes.

Parameters

[in]	unit	NMI unit id 0..1 (k_ra8_ipc_unit_ipc0 / ipc1).
[out]	out_attr	Receives secure / privileged flags.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Attribution read.
k_ra8_err_invalid_arg	unit >= 2.
k_ra8_err_null_ptr	out_attr was NULL.

Precondition: out_attr non-NULL.; IPCSAR / IPCPAR are mapped.

Postcondition: Output reflects SAIPCNMIu / PAIPCNMIu.; No registers are mutated.

Note: Thread safety: re-entrant; pure read.

Since: 0.1.0

Definition at line 656 of file ra8_ipc.c.

References k_ra8_err_invalid_arg, k_ra8_ipc_attr_shift_nmi_base, k_ra8_ipc_nmi_unit_count, k_ra8_ok, ra8_ipc_attr_t::privileged, RA8_CHECK_NULL_PTR, ra8_ipc_ipcpar(), ra8_ipc_ipcsar(), s_tag, and ra8_ipc_attr_t::secure.

◆ ra8_ipc_get_sem_attribution()

ra8_err_t ra8_ipc_get_sem_attribution	(	ra8_ipc_sem_attr_group_t	group,
		ra8_ipc_attr_t *	out_attr )

nodiscard

Read the attribution for an IPCSEM group.

Wraps SAIPCSEM[0..1] / PAIPCSEM[0..1]. Group 0 covers IPCSEM0..7; group 1 covers IPCSEM8..15 (HUM Ch 3.3.1 p 228).

Parameters

[in]	group	Attribution group.
[out]	out_attr	Receives secure / privileged flags.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Attribution read.
k_ra8_err_invalid_arg	group not in {0, 1}.
k_ra8_err_null_ptr	out_attr was NULL.

Precondition: out_attr non-NULL.; IPCSAR / IPCPAR are mapped.

Postcondition: Output reflects SAIPCSEMg / PAIPCSEMg.; No registers are mutated.

Note: Thread safety: re-entrant; pure read.

Since: 0.1.0

Definition at line 672 of file ra8_ipc.c.

References k_ra8_err_invalid_arg, k_ra8_ipc_sem_group_high, k_ra8_ok, ra8_ipc_attr_t::privileged, RA8_CHECK_NULL_PTR, ra8_ipc_ipcpar(), ra8_ipc_ipcsar(), s_tag, and ra8_ipc_attr_t::secure.

◆ ra8_ipc_get_status()

ra8_err_t ra8_ipc_get_status	(	uint8_t	channel,
		uint32_t *	out_sta )

nodiscard

Read the raw channel status register.

Parameters

[in]	channel	Channel id 0..3.
[out]	out_sta	Receives STA value (full 32-bit raw register).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Status read.
k_ra8_err_invalid_arg	channel >= 4.
k_ra8_err_null_ptr	out_sta was NULL.

Precondition: Channel was initialized.; out_sta non-NULL.

Postcondition: *out_sta reflects the live STA value.; No registers are mutated.

Note: Thread safety: re-entrant; pure read.

See also: ra8_ipc_clear_status

Since: 0.1.0

Definition at line 566 of file ra8_ipc.c.

References internal_ra8_ipc_get_regs(), k_ra8_err_invalid_arg, k_ra8_ipc_channel_count, k_ra8_ok, RA8_CHECK_NULL_PTR, s_tag, and r_ipc_channel_regs_t::STA.

◆ ra8_ipc_has_data()

ra8_err_t ra8_ipc_has_data	(	uint8_t	channel,
		bool *	out_has_data )

nodiscard

Predicate: would ra8_ipc_recv_message succeed right now?

Parameters

[in]	channel	Channel id 0..3.
[out]	out_has_data	Receives true if at least one word is queued.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Predicate evaluated.
k_ra8_err_invalid_arg	channel >= 4.
k_ra8_err_null_ptr	out_has_data was NULL.

Precondition: Channel was initialized.; out_has_data non-NULL.

Postcondition: No registers are mutated.; *out_has_data reflects STA.RDY.

Note: Thread safety: re-entrant; pure read.

Since: 0.1.0

Definition at line 620 of file ra8_ipc.c.

References internal_ra8_ipc_get_regs(), k_ra8_err_invalid_arg, k_ra8_ipc_sta_mask_rdy, k_ra8_ok, RA8_CHECK_NULL_PTR, s_tag, and r_ipc_channel_regs_t::STA.

◆ ra8_ipc_init()

ra8_err_t ra8_ipc_init ( const ra8_ipc_config_t * cfg )

nodiscard

Initialise one IPC channel.

Issues an optional FIFO reset and an optional status clear, then stores the per-channel event mask the dispatch path uses to filter which status bits trigger the callback.

The peripheral itself does not have a dedicated MSTPCR bit on the RA8D2 – IPC sits on the always-on CPU bus and is reachable as soon as the secondary core comes out of reset, so no ra8_mstp_enable call is required.

State Machine: <p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p>

Parameters

[in] cfg Non-NULL configuration descriptor.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Channel ready for use.
k_ra8_err_null_ptr	cfg was NULL.
k_ra8_err_invalid_arg	cfg->channel >= 4.

Precondition: Caller is in single-threaded init context (no other code is touching the same channel concurrently).; The CPSCU register window is mapped (it always is on Cortex-M85 bring-up).

Postcondition: Stored event mask matches cfg->event_mask.; If cfg->reset_fifo, the channel FIFO has been drained.

Note: Thread safety: not thread-safe.

See also: ra8_ipc_deinit

Since: 0.1.0

Definition at line 228 of file ra8_ipc.c.

References ra8_ipc_channel_state_t::active, ra8_ipc_config_t::channel, ra8_ipc_config_t::clear_status, r_ipc_channel_regs_t::CLR, ra8_ipc_irq_slot_t::ctx, ra8_ipc_channel_state_t::event_mask, ra8_ipc_config_t::event_mask, ra8_ipc_irq_slot_t::fn, internal_ra8_ipc_get_regs(), k_ra8_err_invalid_arg, k_ra8_ipc_channel_count, k_ra8_ipc_clr_mask_fclr, k_ra8_ipc_clr_mask_irq_all, k_ra8_ipc_clr_mask_rclr, k_ra8_ipc_clr_mask_rst, k_ra8_ipc_irq_event_count, k_ra8_ok, ra8_ipc_channel_state_t::per_event, RA8_CHECK_NULL_PTR, ra8_log_info_val, ra8_ipc_config_t::reset_fifo, s_ipc_channels, and s_tag.

Referenced by arm_ipc_wake().

◆ ra8_ipc_recv_burst()

ra8_err_t ra8_ipc_recv_burst	(	uint8_t	channel,
		uint32_t *	out_data,
		uint32_t	capacity,
		uint32_t *	out_read )

nodiscard

Drain up to capacity words from the channel RX FIFO.

Pops one word per RDY-set FIFO stage; stops as soon as RDY drops or the buffer fills. out_read returns how many words landed in out_data.

Parameters

[in]	channel	Channel id 0..3.
[out]	out_data	Destination array, at least capacity words.
[in]	capacity	Maximum number of words to read.
[out]	out_read	Receives count actually popped (may be 0).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Drain succeeded (may have read 0).
k_ra8_err_invalid_arg	channel >= 4 or capacity == 0.
k_ra8_err_null_ptr	out_data or out_read was NULL.

Precondition: ra8_ipc_init previously enabled the channel.; out_data non-NULL and out_read non-NULL.

Postcondition: *out_read <= capacity.; After the call STA.RDY may still be 1 if the peer kept writing.

Note: Thread safety: not thread-safe per channel.

Since: 0.1.0

Definition at line 532 of file ra8_ipc.c.

References internal_ra8_ipc_get_regs(), k_ra8_err_invalid_arg, k_ra8_ipc_channel_count, k_ra8_ipc_sta_mask_rdy, k_ra8_ok, RA8_CHECK_NULL_PTR, r_ipc_channel_regs_t::RXD, s_tag, and r_ipc_channel_regs_t::STA.

◆ ra8_ipc_recv_message()

ra8_err_t ra8_ipc_recv_message	(	uint8_t	channel,
		uint32_t *	out_msg )

nodiscard

Pop one 32-bit word from the channel RX FIFO.

Reads the channel RXD register. If RDY was 0 at read time the read returns zero and STA.RERR is set (HUM Ch 3.2.13 p 216). The driver returns k_ra8_err_no_data in that case so the caller can retry once a peer has written.

Parameters

[in]	channel	Channel id 0..3.
[out]	out_msg	Receives the next FIFO word; left untouched on error.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Word read.
k_ra8_err_invalid_arg	channel >= 4.
k_ra8_err_null_ptr	out_msg was NULL.
k_ra8_err_no_data	FIFO empty at read time.

Precondition: ra8_ipc_init previously enabled the channel.; Caller holds whatever lock co-ordinates this channel.

Postcondition: On success, FIFO advances by one word.; On empty, STA.RERR is set on the local core.

Note: Thread safety: not thread-safe per channel.

See also: ra8_ipc_send_message

Since: 0.1.0

Definition at line 483 of file ra8_ipc.c.

References internal_ra8_ipc_get_regs(), k_ra8_err_invalid_arg, k_ra8_err_no_data, k_ra8_ipc_channel_count, k_ra8_ipc_sta_mask_rdy, k_ra8_ok, RA8_CHECK_NULL_PTR, r_ipc_channel_regs_t::RXD, s_tag, and r_ipc_channel_regs_t::STA.

◆ ra8_ipc_recv_message_retry()

ra8_err_t ra8_ipc_recv_message_retry	(	uint8_t	channel,
		uint32_t *	out_msg,
		uint16_t	max_retries )

nodiscard

Bounded-retry variant of ra8_ipc_recv_message.

Polls STA.RDY up to max_retries times, clearing RERR at each iteration. Returns k_ra8_err_hw_timeout if no word arrived in the budget.

Parameters

[in]	channel	Channel id 0..3.
[out]	out_msg	Receives the popped word on success.
[in]	max_retries	Iteration cap (<= k_ra8_ipc_retry_max).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Word read.
k_ra8_err_invalid_arg	Bad channel or NULL output pointer.
k_ra8_err_hw_timeout	No word arrived in the retry budget.

Precondition: ra8_ipc_init previously enabled the channel.; out_msg non-NULL.

Postcondition: On success, *out_msg reflects RXD.; On timeout, STA.RERR has been cleared at least once.

Note: Thread safety: not thread-safe per channel.

See also: ra8_ipc_recv_message

Since: 0.1.0

Definition at line 503 of file ra8_ipc.c.

References r_ipc_channel_regs_t::CLR, internal_ra8_ipc_get_regs(), k_ra8_err_hw_timeout, k_ra8_err_invalid_arg, k_ra8_ipc_channel_count, k_ra8_ipc_clr_mask_rclr, k_ra8_ipc_retry_max, k_ra8_ipc_sta_mask_rdy, k_ra8_ok, RA8_CHECK_NULL_PTR, r_ipc_channel_regs_t::RXD, s_tag, and r_ipc_channel_regs_t::STA.

◆ ra8_ipc_reset_fifo()

ra8_err_t ra8_ipc_reset_fifo ( uint8_t channel )

nodiscard

Issue a CLR.RST on one channel without altering callbacks.

Convenience wrapper that drops the FIFO contents (HUM Ch 3.2.14 "RST bit" p 217). Useful for application-level resync without having to tear down callbacks via ra8_ipc_deinit.

Parameters

[in] channel Channel id 0..3.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	FIFO reset issued.
k_ra8_err_invalid_arg	channel >= 4.

Precondition: ra8_ipc_init previously enabled the channel.; Caller holds whatever lock co-ordinates this channel.

Postcondition: STA.RDY and STA.FULL read 0.; Pending FIFO words are discarded.

Note: Thread safety: not thread-safe per channel.

See also: ra8_ipc_deinit

Since: 0.1.0

Definition at line 284 of file ra8_ipc.c.

References r_ipc_channel_regs_t::CLR, internal_ra8_ipc_get_regs(), k_ra8_err_invalid_arg, k_ra8_ipc_clr_mask_rst, and k_ra8_ok.

◆ ra8_ipc_send_burst()

ra8_err_t ra8_ipc_send_burst	(	uint8_t	channel,
		const uint32_t *	data,
		uint32_t	count,
		uint32_t *	out_written )

nodiscard

Push up to count words into the channel TX FIFO.

Writes one word per non-full FIFO stage; honours the 4-stage depth documented in HUM Ch 3.1 p 204. Stops as soon as STA.FULL is set – does not spin or retry. out_written returns the number of words actually pushed; the caller is expected to back-pressure on the remainder.

Parameters

[in]	channel	Channel id 0..3.
[in]	data	Source array, count words long.
[in]	count	Number of words to attempt to send.
[out]	out_written	Receives count actually written (may be 0).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	At least one word written, or zero written because FIFO was full.
k_ra8_err_invalid_arg	channel >= 4 or count == 0.
k_ra8_err_null_ptr	data or out_written was NULL.

Precondition: ra8_ipc_init previously enabled the channel.; data non-NULL and out_written non-NULL.

Postcondition: *out_written <= count.; FIFO depth never exceeds k_ra8_ipc_fifo_depth.

Note: Thread safety: not thread-safe per channel.

See also: ra8_ipc_send_message

Since: 0.1.0

Definition at line 450 of file ra8_ipc.c.

References internal_ra8_ipc_get_regs(), k_ra8_err_invalid_arg, k_ra8_ipc_channel_count, k_ra8_ipc_sta_mask_full, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_ipc_barrier(), s_tag, r_ipc_channel_regs_t::STA, and r_ipc_channel_regs_t::TXD.

◆ ra8_ipc_send_event()

ra8_err_t ra8_ipc_send_event	(	uint8_t	channel,
		ra8_ipc_irq_event_id_t	event_id )

nodiscard

Generate a maskable IRQ event on the peer core.

Parameters

[in]	channel	Channel id 0..3 (call from the send side).
[in]	event_id	IRQ event line 0..7.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Event issued.
k_ra8_err_invalid_arg	channel >= 4 or event_id > 7.

Precondition: ra8_ipc_init has been called for this channel.; Receiving core has unmasked the IPCnIRQm vector in NVIC.

Postcondition: Peer STA.IRQn becomes 1 (until peer writes CLR.CLRn).; Local IPC ISET write has been issued exactly once.

Note: Thread safety: re-entrant per channel; no global state.

Example: (void)ra8_ipc_send_event(2, k_ra8_ipc_irq_event_0);

k_ra8_ipc_irq_event_0
@ k_ra8_ipc_irq_event_0
RA8 ipc IRQ event 0.
Definition ra8_ipc_types.h:64

ra8_ipc_send_event
ra8_err_t ra8_ipc_send_event(uint8_t channel, ra8_ipc_irq_event_id_t event_id)
Generate a maskable IRQ event on the peer core.
Definition ra8_ipc.c:355

See also: ra8_ipc_clear_event

Since: 0.1.0

Definition at line 355 of file ra8_ipc.c.

References internal_ra8_ipc_get_regs(), r_ipc_channel_regs_t::ISET, k_ra8_err_invalid_arg, k_ra8_ipc_channel_count, k_ra8_ipc_irq_event_count, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_ipc_barrier(), and s_tag.

Referenced by notify_m85(), and ra8_ipc_ring_produce().

◆ ra8_ipc_send_message()

ra8_err_t ra8_ipc_send_message	(	uint8_t	channel,
		uint32_t	message )

nodiscard

Push one 32-bit word into the channel TX FIFO.

Writes message to the channel TXD register. The peripheral sets STA.RDY on the receiving side. If the FIFO was full at write time the write is silently dropped and STA.FERR is set (HUM Ch 3.2.12 p 215). The driver returns k_ra8_err_busy in that case so the caller can either retry or escalate.

Parameters

[in]	channel	Channel id 0..3.
[in]	message	32-bit payload to enqueue.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Word accepted.
k_ra8_err_invalid_arg	channel >= 4.
k_ra8_err_busy	FIFO full at write time.

Precondition: ra8_ipc_init previously enabled the channel.; Caller holds whatever lock co-ordinates this channel.

Postcondition: On success, STA.RDY is set on the peer.; On busy, STA.FERR is set on the local core.

Note: Thread safety: not thread-safe per channel.

See also: ra8_ipc_recv_message

Since: 0.1.0

Definition at line 393 of file ra8_ipc.c.

References internal_ra8_ipc_get_regs(), k_ra8_err_busy, k_ra8_err_invalid_arg, k_ra8_ipc_channel_count, k_ra8_ipc_sta_mask_full, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_ipc_barrier(), s_tag, r_ipc_channel_regs_t::STA, and r_ipc_channel_regs_t::TXD.

◆ ra8_ipc_send_message_retry()

ra8_err_t ra8_ipc_send_message_retry	(	uint8_t	channel,
		uint32_t	message,
		uint16_t	max_retries )

nodiscard

Bounded-retry variant of ra8_ipc_send_message.

Polls STA.FULL up to max_retries times, clearing FERR at each iteration so a previous overflow does not stick. Returns k_ra8_err_hw_timeout if the FIFO is still full after the loop.

Parameters

[in]	channel	Channel id 0..3.
[in]	message	32-bit payload to enqueue.
[in]	max_retries	Iteration cap (clamped to k_ra8_ipc_retry_max).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Word accepted.
k_ra8_err_invalid_arg	channel >= 4.
k_ra8_err_hw_timeout	FIFO full for the full retry budget.

Precondition: ra8_ipc_init previously enabled the channel.; max_retries <= k_ra8_ipc_retry_max.

Postcondition: On success, STA.RDY is set on the peer.; On timeout, STA.FERR has been cleared at least once.

Note: Thread safety: not thread-safe per channel.

See also: ra8_ipc_send_message

Since: 0.1.0

Definition at line 418 of file ra8_ipc.c.

References r_ipc_channel_regs_t::CLR, internal_ra8_ipc_get_regs(), k_ra8_err_hw_timeout, k_ra8_err_invalid_arg, k_ra8_ipc_channel_count, k_ra8_ipc_clr_mask_fclr, k_ra8_ipc_retry_max, k_ra8_ipc_sta_mask_full, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_ipc_barrier(), s_tag, r_ipc_channel_regs_t::STA, and r_ipc_channel_regs_t::TXD.

◆ ra8_ipc_set_event_mask()

ra8_err_t ra8_ipc_set_event_mask	(	uint8_t	channel,
		uint32_t	mask )

nodiscard

Update the event-mask filter for an already-initialized channel.

Parameters

[in]	channel	Channel id 0..3.
[in]	mask	New ra8_ipc_event_t bitmask.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Mask stored.
k_ra8_err_invalid_arg	channel >= 4.

Precondition: ra8_ipc_init previously enabled the channel.; mask only contains bits drawn from ra8_ipc_event_t.

Postcondition: Subsequent ra8_ipc_dispatch calls filter against the new mask.; Stored channel state otherwise unchanged.

Note: Thread safety: not thread-safe.

See also: ra8_ipc_init

Since: 0.1.0

Definition at line 296 of file ra8_ipc.c.

References k_ra8_err_invalid_arg, k_ra8_ipc_channel_count, k_ra8_ok, and s_ipc_channels.

Functions

Detailed Description

Function Documentation

◆ ra8_ipc_can_access()

◆ ra8_ipc_can_send()

◆ ra8_ipc_channel_for_recv()

◆ ra8_ipc_channel_for_send()

◆ ra8_ipc_clear_errors()

◆ ra8_ipc_clear_event()

◆ ra8_ipc_clear_status()

◆ ra8_ipc_deinit()

◆ ra8_ipc_get_attribution()

◆ ra8_ipc_get_nmi_attribution()

◆ ra8_ipc_get_sem_attribution()

◆ ra8_ipc_get_status()

◆ ra8_ipc_has_data()

◆ ra8_ipc_init()

◆ ra8_ipc_recv_burst()

◆ ra8_ipc_recv_message()

◆ ra8_ipc_recv_message_retry()

◆ ra8_ipc_reset_fifo()

◆ ra8_ipc_send_burst()

◆ ra8_ipc_send_event()

◆ ra8_ipc_send_message()

◆ ra8_ipc_send_message_retry()

◆ ra8_ipc_set_event_mask()