PDC HAL Module Introduction
- PDC HAL Module Features
- PDC Hardware Support dDetails
PDC HAL Module APIs Overview
PDC HAL Module Operational Overview
- PDC HAL Module Important Operational Notes and Limitations
  - PDC HAL Module Operational Notes
  - PDC HAL Module Limitations
Including the PDC HAL Module in an Application
Configuring the PDC HAL Module
Using the PDC HAL Module in an Application

PDC HAL Module Introduction

The Parallel Data Capture Unit (PDC) HAL module provides a high-level API to capture images from a camera application and uses the PDC peripheral on the Synergy MCU. A user-defined callback can be created to inform the CPU when a capture has been completed.

PDC HAL Module Features

Supports capture from a connected and configured camera.
Supports a callback that informs the CPU when a capture is complete.
Provides a pointer to the capture buffer.
Provides an indication of the event triggering the callback.

PDC HAL Module Block Diagram

PDC Hardware Support dDetails

The following hardware features are, or are not, supported by SSP for PDC:

Legend:

Symbol	Meaning
✓	Available (Tested)
⌧	Not Available (Not tested/not functional or both)
N/A	Not supported by MCU

MCU Group	Supports up to 4095 lines vertical	Supports 4 to 4095 bytes horizontal	Accepts interrupts from Receive Data Ready	Accepts interrupts from Frame End	Accepts interrupts from Overrun	Accepts interrupts from Underrun
S124	N/A	N/A	N/A	N/A	N/A	N/A
S128	N/A	N/A	N/A	N/A	N/A	N/A
S1JA	N/A	N/A	N/A	N/A	N/A	N/A
S3A1	N/A	N/A	N/A	N/A	N/A	N/A
S3A3	N/A	N/A	N/A	N/A	N/A	N/A
S3A6	N/A	N/A	N/A	N/A	N/A	N/A
S3A7	N/A	N/A	N/A	N/A	N/A	N/A
S5D3	N/A	N/A	N/A	N/A	N/A	N/A
S5D5	✓	✓	✓	✓	✓	✓
S5D9	✓	✓	✓	✓	✓	✓
S7G2	✓	✓	✓	✓	✓	✓

MCU Group	Accepts interrupts from Error in wrong number of lines	Accepts interrupts from Error in wrong number of bytes per line	Frame end and receive data ready interrupts can start DTC	Frame end and receive data ready interrupts can start DMAC	Frequency division ratio: Selectable from 2, 4, 6, 8, 10, 12, 14, and 16	Supports PDC Reset Function
S124	N/A	N/A	N/A	N/A	N/A	N/A
S128	N/A	N/A	N/A	N/A	N/A	N/A
S1JA	N/A	N/A	N/A	N/A	N/A	N/A
S3A1	N/A	N/A	N/A	N/A	N/A	N/A
S3A3	N/A	N/A	N/A	N/A	N/A	N/A
S3A6	N/A	N/A	N/A	N/A	N/A	N/A
S3A7	N/A	N/A	N/A	N/A	N/A	N/A
S5D3	N/A	N/A	N/A	N/A	N/A	N/A
S5D5	✓	✓	⌧	⌧	⌧	⌧
S5D9	✓	✓	⌧	⌧	⌧	⌧
S7G2	✓	✓	⌧	⌧	⌧	⌧

MCU Group	Supports Selectable active polarity for VSYNC and HSYNC signals	Supports Monitoring of VSYNC and HSYNC signals	Endian order selectable
S124	N/A	N/A	N/A
S128	N/A	N/A	N/A
S1JA	N/A	N/A	N/A
S3A1	N/A	N/A	N/A
S3A3	N/A	N/A	N/A
S3A6	N/A	N/A	N/A
S3A7	N/A	N/A	N/A
S5D3	N/A	N/A	N/A
S5D5	✓	✓	✓
S5D9	✓	✓	✓
S7G2	✓	✓	✓

PDC HAL Module APIs Overview

The PDC HAL module defines APIs for opening, closing and starting data capture. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of status return values follows the API summary table.

PDC HAL Module API Summary

Function Name	Example API Call and Description
open	`g_pdc.p_api->open(g_pdc.p_ctrl, g_pdc.p_cfg)` Initial configuration.
close	`g_pdc.p_api->close(g_pdc.p_ctrl))` Closes the driver and allows reconfiguration. May reduce power consumption.
captureStart	`g_pdc.p_api->captureStart(g_pdc.p_ctrl, NULL)` Start a capture.
stateGet	`g_pdc.p_api->stateGet(g_pdc.p_ctrl, &state_data)` Get the state of VSYNC and HSYNC pins.
versionGet	`g_pdc.p_api->versionGet(&version)` Return the API version using the version pointer.

Note: For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures, and function variables, review the SSP User's Manual API References for the associated module.

