Video Input Module (VIN) driver implementation. More...

#include "ra8_vin.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_hw_err.h"
#include "ra8_log.h"
#include "ra8_mstp.h"
#include "ra8_vin_regs.h"

Include dependency graph for ra8_vin.c:

Enumerations
enum	ra8_vin_local_t : uint8_t { k_ra8_vin_max_im = 2U , k_ra8_vin_max_dc = 2U , k_ra8_vin_max_clp = 3U , k_ra8_vin_max_yuv444 = 1U , k_ra8_vin_max_dtmd = 2U , k_ra8_vin_max_ymode = 3U , k_ra8_vin_max_vc_sel = 0xFU , k_ra8_vin_max_dt = 0x3FU , k_ra8_vin_max_field_no = 1U , k_ra8_vin_max_lsft = 31U , k_ra8_vin_yc_chan_max = 2U }
	File-scope magic-free constants. More...
enum	ra8_vin_chan_offsets_t : uint16_t { k_ra8_vin_yc_y_set1 = k_ra8_vin_off_yccr1 , k_ra8_vin_yc_y_set2 = k_ra8_vin_off_yccr2 , k_ra8_vin_yc_y_set3 = k_ra8_vin_off_yccr3 , k_ra8_vin_yc_cb_set1 = k_ra8_vin_off_cbccr1 , k_ra8_vin_yc_cb_set2 = k_ra8_vin_off_cbccr2 , k_ra8_vin_yc_cb_set3 = k_ra8_vin_off_cbccr3 , k_ra8_vin_yc_cr_set1 = k_ra8_vin_off_crccr1 , k_ra8_vin_yc_cr_set2 = k_ra8_vin_off_crccr2 , k_ra8_vin_yc_cr_set3 = k_ra8_vin_off_crccr3 }
	Register offsets for one row of the RGB-to-YC matrix. More...
enum	ra8_vin_capture_geom_t : uint16_t { k_ra8_vin_geom_max_dim = 4096U }
	Bounded geometry constants used by ra8_vin_capture_start. More...
enum	ra8_vin_format_bpp_t : uint8_t { k_ra8_vin_bpp_ycbcr422 = 2U , k_ra8_vin_bpp_raw8 = 1U , k_ra8_vin_bpp_rgb888 = 4U }
	Bytes-per-pixel lookup for ra8_vin_input_fmt_t. More...

Functions
static uint32_t	internal_compose_mc (const ra8_vin_config_t *cfg)
	Encode a ra8_vin_config_t into the MC register value.
static void	internal_pulse_st (uint32_t mc_now)
	Pulse MC.ST then absorb the >= 10 ICLK settling time.
static void	internal_mc_rmw (uint32_t clear_mask, uint32_t set_bits)
	Read-modify-write a single bit-field within MC.
ra8_err_t	ra8_vin_init (const ra8_vin_config_t *cfg)
	Initialise VIN with the supplied descriptor.
ra8_err_t	ra8_vin_deinit (void)
	Tear down VIN: stop capture, mask interrupts, drop MSTP.
ra8_err_t	ra8_vin_reset (void)
	Issue a soft reset by re-running the MC.ST settle sequence.
ra8_err_t	ra8_vin_capture_arm (ra8_vin_capture_mode_t mode)
	Start a capture operation.
ra8_err_t	ra8_vin_capture_disarm (void)
	Stop the current capture and drain outstanding AXI traffic.
ra8_err_t	ra8_vin_set_preclip (const ra8_vin_preclip_t *window)
	Programme the pre-clip window (SLPRC / ELPRC / SPPRC / EPPRC).
ra8_err_t	ra8_vin_set_uds_scale (const ra8_vin_uds_scale_t *scale)
	Programme the UDS scaling factor (UDS_SCALE).
ra8_err_t	ra8_vin_set_uds_passband (uint8_t v_bwidth, uint8_t h_bwidth)
	Programme the UDS pass-band bandwidth (UDS_PASS_BWIDTH).
ra8_err_t	ra8_vin_set_uds_clip (uint16_t v_size, uint16_t h_size)
	Programme the UDS output clipping (UDS_CLIP_SIZE).
ra8_err_t	ra8_vin_set_uds_ctrl (const ra8_vin_uds_ctrl_t *ctrl)
	Programme UDS interpolation control (UDS_CTRL).
ra8_err_t	ra8_vin_enable_scaling (bool enable)
	Toggle the MC.SCLE main scaling-enable bit.
ra8_err_t	ra8_vin_lut_program (const uint8_t y_table, const uint8_t cb_table, const uint8_t *cr_table, bool enable)
	Programme all 256 entries of the Y / Cb / Cr conversion LUT.
ra8_err_t	ra8_vin_set_yc_to_rgb (const ra8_vin_yc_to_rgb_t *coeffs)
	Programme the YC -> RGB matrix coefficients (CSCE1..4).
static void	internal_yc_offsets (uint8_t channel, ra8_vin_off_t off1, ra8_vin_off_t off2, ra8_vin_off_t *off3)
	Resolve the (set1, set2, set3) offset triple for one row.
ra8_err_t	ra8_vin_set_rgb_to_yc (uint8_t channel, const ra8_vin_rgb_to_yc_chan_t *row)
	Programme one row of the RGB -> YC matrix.
ra8_err_t	ra8_vin_set_dithering (uint8_t mode, bool direction)
	Configure the dithering mode (MC.DC + MC.DC2).
ra8_err_t	ra8_vin_set_yuv444_mode (uint8_t mode)
	Configure the YUV-444 conversion mode (MC.YUV444).
ra8_err_t	ra8_vin_set_interlace_mode (uint8_t mode)
	Set the interlace mode (MC.IM).
ra8_err_t	ra8_vin_set_data_mode (const ra8_vin_data_mode_t *mode)
	Programme the DMR (Data Mode Register).
ra8_err_t	ra8_vin_set_csi_input (const ra8_vin_csi_input_t *input)
	Programme CSI_IFMD (virtual channel + data type + extension).
ra8_err_t	ra8_vin_set_field_detect (const ra8_vin_field_detect_t *detect)
	Programme CSIFLD (field detection).
ra8_err_t	ra8_vin_set_framebuffers (uint32_t mb1, uint32_t mb2, uint32_t mb3)
	Re-programme MB1 / MB2 / MB3 (ping-pong framebuffers).
ra8_err_t	ra8_vin_set_uv_offset (uint32_t uv_addr)
	Programme UVAOF (UV plane address offset for YC-separated mode).
ra8_err_t	ra8_vin_get_status (uint32_t *out_mask)
	Snapshot the INTS register.
ra8_err_t	ra8_vin_clear_status (uint32_t mask)
	Clear write-1-to-clear bits in the INTS register.
ra8_err_t	ra8_vin_get_module_status (ra8_vin_module_status_t *out_status)
	Decode the MS register into a typed snapshot.
ra8_err_t	ra8_vin_get_line_count (uint16_t *out_count)
	Read the LC (line count) register.
ra8_err_t	ra8_vin_get_active_buffer (uint8_t *out_id)
	Return the active framebuffer index from MS.FBS.
ra8_err_t	ra8_vin_set_interrupt_enable (uint32_t mask)
	Update the IE (Interrupt Enable) mask at runtime.
ra8_err_t	ra8_vin_set_scanline_compare (uint16_t line)
	Programme the SI (Scanline Interrupt) compare register.
ra8_err_t	ra8_vin_attach_handler (ra8_vin_event_fn_t fn, void *ctx)
	Attach a VIN event callback (shared between status + error IRQs).
void	ra8_vin_dispatch (void)
	Snapshot INTS, fire callback, then W1C the latched bits.
ra8_err_t	ra8_vin_enter_stop (void)
	Quiesce VIN and disable its module-stop clock gate.
ra8_err_t	ra8_vin_exit_stop (void)
	Re-enable the VIN clock gate after ra8_vin_enter_stop.
static uint8_t	internal_format_bpp (ra8_vin_input_fmt_t format)
ra8_err_t	ra8_vin_capture_start (void *buf, uint16_t w, uint16_t h, ra8_vin_input_fmt_t format)
	Start a single-frame capture into buf with the supplied geometry.
ra8_err_t	ra8_vin_capture_stop (void)
	Stop the in-flight capture started via ra8_vin_capture_start.
ra8_err_t	ra8_vin_set_window (uint16_t x, uint16_t y, uint16_t w, uint16_t h)
	Programme a region-of-interest pre-clip window.
ra8_err_t	ra8_vin_attach_frame_handler (ra8_vin_frame_fn_t fn, void *ctx)
	Register the frame-end IRQ callback.

Variables
static const char *	s_tag = "VIN"
	Logging tag used by every log call in this TU.
static ra8_vin_event_fn_t	s_vin_fn
	Registered VIN event callback (set by ra8_vin_attach_handler).
