Capture Engine Unit (CEU) driver function prototypes. More...

#include <stdint.h>
#include "ra8_ceu_types.h"
#include "ra8_err.h"

Include dependency graph for ra8_ceu_api.h:

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

Functions
ra8_err_t	ra8_ceu_init (const ra8_ceu_config_t *cfg)
	Power on the CEU and write the full configuration.
ra8_err_t	ra8_ceu_deinit (void)
	Stop the CEU and drop its module-stop bit.
ra8_err_t	ra8_ceu_reset (void)
	Issue a software reset of the capture state machine.
ra8_err_t	ra8_ceu_get_status (uint32_t *out_mask)
	Snapshot the CEU event-status register (CETCR).
ra8_err_t	ra8_ceu_clear_status (uint32_t mask)
	Clear the CETCR event flags identified by mask.
ra8_err_t	ra8_ceu_status_snapshot (ra8_ceu_status_t *out)
	Snapshot CSTSR + CDSSR + the active plane into one struct.
ra8_err_t	ra8_ceu_data_size_get (uint32_t *out_bytes)
	Return the byte count written by the last data-enable capture.
ra8_err_t	ra8_ceu_interrupts_set (uint32_t mask)
	Update the CEIER interrupt-enable bitmask.
ra8_err_t	ra8_ceu_attach_handler (ra8_ceu_event_fn_t fn, void *ctx)
	Register a callback invoked by ra8_ceu_dispatch.
void	ra8_ceu_dispatch (void)
	Drain CEU interrupt events and fire the registered callback.
ra8_err_t	ra8_ceu_enter_stop (void)
	Stop active captures and drop the CEU module-stop bit.
ra8_err_t	ra8_ceu_exit_stop (void)
	Exit the MSTP-gated stop entered by ra8_ceu_enter_stop.
ra8_err_t	ra8_ceu_capture_arm (uint8_t *buffer)
	Arm a capture into the supplied buffer.
ra8_err_t	ra8_ceu_capture_start_ex (const ra8_ceu_buffers_t *bufs)
	Arm a capture using a full address bundle.
ra8_err_t	ra8_ceu_capture_disarm (void)
	Stop the running capture by clearing CAPSR.CE.
ra8_err_t	ra8_ceu_plane_b_program (const ra8_ceu_buffers_t *bufs)
	Mirror the active configuration into Plane B and arm a swap.
ra8_err_t	ra8_ceu_plane_swap_force (void)
	Force an immediate plane swap (CRCMPR.RA).
ra8_err_t	ra8_ceu_firewall_set (bool enable, uint32_t upper_bound)
	Configure the CFWCR firewall window.
ra8_err_t	ra8_ceu_byte_swap_set (const ra8_ceu_byte_swap_t *swap)
	Replace CDOCR byte-swap configuration in-place.
ra8_err_t	ra8_ceu_bundle_size_set (uint32_t size_bytes)
	Configure the bundle-write size (CBDSR).
ra8_err_t	ra8_ceu_low_pass_set (bool enable)
	Enable or disable the input low-pass filter (CLFCR.LPF).
ra8_err_t	ra8_ceu_capture_mode_set (ra8_ceu_capture_mode_t mode)
	Enable or disable continuous-capture mode (CAPCR.CTNCP).
ra8_err_t	ra8_ceu_frame_drop_set (uint8_t count)
	Update the frame-drop counter (CAPCR.FDRP).
ra8_err_t	ra8_ceu_dma_pump (uint8_t channel, const uint8_t src, uint8_t dst, uint32_t bytes)
	Pump a finished CEU bundle into a downstream DMAC channel.
ra8_err_t	ra8_ceu_set_dma_buffer (uint8_t *buf, uint32_t len)
	Cache a DMAC-target framebuffer for the next ra8_ceu_capture_start call.
ra8_err_t	ra8_ceu_capture_start (uint32_t num_frames)
	Start a single or continuous capture into the cached DMA buffer.
ra8_err_t	ra8_ceu_capture_stop (void)
	Stop the in-flight capture started via ra8_ceu_capture_start.

Detailed Description

Capture Engine Unit (CEU) driver function prototypes.

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