Status Return Values

Name	Description
SSP_SUCCESS	API Call Successful.
SSP_ERR_ASSERTION	The parameter p_ctrl or p_sample is NULL.
SSP_ERR_INVALID_ARGUMENT	Parameter has invalid value.
SSP_ERR_NOT_OPEN	Unit is not open.
SSP_ERR_ALREADY_OPEN	Unit is already open.
SSP_ERR_HW_LOCKED	Unable to reserve BSP hardware lock.
SSP_ERR_TIMEOUT	Reset Operation timed out.

Note: Lower-level drivers may return common error codes. Refer to the SSP User's Manual API References for the associated module for a definition of all relevant status return values.

PDC HAL Module Operational Overview

The capture operation requires a configured external camera connected to the Synergy microcontroller. Before performing a capture, the camera must be configured and it must generate a PIXCLK-clock input into the microcontroller. In some instances, a camera requires a running-clock input before it can be configured.

Use the call pdc_api_t::open API (which configures and starts the PCKO-clock output from the PDC into the camera) before initializing the camera. Once the camera is configured, the pdc_api_t::captureStart can be called to capture an image. Configuration of a camera module may require the use of an I²C or SPI interface.

PDC HAL Module Important Operational Notes and Limitations

PDC HAL Module Operational Notes

In most instances, the data rate from a camera or the PDC peripheral is too fast to be serviced by the CPU in an interrupt service routine (ISR). Therefore, this module requires an implementation of the transfer driver on the DMAC to perform a high‑speed transfer from the PDC peripheral and memory.

Both the PDC frame-end and PDC error interrupts must be used to generate interrupts in the following situations:

An interrupt when an image is captured (frame end)
An interrupt when an error occurs

Data Buffer Setting

If p_buffer is set to anything other than NULL, one or more data buffers are created to store image data. The size of each buffer is calculated using the following formula:

Buffer size (bytes) = x_capture_pixels x y_capture_pixels x bytes_per_pixel

For large resolution cameras, the captured image could result in a large amount of data. It may be necessary to locate the buffer(s) in external memory (such as, SDRAM). Consideration should be given to bus bandwidth when using external memory.

For example, when using a high frame-rate camera to do an image capture via the PDC into SDRAM, and using SDRAM to hold the display buffer for an LCD display with a high refresh rate, may cause a data bottleneck from the PDC to memory that results in an overrun-error condition.

Note: If p_buffer is set to NULL, no memory is allocated to store the captured image data. The application must ensure that there is suitable memory of sufficient size available to the PDC. The PDC could capture directly into the display buffer of a connected LCD panel.

PDC HAL Module Limitations

Refer to the latest SSP Release Notes for any additional operational limitations for this module.

Including the PDC HAL Module in an Application

This section describes how to include the PDC HAL Module in an application using the SSP configurator.

Note: This section assumes you are familiar with creating a project, adding threads, adding a stack to a thread and configuring a block within the stack. If you are unfamiliar with any of these items, refer to the first few chapters of the SSP User's Manual to learn how to manage each of these important steps in creating SSP-based applications.

To add the PDC Driver to an application, simply add it to a thread using the stacks selection sequence given in the following table. (The default name for the PDC Driver is g_pdc0. This name can be changed in the associated Properties window.)

PDC HAL Module Selection Sequence

Resource	ISDE Tab	Stacks Selection Sequence
g_pdc0 PDCDriver on r_pdc	Threads	New Stack> Driver> Graphics> PDC Driver on r_pdc

When the PDC Driver on r_pdc is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.

PDC HAL Module Stack

Configuring the PDC HAL Module

The PDC HAL Module must be configured by the user for the desired operation. The available configuration settings and defaults for all the user-accessible properties are given in the properties tab within the SSP configurator and are shown in the following tables for easy reference. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.

Note: You may want to open your ISDE, create the module and explore the property settings in parallel with looking over the following configuration table settings. This will help orient you and can be a useful 'hands-on' approach to learning the ins and outs of developing with SSP.