static void *	s_vin_ctx
	Context value forwarded to s_vin_fn.
static ra8_vin_frame_fn_t	s_vin_frame_fn
	Frame-end callback registered via ra8_vin_attach_frame_handler.
static void *	s_vin_frame_ctx
	Context forwarded to s_vin_frame_fn.
static void *	s_vin_frame_buf
	Buffer base of the most recent ra8_vin_capture_start call.
static uint32_t	s_vin_frame_len
	Cached length (in bytes) of the most recent capture geometry.

Detailed Description

Video Input Module (VIN) driver implementation.

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

/ Round-3 driver for the RA8D2 Video Input Module. Covers every register documented in HUM Ch 67 "Video Input Module" p 3973-4031:

MC / FC / MS / MTCSTOP / DMR for the main pipeline.
SLPRC / ELPRC / SPPRC / EPPRC for pre-clip windowing.
UDS_CTRL / UDS_SCALE / UDS_PASS_BWIDTH / UDS_CLIP_SIZE for the upscaling / downscaling pipeline.
LUTP / LUTD for the 256-entry 10-to-8-bit conversion LUT.
YCCRn / CBCCRn / CRCCRn for RGB -> YC matrix coefficients.
CSCE1..4 for YC -> RGB matrix coefficients.
CSI_IFMD / CSIFLD for CSI-2 input mode and field detection.
IS / MB1..3 / UVAOF / IE / INTS / SI for capture geometry, framebuffer routing, interrupts, and scanline-compare.

The peripheral does not have its own MSTPCR bit on the RA8D2 – its clocks come up alongside MIPI CSI when k_ra8_mstp_mipi_csi is enabled. The driver therefore routes power transitions through the existing ra8_mstp enum rather than opening up MSTPCRC for direct access.

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

Definition in file ra8_vin.c.

Enumeration Type Documentation

◆ ra8_vin_capture_geom_t

enum ra8_vin_capture_geom_t : uint16_t

Bounded geometry constants used by ra8_vin_capture_start.

Enumerator
k_ra8_vin_geom_max_dim	Hardware caps both axes at 4096.

Definition at line 903 of file ra8_vin.c.

◆ ra8_vin_chan_offsets_t

enum ra8_vin_chan_offsets_t : uint16_t

Register offsets for one row of the RGB-to-YC matrix.

Indexed via the channel parameter to ra8_vin_set_rgb_to_yc.

Enumerator
k_ra8_vin_yc_y_set1	RA8 vin yc y set1.
k_ra8_vin_yc_y_set2	RA8 vin yc y set2.
k_ra8_vin_yc_y_set3	RA8 vin yc y set3.
k_ra8_vin_yc_cb_set1	RA8 vin yc cb set1.
k_ra8_vin_yc_cb_set2	RA8 vin yc cb set2.
k_ra8_vin_yc_cb_set3	RA8 vin yc cb set3.
k_ra8_vin_yc_cr_set1	RA8 vin yc cr set1.
k_ra8_vin_yc_cr_set2	RA8 vin yc cr set2.
k_ra8_vin_yc_cr_set3	RA8 vin yc cr set3.

Definition at line 147 of file ra8_vin.c.

◆ ra8_vin_format_bpp_t

enum ra8_vin_format_bpp_t : uint8_t

Bytes-per-pixel lookup for ra8_vin_input_fmt_t.

Enumerator
k_ra8_vin_bpp_ycbcr422	4:2:2 packs to 2 bytes / pixel.
k_ra8_vin_bpp_raw8	RAW8 = 1 byte / pixel.
k_ra8_vin_bpp_rgb888	RGB888 packed in 32-bit cells.

Definition at line 911 of file ra8_vin.c.

◆ ra8_vin_local_t

enum ra8_vin_local_t : uint8_t

File-scope magic-free constants.

Centralises the bounds-check limits used by the setter family so the implementations read close to the HUM register descriptions.

Enumerator
k_ra8_vin_max_im	MC.IM legal max (0..2).
k_ra8_vin_max_dc	MC.DC legal max (0..2).
k_ra8_vin_max_clp	MC.CLP legal max (0..3 with 2 reserved).
k_ra8_vin_max_yuv444	MC.YUV444 legal max.
k_ra8_vin_max_dtmd	DMR.DTMD legal max (0..2).
k_ra8_vin_max_ymode	DMR.YMODE legal max (0..3).
k_ra8_vin_max_vc_sel	CSI_IFMD.VC_SEL 4-bit max.
k_ra8_vin_max_dt	CSI_IFMD.DT 6-bit max.
k_ra8_vin_max_field_no	CSIFLD.FLD_NUM legal max.
k_ra8_vin_max_lsft	Setting 3 LSFT 5-bit max.
k_ra8_vin_yc_chan_max	RGB-to-YC channel index max (0..2).

Definition at line 126 of file ra8_vin.c.

Function Documentation

◆ internal_compose_mc()

uint32_t internal_compose_mc ( const ra8_vin_config_t * cfg )

static

Encode a ra8_vin_config_t into the MC register value.

Folds cfg->{bypass_csc, big_endian, interlace_mode, input_fmt, pixel_clip_mode} into the MC bitfield documented at HUM Ch 67.2.1 "MC: Main Control Register" (p 3975). The ME / ST start-trigger bits are deliberately left clear so the caller can pulse them on demand.

Parameters

[in] cfg Validated configuration.

Returns: Composed MC value with ME / ST left clear.

Return values

0..(uint32_t)-1 Bitwise-OR of the documented MC fields.

Precondition: cfg != NULL (caller-validated).; cfg->input_fmt fits the 3-bit MC.INF field.; cfg->interlace_mode <= k_ra8_vin_max_im.

Postcondition: Returned value has k_ra8_vin_mc_me = 0.; Returned value has k_ra8_vin_mc_st = 0 (start pulse only on demand).

Note: Pure function; safe from any context.

Since: 0.1.0

Definition at line 183 of file ra8_vin.c.

References ra8_vin_config_t::big_endian, ra8_vin_config_t::bypass_csc, ra8_vin_config_t::input_fmt, ra8_vin_config_t::interlace_mode, k_ra8_vin_mc_bps, k_ra8_vin_mc_clp, k_ra8_vin_mc_en, k_ra8_vin_mc_im, k_ra8_vin_mc_inf, k_ra8_vin_mc_shift_clp, k_ra8_vin_mc_shift_im, k_ra8_vin_mc_shift_inf, and ra8_vin_config_t::pixel_clip_mode.

Referenced by ra8_vin_init().

◆ internal_format_bpp()

uint8_t internal_format_bpp ( ra8_vin_input_fmt_t format )

static

Definition at line 919 of file ra8_vin.c.

References k_ra8_vin_bpp_raw8, k_ra8_vin_bpp_rgb888, k_ra8_vin_bpp_ycbcr422, k_ra8_vin_input_raw8, and k_ra8_vin_input_rgb888.

Referenced by ra8_vin_capture_start().

◆ internal_mc_rmw()

void internal_mc_rmw	(	uint32_t	clear_mask,
		uint32_t	set_bits )

static

Read-modify-write a single bit-field within MC.

Atomic from the caller's perspective when IRQs are masked. The helper exists to keep field-update sites from re-implementing the mask / shift dance for HUM Ch 67.2.1 "MC: Main Control Register" (p 3975).

Parameters

[in]	clear_mask	Bits to clear before OR-ing in set_bits.
[in]	set_bits	Bits to set on top of the cleared field.

Precondition: Caller has masked IRQs.; set_bits & ~clear_mask is empty (no out-of-field bits).

Postcondition: MC = (MC & ~clear_mask) | set_bits.; Bits outside clear_mask are unchanged.

Note: Inline helper.

Since: 0.1.0

Definition at line 253 of file ra8_vin.c.

References k_ra8_vin_off_mc, and ra8_vin_reg32().

Referenced by ra8_vin_capture_start(), ra8_vin_enable_scaling(), ra8_vin_lut_program(), ra8_vin_set_dithering(), ra8_vin_set_interlace_mode(), and ra8_vin_set_yuv444_mode().

◆ internal_pulse_st()

void internal_pulse_st ( uint32_t mc_now )

static

Pulse MC.ST then absorb the >= 10 ICLK settling time.

Writes mc_now | MC.ST then reads MC back several times so the peripheral observes the >= 10-ICLK settle window mandated by HUM Ch 67.2.1 "MC: Main Control Register" (p 3975).

Parameters

[in] mc_now Current MC register value (without ST set).

Precondition: Caller holds mc_reg pointer to MC register.; Capture is not in progress.

Postcondition: MC.ST has been pulsed; >= 10 ICLK have elapsed.; MC retains the original mc_now field bits (ST is self-clearing).

Note: Inline helper, single-CPU.

Since: 0.1.0