Public function prototypes for the RA8D2 Capture Engine Unit (CEU) HAL driver: lifecycle (init / deinit / reset), status + IRQ dispatch, power transitions, capture arm/disarm, the live plane / firewall / byte-swap reconfiguration setters, and the DMA-coupling helpers. The configuration descriptors and types these prototypes consume live in ra8_ceu_types.h; both are aggregated by the thin umbrella ra8_ceu.h, which also documents the full driver overview and state machine.

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

Since: 0.1.0

Definition in file ra8_ceu_api.h.

Function Documentation

◆ ra8_ceu_attach_handler()

ra8_err_t ra8_ceu_attach_handler	(	ra8_ceu_event_fn_t	fn,
		void *	ctx )

nodiscard

Register a callback invoked by ra8_ceu_dispatch.

Parameters

[in]	fn	Callback function, or NULL to clear.
[in]	ctx	Opaque context forwarded as the first callback arg.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Callback installed (or cleared).

Precondition: Caller is in single-threaded init or has IRQs masked.; fn is either NULL or points to a callable function.

Postcondition: Subsequent ra8_ceu_dispatch calls invoke fn(ctx, mask).; Previously-registered callback is overwritten.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 419 of file ra8_ceu.c.

References k_ra8_ok, s_ceu_ctx, and s_ceu_fn.

◆ ra8_ceu_bundle_size_set()

ra8_err_t ra8_ceu_bundle_size_set ( uint32_t size_bytes )

nodiscard

Configure the bundle-write size (CBDSR).

HUM Ch 60.2.17 p 3660. The size is in bytes for data-enable mode or in lines for image / data-sync mode. The lower 3 bits are masked off by the hardware to enforce the 8-line/32-byte bundle alignment.

Parameters

[in] size_bytes Bundle size; aligned-down to 8 by the helper.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always.

Precondition: ra8_ceu_init previously called.

Postcondition: CBDSR == size_bytes & ~7.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 741 of file ra8_ceu.c.

References k_ra8_ceu_bundle_align_mask, k_ra8_ceu_off_cbdsr, k_ra8_ok, and ra8_ceu_reg32().

◆ ra8_ceu_byte_swap_set()

ra8_err_t ra8_ceu_byte_swap_set ( const ra8_ceu_byte_swap_t * swap )

nodiscard

Replace CDOCR byte-swap configuration in-place.

Parameters

[in] swap Non-NULL byte-swap descriptor.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Updated.
k_ra8_err_null_ptr	swap was NULL.

Precondition: ra8_ceu_init previously called.; swap is non-NULL.

Postcondition: CDOCR.COBS == swap->swap_8_bit.; CDOCR.COWS == swap->swap_16_bit.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 721 of file ra8_ceu.c.

References k_ra8_ceu_cdocr_mask_cobs, k_ra8_ceu_cdocr_mask_cols, k_ra8_ceu_cdocr_mask_cows, k_ra8_ceu_off_cdocr, k_ra8_ok, ra8_ceu_reg32(), RA8_CHECK_NULL_PTR, s_tag, ra8_ceu_byte_swap_t::swap_16_bit, ra8_ceu_byte_swap_t::swap_32_bit, and ra8_ceu_byte_swap_t::swap_8_bit.

◆ ra8_ceu_capture_arm()

ra8_err_t ra8_ceu_capture_arm ( uint8_t * buffer )

nodiscard

Arm a capture into the supplied buffer.

Writes the buffer base into CDAYR (and CDACR for image-capture mode), clears any pending CETCR flags, and finally sets CAPSR.CE=1. Capture begins on the next VD edge. The CETCR.CPE flag fires when the buffer is filled (single-shot) or at every frame boundary (continuous).

In data-enable-fetch mode the firewall (CFWCR) is automatically armed to image_area_size - 1 from the buffer base.

Parameters

[in] buffer Capture target. Must be non-NULL and 8-byte aligned.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Capture armed; CE bit set.
k_ra8_err_null_ptr	buffer was NULL.
k_ra8_err_invalid_arg	buffer is not 8-byte aligned.
k_ra8_err_busy	A capture is already in progress (CSTSR.CPTON == 1) or a software reset is in flight (CAPSR.CPKIL == 1).

Precondition: ra8_ceu_init previously called.; CEU is idle (CSTSR.CPTON == 0).; buffer is non-NULL and 8-byte aligned.

Postcondition: CDAYR == (uintptr_t)buffer.; CAPSR.CE == 1 (capture armed).

Note: Not thread-safe.

See also: ra8_ceu_dispatch Listens for CETCR.CPE on capture completion.

