RA8 CEU implementation of the camera-source backend. More...

#include "ra8_camera_source_ceu.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_cache.h"
#include "ra8_camera_internal.h"
#include "ra8_ceu.h"
#include "ra8_err.h"
#include "ra8_time.h"

Include dependency graph for ra8_camera_source_ceu.c:

Enumerations
enum	ra8_camera_ceu_alignment_t : uintptr_t { k_ceu_buffer_alignment_mask = 7U }
enum	ra8_camera_ceu_event_t : uint32_t { k_ceu_fatal_events }
	CEU faults that make a pending capture unusable immediately. More...

Functions
static ra8_err_t	internal_ceu_get_info (void ctx, ra8_camera_source_info_t out_info)
	Return validated CEU source metadata.
static void	internal_ceu_frame_bytes (const ra8_camera_source_ceu_state_t state, const ra8_ceu_status_t status, uint32_t *out_bytes)
	Derive the captured byte count for one completed CPE event.
static ra8_err_t	internal_ceu_wait_for_frame (ra8_camera_source_ceu_state_t state, uint32_t out_bytes)
	Poll bounded CEU status until completion, error, or timeout.
static ra8_err_t	internal_ceu_capture (void ctx, const ra8_camera_buffer_t buffer, ra8_camera_frame_t *out_frame)
	Capture one CEU frame into caller-owned storage.
ra8_err_t	ra8_camera_source_ceu_get_last_events (const ra8_camera_source_ceu_state_t state, uint32_t out_events)
	Read the most recent CEU event snapshot retained by the backend.
static ra8_err_t	internal_ceu_cfg_valid (const ra8_camera_source_ceu_cfg_t *cfg)
	Validate CEU capture-source configuration bounds and format pairing.
ra8_err_t	ra8_camera_source_ceu_init (ra8_camera_source_t source, ra8_camera_source_ceu_state_t state, const ra8_camera_source_ceu_cfg_t *cfg)
	Initialize the CEU and bind it as a generic camera source.

Variables
static const ra8_camera_source_iface_t	s_ceu_source_iface

Detailed Description

RA8 CEU implementation of the camera-source backend.

Performs bounded CEU capture and cache maintenance into caller-owned storage while retaining diagnostic event state for HIL reporting.

Tag: [Ring 4 / Service] {World: NS}

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

Since: 0.1.0

Definition in file ra8_camera_source_ceu.c.

Enumeration Type Documentation

◆ ra8_camera_ceu_alignment_t

enum ra8_camera_ceu_alignment_t : uintptr_t

Enumerator
k_ceu_buffer_alignment_mask	Eight-byte CEU buffer alignment mask.

Definition at line 27 of file ra8_camera_source_ceu.c.

◆ ra8_camera_ceu_event_t

enum ra8_camera_ceu_event_t : uint32_t

CEU faults that make a pending capture unusable immediately.

Enumerator
k_ceu_fatal_events	Events that invalidate captured storage.

Definition at line 32 of file ra8_camera_source_ceu.c.

Function Documentation

◆ internal_ceu_capture()

ra8_err_t internal_ceu_capture	(	void *	ctx,
		const ra8_camera_buffer_t *	buffer,
		ra8_camera_frame_t *	out_frame )

static

Capture one CEU frame into caller-owned storage.

Performs cache maintenance, arms CEU, waits, and returns a frame view.

Parameters

[in,out]	ctx	Bound CEU backend state.
[in]	buffer	Caller-owned aligned capture storage.
[out]	out_frame	Completed immutable frame view.

Returns: Error code.

Return values

k_ra8_ok	One complete frame was captured.
k_ra8_err_not_initialized	Backend state is not initialized.
k_ra8_err_invalid_size	Capture storage or byte count is invalid.
k_ra8_err_invalid_arg	Capture storage is not eight-byte aligned.
other	Propagated cache or CEU error.

Precondition: buffer and out_frame were validated by the camera facade.; No other operation uses the CEU or supplied buffer.

Postcondition: On success out_frame views coherent bytes in buffer.; On failure no successful frame view is reported by the facade.

Note: Not thread-safe with respect to the CEU, state, or buffer.

Since: 0.1.0

Definition at line 167 of file ra8_camera_source_ceu.c.

References ra8_camera_buffer_t::capacity, ra8_camera_buffer_t::data, ra8_camera_source_info_t::format, ra8_camera_source_info_t::frame_bytes_max, ra8_camera_source_info_t::height, ra8_camera_source_ceu_state_t::info, ra8_camera_source_ceu_state_t::initialized, internal_ceu_wait_for_frame(), k_ceu_buffer_alignment_mask, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_not_initialized, k_ra8_ok, ra8_camera_source_ceu_state_t::last_events, ra8_cache_dcache_clean_invalidate_by_addr(), ra8_cache_dcache_invalidate_by_addr(), ra8_ceu_capture_start_ex(), ra8_camera_source_info_t::stride_bytes, and ra8_camera_source_info_t::width.

