Capture Engine Unit (r_ceu)

Functions
fsp_err_t	R_CEU_Open (capture_ctrl_t *const p_ctrl, capture_cfg_t const *const p_cfg)
fsp_err_t	R_CEU_Close (capture_ctrl_t *const p_ctrl)
fsp_err_t	R_CEU_CaptureStart (capture_ctrl_t *const p_ctrl, uint8_t *const p_buffer)
fsp_err_t	R_CEU_CallbackSet (capture_ctrl_t *const p_ctrl, void(*p_callback)(capture_callback_args_t *), void *const p_context, capture_callback_args_t *const p_callback_memory)
fsp_err_t	R_CEU_StatusGet (capture_ctrl_t *const p_ctrl, capture_status_t *p_status)

Detailed Description

Driver for the CEU peripheral on RA MCUs. This module implements the CAPTURE Interface.

Overview

The CEU peripheral supports interfacing with external cameras by accepting timing and data signals in order to capture incoming data. A callback is invoked for each V-Sync event, frame of data accepted, or when certain errors occur.

Features

• Supports 8 or 16-bit camera bus
• Capture images up to 5 MP (2560x1920)
• Capture incoming data directly into a user defined memory location without the need for DTC/DMAC
• Capture specified size 'raw' image data using Data Synchronous Fetch Mode (e.g. RGB565, YUV422, etc.)
• Capture binary image data using Data Enable Fetch Mode (e.g. JPEG)
• Capture YCbCr image data using Image Capture Mode
  • Optional hardware conversion from YCbCr422 to YCbCr420
  • Optional scale down
• Perform basic timing signal validation

Configuration

Build Time Configurations for r_ceu

The following build time configurations are defined in fsp_cfg/r_ceu_cfg.h:

Configuration	Options	Default	Description
Parameter Checking	Default (BSP) Enabled Disabled	Default (BSP)	If selected code for parameter checking is included in the build.

Configurations for Graphics > Capture Engine Unit (r_ceu)

This module can be added to the Stacks tab via New Stack > Graphics > Capture Engine Unit (r_ceu). Non-secure callable guard functions can be generated for this module by right clicking the module in the RA Configuration tool and checking the "Non-secure Callable" box.