Since: 0.1.0

Definition at line 521 of file ra8_ceu.c.

References internal_arm_capture(), k_ra8_ceu_buffer_align_mask, k_ra8_err_invalid_arg, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_log_info_val, and s_tag.

Referenced by ra8_ceu_capture_start().

◆ ra8_ceu_capture_disarm()

ra8_err_t ra8_ceu_capture_disarm ( void )

nodiscard

Stop the running capture by clearing CAPSR.CE.

Distinct from ra8_ceu_reset – this only clears the CE bit so the next VD does not start a new frame. Continuous-mode captures use this to break out cleanly without a CPKIL software reset.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always.

Precondition: ra8_ceu_init previously called.; Caller has CEU IRQ masked or is in IRQ context.

Postcondition: CAPSR.CE == 0.; CSTSR.CPTON will go to 0 once the in-flight frame ends.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 564 of file ra8_ceu.c.

References k_ra8_ceu_capsr_mask_ce, k_ra8_ceu_off_capsr, k_ra8_ok, and ra8_ceu_reg32().

Referenced by ra8_ceu_capture_stop().

◆ ra8_ceu_capture_mode_set()

ra8_err_t ra8_ceu_capture_mode_set ( ra8_ceu_capture_mode_t mode )

nodiscard

Enable or disable continuous-capture mode (CAPCR.CTNCP).

Parameters

[in] mode Single-shot or continuous.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always.

Precondition: ra8_ceu_init previously called.

Postcondition: CAPCR.CTNCP reflects mode.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 759 of file ra8_ceu.c.

References k_ra8_ceu_capcr_mask_ctncp, k_ra8_ceu_capture_continuous, k_ra8_ceu_off_capcr, k_ra8_ok, and ra8_ceu_reg32().

◆ ra8_ceu_capture_start()

ra8_err_t ra8_ceu_capture_start ( uint32_t num_frames )

nodiscard

Start a single or continuous capture into the cached DMA buffer.

Wraps ra8_ceu_capture_arm with the buffer that was cached via ra8_ceu_set_dma_buffer. num_frames selects the capture mode:

num_frames == 1 -> single-shot (CAPCR.CTNCP = 0).
num_frames == 0 -> continuous capture (CAPCR.CTNCP = 1).
Otherwise -> single-shot; the driver tracks the remaining count through the dispatcher (out of scope for this entry-point, see
Note below).

Parameters

[in] num_frames 0 = continuous, otherwise number of frames.

Returns
ra8_err_t

Return values

k_ra8_ok Capture armed.

k_ra8_err_invalid_state No buffer cached via ra8_ceu_set_dma_buffer.

k_ra8_err_busy CEU is already capturing.

Precondition
ra8_ceu_init and ra8_ceu_set_dma_buffer were called.

Postcondition
CAPCR.CTNCP reflects continuous vs single.

CAPSR.CE == 1.

Note
Not thread-safe.

See also
ra8_ceu_capture_stop

Since
0.1.0

Definition at line 829 of file ra8_ceu.c.

References k_ra8_ceu_capcr_shift_ctncp, k_ra8_ceu_off_capcr, k_ra8_err_invalid_state, ra8_ceu_capture_arm(), ra8_ceu_reg32(), and s_ceu_dma_buf.

◆ ra8_ceu_capture_start_ex()

ra8_err_t ra8_ceu_capture_start_ex ( const ra8_ceu_buffers_t * bufs )

nodiscard

Arm a capture using a full address bundle.

Like ra8_ceu_capture_start but lets the caller specify the C (chrominance) base, the bottom-field addresses (interlace), and the bundle-2 pair (ping-pong). Pointers left NULL leave the matching register at its previous value.

Parameters

[in] bufs Non-NULL buffer descriptor.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Capture armed; CE set.
k_ra8_err_null_ptr	bufs was NULL or bufs->y_top NULL.
k_ra8_err_invalid_arg	Any non-NULL pointer fails 8-byte alignment.
k_ra8_err_busy	CSTSR.CPTON==1 or CAPSR.CPKIL==1.

Precondition: ra8_ceu_init previously called.; CEU is idle (CSTSR.CPTON == 0).; bufs->y_top is non-NULL and 8-byte aligned.

Postcondition: CDAYR == (uintptr_t)bufs->y_top.; CAPSR.CE == 1.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 551 of file ra8_ceu.c.