Definition at line 221 of file ra8_vin.c.

References k_ra8_vin_mc_st, k_ra8_vin_off_mc, k_ra8_vin_st_settle_reads, and ra8_vin_reg32().

Referenced by ra8_vin_capture_arm(), and ra8_vin_reset().

◆ internal_yc_offsets()

void internal_yc_offsets	(	uint8_t	channel,
		ra8_vin_off_t *	off1,
		ra8_vin_off_t *	off2,
		ra8_vin_off_t *	off3 )

static

Resolve the (set1, set2, set3) offset triple for one row.

Maps the channel index onto the matching YCCRn / CBCCRn / CRCCRn register-offset triple documented at HUM Ch 67.2.27 (p 4002-4011). Used by the runtime CSC programming path so the per-channel writes stay table-driven.

Parameters

[in]	channel	0 = Y (YCCRn), 1 = Cb (CBCCRn), 2 = Cr (CRCCRn).
[out]	off1	Setting 1 offset.
[out]	off2	Setting 2 offset.
[out]	off3	Setting 3 offset.

Precondition: channel <= k_ra8_vin_yc_chan_max.; All out-pointers are non-NULL.

Postcondition: off1/off2/off3 carry the corresponding ra8_vin_off_t values.; No VIN register has been read or written.

Note: Inline helper.

Since: 0.1.0

Definition at line 591 of file ra8_vin.c.

References k_ra8_vin_off_cbccr1, k_ra8_vin_off_cbccr2, k_ra8_vin_off_cbccr3, k_ra8_vin_off_crccr1, k_ra8_vin_off_crccr2, k_ra8_vin_off_crccr3, k_ra8_vin_off_yccr1, k_ra8_vin_off_yccr2, and k_ra8_vin_off_yccr3.

Referenced by ra8_vin_set_rgb_to_yc().

◆ ra8_vin_attach_frame_handler()

ra8_err_t ra8_vin_attach_frame_handler	(	ra8_vin_frame_fn_t	fn,
		void *	ctx )

nodiscard

Register the frame-end IRQ callback.

The driver's generic ra8_vin_dispatch fans every INTS bit through a single mask-style callback. This frame-end variant is invoked only when INTS.FIE is set after a ra8_vin_capture_start call, and receives the cached buffer + length.

Parameters

[in]	fn	Callback (NULL detaches).
[in]	ctx	Forwarded to the callback.

Returns: ra8_err_t

Return values

k_ra8_ok Always.

Precondition: Single-writer context (init or IRQ-masked).

Postcondition: Subsequent ra8_vin_dispatch calls fire fn on FIE.

Note: Not thread-safe.

See also: ra8_vin_dispatch

Since: 0.1.0

Definition at line 983 of file ra8_vin.c.

References k_ra8_ok, s_vin_frame_ctx, and s_vin_frame_fn.

◆ ra8_vin_attach_handler()

ra8_err_t ra8_vin_attach_handler	(	ra8_vin_event_fn_t	fn,
		void *	ctx )

nodiscard

Attach a VIN event callback (shared between status + error IRQs).

Parameters

[in]	fn	Callback invoked from ra8_vin_dispatch. May be NULL to detach.
[in]	ctx	Context value forwarded to the callback.

Returns: ra8_err_t

Return values

k_ra8_ok Always.

Precondition: Caller may not invoke this from within the callback.; Single-writer context (init or IRQ-masked).

Postcondition: Subsequent ra8_vin_dispatch calls invoke fn(ctx, ints).

Note: Not thread-safe; callback storage is plain static state.

See also: ra8_vin_dispatch

Since: 0.1.0

Definition at line 841 of file ra8_vin.c.

References k_ra8_ok, s_vin_ctx, and s_vin_fn.

◆ ra8_vin_capture_arm()

ra8_err_t ra8_vin_capture_arm ( ra8_vin_capture_mode_t mode )

nodiscard

Start a capture operation.

Implements the procedure from HUM Ch 67.3.1 "Initialization Procedure" p 3995:

Ensure ME = 0 and CC = 0 (precondition).
Pulse MC.ST = 1, then read MC back 10 times so the internal state machine settles for >= 10 ICLK cycles.
Set MC.ME = 1.
If continuous mode, set FC.CC = 1.

The MIPI CSI peripheral must be configured and started by the caller separately – VIN consumes data that arrives on the shared CSI->VIN data path.

Parameters

[in] mode Single-shot, continuous, or continuous-with-field- skip (ra8_vin_capture_mode_t).

Returns: ra8_err_t

Return values

k_ra8_ok	Capture armed and running.
k_ra8_err_invalid_state	ME or CC was already 1.
k_ra8_err_invalid_arg	Unknown mode value.

Precondition: ra8_vin_init has been called.; A valid frame buffer is programmed into MB1.

Postcondition: MC.ME = 1.; FC.CC reflects mode.

Note: Not thread-safe.

See also: ra8_vin_capture_stop

Since: 0.1.0

Definition at line 342 of file ra8_vin.c.

References internal_pulse_st(), k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_ok, k_ra8_vin_capture_continuous, k_ra8_vin_capture_continuous_field_skip, k_ra8_vin_capture_single, k_ra8_vin_fc_cc, k_ra8_vin_mc_me, k_ra8_vin_off_fc, k_ra8_vin_off_mc, ra8_log_info_val, ra8_vin_reg32(), and s_tag.

Referenced by ra8_vin_capture_start().

◆ ra8_vin_capture_disarm()

ra8_err_t ra8_vin_capture_disarm ( void )

nodiscard

Stop the current capture and drain outstanding AXI traffic.

Implements HUM Ch 67.3.6 "Stopping capture operation" p 4006:

Clear FC.CC so no new frames are queued.
Clear MC.ME.
Set MTCSTOP.STOPREQ to push outstanding writes to completion; the driver polls MTCSTOP.STOPACK / OUTSTAND a bounded number of times (k_ra8_vin_stop_drain_max) before returning k_ra8_err_hw_timeout.

Returns: ra8_err_t

Return values

k_ra8_ok	Stop sequence drained successfully.
k_ra8_err_invalid_state	ME was already 0 (nothing to stop).
k_ra8_err_hw_timeout	OUTSTAND did not reach 0 in time.

Precondition: ra8_vin_init has been called.; Capture is currently active (MC.ME = 1).

Postcondition: MC.ME and FC.CC are both 0.; MTCSTOP.STOPREQ is asserted, outstanding AXI writes drained.

Note: Not thread-safe.

See also: ra8_vin_capture_start

Since: 0.1.0

Definition at line 376 of file ra8_vin.c.

References k_ra8_err_invalid_state, k_ra8_vin_mc_me, k_ra8_vin_mtcstop_outstand, k_ra8_vin_mtcstop_req, k_ra8_vin_off_fc, k_ra8_vin_off_mc, k_ra8_vin_off_mtcstop, k_ra8_vin_stop_drain_max, ra8_hw_wait_flag_clear32(), ra8_log_info, ra8_vin_reg32(), and s_tag.

Referenced by ra8_vin_capture_stop().

◆ ra8_vin_capture_start()

ra8_err_t ra8_vin_capture_start	(	void *	buf,
		uint16_t	w,
		uint16_t	h,
		ra8_vin_input_fmt_t	format )

nodiscard

Start a single-frame capture into buf with the supplied geometry.

High-level wrapper around ra8_vin_capture_arm(k_ra8_vin_capture_single) that:

Programmes MB1 with (uint32_t)(uintptr_t)buf (HUM Ch 67.2.10 "MB1: Memory Base 1 Register" p 3985).
Sets the IS register (HUM Ch 67.2.13 "IS: Image Stride Register" p 3984) and pre-clip end coordinates to define the capture window.
Updates MC.INF (HUM Ch 67.2.1 "MC: Main Control Register" p 3975) so the input format matches.
Caches buf/w/h so the frame-end handler (registered via ra8_vin_attach_frame_handler) sees the right buffer + length.
Calls ra8_vin_capture_arm(k_ra8_vin_capture_single).

Parameters

[in]	buf	Capture target (must be 64-byte aligned).
[in]	w	Width in pixels (1..4096).
[in]	h	Height in lines (1..4096).
[in]	format	Input format (ra8_vin_input_fmt_t).

Returns: ra8_err_t

Return values

k_ra8_ok	Capture armed.
k_ra8_err_null_ptr	buf was NULL.
k_ra8_err_invalid_arg	w/h out of range or buf misaligned.
k_ra8_err_invalid_state	ME or CC was already 1.

Precondition: ra8_vin_init succeeded.; buf is 64-byte aligned.

Postcondition: MB1 == (uint32_t)(uintptr_t)buf.; MC.ME == 1.

Note: Not thread-safe.

See also: ra8_vin_capture_stop; ra8_vin_attach_frame_handler