Configuration	Options	Default	Description
General
Name	Name must be a valid C symbol	g_ceu0	Module name.
Input
Input > Data Bus Specifications
Data Bus Size	MCU Specific Options		Data bus-width of CEU physical connection.
HSYNC Polarity	High Low	High	Specify the active polarity of the HSYNC signal.
VSYNC Polarity	High Low	High	Specify the active polarity of the VSYNC signal.
Input > Capture Specifications
Input > Capture Specifications > Sample Points
Data Sample Point	Rising edge of the camera clock Falling edge of the camera clock	Rising edge of the camera clock	Specify the external camera clock transition state for fetching the image data (D15 to D0) from the external module.
H-Sync Sample Point	Rising edge of the camera clock Falling edge of the camera clock	Rising edge of the camera clock	Specify the external camera clock transition state for capturing H-Sync from the external module.
V-Sync Sample Point	Rising edge of the camera clock Falling edge of the camera clock	Rising edge of the camera clock	Specify the external camera clock transition state for capturing V-Sync from the external module.
Horizontal capture resolution	Value must be an integer.	640	Specify the number of horizontal pixels to capture.
Vertical capture resolution	Value must be an integer.	480	Specify the number of vertical pixels to capture.
Horizontal pixel offset	Value must be an integer.	0	Number of pixels from H-sync signal up to the start of a valid data period.
Vertical pixel offset	Value must be an integer.	0	Specify the vertical line to start capturing image data.
Capture Mode	Image Capture Data Synchronous Fetch Data Enable Fetch	Data Synchronous Fetch	Capture mode of incoming data.
Image Component Input Order (Image Capture Mode Only)	Cb0, Y0, Cr0, Y1 Cr0, Y0, Cb0, Y1 Y0, Cb0, Y1, Cr0 Y0, Cr0, Y1, Cb0	Cb0, Y0, Cr0, Y1	Set the input order of the luminance component and chrominance component (Image Capture Mode only). This setting must match your camera's output format.
Output
Output > Format
Conversion	YCbCr422 (No Conversion) YCbCr420 (Hardware Conversion from YCbCr422)	YCbCr422 (No Conversion)	Set the output format for captured CEU data. This setting is applicable in Image Capture Mode only.
Output > Scale-Down
Horizontal Size	Value must be an integer.	0	Specify the scaled down output image horizontal size (pixels). This setting is applicable in Image Capture Mode only. If set to 0, horizontal scale-down is disabled.
Vertical Size	Value must be an integer.	0	Specify the scaled down output image vertical size (lines). This setting is applicable in Image Capture Mode only. If set to 0, vertical scale-down is disabled.
Output > Buffer
Data Enable Buffer Size	Value must be a positive integer.	0	Specify size of image region available for use by CEU data bus. (Only applicable to Data Enable Fetch capture mode)
Byte Swapping	Swap 8-bit units Swap 16-bit units Swap 32-bit units		Byte swapping configuration. Bytes may be swapped in 8-bit, 16-bit, or 32-bit units.
Burst Transfer Mode	Transfer in 32-byte units Transfer in 64-byte units Transfer in 128-byte units Transfer in 256-byte units	Transfer in 256-byte units	Specify the unit for transferring data to the bus bridge module.
Interrupts
Interrupts > Selectable CEU Events
One-Frame Capture End Event	Enabled Disabled	Enabled	Capturing one frame from an external module has finished.
Horizontal Sync Event	Enabled Disabled	Disabled	Horizontal sync signal was input from an external module.
Vertical Sync Event	Enabled Disabled	Enabled	Vertical sync signal was input from an external module.
CRAM Buffer Overflow Error	Enabled Disabled	Enabled	Data overflowed in the CRAM write buffer.
H-Sync Validation Error	Enabled Disabled	Disabled	The number of configured H-sync cycles is different than the H-sync cycles input from the external module.
V-Sync Validation Error	Enabled Disabled	Disabled	The number of configured V-sync cycles is different than the V-sync cycles input from the external module.
V-Sync Error	Enabled Disabled	Enabled	V-sync has been input while CEU holds data (insufficient vertical-sync front porch).
No H-Sync error	Enabled Disabled	Enabled	No H-sync signal was input.
No V-Sync error	Enabled Disabled	Enabled	No V-sync signal was input.
Callback	Name must be a valid C symbol.	g_ceu0_user_callback	A user callback function must be provided. This callback is invoked for every successful frame capture as well as other status or error conditions.
CEU Interrupt Priority	MCU Specific Options		Select the CEU interrupt priority.

Clock Configuration

The CEU peripheral is clocked both from PCLKA and externally, from the camera module (VIO_CLK). The external input clock (VIO_CLK) should have a frequency at most the same as the CEU operating clock (PCLKA) frequency, with jitter on both sides included. The PCLKA frequency may be set using the Clocks tab of the RA Configuration editor or by using the CGC Interface at run-time.

Note

At least 10 external clock cycles (VIO_CLK) must elapse after opening the CEU module, before starting a capture.

Pin Configuration

The VIO_CLK pin is a clock input to the MCU and should be connected to the clock output from the camera. The VIO_HD and VIO_VD pins must be connected to the horizontal and vertical sync signal output of the camera respectively. The VIO_D0 to VIO_D15 pins are the data bus input pins and should be connected to the relevant output pins of the camera. For 8-bit camera data bus VIO_D0 to VIO_D7 should be used.

Note

Camera control and serial communication pins must be configured separately and are not controlled by this module.

Capture Resolution

• For Data Synchronous Fetch Mode and Image Capture Mode, capture size is calculated using the configured Horizontal Resolution, Vertical Resolution, and Bytes Per Pixel.
• For Data Enable Fetch Mode, the capture size is controlled by the external module and is defined as a period from a VD rising edge to the VD falling edge. For this mode Horizontal Resolution and Vertical Resolution are not used. However, the maximum capture size is configured using the 'Data Enable Buffer Size' option, which is used to configure the maximum write 'Firewall Address' location.

Note

For Data Enable Fetch Mode, the external module must transmit data in 4-byte units.

Capture Offset