Configuration Settings for the PDC HAL Module on r_pdc

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Enable or disable the parameter error checking.
Name	g_pdc0	The name of the PDC module instance. Specify arbitrary C symbol.
Name of the data buffer to store image data	g_user_buffer	Specify the name of the data buffer to create or set to NULL if it is to be created by the user external to the PDC driver.
Section where data buffer is allocated	sdram	Specify the RAM section for the image data buffer. Typically bss (internal RAM) or sdram.
Number of bytes per pixel	2	Specify the number of bytes per pixel of the captured image data.
Number of image data buffers	1	Specify the number of buffers to create.
Clock Divider	CLK/2, CLK/4, CLK/6, CLK/8, CLK10, CLK12, CLK14, CLK16 Default: CLK/2	Specify the clock divider of the clock input to the PDC peripheral.
Endian of image data	Little, Big Default: Little	Specify the endian of the captured image data.
HYSNC signal polarity	High, Low Default: High	Specify the active polarity of the HSYNC signal.
VSYNC signal polarity	High, Low Default: High	Specify the active polarity of the VSYNC signal.
Number of pixels to capture horizontally	640	Number of horizontal pixels to capture.
Number of pixels to capture vertically	480	Number of vertical lines to capture.
Horizontal pixel to start capture from	0	Horizontal pixel to start capturing image data from. Allows an image smaller than the native resolution of a camera to be captured.
Line to start capture from	0	Vertical line to start capturing image data from. Allows an image smaller than the native resolution of a camera to be captured.
Callback	g_pdc_user_callback	A user callback function can be registered in open. If this callback function is provided, it is called from the interrupt service routine (ISR) each time a frame is captured and ready to be processed. Warning: Since the callback is called from an ISR, care should be taken not to use blocking calls or lengthy processing. Spending excessive time in an ISR can affect the responsiveness of the system.
Frame End Interrupt Priority	Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX) Default: Disabled	The driver needs a valid interrupt priority setting. It will not function if disabled.
PDC Interrupt Priority	Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX) Default: Disabled	The driver needs a valid interrupt priority setting. It will not function if disabled.

Note: The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

Configuration Settings for the PDC HAL Module Lower-Lever Module

Typically, only a small number of settings must be modified from the default for lower level drivers as indicated via the Red text in the Thread Stack block. Notice that some of the configuration properties must be set to a certain value for proper framework operation and will be locked to prevent user modification. The following table identifies all the settings within the properties section for the module:

Configuration Settings for the Transfer Driver on r_dmac Event PDC RECEIVE DATA READY

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Parameter selection.
Name	g_transfer0	Driver name.
Mode	Block	Mode selection.
Transfer Size	4 Bytes	Transfer size selection.
Destination Address Mode	Incremented	Destination address mode selection.
Source Address Mode	Fixed	Source address mode selection.
Repeat Area (Unused in Normal Mode	Source	Repeat area selection.
Destination Pointer	NULL	Destination pointer selection.
Source Pointer	NULL	Source pointer selection.
Number of Transfers	8	Number of transfers selection.
Number of Blocks (Valid only in Block Mode)	1	Number of blocks selection.
Activation Source (Must enable IRQ)	Event PDC RECEIVE DATA READY	Activation source selection.
Auto Enable	FALSE	Auto enable selection.
Callback (Only valid with Software start)	NULL	Callback selection.
Interrupt Priority	Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX) Default: Disabled	Interrupt priority selection.

Note: The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

PDC HAL Module Clock Configuration

The PDC uses the PCLKB as its clock source. The only restriction when configuring this clock is that the PIXCLCK should be less than 0.6 x PCLKB so the PCLKB frequency should be set accordingly.

PDC HAL Module Pin Configuration

The PDC peripheral module uses pins on the MCU to communicate to external devices. I/O pins must be selected and configured as required by the external device. The following table depicts the method to select pins within the SSP configuration window and the subsequent table gives an example selection for PDC pins:

Pin Selection for the PDC HAL Module on r_pdc

Resource	ISDE Tab	Pin selection Sequence
PDC	Pins	Select Peripherals> Graphics: PDC> PDC0

Note: The selection sequence assumes KINT0 is the desired hardware target for the driver.

Pin Configuration Settings for the PDC HAL Module on r_pdc

Property	Value	Description
Pin Group Selection	Mixed, _A Only Default: Mixed	Pin group selection.
Operation Mode	Disabled, Custom, Enabled Default: Disabled	Select Enabled as the Operation Mode for PDC.
HSYNC	None, P704 Default: None	HSYNC Pin.
PCKO	None, P511 Default: P511	PCKO Pin.
PIXCLK	None, P705 Default: None	PIXCLK Pin.
VSYNC	None, P512 Default: P512	VSNC Pin.
PIXD0:7	None, Pnnn Default: None	PIX Data0:7 Pins.

Note: The example settings are for a project using the Synergy S7G2 MCU Group and the SK-S7G2 Kit. Other Synergy MCUs and Synergy Kits may have different available pin configuration settings.

Using the PDC HAL Module in an Application

The typical steps in using the PDC HAL module in an application are:

Initialize the PDC HAL module using the pdc_api_t::open API.
Configure the camera as needed.
Start image capture using the pdc_api_t::captureStart API.
Callback is called when image is captured.
Read state of HSYNC and VSTNC using pdc_api_t::stateGet API.
Process data as needed.
Close using the pdc_api_t::close API.

These common steps are illustrated in a typical operational flow diagram in the following figure:

Flow Diagram of a Typical PDC HAL Module Application

Table of Contents