Since: 0.1.0

Definition at line 933 of file ra8_vin.c.

References internal_format_bpp(), internal_mc_rmw(), k_ra8_err_invalid_arg, k_ra8_vin_capture_single, k_ra8_vin_geom_max_dim, k_ra8_vin_mb_align_mask, k_ra8_vin_mc_inf, k_ra8_vin_mc_shift_inf, k_ra8_vin_off_is, k_ra8_vin_off_mb1, RA8_CHECK_NULL_PTR, ra8_vin_capture_arm(), ra8_vin_reg32(), s_tag, s_vin_frame_buf, and s_vin_frame_len.

◆ ra8_vin_capture_stop()

ra8_err_t ra8_vin_capture_stop ( void )

nodiscard

Stop the in-flight capture started via ra8_vin_capture_start.

Wraps ra8_vin_capture_disarm – exists so the high-level start / stop pair share matching names.

Returns: ra8_err_t error code from ra8_vin_capture_disarm.

Precondition: ra8_vin_capture_start was previously called.

Postcondition: MC.ME and FC.CC are both 0.

Note: Not thread-safe.

See also: ra8_vin_capture_start

Since: 0.1.0

Definition at line 959 of file ra8_vin.c.

References ra8_vin_capture_disarm().

◆ ra8_vin_clear_status()

ra8_err_t ra8_vin_clear_status ( uint32_t mask )

nodiscard

Clear write-1-to-clear bits in the INTS register.

Only the bits in mask that intersect k_ra8_vin_int_w1c_mask are written back; all other bits are gated off so a careless caller cannot toggle status bits the hardware owns.

Parameters

[in] mask Bits to clear (subset of ra8_vin_int_mask_t).

Returns: ra8_err_t

Return values

k_ra8_ok Always.

Precondition: Driver is in any post-init state.

Postcondition: Bits in mask & k_ra8_vin_int_w1c_mask read as 0 next access.

Note: Re-entrant; single masked register write.

See also: ra8_vin_get_status

Since: 0.1.0

Definition at line 783 of file ra8_vin.c.

References k_ra8_ok, k_ra8_vin_int_w1c_mask, k_ra8_vin_off_ints, and ra8_vin_reg32().

◆ ra8_vin_deinit()

ra8_err_t ra8_vin_deinit ( void )

nodiscard

Tear down VIN: stop capture, mask interrupts, drop MSTP.

Returns: ra8_err_t

Return values

k_ra8_ok Always.

Precondition: Driver has been initialized (otherwise this is a no-op write).

Postcondition: MC.ME and FC.CC are 0.; Registered callback (if any) is cleared.

Note: Not thread-safe.

See also: ra8_vin_init

Since: 0.1.0

Definition at line 308 of file ra8_vin.c.

References k_ra8_mstp_mipi_csi, k_ra8_vin_int_w1c_mask, k_ra8_vin_off_fc, k_ra8_vin_off_ie, k_ra8_vin_off_ints, k_ra8_vin_off_mc, ra8_mstp_disable(), ra8_vin_reg32(), s_vin_ctx, s_vin_fn, s_vin_frame_buf, s_vin_frame_ctx, s_vin_frame_fn, and s_vin_frame_len.

◆ ra8_vin_dispatch()

void ra8_vin_dispatch ( void )

Snapshot INTS, fire callback, then W1C the latched bits.

Intended to be called from the VIN status / error ISR. Reads the current INTS value, hands it to the registered callback (if any), and writes back the W1C subset to acknowledge the event with the hardware.

Precondition: Called from a single CPU context.; ra8_vin_init was successful.

Postcondition: W1C bits in INTS read as 0 after this returns.; Callback (if any) has run exactly once with the snapshot.

Note: Re-entrant only across distinct VIN instances (there is one). See HUM Ch 47 "Video Input Module (VIN)" pp 2455-2540.

See also: ra8_vin_attach_handler

Since: 0.1.0

Definition at line 849 of file ra8_vin.c.

References k_ra8_vin_int_fme, k_ra8_vin_int_w1c_mask, k_ra8_vin_off_ints, ra8_vin_reg32(), s_vin_ctx, s_vin_fn, s_vin_frame_buf, s_vin_frame_ctx, s_vin_frame_fn, and s_vin_frame_len.

◆ ra8_vin_enable_scaling()

ra8_err_t ra8_vin_enable_scaling ( bool enable )

nodiscard

Toggle the MC.SCLE main scaling-enable bit.

Parameters

[in] enable True -> SCLE = 1, false -> SCLE = 0.

Returns: ra8_err_t

Return values

k_ra8_ok Always.

Precondition: Driver initialized.; Capture not running (caller stops first if needed).

Postcondition: MC.SCLE matches enable.

Note: Not thread-safe.

See also: ra8_vin_set_uds_scale

Since: 0.1.0

Definition at line 499 of file ra8_vin.c.

References internal_mc_rmw(), k_ra8_ok, and k_ra8_vin_mc_scle.

◆ ra8_vin_enter_stop()

ra8_err_t ra8_vin_enter_stop ( void )

nodiscard

Quiesce VIN and disable its module-stop clock gate.

Stops capture (MC.ME = 0) and disables the MIPI CSI MSTP bit. Note that this also gates the MIPI CSI receiver since the two peripherals share k_ra8_mstp_mipi_csi.

Returns: ra8_err_t error code from ra8_mstp_disable.

Precondition: Caller has stopped any in-flight CSI traffic.; Driver was previously initialized.

Postcondition: MC.ME = 0.; MIPI CSI MSTP gate is closed.

Note: Not thread-safe.

See also: ra8_vin_exit_stop

Since: 0.1.0

Definition at line 876 of file ra8_vin.c.

References k_ra8_mstp_mipi_csi, k_ra8_vin_mc_me, k_ra8_vin_off_fc, k_ra8_vin_off_mc, ra8_mstp_disable(), and ra8_vin_reg32().

◆ ra8_vin_exit_stop()

ra8_err_t ra8_vin_exit_stop ( void )

nodiscard

Re-enable the VIN clock gate after ra8_vin_enter_stop.

Returns: ra8_err_t error code from ra8_mstp_enable.

Precondition: ra8_vin_enter_stop was called.; Caller will re-issue ra8_vin_capture_start afterwards.

Postcondition: MIPI CSI MSTP gate is open.; VIN registers are accessible again.

Note: Not thread-safe.

See also: ra8_vin_enter_stop

Since: 0.1.0

Definition at line 888 of file ra8_vin.c.

References k_ra8_mstp_mipi_csi, and ra8_mstp_enable().

◆ ra8_vin_get_active_buffer()

ra8_err_t ra8_vin_get_active_buffer ( uint8_t * out_id )

nodiscard

Return the active framebuffer index from MS.FBS.

Parameters

[out] out_id Non-NULL destination (ra8_vin_ms_fbs_t).

Returns: ra8_err_t

Return values

k_ra8_ok	Read OK.
k_ra8_err_null_ptr	out_id was NULL.

Precondition: out_id != NULL.; Driver in any post-init state.

Postcondition: *out_id carries 0..3.

Note: Re-entrant.

See also: ra8_vin_get_module_status

Since: 0.1.0

Definition at line 815 of file ra8_vin.c.

References k_ra8_ok, k_ra8_vin_ms_fbs, k_ra8_vin_ms_shift_fbs, k_ra8_vin_off_ms, RA8_CHECK_NULL_PTR, ra8_vin_reg32(), and s_tag.

◆ ra8_vin_get_line_count()

ra8_err_t ra8_vin_get_line_count ( uint16_t * out_count )

nodiscard

Read the LC (line count) register.

Parameters

[out] out_count Non-NULL destination.

Returns: ra8_err_t

Return values

k_ra8_ok	Read OK.
k_ra8_err_null_ptr	out_count was NULL.

Precondition: out_count != NULL.; Driver in any post-init state.

Postcondition: *out_count carries 0..4095.

Note: Re-entrant.

See also: ra8_vin_get_module_status

Since: 0.1.0

Definition at line 807 of file ra8_vin.c.

References k_ra8_ok, k_ra8_vin_lc_mask, k_ra8_vin_off_lc, RA8_CHECK_NULL_PTR, ra8_vin_reg32(), and s_tag.

◆ ra8_vin_get_module_status()

ra8_err_t ra8_vin_get_module_status ( ra8_vin_module_status_t * out_status )

nodiscard

Decode the MS register into a typed snapshot.

Parameters

[out] out_status Non-NULL destination.

Returns: ra8_err_t

Return values

k_ra8_ok	Snapshot taken.
k_ra8_err_null_ptr	out_status was NULL.

Precondition: out_status != NULL.; Driver in any post-init state.

Postcondition: *out_status decoded.

Note: Re-entrant.

See also: ra8_vin_get_active_buffer

Since: 0.1.0