The blanking period from a horizontal or vertical sync signal differs among external modules. Therefore, the capture start location must be specified in terms of external cycles from the sync signal so that an image can be captured from the valid image area. Some external modules output a horizontal sync signal as a data enable signal. In this case, there is no blanking period so the configured offsets must be cleared to 0.

• The horizontal capture start location must be specified in terms of the number of pixels from a horizontal sync signal.
• The vertical capture start location must be specified in terms of the number of H-cycles from a vertical sync signal.

Note

Capture offset is not used when Data Enable Fetch Mode is configured.

Scale Down

Scale down is configured by setting Output > Scale-Down properties to the desired output image dimensions in the configurator. When the configured output image size is less than the output input image size, the image will be scaled down to the output size before writing the data to memory.

The configurator automatically calculates the appropriate capture filter register scaling settings based on the requested output size. The filter output must be a multiple of 4 (vertical lines) or 8 (horizontal pixels).

Note

Hardware scale-down is available only in Image Capture Mode.

See also: Scale Down Limitations.

Usage Notes

Interrupt Configuration

• CEU V-sync, capture-end, and error interrupts are used by this module for reporting capture status and error events such as overrun, vertical line number setting and other capture errors.

Note

If both a capture complete event and capture error event occur simultaneously, the capture complete event should be disregarded.

CEU Setup With External Camera

• Ensure that the memory pointed to by p_buffer is both valid and large enough to store a complete image.
• Ensure that the capture buffer address is 4-byte aligned and the buffer size is divisible by 32 bytes.

Note

Any required configuration for external cameras must be performed by the application.

Notes on Buffer Allocation in Data Synchronous Fetch Mode

• When Data Synchronous Fetch Mode is configured, the amount of space required (in bytes) may be calculated as size (bytes) = image width (pixels) * image height (lines) * number of bytes per pixel.

Notes on Buffer Allocation in Image Capture Mode

Image Capture Mode captures luminance (Y) and chrominance (Cb/Cr) components of the image in separate memory locations and can be selected by the Input > Capture Mode property.

• The Y and Cb/Cr buffers must be contiguously allocated in memory, with the chrominance buffer located immediately after the luminance buffer.
• The size of the luminance buffer in bytes should be the image width (pixels) * image height (lines) * 2.
• The size of the chrominance buffer varies depending on whether YCbCr420 format conversion is enabled
  • YCbCr422 (no conversion): Same size as luminance buffer
  • YCbCr420 (format conversion enabled): Half size of luminance buffer
• Pass the contiguous buffer pointer to R_CEU_CaptureStart. The firmware will automatically calculate the chrominance buffer address based on the expected luminance data size.

YCbCr422 Buffer Example in Image Capture Mode

/* Allocation example */
#define LUMINANCE_BUFFER_SIZE_BYTES      (IMAGE_WIDTH * IMAGE_HEIGHT)
#define CHROMINANCE_BUFFER_SIZE_BYTES    (LUMINANCE_BUFFER_SIZE_BYTES)

__ALIGNED(32) uint8_t buffer_ycbcr422[LUMINANCE_BUFFER_SIZE_BYTES +
                                      CHROMINANCE_BUFFER_SIZE_BYTES] __attribute__((section(BSP_UNINIT_SECTION_PREFIX
                                                                                            ".sdram_noinit")));

/* Access example */
uint8_t * p_luma_ycbcr422   = &buffer_ycbcr422[0];
uint8_t * p_chroma_ycbcr422 = &buffer_ycbcr422[LUMINANCE_BUFFER_SIZE_BYTES];

YCbCr420 Buffer Example in Image Capture Mode

/* Allocation example */
#define LUMINANCE_BUFFER_SIZE_BYTES      (IMAGE_WIDTH * IMAGE_HEIGHT)
#define CHROMINANCE_BUFFER_SIZE_BYTES    (LUMINANCE_BUFFER_SIZE_BYTES / 2)

__ALIGNED(32) uint8_t buffer_ycbcr420[LUMINANCE_BUFFER_SIZE_BYTES +
                                      CHROMINANCE_BUFFER_SIZE_BYTES] __attribute__((section(BSP_UNINIT_SECTION_PREFIX
                                                                                            ".sdram_noinit")));

