MIPI CSI-2 receiver HAL driver – interrupt path and per-VC framing. More...

#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_hal_internal.h"
#include "ra8_log.h"
#include "ra8_mipi_csi.h"
#include "ra8_mipi_csi_regs.h"
#include "ra8_mstp.h"

Include dependency graph for ra8_mipi_csi_irq.c:

Enumerations
enum	ra8_mipi_csi_irq_intern_t : uint16_t { k_ra8_mipi_csi_vc_invalid_idx = 0xFFU }
	Internal limits used by this translation unit only. More...

Functions
ra8_err_t	ra8_mipi_csi_attach_handler (ra8_mipi_csi_event_fn_t fn, void *ctx)
	Attach the module-level CSI event callback.
ra8_err_t	ra8_mipi_csi_attach_dl_handler (ra8_mipi_csi_dl_event_fn_t fn, void *ctx)
	Attach the per-data-lane callback (MIPI CSI DL vector).
ra8_err_t	ra8_mipi_csi_attach_vc_handler (ra8_mipi_csi_vc_event_fn_t fn, void *ctx)
	Attach the per-VC callback (MIPI CSI VC vector).
ra8_err_t	ra8_mipi_csi_attach_pm_handler (ra8_mipi_csi_pm_event_fn_t fn, void *ctx)
	Attach the power-management callback (MIPI CSI PM vector).
ra8_err_t	ra8_mipi_csi_attach_short_packet_handler (ra8_mipi_csi_short_event_fn_t fn, void *ctx)
	Attach the short-packet FIFO callback (MIPI CSI GST vector).
void	ra8_mipi_csi_dispatch (void)
	ISR-side dispatcher for the receive vector.
void	ra8_mipi_csi_dispatch_dl (void)
	ISR-side dispatcher for the data-lane vector.
void	ra8_mipi_csi_dispatch_vc (void)
	ISR-side dispatcher for the per-VC vector.
void	ra8_mipi_csi_dispatch_pm (void)
	ISR-side dispatcher for the power-management vector.
void	ra8_mipi_csi_dispatch_short_packet (void)
	ISR-side dispatcher for the generic-short-packet vector.
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).
static ra8_err_t	internal_format_to_bit (ra8_mipi_csi_data_format_t format, bool is_high, uint32_t bit)
static void	internal_recompute_dt_filter (void)
ra8_err_t	ra8_mipi_csi_set_virtual_channels (uint16_t vc_mask)
	Filter which CSI-2 virtual channels the receiver will surface.
ra8_err_t	ra8_mipi_csi_set_data_format (uint8_t vc, ra8_mipi_csi_data_format_t format)
	Select the CSI-2 payload format the receiver should accept on a specific virtual channel.
ra8_err_t	ra8_mipi_csi_attach_error_handler (ra8_mipi_csi_error_fn_t fn, void *ctx)
	Register a callback invoked on ECC / CRC error reports.

Variables
static const char *	s_tag = "MIPI_CSI"
	Log tag prefix used by every ra8_log_* call below.
static ra8_mipi_csi_event_fn_t	s_mipi_csi_fn
	Currently-attached receive event callback.
static void *	s_mipi_csi_ctx
	Caller context forwarded to the receive event callback.
static ra8_mipi_csi_dl_event_fn_t	s_mipi_csi_dl_fn
	Currently-attached data-lane callback.
static void *	s_mipi_csi_dl_ctx
	Caller context forwarded to the data-lane callback.
static ra8_mipi_csi_vc_event_fn_t	s_mipi_csi_vc_fn
	Currently-attached per-VC callback.
static void *	s_mipi_csi_vc_ctx
	Caller context forwarded to the per-VC callback.
static ra8_mipi_csi_pm_event_fn_t	s_mipi_csi_pm_fn
	Currently-attached power-management callback.
static void *	s_mipi_csi_pm_ctx
	Caller context forwarded to the PM callback.
static ra8_mipi_csi_short_event_fn_t	s_mipi_csi_gst_fn
	Currently-attached short-packet FIFO callback.
static void *	s_mipi_csi_gst_ctx
	Caller context forwarded to the short-packet callback.
static ra8_mipi_csi_error_fn_t	s_mipi_csi_err_fn
	Callback invoked from dispatch_vc when an ECC/CRC error is decoded out of a VCST snapshot.