References internal_arm_capture(), internal_validate_buffers(), k_ra8_ok, RA8_CHECK_NULL_PTR, s_tag, and ra8_ceu_buffers_t::y_top.

Referenced by internal_ceu_capture().

◆ ra8_ceu_capture_stop()

ra8_err_t ra8_ceu_capture_stop ( void )

nodiscard

Stop the in-flight capture started via ra8_ceu_capture_start.

Wraps ra8_ceu_capture_disarm so the high-level start/stop pair share matching names.

Returns: ra8_err_t error code from ra8_ceu_capture_disarm.

Precondition: ra8_ceu_capture_start was previously called.

Postcondition: CAPSR.CE == 0.

Note: Not thread-safe.

See also: ra8_ceu_capture_start

Since: 0.1.0

Definition at line 848 of file ra8_ceu.c.

References ra8_ceu_capture_disarm().

◆ ra8_ceu_clear_status()

ra8_err_t ra8_ceu_clear_status ( uint32_t mask )

nodiscard

Clear the CETCR event flags identified by mask.

CETCR is "write-0-to-clear" per HUM Ch 60.2.22 – writing the complement of mask clears exactly those bits. The driver does a read-modify-write so other in-flight flags survive.

Parameters

[in] mask Bitmask of k_ra8_ceu_evt_* values to clear.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always; mask of zero is a no-op.

Precondition: CEU is powered (MSTPC16 cleared).; mask only contains bits defined in ra8_ceu_cetcr_mask_t.

Postcondition: Bits in mask are deasserted in CETCR.; Bits not in mask retain their previous state.

Note: Not thread-safe.

See also: ra8_ceu_get_status

Since: 0.1.0

Definition at line 370 of file ra8_ceu.c.

References k_ra8_ceu_off_cetcr, k_ra8_ok, and ra8_ceu_reg32().

Referenced by internal_ceu_wait_for_frame().

◆ ra8_ceu_data_size_get()

ra8_err_t ra8_ceu_data_size_get ( uint32_t * out_bytes )

nodiscard

Return the byte count written by the last data-enable capture.

Reads CDSSR per HUM Ch 60.2.24 p 3674. Only meaningful after a data-enable-fetch capture completes; in image / data-sync modes this register stays at zero.

Parameters

[out] out_bytes Non-NULL byte-count receiver.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Snapshot taken.
k_ra8_err_null_ptr	out_bytes was NULL.

Precondition: out_bytes is non-NULL.; ra8_ceu_init previously called.

Postcondition: *out_bytes == CDSSR.

Note: Thread-safe (read-only).

Since: 0.1.0

Definition at line 403 of file ra8_ceu.c.

References k_ra8_ceu_off_cdssr, k_ra8_ok, ra8_ceu_reg32(), RA8_CHECK_NULL_PTR, and s_tag.

◆ ra8_ceu_deinit()

ra8_err_t ra8_ceu_deinit ( void )

nodiscard

Stop the CEU and drop its module-stop bit.

Issues CAPSR.CPKIL=1 to abort any active capture, masks every interrupt source by writing 0 to CEIER, clears the registered callback, and finally calls ra8_mstp_disable(k_ra8_mstp_ceu).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Driver torn down, MSTP released.
k_ra8_err_hw_timeout	MSTP disable read-back failed.

Precondition: ra8_ceu_init was previously called successfully.; Caller does not race a CEU IRQ on another core.

Postcondition: CEU is fully powered down (MSTPC16 set).; Registered callback is cleared.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 336 of file ra8_ceu.c.

References k_ra8_ceu_capsr_mask_cpkil, k_ra8_ceu_off_capsr, k_ra8_ceu_off_ceier, k_ra8_mstp_ceu, ra8_ceu_reg32(), ra8_mstp_disable(), s_ceu_ctx, s_ceu_dma_buf, s_ceu_dma_len, s_ceu_fn, s_ceu_image_area, and s_ceu_int_enable.

◆ ra8_ceu_dispatch()

void ra8_ceu_dispatch ( void )

Drain CEU interrupt events and fire the registered callback.

Intended to be called from the CEU ISR (or from a soft-IRQ context fed by the ISR). Snapshots CETCR, clears the observed bits via write-0, and invokes the registered callback with the masked event set. The mask passed to the callback is gated by the currently-enabled CEIER bits.

Precondition: ra8_ceu_init previously called.; Caller is the CEU IRQ context (or has IRQs masked).