/* Access example */
uint8_t * p_luma_ycbcr420   = &buffer_ycbcr420[0];
uint8_t * p_chroma_ycbcr420 = &buffer_ycbcr420[LUMINANCE_BUFFER_SIZE_BYTES];

Limitations

Scale Down Limitations

• Scale down is available only in Image Capture Mode
• When the input image is larger than VGA (640×480) the output image size must be between SubQCIF (128×96) and VGA (640×480), inclusive.
• The scaled output image cannot be larger than VGA, regardless of input size
• Images cannot be scaled down by more than 1/16

Examples

Basic Example

This is a basic example of minimal use of the CEU in an application. This example shows how this driver can be used for capturing data from an external I/O device such as an image sensor.

bool g_ceu_capture_error;
bool g_ceu_capture_complete;

void ceu_minimal_example (void)
{
    fsp_err_t err = FSP_SUCCESS;

    g_ceu_capture_error    = false;
    g_ceu_capture_complete = false;

    err = R_CEU_Open(&g_ceu0_ctrl, &g_ceu0_cfg);
    assert(FSP_SUCCESS == err);


    err = R_CEU_CaptureStart(&g_ceu0_ctrl, g_user_buffer);
    assert(FSP_SUCCESS == err);


    while (!g_ceu_capture_complete && !g_ceu_capture_error)
    {
        /* Wait for capture to complete. */
    }

/* Process image here if capture was successful. */

    err = R_CEU_Close(&g_ceu0_ctrl);
    assert(FSP_SUCCESS == err);

}

void ceu_callback (capture_callback_args_t * p_args)
{
    /* Multiple event flags may be set simultaneously */
    if (p_args->event & (uint32_t) ~(CEU_EVENT_HD | CEU_EVENT_VD | CEU_EVENT_FRAME_END))
    {
        /* Error processing should occur first. Application should not process complete event if error occurred. */
        g_ceu_capture_error = true;
    }
    else
    {
        if (p_args->event & CEU_EVENT_VD)
        {
            /* Capture has started. Process V-Sync event. */
        }

        if (p_args->event & CEU_EVENT_FRAME_END)
        {
            /* Capture is complete and no error has occurred */
            g_ceu_capture_complete = true;
        }
    }
}

Data Structures
struct	ceu_byte_swapping_t
struct	ceu_edge_info_t
struct	ceu_extended_cfg_t
struct	ceu_instance_ctrl_t

Enumerations
enum	ceu_capture_mode_t
enum	ceu_data_bus_size_t
enum	ceu_hsync_polarity_t
enum	ceu_vsync_polarity_t
enum	ceu_burst_transfer_mode_t
enum	ceu_event_t
enum	ceu_capture_format_t
enum	ceu_input_order_t
enum	ceu_output_format_t

---

Data Structure Documentation

ceu_byte_swapping_t

struct ceu_byte_swapping_t

Swap bits configuration

Data Fields
uint8_t	swap_8bit_units: 1	Byte swapping in 8-bit units.
uint8_t	swap_16bit_units: 1	Byte swapping in 16-bit units.
uint8_t	swap_32bit_units: 1	Byte swapping in 32-bit units.

ceu_edge_info_t

struct ceu_edge_info_t

Edge information for latching signals

Data Fields
uint8_t	dsel: 1	Sets the edge for fetching the image data (D15 to D0) from an external module.
uint8_t	hdsel: 1	Sets the edge for capturing hd from external module.
uint8_t	vdsel: 1	Sets the edge for capturing vd from external module.

ceu_extended_cfg_t

struct ceu_extended_cfg_t

Extended configuration structure for CEU.

Data Fields
ceu_capture_format_t	capture_format	Capture format for incoming data.
ceu_input_order_t	input_order	Input Y and CbCr order (Used for image capture mode)
ceu_output_format_t	output_format	Output format for storing to memory (Used for image capture mode)
ceu_data_bus_size_t	data_bus_width	Size of camera data bus.
ceu_edge_info_t	edge_info
ceu_hsync_polarity_t	hsync_polarity	Polarity of HSYNC input.
ceu_vsync_polarity_t	vsync_polarity	Polarity of VSYNC input.
uint32_t	image_area_size	Image capture size. Used when setting firewall address for Data Enable Fetch mode.
ceu_byte_swapping_t	byte_swapping	Controls byte swapping in 8-bit, 16-bit and 32-bit units.
ceu_burst_transfer_mode_t	burst_mode	Bus transfer data size.
uint32_t	scale_down_factor	Scale down capture filter register setting (Used for image capture mode)
uint16_t	h_output_size	Output image horizontal size, in pixels (Used for image capture mode)
uint16_t	v_output_size	Output image vertical size, in lines (Used for image capture mode)
uint32_t	interrupts_enabled	Enabled interrupt events bit mask.
uint8_t	ceu_ipl	PDC interrupt priority.
IRQn_Type	ceu_irq	PDC IRQ number.