static void *	s_mipi_csi_err_ctx
	Caller context forwarded to the error callback.
static uint8_t	s_mipi_csi_vc_format [k_ra8_mipi_csi_vc_count]
	Software shadow of the per-VC payload format selection published by ra8_mipi_csi_set_data_format.
static uint32_t	s_mipi_csi_vcie_saved [k_ra8_mipi_csi_vc_count]
	Snapshot of VCIE(M) at the time the last ra8_mipi_csi_set_virtual_channels call masked it off.

Detailed Description

MIPI CSI-2 receiver HAL driver – interrupt path and per-VC framing.

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

Companion translation unit to ra8_mipi_csi.c. Owns the interrupt-driven callback surface of the RA8D2 MIPI CSI-2 receiver: the attach-handler registration functions, the module / data-lane / virtual-channel / power-management / short-packet dispatchers, and the per-VC framing helpers (data-format shadow + error reporting) from HUM Ch 66 ("MIPI CSI Interface" p 3935-3972).

All the mutable callback function-pointer and context statics, plus the per-VC format shadow and saved-VCIE arrays, live here. The lifecycle code in ra8_mipi_csi.c detaches every callback through the promoted priv_ra8_mipi_csi_detach_all_handlers helper so that the mutable state stays owned by a single translation unit.

Every register access carries a HUM Ch 66 citation immediately above the access, per project policy.

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

Since: 0.1.0

Definition in file ra8_mipi_csi_irq.c.

Enumeration Type Documentation

◆ ra8_mipi_csi_irq_intern_t

enum ra8_mipi_csi_irq_intern_t : uint16_t

Internal limits used by this translation unit only.

k_ra8_mipi_csi_vc_invalid_idx is the sentinel VC id forwarded to the per-VC callback when reporting the "generic" (non-VC-attributable) MLF/ECD error aggregate.

Enumerator
k_ra8_mipi_csi_vc_invalid_idx	Sentinel for "generic" event.

Definition at line 58 of file ra8_mipi_csi_irq.c.

Function Documentation

◆ internal_format_to_bit()

ra8_err_t internal_format_to_bit	(	ra8_mipi_csi_data_format_t	format,
		bool *	is_high,
		uint32_t *	bit )

static

Definition at line 383 of file ra8_mipi_csi_irq.c.

References k_ra8_err_invalid_arg, k_ra8_mipi_csi_dteh_raw8_mask, k_ra8_mipi_csi_dteh_rgb888_mask, k_ra8_mipi_csi_dtel_yuv422_10_mask, k_ra8_mipi_csi_dtel_yuv422_8_mask, k_ra8_mipi_csi_format_off, k_ra8_mipi_csi_format_raw10, k_ra8_mipi_csi_format_raw8, k_ra8_mipi_csi_format_rgb888, k_ra8_mipi_csi_format_yuv420, k_ra8_mipi_csi_format_yuv422_10, k_ra8_mipi_csi_format_yuv422_8, and k_ra8_ok.

Referenced by internal_recompute_dt_filter(), and ra8_mipi_csi_set_data_format().

◆ internal_recompute_dt_filter()

void internal_recompute_dt_filter ( void )

static

Definition at line 422 of file ra8_mipi_csi_irq.c.

References internal_format_to_bit(), k_ra8_mipi_csi_off_dteh, k_ra8_mipi_csi_off_dtel, k_ra8_mipi_csi_vc_count, ra8_mipi_csi_reg32(), and s_mipi_csi_vc_format.

Referenced by ra8_mipi_csi_set_data_format().

◆ 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().

◆ ra8_mipi_csi_attach_dl_handler()

ra8_err_t ra8_mipi_csi_attach_dl_handler	(	ra8_mipi_csi_dl_event_fn_t	fn,
		void *	ctx )

nodiscard

Attach the per-data-lane callback (MIPI CSI DL vector).

Parameters

[in]	fn	Callback fired by ra8_mipi_csi_dispatch_dl.
[in]	ctx	Caller context forwarded to fn.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always.

Precondition: Caller is in single-threaded init context.; fn is either nullptr or a valid function pointer.

Postcondition: ra8_mipi_csi_dispatch_dl will invoke fn for matching lanes.; No hardware state is modified.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 199 of file ra8_mipi_csi_irq.c.