◆ internal_ceu_cfg_valid()

ra8_err_t internal_ceu_cfg_valid ( const ra8_camera_source_ceu_cfg_t * cfg )

static

Validate CEU capture-source configuration bounds and format pairing.

Rejects zero geometry or polling bounds, a capture-format and output-format pairing that disagrees about JPEG framing, and (for JPEG) a non-zero row stride or an image-area size that does not match the caller's declared maximum frame size.

Parameters

[in] cfg Candidate CEU capture-source configuration.

Returns: Error code.

Return values

k_ra8_ok	Every bound and format pairing is valid.
k_ra8_err_invalid_arg	A bound is zero or a format pairing disagrees.

Precondition: cfg is non-null.; No hardware state has been touched by this call.

Postcondition: cfg is unchanged.; Neither backend state nor CEU hardware is touched.

Note: Thread-safe; reads only the caller-owned configuration.

Since: 0.1.0

Definition at line 261 of file ra8_camera_source_ceu.c.

References ra8_ceu_config_t::capture_format, ra8_camera_source_ceu_cfg_t::ceu, ra8_camera_source_info_t::format, ra8_camera_source_info_t::frame_bytes_max, ra8_camera_source_info_t::height, ra8_ceu_config_t::image_area_size, k_ra8_camera_format_jpeg, k_ra8_ceu_fmt_data_enable, k_ra8_err_invalid_arg, k_ra8_ok, ra8_camera_source_ceu_cfg_t::output, ra8_camera_source_ceu_cfg_t::poll_attempts, ra8_camera_source_ceu_cfg_t::poll_interval_ms, RA8_INTERNAL, ra8_camera_source_info_t::stride_bytes, and ra8_camera_source_info_t::width.

Referenced by ra8_camera_source_ceu_init().

◆ internal_ceu_frame_bytes()

void internal_ceu_frame_bytes	(	const ra8_camera_source_ceu_state_t *	state,
		const ra8_ceu_status_t *	status,
		uint32_t *	out_bytes )

static

Derive the captured byte count for one completed CPE event.

A fixed-frame capture always reports the configured bound; a data-enable capture reports CDSSR when the peripheral latched a nonzero value and falls back to the configured bound otherwise.

Parameters

[in]	state	Initialized caller-owned CEU backend state.
[in]	status	Status snapshot that observed the completion event.
[out]	out_bytes	Captured byte count for this completion.

Precondition: state is initialized and status observed k_ra8_ceu_evt_cpe.; out_bytes points to writable storage.

Postcondition: out_bytes holds exactly the byte count this rule prescribes.; Neither state nor CEU hardware is touched.

Note: Not thread-safe with respect to state.

Since: 0.1.0

Definition at line 80 of file ra8_camera_source_ceu.c.

References ra8_camera_source_ceu_state_t::capture_format, ra8_ceu_status_t::data_size, ra8_camera_source_info_t::frame_bytes_max, ra8_camera_source_ceu_state_t::info, k_ra8_ceu_fmt_data_enable, and RA8_INTERNAL.

Referenced by internal_ceu_wait_for_frame().

◆ internal_ceu_get_info()

ra8_err_t internal_ceu_get_info	(	void *	ctx,
		ra8_camera_source_info_t *	out_info )

static

Return validated CEU source metadata.

Copies immutable metadata from initialized caller-owned state.

Parameters

[in]	ctx	Bound CEU backend state.
[out]	out_info	Destination metadata structure.

Returns: Error code.

Return values

k_ra8_ok	Metadata was copied.
k_ra8_err_not_initialized	Backend state is absent or uninitialized.

Precondition: out_info points to writable storage.; No concurrent operation mutates ctx.

Postcondition: On success out_info equals the configured source metadata.; CEU hardware and backend state are unchanged.

Note: Thread-safe only while the caller prevents concurrent reinitialization.

Since: 0.1.0

Definition at line 52 of file ra8_camera_source_ceu.c.

References ra8_camera_source_ceu_state_t::info, ra8_camera_source_ceu_state_t::initialized, k_ra8_err_not_initialized, k_ra8_ok, and RA8_INTERNAL.

◆ internal_ceu_wait_for_frame()

ra8_err_t internal_ceu_wait_for_frame	(	ra8_camera_source_ceu_state_t *	state,
		uint32_t *	out_bytes )

static

Poll bounded CEU status until completion, error, or timeout.

Accumulates diagnostics while waiting for completion. Sync-timing events can precede a valid CPE and therefore do not terminate the capture; illegal writes, CRAM overflow, and firewall faults terminate immediately. A data-enable transfer whose CDSSR is zero returns the configured capacity so a format-aware caller can locate its own end marker within that bound.

Parameters

[in,out]	state	Initialized caller-owned CEU backend state.
[out]	out_bytes	Captured byte count on completion.

Returns: Error code.

Return values

k_ra8_ok	A complete frame was observed.
k_ra8_err_hw_error	A CEU error event was observed.
k_ra8_err_hw_timeout	The bounded poll expired.
other	Propagated CEU status error.