ceu_instance_ctrl_t

struct ceu_instance_ctrl_t

CEU instance control block. DO NOT INITIALIZE.

Enumeration Type Documentation

ceu_capture_mode_t

enum ceu_capture_mode_t

Capture mode

Enumerator
CEU_CAPTURE_MODE_SINGLE	Single image capture.
CEU_CAPTURE_MODE_CONTINUOUS	Continuous image capture.

ceu_data_bus_size_t

enum ceu_data_bus_size_t

Data bus width

Enumerator
CEU_DATA_BUS_SIZE_8_BIT	Data bus is 8-bit.
CEU_DATA_BUS_SIZE_16_BIT	Data bus is 16-bit.

ceu_hsync_polarity_t

enum ceu_hsync_polarity_t

Polarity of input HSYNC signal

Enumerator
CEU_HSYNC_POLARITY_HIGH	HSYNC signal is active high.
CEU_HSYNC_POLARITY_LOW	HSYNC signal is active low.

ceu_vsync_polarity_t

enum ceu_vsync_polarity_t

Polarity of input VSYNC signal

Enumerator
CEU_VSYNC_POLARITY_HIGH	VSYNC signal is active high.
CEU_VSYNC_POLARITY_LOW	VSYNC signal is active low.

ceu_burst_transfer_mode_t

enum ceu_burst_transfer_mode_t

Enumerator
CEU_BURST_TRANSFER_MODE_X1	Transferred to the bus in 32-byte units */.
CEU_BURST_TRANSFER_MODE_X2	Transferred to the bus in 64-byte units */.
CEU_BURST_TRANSFER_MODE_X4	Transferred to the bus in 128-byte units */.
CEU_BURST_TRANSFER_MODE_X8	Transferred to the bus in 256-byte units */.

ceu_event_t

enum ceu_event_t

Enumerator
CEU_EVENT_FRAME_END	Frame end event (CPE)
CEU_EVENT_HD	(Not Used) HD received (HD)
CEU_EVENT_VD	VD received (VD)
CEU_EVENT_CRAM_OVERFLOW	Data overflowed in the CRAM buffer (CDTOF)
CEU_EVENT_HD_MISMATCH	HD mismatch (IGHS)
CEU_EVENT_VD_MISMATCH	VD mismatch (IGVS)
CEU_EVENT_VD_ERROR	Invalid VD condition (VBP)
CEU_EVENT_FIREWALL	Data write address exceeds firewall (FWF)
CEU_EVENT_HD_MISSING	HD was expected but not input (NHD)
CEU_EVENT_VD_MISSING	VD was expected but not input (NVD)

ceu_capture_format_t

enum ceu_capture_format_t

Capture mode for CEU.

Enumerator
CEU_CAPTURE_FORMAT_IMAGE_CAPTURE	YCbCr data.
CEU_CAPTURE_FORMAT_DATA_SYNCHRONOUS	Raw formatted data.
CEU_CAPTURE_FORMAT_DATA_ENABLE	JPG formatted data.

ceu_input_order_t

enum ceu_input_order_t

Set the input order of the luminance component and chrominance component (Y and CbCr). Used for image capture mode only.

Enumerator
CEU_INPUT_ORDER_CB0Y0CR0Y1	Image input data is fetched in the order of Cb0, Y0, Cr0, Y1.
CEU_INPUT_ORDER_CR0Y0CB0Y1	Image input data is fetched in the order of Cr0, Y0, Cb0, Y1.
CEU_INPUT_ORDER_Y0CB0Y1CR0	Image input data is fetched in the order of Y0, Cb0, Y1, Cr0.
CEU_INPUT_ORDER_Y0CR0Y1CB0	Image input data is fetched in the order of Y0, Cr0, Y1, Cb0.