References k_ra8_ok, s_mipi_csi_dl_ctx, and s_mipi_csi_dl_fn.

◆ ra8_mipi_csi_attach_error_handler()

ra8_err_t ra8_mipi_csi_attach_error_handler	(	ra8_mipi_csi_error_fn_t	fn,
		void *	ctx )

nodiscard

Register a callback invoked on ECC / CRC error reports.

The CSI VC dispatcher already surfaces VCST contents. This helper filters those events down to the ECC + CRC error subset and decodes them into a ra8_mipi_csi_error_report_t for the caller. Pass fn = nullptr to detach.

Parameters

[in]	fn	Callback to invoke (or NULL to detach).
[in]	ctx	Caller-owned context forwarded to fn.

Returns: ra8_err_t outcome.

Return values

k_ra8_ok Always.

Precondition: Caller's fn is ISR-safe.; Caller owns the ctx lifetime for as long as fn is attached.

Postcondition: Subsequent ra8_mipi_csi_dispatch_vc calls forward ECC/CRC errors to fn in addition to the VC callback.; Detaching with NULL silently swallows further errors.

Note: ISR-safe.

Since: 0.1.0

Definition at line 489 of file ra8_mipi_csi_irq.c.

References k_ra8_ok, s_mipi_csi_err_ctx, and s_mipi_csi_err_fn.

◆ ra8_mipi_csi_attach_handler()

ra8_err_t ra8_mipi_csi_attach_handler	(	ra8_mipi_csi_event_fn_t	fn,
		void *	ctx )

nodiscard

Attach the module-level CSI event callback.

Attach the receive-status callback (MIPI CSI RX vector).

Stores the supplied callback and opaque context for later invocation by ra8_mipi_csi_dispatch when a module-level event fires.

Parameters

[in]	fn	Event-callback function pointer (NULL to detach).
[in]	ctx	Opaque context passed back to the callback.

Returns: ra8_err_t outcome.

Return values

k_ra8_ok Always returned in the current implementation.

Precondition: Module has been initialized via ra8_mipi_csi_init.; Caller serialises with the IRQ source if registering at runtime.

Postcondition: Subsequent ra8_mipi_csi_dispatch calls invoke fn with ctx.; Previously registered callback (if any) is overwritten.

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

Since: 0.1.0

Definition at line 192 of file ra8_mipi_csi_irq.c.

References k_ra8_ok, s_mipi_csi_ctx, and s_mipi_csi_fn.

◆ ra8_mipi_csi_attach_pm_handler()

ra8_err_t ra8_mipi_csi_attach_pm_handler	(	ra8_mipi_csi_pm_event_fn_t	fn,
		void *	ctx )

nodiscard

Attach the power-management callback (MIPI CSI PM vector).

Parameters

[in]	fn	Callback fired by ra8_mipi_csi_dispatch_pm.
[in]	ctx	Caller context forwarded to fn.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always.

Precondition: Caller is in single-threaded init context.; fn is either nullptr or a valid function pointer.

Postcondition: ra8_mipi_csi_dispatch_pm will invoke fn until detached.; No hardware state is modified.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 213 of file ra8_mipi_csi_irq.c.

References k_ra8_ok, s_mipi_csi_pm_ctx, and s_mipi_csi_pm_fn.

◆ ra8_mipi_csi_attach_short_packet_handler()

ra8_err_t ra8_mipi_csi_attach_short_packet_handler	(	ra8_mipi_csi_short_event_fn_t	fn,
		void *	ctx )

nodiscard

Attach the short-packet FIFO callback (MIPI CSI GST vector).

Parameters

[in]	fn	Callback fired by ra8_mipi_csi_dispatch_short_packet.
[in]	ctx	Caller context forwarded to fn.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always.

Precondition: Caller is in single-threaded init context.; fn is either nullptr or a valid function pointer.

Postcondition: ra8_mipi_csi_dispatch_short_packet will invoke fn until detached.; No hardware state is modified.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 220 of file ra8_mipi_csi_irq.c.

References k_ra8_ok, s_mipi_csi_gst_ctx, and s_mipi_csi_gst_fn.

◆ ra8_mipi_csi_attach_vc_handler()

ra8_err_t ra8_mipi_csi_attach_vc_handler	(	ra8_mipi_csi_vc_event_fn_t	fn,
		void *	ctx )

nodiscard

