Cross-translation-unit private helpers shared inside ra8_hal. More...

#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_canfd_regs.h"
#include "ra8_dotf.h"
#include "ra8_err.h"
#include "ra8_rmac_regs.h"
#include "ra8_ssie_regs.h"
#include "ra8_usb_hmsc.h"

Include dependency graph for ra8_hal_internal.h:

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

Go to the source code of this file.

Data Structures
struct	ra8_ssie_runtime_t
	Per-channel runtime bookkeeping. More...
struct	ra8_usb_hmsc_state_t
	Singleton shadow state for the host-MSC driver. More...

Enumerations
enum	ra8_ssie_internal_const_t : uint8_t { k_ra8_ssie_dma_ch_unused = 0xFFU , k_ra8_ssie_dma_max_ch = 8U , k_ra8_ssie_thresh_max = 0x1FU }
	Internal magic-number constants promoted to typed enums. More...

Functions
static bool	internal_ra8_dotf_internal_channel_in_range (uint8_t channel)
	Bound-check a DOTF channel index.
static bool	internal_port_ok (ra8_rmac_port_t port)
	Range-check an RMAC port argument.
void	priv_ra8_mipi_csi_detach_all_handlers (void)
	Detach every MIPI CSI-2 receiver callback (module / data-lane / virtual-channel / power-management / short-packet).
volatile r_ssie_regs_t *	priv_ra8_ssie_internal_regs (uint8_t channel)
	Validate an SSIE channel index and return its register block.
ra8_err_t	priv_ra8_canfd_internal_set_channel_mode (volatile r_canfd_t *reg, ra8_chmdc_mode_t mode)
	Drive CFDC[0].CTR.CHMDC and wait for the matching status bit.

Variables
ra8_ssie_runtime_t	g_ssie_runtime [k_ra8_ssie_channel_count]
	Per-channel SSIE runtime state, shared across the ra8_ssie split.
ra8_usb_hmsc_state_t	g_usb_hmsc_state
	Singleton host-MSC shadow state, shared across the ra8_usb_hmsc split.

Detailed Description

Cross-translation-unit private helpers shared inside ra8_hal.

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

Private (library-internal) header used to share small inline helpers and extern declarations between sibling translation units of a single ra8_hal driver that has been split across multiple .c files purely to satisfy the per-file size cap. It is NOT part of the public HAL surface and must never be included from outside libs/ra8_hal/src.

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

Since: 0.1.0

Definition in file ra8_hal_internal.h.

Enumeration Type Documentation

◆ ra8_ssie_internal_const_t

enum ra8_ssie_internal_const_t : uint8_t

Internal magic-number constants promoted to typed enums.

Enumerator
k_ra8_ssie_dma_ch_unused	Sentinel: no DMA channel.
k_ra8_ssie_dma_max_ch	DMAC channel count (0..7).
k_ra8_ssie_thresh_max	Max SSISCR threshold value.

Definition at line 141 of file ra8_hal_internal.h.

Function Documentation

◆ internal_port_ok()

bool internal_port_ok ( ra8_rmac_port_t port )

inlinestatic

Range-check an RMAC port argument.

Shared between ra8_rmac.c and ra8_rmac_mgmt.c. Defined static inline in this private header so each translation unit gets its own copy with no external linkage symbol, keeping the split link-clean while preserving the original single-definition behavior.

Parameters

[in] port Port to validate.

Returns: true if port is one of ra8_rmac_port_t.

Return values

true	Port index is in range.
false	Port index is out of range.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 90 of file ra8_hal_internal.h.

References k_ra8_rmac_port_count, and RA8_INTERNAL.

◆ internal_ra8_dotf_internal_channel_in_range()

bool internal_ra8_dotf_internal_channel_in_range ( uint8_t channel )

inlinestatic

Bound-check a DOTF channel index.

Shared between ra8_dotf.c and ra8_dotf_power.c. Defined static inline in this private header so each translation unit gets its own copy with no external linkage symbol, keeping the split link-clean while preserving the original single-definition behavior.

Parameters

[in] channel Caller-provided channel value.

Returns: true if channel is in [0, k_ra8_dotf_channel_count).

Return values

true	Channel index is in range.
false	Channel index is out of range.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 54 of file ra8_hal_internal.h.

References k_ra8_dotf_channel_count, and RA8_INTERNAL.

Referenced by internal_open_validate_init(), and ra8_dotf_set_region_window().

◆ priv_ra8_canfd_internal_set_channel_mode()