ceu_output_format_t

enum ceu_output_format_t

Format for outputting captured CEU data to memory.

Enumerator
CEU_OUTPUT_FORMAT_YCBCR420	Output the data in YCbCr 4:2:0 format (hardware conversion from YCbCr 4:2:2)
CEU_OUTPUT_FORMAT_YCBCR422	Output the data in YCbCr 4:2:2 format (no conversion)

Function Documentation

R_CEU_Open()

fsp_err_t R_CEU_Open	(	capture_ctrl_t *const	p_ctrl,
		capture_cfg_t const *const	p_cfg
	)

CEU module initialization.

Implements capture_api_t::open

The function provides initial configuration for the CEU module. Further initialization may be performed in capture_api_t::captureStart. This function should be called once prior to calling any other CEU API functions. After the CEU is opened the Open function should not be called again without first calling the Close function.

Example:

    err = R_CEU_Open(&g_ceu0_ctrl, &g_ceu0_cfg);
    assert(FSP_SUCCESS == err);

Return values

FSP_SUCCESS	Initialization was successful.
FSP_ERR_ASSERTION	One or more parameters is NULL.
FSP_ERR_ALREADY_OPEN	Module is already open.

R_CEU_Close()

fsp_err_t R_CEU_Close

(

capture_ctrl_t *const

p_ctrl

)

Stops and closes the transfer interface.

Implements capture_api_t::close

Stops any active captures, clears internal driver state-data, disables interrupts, and powers off the CEU peripheral.

Example:

    err = R_CEU_Close(&g_ceu0_ctrl);
    assert(FSP_SUCCESS == err);

Return values

FSP_SUCCESS	Initialization was successful.
FSP_ERR_ASSERTION	One or more parameters is NULL.
FSP_ERR_NOT_OPEN	Open has not been successfully called.

R_CEU_CaptureStart()

fsp_err_t R_CEU_CaptureStart	(	capture_ctrl_t *const	p_ctrl,
		uint8_t *const	p_buffer
	)

Starts a capture.

Implements capture_api_t::captureStart.

Sets up the interface to transfer data from the CEU into the specifiec buffer. Configures the CEU settings as previously set by the capture_api_t::open API. When a capture is complete the callback registered during capture_api_t::open API call or by capture_api_t::callbackSet API will be called.

Example:

    err = R_CEU_CaptureStart(&g_ceu0_ctrl, g_user_buffer);
    assert(FSP_SUCCESS == err);

Return values

FSP_SUCCESS	Initialization was successful.
FSP_ERR_ASSERTION	One or more parameters is NULL.
FSP_ERR_NOT_OPEN	Open has not been successfully called.
FSP_ERR_INVALID_ADDRESS	Invalid buffer address alignment.
FSP_ERR_IN_USE	Capture is in progress.
FSP_ERR_INVALID_STATE	Capture is pending.
FSP_ERR_NOT_INITIALIZED	Callback function has not been set.

R_CEU_CallbackSet()

fsp_err_t R_CEU_CallbackSet	(	capture_ctrl_t *const	p_ctrl,
		void(*)(capture_callback_args_t *)	p_callback,
		void *const	p_context,
		capture_callback_args_t *const	p_callback_memory
	)

Updates the user callback and has option of providing memory for callback structure.

Implements capture_api_t::callbackSet.

Return values

FSP_SUCCESS	Initialization was successful.
FSP_ERR_ASSERTION	One or more parameters is NULL.
FSP_ERR_NOT_OPEN	Open has not been successfully called.
FSP_ERR_NO_CALLBACK_MEMORY	p_callback is non-secure and p_callback_memory is either secure or NULL.

R_CEU_StatusGet()

fsp_err_t R_CEU_StatusGet	(	capture_ctrl_t *const	p_ctrl,
		capture_status_t *	p_status
	)

Provides the ceu operating status.

Implements capture_api_t::statusGet.

Return values

FSP_SUCCESS	Initialization was successful.
FSP_ERR_ASSERTION	One or more parameters is NULL.
FSP_ERR_NOT_OPEN	Open has not been successfully called.