Postcondition: All bits that were observed in CETCR are cleared.; Registered callback (if any) was invoked exactly once.

Note: Returns silently if no callback is registered.

Since: 0.1.0

Definition at line 427 of file ra8_ceu.c.

References k_ra8_ceu_off_cetcr, ra8_ceu_reg32(), s_ceu_ctx, s_ceu_fn, and s_ceu_int_enable.

◆ ra8_ceu_dma_pump()

ra8_err_t ra8_ceu_dma_pump	(	uint8_t	channel,
		const uint8_t *	src,
		uint8_t *	dst,
		uint32_t	bytes )

nodiscard

Pump a finished CEU bundle into a downstream DMAC channel.

The CEU writes pixels straight to SRAM/SDRAM via its own bus initiator, so it does not need the DMAC for the camera pixel path. This helper exists for the application-level pump that copies a completed CEU frame into a second buffer (e.g. ping-ponging frames into the GLCDC layer-2 framebuffer). It packages the existing ra8_dmac_start call with the CEU's preferred 32-bit / source+dest-incrementing layout.

Parameters

[in]	channel	DMAC channel index.
[in]	src	Source buffer (typically the CDAYR-pointed window).
[in]	dst	Destination buffer.
[in]	bytes	Bytes to copy (multiple of 4).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	DMAC channel armed.
k_ra8_err_null_ptr	src or dst was NULL.
k_ra8_err_invalid_arg	bytes not a multiple of 4 or 0.

Precondition: ra8_ceu_init previously called.; ra8_dmac_init (or equivalent) previously called.

Postcondition: DMAC channel channel armed for a one-shot block transfer.

Note: Wraps ra8_dmac_start – the channel becomes unavailable to other consumers until the transfer completes.

Since: 0.1.0

Definition at line 783 of file ra8_ceu.c.

References k_ra8_ceu_dma_byte_align_mask, k_ra8_ceu_dma_count_shift, k_ra8_dmac_width_word, k_ra8_err_invalid_arg, RA8_CHECK_NULL_PTR, ra8_dmac_start(), and s_tag.

◆ ra8_ceu_enter_stop()

ra8_err_t ra8_ceu_enter_stop ( void )

nodiscard

Stop active captures and drop the CEU module-stop bit.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	CEU stopped + MSTP released.
k_ra8_err_hw_timeout	MSTP disable read-back failed.

Precondition: ra8_ceu_init previously called.; Caller does not race the CEU ISR.

Postcondition: CEU is in MSTP-gated stop.; No further CEU IRQs will fire until ra8_ceu_exit_stop.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 446 of file ra8_ceu.c.

References k_ra8_ceu_capsr_mask_cpkil, k_ra8_ceu_off_capsr, k_ra8_mstp_ceu, ra8_ceu_reg32(), and ra8_mstp_disable().

◆ ra8_ceu_exit_stop()

ra8_err_t ra8_ceu_exit_stop ( void )

nodiscard

Exit the MSTP-gated stop entered by ra8_ceu_enter_stop.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	MSTP re-enabled, CEU window accessible.
k_ra8_err_hw_timeout	MSTP enable read-back failed.

Precondition: ra8_ceu_enter_stop was previously called.; Caller does not race the CEU ISR.

Postcondition: CEU window is accessible (MSTPC16 cleared).; Caller must reprogram any registers that lost state.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 454 of file ra8_ceu.c.

References k_ra8_mstp_ceu, and ra8_mstp_enable().

◆ ra8_ceu_firewall_set()

ra8_err_t ra8_ceu_firewall_set	(	bool	enable,
		uint32_t	upper_bound )

nodiscard

Configure the CFWCR firewall window.

HUM Ch 60.2.18 "CFWCR" p 3661. The firewall fires CETCR.FWF if the data-enable-fetch engine attempts a write past the supplied upper-bound address. Disabled if enable is false or the upper-bound is zero.

Parameters

[in]	enable	True to assert CFWCR.FWE.
[in]	upper_bound	Upper-bound address (lower 5 bits forced to 0x1F by the hardware).

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always.

Precondition: ra8_ceu_init previously called.

Postcondition: CFWCR == (enable?FWE:0) | (upper_bound & FWV mask).

Note: Not thread-safe.

Since: 0.1.0

Definition at line 709 of file ra8_ceu.c.

