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
Supported Devices
| Device Group | Devices |
| RA8 | RA8D1, RA8D2, RA8E1, RA8M1, RA8M2, RA8P1 |
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 | Specify the active polarity of the HSYNC signal. |
| VSYNC Polarity |
| 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 | Capturing one frame from an external module has finished. |
| Horizontal Sync Event |
| Disabled | Horizontal sync signal was input from an external module. |
| Vertical Sync Event |
| Enabled | Vertical sync signal was input from an external module. |
| CRAM Buffer Overflow Error |
| Enabled | Data overflowed in the CRAM write buffer. |
| H-Sync Validation Error |
| Disabled | The number of configured H-sync cycles is different than the H-sync cycles input from the external module. |
| V-Sync Validation Error |
| Disabled | The number of configured V-sync cycles is different than the V-sync cycles input from the external module. |
| V-Sync Error |
| Enabled | V-sync has been input while CEU holds data (insufficient vertical-sync front porch). |
| No H-Sync error |
| Enabled | No H-sync signal was input. |
| No V-Sync error |
| 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
#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")));
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
#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")));
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)
{
g_ceu_capture_error = false;
g_ceu_capture_complete = false;
assert(FSP_SUCCESS == err);
assert(FSP_SUCCESS == err);
while (!g_ceu_capture_complete && !g_ceu_capture_error)
{
}
assert(FSP_SUCCESS == err);
}
{
{
g_ceu_capture_error = true;
}
else
{
{
}
{
g_ceu_capture_complete = true;
}
}
}
◆ ceu_byte_swapping_t
| struct ceu_byte_swapping_t |
| 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
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.
◆ 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
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
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
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
| 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
| 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
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
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
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)
|
◆ R_CEU_Open()
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:
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()
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:
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()
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:
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()
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()
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. |