Attach the per-VC callback (MIPI CSI VC vector).

Parameters

[in]	fn	Callback fired by ra8_mipi_csi_dispatch_vc.
[in]	ctx	Caller context forwarded to fn.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always.

Precondition: Caller is in single-threaded init context.; fn is either nullptr or a valid function pointer.

Postcondition: ra8_mipi_csi_dispatch_vc will invoke fn per VC + once for generic.; No hardware state is modified.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 206 of file ra8_mipi_csi_irq.c.

References k_ra8_ok, s_mipi_csi_vc_ctx, and s_mipi_csi_vc_fn.

◆ ra8_mipi_csi_dispatch()

void ra8_mipi_csi_dispatch ( void )

ISR-side dispatcher for the receive vector.

Designed to be called from the wired-up MIPI CSI receive ISR (mipi_csi_rx_isr in the FSP layout). Reads RXST once, writes RACTDETC to RXSC to clear the sticky detect bit, then forwards the RXST snapshot to the registered callback.

Precondition: ra8_mipi_csi_init has succeeded.; Caller is the IRQ context owned by the MIPI CSI RX vector.

Postcondition: RXSC.RACTDETC has been written 1.; If a handler is attached, it has run synchronously.

Note: Thread safety: ISR-only; do not call from threads.

Since: 0.1.0

Definition at line 228 of file ra8_mipi_csi_irq.c.

References k_ra8_mipi_csi_off_rxsc, k_ra8_mipi_csi_off_rxst, k_ra8_mipi_csi_rxsc_ractdetc_mask, ra8_mipi_csi_reg32(), s_mipi_csi_ctx, and s_mipi_csi_fn.

◆ ra8_mipi_csi_dispatch_dl()

void ra8_mipi_csi_dispatch_dl ( void )

ISR-side dispatcher for the data-lane vector.

Reads MIST + DLST0 + DLST1, W1C-clears DLSC0/DLSC1 (preserving the RO ULP bit), and invokes the data-lane callback once per lane that showed up in MIST.

Precondition: ra8_mipi_csi_init has succeeded.; Caller is the IRQ context owned by the MIPI CSI DL vector.

Postcondition: DLSC0 / DLSC1 have been W1C-cleared.; Handler ran once per lane that flagged in MIST.

Note: Thread safety: ISR-only.

Since: 0.1.0

Definition at line 244 of file ra8_mipi_csi_irq.c.

References k_ra8_mipi_csi_dlsc_all_mask, k_ra8_mipi_csi_mist_dl0s_mask, k_ra8_mipi_csi_mist_dl1s_mask, k_ra8_mipi_csi_off_dlsc0, k_ra8_mipi_csi_off_dlsc1, k_ra8_mipi_csi_off_dlst0, k_ra8_mipi_csi_off_dlst1, k_ra8_mipi_csi_off_mist, ra8_mipi_csi_reg32(), s_mipi_csi_dl_ctx, and s_mipi_csi_dl_fn.

◆ ra8_mipi_csi_dispatch_pm()

void ra8_mipi_csi_dispatch_pm ( void )

ISR-side dispatcher for the power-management vector.

Reads PMST, W1C-clears the lower 8 bits via PMSC, then invokes the PM callback.

Precondition: ra8_mipi_csi_init has succeeded.; Caller is the IRQ context owned by the MIPI CSI PM vector.

Postcondition: PMSC has been written with the W1C-clearable bits.; Handler ran once with the PMST snapshot.

Note: Thread safety: ISR-only.

Since: 0.1.0

Definition at line 330 of file ra8_mipi_csi_irq.c.

References k_ra8_mipi_csi_off_pmsc, k_ra8_mipi_csi_off_pmst, k_ra8_mipi_csi_pmst_w1c_mask, ra8_mipi_csi_reg32(), s_mipi_csi_pm_ctx, and s_mipi_csi_pm_fn.

◆ ra8_mipi_csi_dispatch_short_packet()

void ra8_mipi_csi_dispatch_short_packet ( void )

ISR-side dispatcher for the generic-short-packet vector.

Reads GSST, W1C-clears GOV via GSSC, then invokes the GST callback. The handler is expected to drain the FIFO via ra8_mipi_csi_read_short_packet.

Precondition: ra8_mipi_csi_init has succeeded.; Caller is the IRQ context owned by the MIPI CSI GST vector.