References k_ra8_ceu_cfwcr_mask_fwe, k_ra8_ceu_cfwcr_mask_fwv, k_ra8_ceu_off_cfwcr, k_ra8_ok, and ra8_ceu_reg32().

◆ ra8_ceu_frame_drop_set()

ra8_err_t ra8_ceu_frame_drop_set ( uint8_t count )

nodiscard

Update the frame-drop counter (CAPCR.FDRP).

Parameters

[in] count Number of frames to skip between captures (0..255).

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always.

Precondition: ra8_ceu_init previously called.

Postcondition: CAPCR.FDRP == count.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 772 of file ra8_ceu.c.

References k_ra8_ceu_capcr_mask_fdrp, k_ra8_ceu_capcr_shift_fdrp, k_ra8_ceu_off_capcr, k_ra8_ok, and ra8_ceu_reg32().

◆ ra8_ceu_get_status()

ra8_err_t ra8_ceu_get_status ( uint32_t * out_mask )

nodiscard

Snapshot the CEU event-status register (CETCR).

Parameters

[out] out_mask Receives the raw CETCR value.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Snapshot taken.
k_ra8_err_null_ptr	out_mask was NULL.

Precondition: out_mask is non-NULL.; ra8_ceu_init previously called (CEU MSTP cleared).

Postcondition: *out_mask reflects the value of CETCR at call time.; No status flag is cleared.

Note: Thread-safe with respect to its own register read.

See also: ra8_ceu_clear_status

Since: 0.1.0

Definition at line 362 of file ra8_ceu.c.

References k_ra8_ceu_off_cetcr, k_ra8_ok, ra8_ceu_reg32(), RA8_CHECK_NULL_PTR, and s_tag.

◆ ra8_ceu_init()

ra8_err_t ra8_ceu_init ( const ra8_ceu_config_t * cfg )

nodiscard

Power on the CEU and write the full configuration.

Steps performed:

ra8_mstp_enable(k_ra8_mstp_ceu) to release MSTPC16.
Wait for any in-flight software reset (CSTSR.CPTON==0, CAPSR.CPKIL==0) with a bounded spin.
Program CFLCR (scale-down), CAIFR (interlace), CAPCR (continuous + burst + frame-drop), CAMCR (sync polarities, latch edges, capture format, input order, FLDPOL, DTIF), CMCYR (image dimensions), CAMOR (start offsets), CAPWR (capture cycles), CFSZR (filter clip), CDWDR (destination stride), CLFCR (LPF enable), CDOCR (output format, byte swap, bundle-write enable), CFWCR (firewall off; armed in capture_start).
Clear CETCR and write CEIER from cfg->interrupts.

Parameters

[in] cfg Non-NULL configuration descriptor.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Capture engine powered + configured.
k_ra8_err_null_ptr	cfg was NULL.
k_ra8_err_invalid_arg	cfg->capture_mode is continuous in a non-image-capture format.
k_ra8_err_hw_timeout	MSTP enable failed or the reset-clear spin overran.

Precondition: cfg is non-NULL.; ra8_mstp_init has been called.

Postcondition: CEU module-stop bit is cleared.; CEU is in idle (CSTSR.CPTON == 0) and ready for ra8_ceu_capture_start.

Note: Not thread-safe – single-threaded init context only.

See also: ra8_ceu_capture_start

Since: 0.1.0

Definition at line 300 of file ra8_ceu.c.

References ra8_ceu_config_t::capture_format, ra8_ceu_config_t::capture_mode, ra8_ceu_config_t::image_area_size, internal_wait_idle(), ra8_ceu_config_t::interrupts, k_ra8_ceu_capture_continuous, k_ra8_ceu_fmt_image_capture, k_ra8_ceu_off_ceier, k_ra8_err_invalid_arg, k_ra8_mstp_ceu, k_ra8_ok, priv_ra8_ceu_program_destination(), priv_ra8_ceu_program_format(), priv_ra8_ceu_program_geometry(), ra8_ceu_reg32(), RA8_CHECK_NULL_PTR, ra8_log_info_val, ra8_mstp_enable(), RA8_RETURN_ON_ERROR, s_ceu_capture_format, s_ceu_image_area, s_ceu_int_enable, s_tag, and ra8_ceu_config_t::width_px.

Referenced by ra8_camera_source_ceu_init().

◆ ra8_ceu_interrupts_set()