Definition at line 793 of file ra8_vin.c.

References ra8_vin_module_status_t::active_video, ra8_vin_module_status_t::capture_active, ra8_vin_module_status_t::even_field, ra8_vin_module_status_t::frame_buffer_id, k_ra8_ok, k_ra8_vin_ms_av, k_ra8_vin_ms_ca, k_ra8_vin_ms_fbs, k_ra8_vin_ms_fms, k_ra8_vin_ms_fs, k_ra8_vin_ms_ma, k_ra8_vin_ms_shift_fbs, k_ra8_vin_ms_shift_fms, k_ra8_vin_off_ms, ra8_vin_module_status_t::latest_frame_buffer, ra8_vin_module_status_t::memory_active, RA8_CHECK_NULL_PTR, ra8_vin_reg32(), and s_tag.

◆ ra8_vin_get_status()

ra8_err_t ra8_vin_get_status ( uint32_t * out_mask )

nodiscard

Snapshot the INTS register.

Parameters

[out] out_mask Receives the current INTS value.

Returns: ra8_err_t

Return values

k_ra8_ok	Snapshot taken.
k_ra8_err_null_ptr	out_mask was NULL.

Precondition: out_mask != NULL.; Driver is in any post-init state.

Postcondition: *out_mask contains the value of INTS.

Note: Re-entrant; just a register read.

See also: ra8_vin_clear_status

Since: 0.1.0

Definition at line 775 of file ra8_vin.c.

References k_ra8_ok, k_ra8_vin_off_ints, RA8_CHECK_NULL_PTR, ra8_vin_reg32(), and s_tag.

◆ ra8_vin_init()

ra8_err_t ra8_vin_init ( const ra8_vin_config_t * cfg )

nodiscard

Initialise VIN with the supplied descriptor.