ra8_err_t priv_ra8_canfd_internal_set_channel_mode	(	volatile r_canfd_t *	reg,
		ra8_chmdc_mode_t	mode )

Drive CFDC[0].CTR.CHMDC and wait for the matching status bit.

Promoted from a file-scope static helper in ra8_canfd.c to TU-external linkage so the bit-timing TU (ra8_canfd_timing.c) can transition the channel through CH_RESET / CH_OPERATION around an NCFG / DCFG edit, which is only writable while the channel is halted or in reset. The single definition stays in ra8_canfd.c beside the rest of the mode-transition machinery (HUM Ch 41 p 2762 "CFDCnCTR.CHMDC", p 2766 "CFDCnSTS").

Parameters

[in]	reg	CANFD channel register block.
[in]	mode	Requested channel mode (reset / halt / operation).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	The channel latched the requested mode.
k_ra8_err_hw_timeout	The status bit never latched within the budget.

Precondition: reg is non-NULL and points to a CANFD instance.; The CANFD block clock and channel MSTP gate are already alive.

Postcondition: On success the channel state machine reflects mode.; No global state is modified on the error path.

Note: Not thread-safe; init / reconfigure context only.; Module-private to libs/ra8_hal/src; not part of the public surface.

Since: 0.1.0

Mirrors r_canfd_mode_ctr_set + r_canfd_mode_transition from FSP r_canfd.c. The CHMDC field is bits [1:0] of CTR (FSP R_CANFD_CFDC_CTR_b.CHMDC). After a write the channel state machine drives CRSTSTS / CHLTSTS / CSLPSTS in CFDC[0].STS.

Parameters

[in]	reg	See header declaration for direction and constraints.
[in]	mode	See header declaration for direction and constraints.

Returns: ra8_err_t error code (or void if the signature returns void).

Return values

k_ra8_ok	Success path.
k_ra8_err_invalid_arg	Caller violated a precondition.

Precondition: Driver state has been initialized by the matching *_init.; Caller has validated all pointer parameters.

Postcondition: Side effects are limited to those documented in the header.; No global state is modified on the error path.

Note: Thread safety: see the header declaration.

Since: 0.1.0

Definition at line 138 of file ra8_canfd.c.

References r_canfd_t::CFDC, r_canfd_cfdc_t::CTR, internal_wait_status_bit(), k_ra8_canfd_spin, k_ra8_chmdc_halt, k_ra8_chmdc_reset, k_ra8_cnctr_mask_chmdc, k_ra8_cnctr_mask_cslpr, k_ra8_cnsts_bit_chltst, k_ra8_cnsts_bit_crstst, ra8_hw_wait_flag_clear32(), and r_canfd_cfdc_t::STS.

Referenced by internal_canfd_open_channel(), ra8_canfd_deinit(), ra8_canfd_set_bitrate(), ra8_canfd_set_tdc(), and ra8_canfd_set_test_mode().

◆ priv_ra8_mipi_csi_detach_all_handlers()

void priv_ra8_mipi_csi_detach_all_handlers ( void )

Detach every MIPI CSI-2 receiver callback (module / data-lane / virtual-channel / power-management / short-packet).

Clears the ten callback function-pointer / context statics owned by ra8_mipi_csi_irq.c back to nullptr. Invoked by ra8_mipi_csi_deinit during teardown so that no stale callback can fire after the receiver has been gated. The per-VC error callback is left untouched, mirroring the pre-split ra8_mipi_csi_deinit behaviour.

Returns: Nothing.

Precondition: The MIPI CSI-2 receiver is being torn down by ra8_mipi_csi_deinit.; Caller serialises with the CSI IRQ sources.

Postcondition: All ten module/lane/VC/PM/short callback slots are nullptr.; No subsequent dispatch invokes a previously-registered callback.

Note: Not thread-safe; the caller must serialise concurrent access.

Since: 0.1.0

Definition at line 361 of file ra8_mipi_csi_irq.c.

References s_mipi_csi_ctx, s_mipi_csi_dl_ctx, s_mipi_csi_dl_fn, s_mipi_csi_fn, s_mipi_csi_gst_ctx, s_mipi_csi_gst_fn, s_mipi_csi_pm_ctx, s_mipi_csi_pm_fn, s_mipi_csi_vc_ctx, and s_mipi_csi_vc_fn.

Referenced by ra8_mipi_csi_deinit().

◆ priv_ra8_ssie_internal_regs()