ra8_err_t ra8_ceu_interrupts_set ( uint32_t mask )

nodiscard

Update the CEIER interrupt-enable bitmask.

Parameters

[in] mask Bitwise-OR of k_ra8_ceu_evt_* values.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always.

Precondition: ra8_ceu_init previously called.; mask only contains bits defined in ra8_ceu_cetcr_mask_t.

Postcondition: CEIER == mask.; Future ra8_ceu_dispatch calls gate the callback against the new mask.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 411 of file ra8_ceu.c.

References k_ra8_ceu_off_ceier, k_ra8_ok, ra8_ceu_reg32(), and s_ceu_int_enable.

◆ ra8_ceu_low_pass_set()

ra8_err_t ra8_ceu_low_pass_set ( bool enable )

nodiscard

Enable or disable the input low-pass filter (CLFCR.LPF).

Parameters

[in] enable true => CLFCR.LPF = 1.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always.

Precondition: ra8_ceu_init previously called.

Postcondition: CLFCR.LPF == enable.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 748 of file ra8_ceu.c.

References k_ra8_ceu_clfcr_mask_lpf, k_ra8_ceu_off_clfcr, k_ra8_ok, and ra8_ceu_reg32().

◆ ra8_ceu_plane_b_program()

ra8_err_t ra8_ceu_plane_b_program ( const ra8_ceu_buffers_t * bufs )

nodiscard

Mirror the active configuration into Plane B and arm a swap.

Writes the current Plane A image of every 3-plane register into Plane B (offset +0x1000) and sets CRCNTR.RVS so the CEU swaps planes on the next VD edge. Used to apply a new geometry / new capture buffer without dropping a frame.

Parameters

[in] bufs Buffer bundle to install on Plane B; pass NULL to copy the existing Plane A addresses unchanged.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Plane B armed.
k_ra8_err_invalid_arg	Any non-NULL pointer is misaligned.

Precondition: ra8_ceu_init previously called.; Caller does not race the CEU ISR.

Postcondition: Plane B mirrors Plane A (with bufs overrides applied).; CRCNTR.RVS == 1 (swap armed for next VD).

Note: Not thread-safe.

Since: 0.1.0

Definition at line 681 of file ra8_ceu.c.

References internal_plane_b_apply_overrides(), internal_plane_b_mirror_from_a(), internal_validate_buffers(), k_ra8_ceu_crcntr_mask_rc, k_ra8_ceu_crcntr_mask_rs, k_ra8_ceu_crcntr_mask_rvs, k_ra8_ceu_off_crcntr, k_ra8_ok, and ra8_ceu_reg32().

◆ ra8_ceu_plane_swap_force()

ra8_err_t ra8_ceu_plane_swap_force ( void )

nodiscard

Force an immediate plane swap (CRCMPR.RA).

HUM Ch 60.2.9 "CRCMPR" p 3649. Bypasses the VD-edge sync the normal Plane-B path uses; use only when a frame must be dropped.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always.

Precondition: ra8_ceu_init previously called.

Postcondition: CRCMPR.RA == 1 momentarily; the bit self-clears.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 702 of file ra8_ceu.c.

References k_ra8_ceu_crcmpr_mask_ra, k_ra8_ceu_off_crcmpr, k_ra8_ok, and ra8_ceu_reg32().

◆ ra8_ceu_reset()

ra8_err_t ra8_ceu_reset ( void )

nodiscard

Issue a software reset of the capture state machine.

Sets CAPSR.CPKIL and spins on CSTSR.CPTON / CAPSR.CPKIL until both clear or the budget expires. Used to recover from a stuck capture (e.g. after a sensor stopped emitting VD edges).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Reset completed cleanly.
k_ra8_err_hw_timeout	Status bits did not clear in budget.

Precondition: ra8_ceu_init previously called.; Caller has the CEU IRQ masked or is in CEU IRQ context.

Postcondition: CSTSR.CPTON == 0.; CAPSR.CPKIL == 0.

Note: Bounded spin of k_ra8_ceu_reset_spin iterations.

Since: 0.1.0

Definition at line 355 of file ra8_ceu.c.

References internal_wait_idle(), k_ra8_ceu_capsr_mask_cpkil, k_ra8_ceu_off_capsr, and ra8_ceu_reg32().

Referenced by internal_ceu_wait_for_frame().

◆ ra8_ceu_set_dma_buffer()