Brings the MIPI CSI clock gate up via the MIPI-CSI MSTP bit (VIN does not have its own MSTPCR bit on the RA8D2; the peripheral's clocks are released as a side-effect of enabling MIPI CSI – see HUM Ch 11.2.8 "MSTPCRC" and section 67.1 "Block Diagram"). The function then writes a clean MC value (ME = 0), programmes IS / MB1..3 / IE / SI / MC.IM / MC.CLP, and clears all latched INTS bits.

Pre-clip, scaling, LUT, and colour-space coefficients are left at their reset defaults. Use the dedicated setters to programme them before ra8_vin_capture_start.

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

Return values

k_ra8_ok	Success.
k_ra8_err_null_ptr	cfg was NULL.
k_ra8_err_invalid_arg	cfg.image_stride_px was 0 or cfg.interlace_mode / pixel_clip_mode out of range.
k_ra8_err_hw_init_failed	MSTP enable failed.

Precondition: IRQs masked or single-threaded init context.; cfg->framebuffer_addr_1 is 64-byte aligned.

Postcondition: MC reflects cfg, ME bit is cleared.; INTS is fully cleared.

Note: Not thread-safe.

See also: ra8_vin_capture_start; ra8_vin_deinit

Since: 0.1.0

Definition at line 260 of file ra8_vin.c.

References ra8_vin_config_t::framebuffer_addr_1, ra8_vin_config_t::framebuffer_addr_2, ra8_vin_config_t::framebuffer_addr_3, ra8_vin_config_t::image_stride_px, ra8_vin_config_t::interlace_mode, internal_compose_mc(), ra8_vin_config_t::interrupt_enable, k_ra8_err_invalid_arg, k_ra8_mstp_mipi_csi, k_ra8_ok, k_ra8_vin_int_w1c_mask, k_ra8_vin_max_clp, k_ra8_vin_max_im, k_ra8_vin_off_fc, k_ra8_vin_off_ie, k_ra8_vin_off_ints, k_ra8_vin_off_is, k_ra8_vin_off_mb1, k_ra8_vin_off_mb2, k_ra8_vin_off_mb3, k_ra8_vin_off_mc, k_ra8_vin_off_si, ra8_vin_config_t::pixel_clip_mode, RA8_CHECK_NULL_PTR, ra8_log_info_val, ra8_mstp_enable(), RA8_RETURN_ON_ERROR, ra8_vin_reg32(), s_tag, and ra8_vin_config_t::scanline_compare.

◆ ra8_vin_lut_program()

ra8_err_t ra8_vin_lut_program	(	const uint8_t *	y_table,
		const uint8_t *	cb_table,
		const uint8_t *	cr_table,
		bool	enable )

nodiscard

Programme all 256 entries of the Y / Cb / Cr conversion LUT.

HUM Ch 67.2.25 / 67.2.26 p 4000-4001. Each LUT byte is written by:

Setting LUTP to the 10-bit (Y, Cb, Cr) pointer triple.
Writing LUTD with the (Y, Cb, Cr) byte triple.

The driver loops 256 iterations, advancing all three pointers in lock-step. Pass NULL for cb or cr to reuse y for that channel; passing NULL for y returns k_ra8_err_null_ptr.

enable then drives MC.LUTE so the hardware actually consumes the table on the next frame.

Parameters

[in]	y_table	Pointer to 256 8-bit Y values (must be non-NULL).
[in]	cb_table	Pointer to 256 8-bit Cb values (NULL -> use Y).
[in]	cr_table	Pointer to 256 8-bit Cr values (NULL -> use Y).
[in]	enable	Drive MC.LUTE after programming.

Returns: ra8_err_t

Return values

k_ra8_ok	LUT programmed.
k_ra8_err_null_ptr	y_table was NULL.

Precondition: Driver initialized.; Capture not running.

Postcondition: All 256 LUT entries reflect the supplied tables.; MC.LUTE matches enable.

Note: Not thread-safe; writes 256 LUTP/LUTD pairs.

See also: ra8_vin_init

Since: 0.1.0

Definition at line 509 of file ra8_vin.c.

References internal_mc_rmw(), k_ra8_ok, k_ra8_vin_lut_entries, k_ra8_vin_lutd_ltcbdt, k_ra8_vin_lutd_ltcrdt, k_ra8_vin_lutd_ltydt, k_ra8_vin_lutd_shift_ltcbdt, k_ra8_vin_lutd_shift_ltcrdt, k_ra8_vin_lutd_shift_ltydt, k_ra8_vin_lutp_ltcbpr, k_ra8_vin_lutp_ltcrpr, k_ra8_vin_lutp_ltypr, k_ra8_vin_lutp_shift_ltcbpr, k_ra8_vin_lutp_shift_ltcrpr, k_ra8_vin_lutp_shift_ltypr, k_ra8_vin_mc_lute, k_ra8_vin_off_lutd, k_ra8_vin_off_lutp, RA8_CHECK_NULL_PTR, ra8_vin_reg32(), and s_tag.

◆ ra8_vin_reset()

ra8_err_t ra8_vin_reset ( void )

nodiscard

Issue a soft reset by re-running the MC.ST settle sequence.

HUM Ch 67.3.1 p 3995 – writes ME = 0, pulses MC.ST = 1, then absorbs the >= 10 ICLK settling time by reading MC back the configured number of times (k_ra8_vin_st_settle_reads).

Returns: ra8_err_t

Return values

k_ra8_ok Always.

Precondition: ra8_vin_init succeeded.; Caller has masked IRQs.

Postcondition: MC.ME = 0.; Internal pipeline state is back to its post-startup defaults.

Note: Not thread-safe.

See also: ra8_vin_capture_start

Since: 0.1.0

Definition at line 330 of file ra8_vin.c.

References internal_pulse_st(), k_ra8_ok, k_ra8_vin_mc_me, k_ra8_vin_off_mc, ra8_log_info, ra8_vin_reg32(), and s_tag.

◆ ra8_vin_set_csi_input()

ra8_err_t ra8_vin_set_csi_input ( const ra8_vin_csi_input_t * input )

nodiscard

Programme CSI_IFMD (virtual channel + data type + extension).

Parameters

[in] input Non-NULL CSI input descriptor.

Returns: ra8_err_t

Return values

k_ra8_ok	Programmed.
k_ra8_err_null_ptr	input was NULL.
k_ra8_err_invalid_arg	virtual_channel > 15 or data_type > 0x3F.

Precondition: Driver initialized, capture not running.; input != NULL.

Postcondition: CSI_IFMD reflects input.

Note: Not thread-safe.

See also: ra8_vin_set_field_detect

Since: 0.1.0

Definition at line 703 of file ra8_vin.c.

References ra8_vin_csi_input_t::data_type, k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_vin_csi_ifmd_des0, k_ra8_vin_csi_ifmd_dt, k_ra8_vin_csi_ifmd_shift_dt, k_ra8_vin_csi_ifmd_shift_vc_sel, k_ra8_vin_csi_ifmd_vc_sel, k_ra8_vin_max_dt, k_ra8_vin_max_vc_sel, k_ra8_vin_off_csi_ifmd, RA8_CHECK_NULL_PTR, ra8_vin_reg32(), s_tag, ra8_vin_csi_input_t::virtual_channel, and ra8_vin_csi_input_t::zero_extend.

◆ ra8_vin_set_data_mode()

ra8_err_t ra8_vin_set_data_mode ( const ra8_vin_data_mode_t * mode )

nodiscard

Programme the DMR (Data Mode Register).

HUM Ch 67.2.19 p 3992. Composes DTMD / ABIT / BPSM / EXRGB / YC_THR / YMODE / A8BIT into a single 32-bit write.

Parameters

[in] mode Non-NULL DMR descriptor.

Returns: ra8_err_t

Return values

k_ra8_ok	Programmed.
k_ra8_err_null_ptr	mode was NULL.
k_ra8_err_invalid_arg	conv_mode > 2 or y_mode > 3.

Precondition: Driver initialized, capture not running.; mode != NULL.

Postcondition: DMR reflects mode.

Note: Not thread-safe.

See also: ra8_vin_set_uv_offset

Since: 0.1.0

Definition at line 677 of file ra8_vin.c.

References ra8_vin_data_mode_t::alpha_bit, ra8_vin_data_mode_t::alpha_byte, ra8_vin_data_mode_t::byte_swap, ra8_vin_data_mode_t::conv_mode, ra8_vin_data_mode_t::extend_rgb, k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_vin_dmr_a8bit, k_ra8_vin_dmr_abit, k_ra8_vin_dmr_bpsm, k_ra8_vin_dmr_dtmd, k_ra8_vin_dmr_exrgb, k_ra8_vin_dmr_shift_a8bit, k_ra8_vin_dmr_shift_dtmd, k_ra8_vin_dmr_shift_ymode, k_ra8_vin_dmr_yc_thr, k_ra8_vin_dmr_ymode, k_ra8_vin_max_dtmd, k_ra8_vin_max_ymode, k_ra8_vin_off_dmr, RA8_CHECK_NULL_PTR, ra8_vin_reg32(), s_tag, ra8_vin_data_mode_t::y_mode, and ra8_vin_data_mode_t::yc_through.

◆ ra8_vin_set_dithering()

ra8_err_t ra8_vin_set_dithering	(	uint8_t	mode,
		bool	direction )

nodiscard

Configure the dithering mode (MC.DC + MC.DC2).

HUM Ch 67.2.1 p 3975. The DC field picks one of three patterns (ra8_vin_dc_value_t); the DC2 bit reverses the direction of the ordered patterns. Caller is responsible for keeping the input pixel depth large enough for dithering to be meaningful.

Parameters

[in]	mode	Dither pattern (ra8_vin_dc_value_t).
[in]	direction	True -> DC2 = 1, false -> DC2 = 0.

Returns: ra8_err_t

Return values

k_ra8_ok	Programmed.
k_ra8_err_invalid_arg	mode > 2.

Precondition: Driver initialized, capture not running.; Mode value is one of k_ra8_vin_dc_*.

Postcondition: MC.DC and MC.DC2 reflect the new values.

Note: Not thread-safe.

See also: ra8_vin_set_yuv444_mode

Since: 0.1.0

Definition at line 641 of file ra8_vin.c.

References internal_mc_rmw(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_vin_max_dc, k_ra8_vin_mc_dc, k_ra8_vin_mc_dc2, and k_ra8_vin_mc_shift_dc.

◆ ra8_vin_set_field_detect()

ra8_err_t ra8_vin_set_field_detect ( const ra8_vin_field_detect_t * detect )

nodiscard

Programme CSIFLD (field detection).

Parameters

[in] detect Non-NULL field-detect descriptor.

Returns: ra8_err_t

Return values

k_ra8_ok	Programmed.
k_ra8_err_null_ptr	detect was NULL.
k_ra8_err_invalid_arg	even_field_num > 1.

Precondition: Driver initialized.; detect != NULL.

Postcondition: CSIFLD reflects detect.

Note: Not thread-safe.

See also: ra8_vin_set_csi_input

Since: 0.1.0

Definition at line 720 of file ra8_vin.c.

References ra8_vin_field_detect_t::enable, ra8_vin_field_detect_t::even_field_num, ra8_vin_field_detect_t::even_field_sel, k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_vin_csifld_fld_en, k_ra8_vin_csifld_fld_num, k_ra8_vin_csifld_fld_sel, k_ra8_vin_max_field_no, k_ra8_vin_off_csifld, RA8_CHECK_NULL_PTR, ra8_vin_reg32(), and s_tag.

◆ ra8_vin_set_framebuffers()

ra8_err_t ra8_vin_set_framebuffers	(	uint32_t	mb1,
		uint32_t	mb2,
		uint32_t	mb3 )

nodiscard

Re-programme MB1 / MB2 / MB3 (ping-pong framebuffers).

HUM Ch 67.2.10..67.2.12 p 3985-3987. Lower 7 address bits are forced to zero (64-byte alignment); the function rejects unaligned inputs with k_ra8_err_invalid_arg.

Parameters

[in]	mb1	New MB1 base; ignored if zero.
[in]	mb2	New MB2 base; ignored if zero.
[in]	mb3	New MB3 base; ignored if zero.

Returns: ra8_err_t

Return values

k_ra8_ok	Programmed.
k_ra8_err_invalid_arg	Any non-zero base unaligned.

Precondition: Driver initialized.; At least one of mb1/mb2/mb3 is non-zero.

Postcondition: Specified MBn registers reflect the new bases.

Note: Not thread-safe; safe to call mid-capture per HUM Ch 67.3.4 p 4005 ("Switching the buffer during operation").

See also: ra8_vin_get_active_buffer

Since: 0.1.0

Definition at line 741 of file ra8_vin.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_vin_mb_align_mask, k_ra8_vin_off_mb1, k_ra8_vin_off_mb2, k_ra8_vin_off_mb3, and ra8_vin_reg32().

◆ ra8_vin_set_interlace_mode()

ra8_err_t ra8_vin_set_interlace_mode ( uint8_t mode )

nodiscard

Set the interlace mode (MC.IM).

Parameters

[in] mode ra8_vin_im_value_t.

Returns: ra8_err_t

Return values

k_ra8_ok	Programmed.
k_ra8_err_invalid_arg	mode > 2.

Precondition: Driver initialized, capture not running.; Mode is one of k_ra8_vin_im_*.

Postcondition: MC.IM reflects mode.

Note: Not thread-safe.

See also: ra8_vin_capture_start

Since: 0.1.0

Definition at line 667 of file ra8_vin.c.

References internal_mc_rmw(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_vin_max_im, k_ra8_vin_mc_im, and k_ra8_vin_mc_shift_im.

◆ ra8_vin_set_interrupt_enable()

ra8_err_t ra8_vin_set_interrupt_enable ( uint32_t mask )

nodiscard

Update the IE (Interrupt Enable) mask at runtime.

Parameters

[in] mask Bitwise OR of ra8_vin_int_mask_t values.

Returns: ra8_err_t

Return values

k_ra8_ok Always.

Precondition: Driver initialized.; Caller has masked the VIN IRQ if updating mid-capture.

Postcondition: IE register equals mask.

Note: Not thread-safe.

See also: ra8_vin_set_scanline_compare

Since: 0.1.0

Definition at line 824 of file ra8_vin.c.

References k_ra8_ok, k_ra8_vin_off_ie, and ra8_vin_reg32().

◆ ra8_vin_set_preclip()

ra8_err_t ra8_vin_set_preclip ( const ra8_vin_preclip_t * window )

nodiscard

Programme the pre-clip window (SLPRC / ELPRC / SPPRC / EPPRC).

HUM Ch 67.2.4..67.2.7 p 3980-3981. Defines the rectangle of the input image that survives the pre-clip stage. End values must be >= start values; both sides are clamped to 12 bits (4095 max).

Parameters

[in] window Non-NULL pre-clip descriptor.

Returns: ra8_err_t

Return values

k_ra8_ok	Window programmed.
k_ra8_err_null_ptr	window was NULL.
k_ra8_err_invalid_arg	end < start or value > 4095.

Precondition: Driver initialized, capture not running.; window != NULL.

Postcondition: SLPRC/ELPRC/SPPRC/EPPRC reflect window.; Pre-clip-violation IRQs (PRCLIPH/PRCLIPV) become meaningful.

Note: Not thread-safe.

See also: ra8_vin_set_uds_clip

Since: 0.1.0

Definition at line 407 of file ra8_vin.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_vin_off_elprc, k_ra8_vin_off_epprc, k_ra8_vin_off_slprc, k_ra8_vin_off_spprc, k_ra8_vin_preclip_mask, ra8_vin_preclip_t::line_end, ra8_vin_preclip_t::line_start, ra8_vin_preclip_t::pixel_end, ra8_vin_preclip_t::pixel_start, RA8_CHECK_NULL_PTR, ra8_vin_reg32(), and s_tag.

Referenced by ra8_vin_set_window().

◆ ra8_vin_set_rgb_to_yc()

ra8_err_t ra8_vin_set_rgb_to_yc	(	uint8_t	channel,
		const ra8_vin_rgb_to_yc_chan_t *	row )

nodiscard

Programme one row of the RGB -> YC matrix.

HUM Ch 67.2.27..67.2.35 p 4002-4011. The three rows correspond to Y (channel 0), Cb (channel 1), and Cr (channel 2). Each row writes three registers: setting 1 (R), setting 2 (G+B), setting 3 (LAP + LHEN + LSFT).

Parameters

[in]	channel	Row index 0 (Y), 1 (Cb), 2 (Cr).
[in]	row	Non-NULL coefficient descriptor.

Returns: ra8_err_t

Return values

k_ra8_ok	Row written.
k_ra8_err_null_ptr	row was NULL.
k_ra8_err_invalid_arg	channel > 2 or shift_down > 31.

Precondition: Driver initialized, capture not running.; row != NULL and channel < 3.

Postcondition: YCCRn / CBCCRn / CRCCRn reflect row.

Note: Not thread-safe.

See also: ra8_vin_set_yc_to_rgb

Since: 0.1.0

Definition at line 609 of file ra8_vin.c.

References ra8_vin_rgb_to_yc_chan_t::add_offset, ra8_vin_rgb_to_yc_chan_t::b_coeff, ra8_vin_rgb_to_yc_chan_t::enable_hen, ra8_vin_rgb_to_yc_chan_t::g_coeff, internal_yc_offsets(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_vin_max_lsft, k_ra8_vin_off_yccr1, k_ra8_vin_off_yccr2, k_ra8_vin_off_yccr3, k_ra8_vin_yc1_rp, k_ra8_vin_yc2_bp, k_ra8_vin_yc2_gp, k_ra8_vin_yc3_ap, k_ra8_vin_yc3_hen, k_ra8_vin_yc3_sft, k_ra8_vin_yc_chan_max, k_ra8_vin_yccr_shift_bp, k_ra8_vin_yccr_shift_sft, ra8_vin_rgb_to_yc_chan_t::r_coeff, RA8_CHECK_NULL_PTR, ra8_vin_reg32(), s_tag, and ra8_vin_rgb_to_yc_chan_t::shift_down.

◆ ra8_vin_set_scanline_compare()

ra8_err_t ra8_vin_set_scanline_compare ( uint16_t line )

nodiscard

Programme the SI (Scanline Interrupt) compare register.

Parameters

[in] line 12-bit compare value, 0 disables.

Returns: ra8_err_t

Return values

k_ra8_ok	Programmed.
k_ra8_err_invalid_arg	line > 4095.

Precondition: Driver initialized.; line <= 4095.

Postcondition: SI register equals line.

Note: Not thread-safe.

See also: ra8_vin_set_interrupt_enable

Since: 0.1.0

Definition at line 831 of file ra8_vin.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_vin_off_si, k_ra8_vin_si_mask, and ra8_vin_reg32().

◆ ra8_vin_set_uds_clip()

ra8_err_t ra8_vin_set_uds_clip	(	uint16_t	v_size,
		uint16_t	h_size )

nodiscard

Programme the UDS output clipping (UDS_CLIP_SIZE).

HUM Ch 67.2.24 p 3999. 12-bit output clipping size for V and H after scaling.

Parameters

[in]	v_size	Vertical pixel count (0..4095).
[in]	h_size	Horizontal pixel count (0..4095).

Returns: ra8_err_t

Return values

k_ra8_ok	Programmed.
k_ra8_err_invalid_arg	Value > 4095.

Precondition: Driver initialized.; Both sizes <= 4095.

Postcondition: UDS_CLIP_SIZE reflects the new values.

Note: Not thread-safe.

See also: ra8_vin_set_uds_scale

Since: 0.1.0

Definition at line 460 of file ra8_vin.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_vin_off_uds_clip_size, k_ra8_vin_uds_clip_h, k_ra8_vin_uds_clip_shift_h, k_ra8_vin_uds_clip_shift_v, k_ra8_vin_uds_clip_v, k_ra8_vin_uds_max_clip, and ra8_vin_reg32().

◆ ra8_vin_set_uds_ctrl()

ra8_err_t ra8_vin_set_uds_ctrl ( const ra8_vin_uds_ctrl_t * ctrl )

nodiscard

Programme UDS interpolation control (UDS_CTRL).

HUM Ch 67.2.21 p 3996. Picks bilinear vs nearest-neighbour per channel, plus the multi-tap mode flag and two advanced-mode tweaks. ra8_vin_enable_scaling toggles the MC.SCLE main enable.

Parameters

[in] ctrl Non-NULL UDS control descriptor.

Returns: ra8_err_t

Return values

k_ra8_ok	Programmed.
k_ra8_err_null_ptr	ctrl was NULL.

Precondition: Driver initialized.; ctrl != NULL.

Postcondition: UDS_CTRL reflects ctrl.

Note: Not thread-safe.

See also: ra8_vin_set_uds_scale

Since: 0.1.0

Definition at line 472 of file ra8_vin.c.

References ra8_vin_uds_ctrl_t::advanced_amd, ra8_vin_uds_ctrl_t::advanced_bl, ra8_vin_uds_ctrl_t::b_cb_nearest, ra8_vin_uds_ctrl_t::g_y_nearest, k_ra8_ok, k_ra8_vin_off_uds_ctrl, k_ra8_vin_uds_ctrl_amd, k_ra8_vin_uds_ctrl_bc, k_ra8_vin_uds_ctrl_bladv, k_ra8_vin_uds_ctrl_ne_bcb, k_ra8_vin_uds_ctrl_ne_gy, k_ra8_vin_uds_ctrl_ne_rcr, ra8_vin_uds_ctrl_t::multitap, ra8_vin_uds_ctrl_t::r_cr_nearest, RA8_CHECK_NULL_PTR, ra8_vin_reg32(), and s_tag.

◆ ra8_vin_set_uds_passband()

ra8_err_t ra8_vin_set_uds_passband	(	uint8_t	v_bwidth,
		uint8_t	h_bwidth )

nodiscard

Programme the UDS pass-band bandwidth (UDS_PASS_BWIDTH).

HUM Ch 67.2.23 p 3998. 7-bit V and H pass-band bandwidth values applied by the multi-tap filter.

Parameters

[in]	v_bwidth	Vertical bandwidth (0..127).
[in]	h_bwidth	Horizontal bandwidth (0..127).

Returns: ra8_err_t

Return values

k_ra8_ok	Programmed.
k_ra8_err_invalid_arg	Value > 127.

Precondition: Driver initialized.; v_bwidth + h_bwidth in legal 7-bit range.

Postcondition: UDS_PASS_BWIDTH reflects the new values.

Note: Not thread-safe.

See also: ra8_vin_set_uds_scale

Since: 0.1.0

Definition at line 448 of file ra8_vin.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_vin_off_uds_pass_bwidth, k_ra8_vin_uds_bwidth_h, k_ra8_vin_uds_bwidth_shift_h, k_ra8_vin_uds_bwidth_shift_v, k_ra8_vin_uds_bwidth_v, k_ra8_vin_uds_max_bw, and ra8_vin_reg32().

◆ ra8_vin_set_uds_scale()

ra8_err_t ra8_vin_set_uds_scale ( const ra8_vin_uds_scale_t * scale )

nodiscard

Programme the UDS scaling factor (UDS_SCALE).

HUM Ch 67.2.22 p 3997. Set the integer mantissa and 12-bit fraction for both axes; the driver enables MC.SCLE only via ra8_vin_set_uds_ctrl(....multitap = ?,...) plus ra8_vin_enable_scaling(true). UDS_SCALE itself is loaded by ra8_vin_capture_start matching HUM Ch 67.3.5 p 4006.

Parameters

[in] scale Non-NULL scaling factor descriptor.

Returns: ra8_err_t

Return values

k_ra8_ok	Scale programmed.
k_ra8_err_null_ptr	scale was NULL.
k_ra8_err_invalid_arg	Mantissa > 15 or fraction > 4095.

Precondition: Driver initialized.; scale != NULL.

Postcondition: UDS_SCALE reflects scale.

Note: Not thread-safe.

See also: ra8_vin_set_uds_passband; ra8_vin_set_uds_clip

Since: 0.1.0

Definition at line 429 of file ra8_vin.c.

◆ ra8_vin_set_uv_offset()

ra8_err_t ra8_vin_set_uv_offset ( uint32_t uv_addr )

nodiscard

Programme UVAOF (UV plane address offset for YC-separated mode).

Parameters

[in] uv_addr 64-byte-aligned UV plane base; 0 disables.

Returns: ra8_err_t

Return values

k_ra8_ok	Programmed.
k_ra8_err_invalid_arg	Address not 64-byte aligned.

Precondition: Driver initialized.; uv_addr is either zero or 64-byte aligned.

Postcondition: UVAOF reflects uv_addr.

Note: Not thread-safe.

See also: ra8_vin_set_data_mode

Since: 0.1.0

Definition at line 765 of file ra8_vin.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_vin_mb_align_mask, k_ra8_vin_off_uvaof, and ra8_vin_reg32().

◆ ra8_vin_set_window()

ra8_err_t ra8_vin_set_window	(	uint16_t	x,
		uint16_t	y,
		uint16_t	w,
		uint16_t	h )

nodiscard

Programme a region-of-interest pre-clip window.

Wraps ra8_vin_set_preclip with a (x, y, w, h) signature for callers that prefer (x, y) over (start_line, start_pixel). HUM Ch 67.2.4.. 67.2.7 p 3980-3981.

Parameters

[in]	x	Top-left pixel index (0..4095).
[in]	y	Top-left line index (0..4095).
[in]	w	Window width in pixels (>=1).
[in]	h	Window height in lines (>=1).

Returns: ra8_err_t

Return values

k_ra8_ok	Window programmed.
k_ra8_err_invalid_arg	Arguments out of range.

Precondition: Driver initialized, capture not running.; w >= 1, h >= 1, x + w - 1 <= 4095, y + h - 1 <= 4095.

Postcondition: SLPRC/ELPRC/SPPRC/EPPRC reflect the requested window.

Note: Not thread-safe.

See also: ra8_vin_set_preclip

Since: 0.1.0

Definition at line 964 of file ra8_vin.c.

References k_ra8_err_invalid_arg, k_ra8_vin_preclip_mask, and ra8_vin_set_preclip().

◆ ra8_vin_set_yc_to_rgb()

ra8_err_t ra8_vin_set_yc_to_rgb ( const ra8_vin_yc_to_rgb_t * coeffs )

nodiscard

Programme the YC -> RGB matrix coefficients (CSCE1..4).

HUM Ch 67.2.36..67.2.39 p 4011-4015. Loads the 14-bit Y multiplier, the 12-bit Y / CbCr subtraction terms, and the 14-bit Cr/Cb multiplier pairs.

Parameters

[in] coeffs Non-NULL coefficient descriptor.

Returns: ra8_err_t

Return values

k_ra8_ok	Coefficients written.
k_ra8_err_null_ptr	coeffs was NULL.

Precondition: Driver initialized, capture not running.; coeffs != NULL.

Postcondition: CSCE1..4 reflect coeffs.

Note: Not thread-safe.

See also: ra8_vin_set_rgb_to_yc

Since: 0.1.0

Definition at line 540 of file ra8_vin.c.

◆ ra8_vin_set_yuv444_mode()

ra8_err_t ra8_vin_set_yuv444_mode ( uint8_t mode )

nodiscard

Configure the YUV-444 conversion mode (MC.YUV444).

HUM Ch 67.2.1 p 3975. Picks data-extend vs interpolate when promoting 4:2:2 input to 4:4:4 internally.

Parameters

[in] mode ra8_vin_yuv444_value_t.

Returns: ra8_err_t

Return values

k_ra8_ok	Programmed.
k_ra8_err_invalid_arg	mode > 1.

Precondition: Driver initialized, capture not running.; Mode is one of k_ra8_vin_yuv444_*.

Postcondition: MC.YUV444 matches mode.

Note: Not thread-safe.

See also: ra8_vin_set_dithering

Since: 0.1.0

Definition at line 657 of file ra8_vin.c.

References internal_mc_rmw(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_vin_max_yuv444, and k_ra8_vin_mc_yuv444.

Variable Documentation

◆ s_tag

const char* s_tag = "VIN"

static

Logging tag used by every log call in this TU.

Static storage so it cannot be modified from outside this file. Matches the convention from ra8_glcdc.c and ra8_acmphs.c.

Note: Read-only after init; safe from any context.

Since: 0.1.0

Definition at line 57 of file ra8_vin.c.

◆ s_vin_ctx

void* s_vin_ctx

static

Context value forwarded to s_vin_fn.

Opaque pointer supplied to ra8_vin_attach_handler and handed back to the callback unchanged – the driver never dereferences it.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 88 of file ra8_vin.c.

Referenced by ra8_vin_attach_handler(), ra8_vin_deinit(), and ra8_vin_dispatch().

◆ s_vin_fn

ra8_vin_event_fn_t s_vin_fn

static

Registered VIN event callback (set by ra8_vin_attach_handler).

Single shared callback for both the status and error IRQ vectors. NULL means "no callback installed" – ra8_vin_dispatch becomes a status-clear-only no-op in that case.

Warning: Direct modification outside ra8_vin_attach_handler is not supported; callers must go through the API so future locking can be added without source-code churn.

Note: Not thread-safe; protected by the caller's IRQ-mask discipline.

Since: 0.1.0

Definition at line 75 of file ra8_vin.c.

Referenced by ra8_vin_attach_handler(), ra8_vin_deinit(), and ra8_vin_dispatch().

◆ s_vin_frame_buf

void* s_vin_frame_buf

static

Buffer base of the most recent ra8_vin_capture_start call.

Since: 0.1.0

Definition at line 109 of file ra8_vin.c.

Referenced by ra8_vin_capture_start(), ra8_vin_deinit(), and ra8_vin_dispatch().

◆ s_vin_frame_ctx

void* s_vin_frame_ctx

static

Context forwarded to s_vin_frame_fn.

Since: 0.1.0

Definition at line 102 of file ra8_vin.c.

Referenced by ra8_vin_attach_frame_handler(), ra8_vin_deinit(), and ra8_vin_dispatch().

◆ s_vin_frame_fn

ra8_vin_frame_fn_t s_vin_frame_fn

static

Frame-end callback registered via ra8_vin_attach_frame_handler.

Since: 0.1.0

Definition at line 95 of file ra8_vin.c.

Referenced by ra8_vin_attach_frame_handler(), ra8_vin_deinit(), and ra8_vin_dispatch().

◆ s_vin_frame_len

uint32_t s_vin_frame_len

static

Cached length (in bytes) of the most recent capture geometry.

Since: 0.1.0

Definition at line 116 of file ra8_vin.c.

Referenced by ra8_vin_capture_start(), ra8_vin_deinit(), and ra8_vin_dispatch().

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_vin_capture_geom_t

◆ ra8_vin_chan_offsets_t

◆ ra8_vin_format_bpp_t

◆ ra8_vin_local_t

Function Documentation

◆ internal_compose_mc()

◆ internal_format_bpp()

◆ internal_mc_rmw()

◆ internal_pulse_st()

◆ internal_yc_offsets()

◆ ra8_vin_attach_frame_handler()

◆ ra8_vin_attach_handler()

◆ ra8_vin_capture_arm()

◆ ra8_vin_capture_disarm()

◆ ra8_vin_capture_start()

◆ ra8_vin_capture_stop()

◆ ra8_vin_clear_status()

◆ ra8_vin_deinit()

◆ ra8_vin_dispatch()

◆ ra8_vin_enable_scaling()

◆ ra8_vin_enter_stop()

◆ ra8_vin_exit_stop()

◆ ra8_vin_get_active_buffer()

◆ ra8_vin_get_line_count()

◆ ra8_vin_get_module_status()

◆ ra8_vin_get_status()

◆ ra8_vin_init()

◆ ra8_vin_lut_program()

◆ ra8_vin_reset()

◆ ra8_vin_set_csi_input()

◆ ra8_vin_set_data_mode()

◆ ra8_vin_set_dithering()

◆ ra8_vin_set_field_detect()

◆ ra8_vin_set_framebuffers()

◆ ra8_vin_set_interlace_mode()

◆ ra8_vin_set_interrupt_enable()

◆ ra8_vin_set_preclip()

◆ ra8_vin_set_rgb_to_yc()

◆ ra8_vin_set_scanline_compare()

◆ ra8_vin_set_uds_clip()

◆ ra8_vin_set_uds_ctrl()

◆ ra8_vin_set_uds_passband()

◆ ra8_vin_set_uds_scale()

◆ ra8_vin_set_uv_offset()

◆ ra8_vin_set_window()

◆ ra8_vin_set_yc_to_rgb()

◆ ra8_vin_set_yuv444_mode()

Variable Documentation

◆ s_tag

◆ s_vin_ctx

◆ s_vin_fn

◆ s_vin_frame_buf

◆ s_vin_frame_ctx

◆ s_vin_frame_fn

◆ s_vin_frame_len