Precondition: A capture is armed and state is initialized.; out_bytes points to writable storage.

Postcondition: state retains the last observed raw event bits.; On error or timeout an in-flight capture is software-reset.

Note: Blocking and not thread-safe with respect to the CEU.

Since: 0.1.0

Definition at line 113 of file ra8_camera_source_ceu.c.

References ra8_ceu_status_t::events, internal_ceu_frame_bytes(), k_ceu_fatal_events, k_ra8_ceu_evt_cpe, k_ra8_ceu_evt_mask_all, k_ra8_err_hw_error, k_ra8_err_hw_timeout, k_ra8_ok, ra8_camera_source_ceu_state_t::last_events, ra8_camera_source_ceu_state_t::poll_attempts, ra8_camera_source_ceu_state_t::poll_interval_ms, ra8_ceu_clear_status(), ra8_ceu_reset(), ra8_ceu_status_snapshot(), ra8_delay_ms(), and RA8_INTERNAL.

Referenced by internal_ceu_capture().

◆ ra8_camera_source_ceu_get_last_events()

ra8_err_t ra8_camera_source_ceu_get_last_events	(	const ra8_camera_source_ceu_state_t *	state,
		uint32_t *	out_events )

nodiscard

Read the most recent CEU event snapshot retained by the backend.

Returns caller-owned diagnostic state only; it does not touch CEU registers or clear hardware event latches.

Parameters

[in]	state	Initialized caller-owned backend state.
[out]	out_events	Receives raw ra8_ceu_event_t bits.

Returns: Error code.

Return values

k_ra8_ok	A snapshot was returned.
k_ra8_err_null_ptr	An argument was nullptr.
k_ra8_err_not_initialized	The backend is not bound.

Precondition: No capture is concurrently mutating state.; out_events points to writable storage.

Postcondition: Hardware registers are not accessed or modified.; On success out_events equals the last observed raw CEU event bits.

Note: Thread-safe only while the caller prevents concurrent capture updates.

Since: 0.1.0

Definition at line 222 of file ra8_camera_source_ceu.c.

References ra8_camera_source_ceu_state_t::initialized, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, and ra8_camera_source_ceu_state_t::last_events.

Referenced by c6_cam_camera_report_last_error(), cam_capture_frame_and_report(), and internal_report_capture_events().

◆ ra8_camera_source_ceu_init()

ra8_err_t ra8_camera_source_ceu_init	(	ra8_camera_source_t *	source,
		ra8_camera_source_ceu_state_t *	state,
		const ra8_camera_source_ceu_cfg_t *	cfg )

nodiscard

Initialize the CEU and bind it as a generic camera source.

Validates fixed-frame versus data-enable metadata, initializes the CEU HAL, then binds the facade handle to caller-owned backend state.

Parameters

[out]	source	Generic source handle to bind.
[out]	state	Caller-owned backend state.
[in]	cfg	CEU and output metadata configuration.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	CEU initialized and source bound.
k_ra8_err_null_ptr	An argument was nullptr.
k_ra8_err_invalid_arg	Metadata or poll bounds are invalid.
other	Forwarded from ra8_ceu_init.

Precondition: source and state remain alive for every later source operation.; cfg describes storage bounds matching its CEU capture format.

Postcondition: On success source dispatches through the CEU backend.; On success state owns all mutable backend state; no heap is used.

Note: Not thread-safe with respect to the same source, state, or CEU.

Since: 0.1.0

Definition at line 294 of file ra8_camera_source_ceu.c.

References ra8_ceu_config_t::capture_format, ra8_camera_source_ceu_cfg_t::ceu, internal_ceu_cfg_valid(), k_ra8_err_null_ptr, k_ra8_ok, ra8_camera_source_ceu_cfg_t::output, ra8_camera_source_ceu_cfg_t::poll_attempts, ra8_camera_source_ceu_cfg_t::poll_interval_ms, ra8_ceu_init(), and s_ceu_source_iface.

Referenced by c6_cam_camera_init(), cam_capture_source_bind(), and internal_bring_up_capture_pipeline().

Variable Documentation

◆ s_ceu_source_iface

const ra8_camera_source_iface_t s_ceu_source_iface

static

Initial value:

                                                          = {
  .get_info = internal_ceu_get_info,
  .capture  = internal_ceu_capture,
}

Definition at line 239 of file ra8_camera_source_ceu.c.

Referenced by ra8_camera_source_ceu_init().

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_camera_ceu_alignment_t

◆ ra8_camera_ceu_event_t

Function Documentation

◆ internal_ceu_capture()

◆ internal_ceu_cfg_valid()

◆ internal_ceu_frame_bytes()

◆ internal_ceu_get_info()

◆ internal_ceu_wait_for_frame()

◆ ra8_camera_source_ceu_get_last_events()

◆ ra8_camera_source_ceu_init()

Variable Documentation

◆ s_ceu_source_iface