ra8_err_t ra8_ceu_set_dma_buffer	(	uint8_t *	buf,
		uint32_t	len )

nodiscard

Cache a DMAC-target framebuffer for the next ra8_ceu_capture_start call.

The CEU writes pixel data straight to memory via its own bus initiator, so the "DMA buffer" here is just the next CDAYR target the driver will arm when ra8_ceu_capture_start(num_frames) is called. The length is cached so the frame-end callback can hand the whole buffer back to the consumer.

Parameters

[in]	buf	Capture target (must be 8-byte aligned per HUM Ch 60.2.13 p 3656).
[in]	len	Buffer length in bytes (>0).

Returns: ra8_err_t

Return values

k_ra8_ok	Buffer cached.
k_ra8_err_null_ptr	buf was NULL.
k_ra8_err_invalid_arg	len was 0 or buf misaligned.

Precondition: ra8_ceu_init previously called.; buf is non-NULL and 8-byte aligned, len > 0.

Postcondition: The driver remembers (buf, len) for the next capture_start.

Note: Not thread-safe.

See also: ra8_ceu_capture_start

Since: 0.1.0

Definition at line 814 of file ra8_ceu.c.

References k_ra8_ceu_buffer_align_mask, k_ra8_err_invalid_arg, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_log_info_val, s_ceu_dma_buf, s_ceu_dma_len, and s_tag.

◆ ra8_ceu_status_snapshot()

ra8_err_t ra8_ceu_status_snapshot ( ra8_ceu_status_t * out )

nodiscard

Snapshot CSTSR + CDSSR + the active plane into one struct.

Parameters

[out] out Non-NULL status struct to populate.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Snapshot taken.
k_ra8_err_null_ptr	out was NULL.

Precondition: out is non-NULL.; ra8_ceu_init previously called.

Postcondition: out->capturing mirrors CSTSR.CPTON.; out->data_size mirrors CDSSR.

Note: Thread-safe (read-only).

Since: 0.1.0

Definition at line 383 of file ra8_ceu.c.

References ra8_ceu_status_t::active_plane, ra8_ceu_status_t::capturing, ra8_ceu_status_t::data_size, ra8_ceu_status_t::events, k_ra8_ceu_capsr_mask_cpkil, k_ra8_ceu_cstsr_mask_cpfld, k_ra8_ceu_cstsr_mask_cpton, k_ra8_ceu_cstsr_mask_crst, k_ra8_ceu_off_capsr, k_ra8_ceu_off_cdssr, k_ra8_ceu_off_cetcr, k_ra8_ceu_off_cstsr, k_ra8_ceu_plane_a, k_ra8_ceu_plane_b, k_ra8_ok, ra8_ceu_reg32(), RA8_CHECK_NULL_PTR, ra8_ceu_status_t::reset_in_flight, s_tag, and ra8_ceu_status_t::top_field.

Referenced by internal_ceu_wait_for_frame().

k_ra8_ok	Capture armed.
k_ra8_err_invalid_state	No buffer cached via ra8_ceu_set_dma_buffer.
k_ra8_err_busy	CEU is already capturing.

Functions

Detailed Description

Function Documentation

◆ ra8_ceu_attach_handler()

◆ ra8_ceu_bundle_size_set()

◆ ra8_ceu_byte_swap_set()

◆ ra8_ceu_capture_arm()

◆ ra8_ceu_capture_disarm()

◆ ra8_ceu_capture_mode_set()

◆ ra8_ceu_capture_start()

◆ ra8_ceu_capture_start_ex()

◆ ra8_ceu_capture_stop()

◆ ra8_ceu_clear_status()

◆ ra8_ceu_data_size_get()

◆ ra8_ceu_deinit()

◆ ra8_ceu_dispatch()

◆ ra8_ceu_dma_pump()

◆ ra8_ceu_enter_stop()

◆ ra8_ceu_exit_stop()

◆ ra8_ceu_firewall_set()

◆ ra8_ceu_frame_drop_set()

◆ ra8_ceu_get_status()

◆ ra8_ceu_init()

◆ ra8_ceu_interrupts_set()

◆ ra8_ceu_low_pass_set()

◆ ra8_ceu_plane_b_program()

◆ ra8_ceu_plane_swap_force()

◆ ra8_ceu_reset()

◆ ra8_ceu_set_dma_buffer()

◆ ra8_ceu_status_snapshot()