Postcondition: GSSC has been written with the W1C-clearable bits.; Handler ran once with the GSST snapshot.

Note: Thread safety: ISR-only.

Since: 0.1.0

Definition at line 346 of file ra8_mipi_csi_irq.c.

References k_ra8_mipi_csi_gssc_govc_mask, k_ra8_mipi_csi_off_gssc, k_ra8_mipi_csi_off_gsst, ra8_mipi_csi_reg32(), s_mipi_csi_gst_ctx, and s_mipi_csi_gst_fn.

◆ ra8_mipi_csi_dispatch_vc()

void ra8_mipi_csi_dispatch_vc ( void )

ISR-side dispatcher for the per-VC vector.

Reads MIST, then for every VC bit that is set walks the per-channel registers, clears each VCSC(M), and invokes the per-VC callback. Generic errors (MLF + ECD) are accumulated and delivered as a final callback with vc = 0xFF.

Precondition: ra8_mipi_csi_init has succeeded.; Caller is the IRQ context owned by the MIPI CSI VC vector.

Postcondition: Every flagged VCSC(M) has been written.; Handler ran once per VC plus once for the generic-error summary.

Note: Thread safety: ISR-only.

Since: 0.1.0

Definition at line 273 of file ra8_mipi_csi_irq.c.

References k_ra8_mipi_csi_mist_vc_mask, k_ra8_mipi_csi_mist_vc_shift, k_ra8_mipi_csi_off_mist, k_ra8_mipi_csi_off_vcsc0, k_ra8_mipi_csi_off_vcst0, k_ra8_mipi_csi_vc_count, k_ra8_mipi_csi_vc_invalid_idx, k_ra8_mipi_csi_vcsc_per_vc_mask, k_ra8_mipi_csi_vcst_crc_mask, k_ra8_mipi_csi_vcst_ecc_mask, k_ra8_mipi_csi_vcst_ecd_mask, k_ra8_mipi_csi_vcst_generic_err_mask, ra8_mipi_csi_reg32(), ra8_mipi_csi_vc_off(), s_mipi_csi_err_ctx, s_mipi_csi_err_fn, s_mipi_csi_vc_ctx, and s_mipi_csi_vc_fn.

◆ ra8_mipi_csi_set_data_format()

ra8_err_t ra8_mipi_csi_set_data_format	(	uint8_t	vc,
		ra8_mipi_csi_data_format_t	format )

nodiscard

Select the CSI-2 payload format the receiver should accept on a specific virtual channel.

The hardware filter (DTEL/DTEH) is global across virtual channels – selecting a format on one VC therefore enables the matching DT bit for the entire receiver. The driver records the per-VC selection in a software shadow so a subsequent call with k_ra8_mipi_csi_format_off can re-compute the union and clear the DT bit if no other VC still wants it. HUM Ch 66.3.10/66.3.11 pp 3943-3944.

Parameters

[in]	vc	Virtual channel index (0..15).
[in]	format	Payload format to accept (or _off to disable).

Returns: ra8_err_t outcome.

Return values

k_ra8_ok	Filter updated.
k_ra8_err_invalid_arg	vc > 15 or unknown format value.

Precondition: ra8_mipi_csi_init has succeeded.; vc is in 0..15.

Postcondition: DTEL/DTEH reflect the union of all per-VC selections.; Future calls to ra8_mipi_csi_set_data_type_filter override these contributions with explicit masks.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 473 of file ra8_mipi_csi_irq.c.

References internal_format_to_bit(), internal_recompute_dt_filter(), k_ra8_err_invalid_arg, k_ra8_mipi_csi_vc_count, k_ra8_ok, and s_mipi_csi_vc_format.

◆ ra8_mipi_csi_set_virtual_channels()

ra8_err_t ra8_mipi_csi_set_virtual_channels ( uint16_t vc_mask )

nodiscard

Filter which CSI-2 virtual channels the receiver will surface.

Each bit i of vc_mask enables VCi (i = 0..15). The driver disables VCIE on every channel whose bit is clear (so spurious traffic does not raise IRQs) and restores the previous IRQ mask on channels that are re-enabled. HUM Ch 66.3.20 "VCIE(M)" p 3952.

Parameters

[in] vc_mask Bitmap of accepted virtual channels (bit 0 = VC0).