volatile r_ssie_regs_t * priv_ra8_ssie_internal_regs ( uint8_t channel )

Validate an SSIE channel index and return its register block.

Shared between ra8_ssie.c and ra8_ssie_stream.c. Promoted from a file-scope static helper to TU-external linkage so the streaming TU can reuse the same channel-bounds check before touching SSIE registers. Returns nullptr for an out-of-range channel exactly like ra8_ssie().

Parameters

[in] channel Channel index supplied by the caller.

Returns: Volatile pointer to the channel's register block, or nullptr on an out-of-range channel index.

Return values

nullptr Channel index is out of range.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Validate an SSIE channel index and return its register block.

Definition at line 101 of file ra8_ssie.c.

References k_ra8_ssie_channel_count, and ra8_ssie().

Referenced by ra8_ssie_attach_dma(), ra8_ssie_clear_status(), ra8_ssie_deinit(), ra8_ssie_dispatch(), ra8_ssie_get_status(), ra8_ssie_init(), ra8_ssie_mute(), ra8_ssie_read_buffer(), ra8_ssie_read_sample(), ra8_ssie_recv_iso(), ra8_ssie_send_iso(), ra8_ssie_set_irq_enable(), ra8_ssie_set_thresholds(), ra8_ssie_start(), ra8_ssie_start_recovery(), ra8_ssie_stop(), ra8_ssie_write_buffer(), and ra8_ssie_write_sample().

Variable Documentation

◆ g_ssie_runtime

ra8_ssie_runtime_t g_ssie_runtime[k_ra8_ssie_channel_count]

extern

Per-channel SSIE runtime state, shared across the ra8_ssie split.

Per-channel runtime state.

Single definition lives in ra8_ssie.c; ra8_ssie_stream.c reads and writes the same object through this extern declaration. The mutable DMA-channel bookkeeping must remain one object so that attach/detach in the stream TU and init/deinit in the lifecycle TU agree on per-channel state.

Note: Module-private to libs/ra8_hal/src; not part of the public surface.

Warning: Not thread-safe; callers must serialise concurrent access.

Since: 0.1.0

Initialized to zero / unused.

Single definition for the ra8_ssie split; ra8_ssie_stream.c shares this object via the extern declaration in ra8_hal_internal.h. External linkage (no static) is required so both translation units bind the same storage. The s_ssie_ prefix keeps it clang-tidy-clean and link-unique.

Definition at line 73 of file ra8_ssie.c.

Referenced by internal_start_rx_dma(), internal_start_tx_dma(), internal_unwind_tx_dma(), ra8_ssie_attach_dma(), ra8_ssie_attach_dma_pair(), ra8_ssie_deinit(), ra8_ssie_detach_dma(), and ra8_ssie_init().

◆ g_usb_hmsc_state

ra8_usb_hmsc_state_t g_usb_hmsc_state

extern

Singleton host-MSC shadow state, shared across the ra8_usb_hmsc split.

Single definition lives in ra8_usb_hmsc.c; ra8_usb_hmsc_enum.c reads and writes the same object through this extern declaration. The mutable state (attach flags, negotiated speed, device snapshot, BOT tag counter) must remain one object so the enumeration ladder and the command path agree on the attached device.

Note: Module-private to libs/ra8_hal/src; not part of the public surface.

Warning: Not thread-safe; callers must serialise concurrent access.

Since: 0.1.0

Definition at line 222 of file ra8_usb_hmsc.c.

Referenced by internal_check_ready(), internal_enum_assign_addr(), internal_enum_configure(), internal_enum_fill_ids(), internal_enum_hunt(), internal_enum_note_endpoint(), internal_enum_publish(), internal_enum_read_config(), internal_enum_read_dev_desc(), internal_enum_walk_cfg(), internal_next_tag(), internal_recv_bytes(), internal_run_data_out(), internal_send_cbw(), ra8_usb_hmsc_attach_callback(), ra8_usb_hmsc_close(), ra8_usb_hmsc_enumerate(), and ra8_usb_hmsc_init().

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_ssie_internal_const_t

Function Documentation

◆ internal_port_ok()

◆ internal_ra8_dotf_internal_channel_in_range()

◆ priv_ra8_canfd_internal_set_channel_mode()

◆ priv_ra8_mipi_csi_detach_all_handlers()

◆ priv_ra8_ssie_internal_regs()

Variable Documentation

◆ g_ssie_runtime

◆ g_usb_hmsc_state