Detailed Description

Camera driver interface.

The Camera header file should be included in an application as follows:

Overview

The Camera driver is used to retrieve the data being transferred by the Camera sensor. This driver provides an API for capturing the image from the Camera sensor. The camera sensor control and implementation are the responsibility of the application using the interface.

The Camera driver has been designed to operate in an RTOS environment. It protects its transactions with OS primitives supplied by the underlying RTOS.

Usage

The Camera driver includes the following APIs:

Camera_init(): Initialize the Camera driver.
Camera_Params_init(): Initialize a Camera_Params structure with default vaules.
Camera_open(): Open an instance of the Camera driver.
Camera_control(): Performs implemenation-specific features on a given Camera peripheral.
Camera_capture(): Capture a frame.
Camera_close(): De-initialize a given Camera instance.

Camera Driver Configuration

In order to use the Camera APIs, the application is required to provide device-specific Camera configuration in the Board.c file. The Camera driver interface defines a configuration data structure:

typedef struct {
    Camera_FxnTable const  *fxnTablePtr;
    void                   *object;
    void            const  *hwAttrs;
} Camera_Config;

The application must declare an array of Camera_Config elements, named Camera_config[]. Each element of Camera_config[] must be populated with pointers to a device specific Camera driver implementation's function table, driver object, and hardware attributes. The hardware attributes define properties such as the Camera peripheral's base address. Each element in Camera_config[] corresponds to a Camera instance, and none of the elements should have NULL pointers. There is no correlation between the index and the peripheral designation (such as Camera0 or Camera1). For example, it is possible to use Camera_config[0] for Camera1.

Because the Camera configuration is very device dependent, you will need to check the doxygen for the device specific Camera implementation. There you will find a description of the Camera hardware attributes. Please also refer to the Board.c file of any of your examples to see the Camera configuration.

Initializing the Camear Driver

The application initializes the Camera driver by calling Camera_init(). This function must be called before any other Camera API. Camera_init() iterates through the elements of the Camera_config[] array, calling the element's device implementation Camera initialization function.

Camera Parameters

The Camera_Params structure is passed to Camera_open(). If NULL is passed for the parameters, Camera_open() uses default parameters. A Camera_Params structure is initialized with default values by passing it to Camera_Params_init(). Some of the Camera parameters are described below. To see brief descriptions of all the parameters, see Camera_Params.

Camera Modes

The Camera driver operates in either blocking mode or callback mode:

Camera_MODE_BLOCKING: The call to Camera_capture() blocks until the capture has completed.
Camera_MODE_CALLBACK: The call to Camera_capture() returns immediately. When the capture completes, the Camera driver will call a user- specified callback function.

The capture mode is determined by the Camera_Params.captureMode parameter passed to Camera_open(). The Camera driver defaults to blocking mode, if the application does not set it.

Once a Camera driver instance is opened, the only way to change the capture mode is to close and re-open the Camera instance with the new capture mode.

Opening the driver

The following example opens a Camera driver instance in blocking mode:

Camera_Handle      handle;
Camera_Params      params;
Camera_Params_init(&params);
params.captureMode       =  Camera_MODE_BLOCKING;
< Change any other params as required >
handle = Camera_open(someCamera_configIndexValue, &params);
if (!handle) {
    // Error opening the Camera driver
}

Capturing an Image

The following code example captures a frame.

unsigned char captureBuffer[1920];
ret = Camera_capture(handle, &captureBuffer, sizeof(captureBuffer));

Implementation

This module serves as the main interface for RTOS applications. Its purpose is to redirect the module's APIs to specific peripheral implementations which are specified using a pointer to a Camera_FxnTable.

The Camera driver interface module is joined (at link time) to an array of Camera_Config data structures named Camera_config. Camera_config is implemented in the application with each entry being an instance of a Camera peripheral. Each entry in Camera_config contains a:

(Camera_FxnTable *) to a set of functions that implement a Camera peripheral
(void *) data object that is associated with the Camera_FxnTable
(void *) hardware attributes that are associated to the Camera_FxnTable

#include <stdint.h>
#include <stddef.h>

Include dependency graph for Camera.h:

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

Go to the source code of this file.

Data Structures
struct	Camera_Params
	Camera Parameters. More...

struct	Camera_FxnTable
	The definition of a Camera function table that contains the required set of functions to control a specific Camera driver implementation. More...

struct	Camera_Config_
	Camera Global configuration. More...

Macros
#define	CAMERA_CMD_RESERVED (32)

#define	CAMERA_STATUS_RESERVED (-32)

#define	CAMERA_STATUS_SUCCESS (0)
	Successful status code returned by Camera_control(). More...

#define	CAMERA_STATUS_ERROR (-1)
	Generic error status code returned by Camera_control(). More...

#define	CAMERA_STATUS_UNDEFINEDCMD (-2)
	An error status code returned by Camera_control() for undefined command codes. More...

#define	Camera_WAIT_FOREVER (~(0U))
	Wait forever define. More...

Typedefs
typedef struct Camera_Config_ *	Camera_Handle
	A handle that is returned from a Camera_open() call. More...

typedef void(*	Camera_Callback) (Camera_Handle handle, void *buf, size_t frameLength)
	The definition of a callback function used by the Camera driver when used in Camera_MODE_CALLBACK. More...

typedef void(*	Camera_CloseFxn) (Camera_Handle handle)
	A function pointer to a driver specific implementation of Camera_close(). More...

typedef int_fast16_t(*	Camera_ControlFxn) (Camera_Handle handle, uint_fast16_t cmd, void *arg)
	A function pointer to a driver specific implementation of Camera_control(). More...

typedef void(*	Camera_InitFxn) (Camera_Handle handle)
	A function pointer to a driver specific implementation of Camera_init(). More...

typedef Camera_Handle(*	Camera_OpenFxn) (Camera_Handle handle, Camera_Params *params)
	A function pointer to a driver specific implementation of Camera_open(). More...

typedef int_fast16_t(*	Camera_CaptureFxn) (Camera_Handle handle, void buffer, size_t bufferlen, size_t frameLen)
	A function pointer to a driver specific implementation of Camera_capture(). More...

typedef struct Camera_Config_	Camera_Config
	Camera Global configuration. More...

Enumerations
enum	Camera_CaptureMode { Camera_MODE_BLOCKING, Camera_MODE_CALLBACK }
	Camera capture mode settings. More...

enum	Camera_HSyncPolarity { Camera_HSYNC_POLARITY_HIGH = 0, Camera_HSYNC_POLARITY_LOW }
	Camera HSync polarity. More...

enum	Camera_VSyncPolarity { Camera_VSYNC_POLARITY_HIGH = 0, Camera_VSYNC_POLARITY_LOW }
	Camera VSync polarity. More...

enum	Camera_PixelClkConfig { Camera_PCLK_CONFIG_RISING_EDGE = 0, Camera_PCLK_CONFIG_FALLING_EDGE }
	Camera pixel clock configuration. More...

enum	Camera_ByteOrder { Camera_BYTE_ORDER_NORMAL = 0, Camera_BYTE_ORDER_SWAP }
	Camera byte order. More...

enum	Camera_IfSynchoronisation { Camera_INTERFACE_SYNC_OFF = 0, Camera_INTERFACE_SYNC_ON }
	Camera interface synchronization. More...

enum	Camera_StopCaptureConfig { Camera_STOP_CAPTURE_IMMEDIATE = 0, Camera_STOP_CAPTURE_FRAME_END }
	Camera stop capture configuration. More...

enum	Camera_StartCaptureConfig { Camera_START_CAPTURE_IMMEDIATE = 0, Camera_START_CAPTURE_FRAME_START }
	Camera start capture configuration. More...

Functions
void	Camera_close (Camera_Handle handle)
	Function to close a Camera peripheral specified by the Camera handle. More...

int_fast16_t	Camera_control (Camera_Handle handle, uint_fast16_t cmd, void *arg)
	Function performs implementation specific features on a given Camera_Handle. More...

void	Camera_init (void)
	Function to initializes the Camera module. More...

Camera_Handle	Camera_open (uint_least8_t index, Camera_Params *params)
	Function to initialize a given Camera peripheral specified by the particular index value. The parameter specifies which mode the Camera will operate. More...

void	Camera_Params_init (Camera_Params *params)
	Function to initialize the Camera_Params structure to its defaults. More...

int_fast16_t	Camera_capture (Camera_Handle handle, void buffer, size_t bufferlen, size_t frameLen)
	Function that handles the Camera capture of a frame. More...

Macro Definition Documentation

§ Camera_WAIT_FOREVER

#define Camera_WAIT_FOREVER (~(0U))

Wait forever define.

Typedef Documentation

§ Camera_Handle

typedef struct Camera_Config_* Camera_Handle

A handle that is returned from a Camera_open() call.

§ Camera_Callback

typedef void(* Camera_Callback) (Camera_Handle handle, void *buf, size_t frameLength)

The definition of a callback function used by the Camera driver when used in Camera_MODE_CALLBACK.

Parameters

Camera_Handle	Camera_Handle
buf	Pointer to capture buffer
frameLength	length of frame

§ Camera_CloseFxn

typedef void(* Camera_CloseFxn) (Camera_Handle handle)

A function pointer to a driver specific implementation of Camera_close().

§ Camera_ControlFxn

typedef int_fast16_t(* Camera_ControlFxn) (Camera_Handle handle, uint_fast16_t cmd, void *arg)

A function pointer to a driver specific implementation of Camera_control().

§ Camera_InitFxn

typedef void(* Camera_InitFxn) (Camera_Handle handle)

A function pointer to a driver specific implementation of Camera_init().

§ Camera_OpenFxn

typedef Camera_Handle(* Camera_OpenFxn) (Camera_Handle handle, Camera_Params *params)

A function pointer to a driver specific implementation of Camera_open().

§ Camera_CaptureFxn

typedef int_fast16_t(* Camera_CaptureFxn) (Camera_Handle handle, void *buffer, size_t bufferlen, size_t *frameLen)

A function pointer to a driver specific implementation of Camera_capture().

§ Camera_Config

typedef struct Camera_Config_ Camera_Config

Camera Global configuration.

The Camera_Config structure contains a set of pointers used to characterize the Camera driver implementation.

This structure needs to be defined before calling Camera_init() and it must not be changed thereafter.

See also: Camera_init()

Enumeration Type Documentation

§ Camera_CaptureMode

enum Camera_CaptureMode

Camera capture mode settings.

This enum defines the capture mode for the configured Camera.

Enumerator
Camera_MODE_BLOCKING	Uses a semaphore to block while data is being sent. Context of the call must be a Task.
Camera_MODE_CALLBACK	Non-blocking and will return immediately. When the capture by the interrupt is finished the configured callback function is called.

§ Camera_HSyncPolarity

enum Camera_HSyncPolarity

Camera HSync polarity.

This enum defines the polarity of the HSync signal.

Enumerator
Camera_HSYNC_POLARITY_HIGH
Camera_HSYNC_POLARITY_LOW

§ Camera_VSyncPolarity

enum Camera_VSyncPolarity

Camera VSync polarity.

This enum defines the polarity of the VSync signal.

Enumerator
Camera_VSYNC_POLARITY_HIGH
Camera_VSYNC_POLARITY_LOW

§ Camera_PixelClkConfig

enum Camera_PixelClkConfig

Camera pixel clock configuration.

This enum defines the pixel clock configuration.

Enumerator
Camera_PCLK_CONFIG_RISING_EDGE
Camera_PCLK_CONFIG_FALLING_EDGE

§ Camera_ByteOrder

enum Camera_ByteOrder

Camera byte order.

This enum defines the byte order of camera capture.

Enumerator
Camera_BYTE_ORDER_NORMAL
Camera_BYTE_ORDER_SWAP

§ Camera_IfSynchoronisation

enum Camera_IfSynchoronisation

Camera interface synchronization.

This enum defines the sensor to camera interface synchronization configuration.

Enumerator
Camera_INTERFACE_SYNC_OFF
Camera_INTERFACE_SYNC_ON

§ Camera_StopCaptureConfig

enum Camera_StopCaptureConfig

Camera stop capture configuration.

This enum defines the stop capture configuration.

Enumerator
Camera_STOP_CAPTURE_IMMEDIATE
Camera_STOP_CAPTURE_FRAME_END

§ Camera_StartCaptureConfig

enum Camera_StartCaptureConfig

Camera start capture configuration.

This enum defines the start capture configuration.

Enumerator
Camera_START_CAPTURE_IMMEDIATE
Camera_START_CAPTURE_FRAME_START

Function Documentation

§ Camera_close()

void Camera_close ( Camera_Handle handle )

Function to close a Camera peripheral specified by the Camera handle.

Precondition: Camera_open() had to be called first.

Parameters

handle A Camera_Handle returned from Camera_open

See also: Camera_open()

§ Camera_control()

int_fast16_t Camera_control	(	Camera_Handle	handle,
		uint_fast16_t	cmd,
		void *	arg
	)

Function performs implementation specific features on a given Camera_Handle.

Commands for Camera_control can originate from Camera.h or from implementation specific Camera*.h (CameraCC32XX.h, etc.. ) files. While commands from Camera.h are API portable across driver implementations, not all implementations may support all these commands. Conversely, commands from driver implementation specific Camera*.h files add unique driver capabilities but are not API portable across all Camera driver implementations.

Commands supported by Camera.h follow a Camera_CMD_<cmd> naming convention.
Commands supported by Camera*.h follow a Camera*_CMD_<cmd> naming convention.
Each control command defines arg differently. The types of arg are documented with each command.

See Camera_control command codes for command codes.

See Camera_control return status codes for status codes.

Precondition: Camera_open() has to be called first.

Parameters

handle	A Camera handle returned from Camera_open()
cmd	Camera.h or Camera*.h commands.
arg	An optional R/W (read/write) command argument accompanied with cmd

Returns: Implementation specific return codes. Negative values indicate unsuccessful operations.

See also: Camera_open()

§ Camera_init()

void Camera_init ( void )

Function to initializes the Camera module.

Precondition: The Camera_config structure must exist and be persistent before this function can be called. This function must also be called before any other Camera driver APIs. This function call does not modify any peripheral registers.

§ Camera_open()

Camera_Handle Camera_open	(	uint_least8_t	index,
		Camera_Params *	params
	)

Function to initialize a given Camera peripheral specified by the particular index value. The parameter specifies which mode the Camera will operate.

Precondition: Camera controller has been initialized

Parameters

index	Logical peripheral number for the Camera indexed into the Camera_config table
params	Pointer to an parameter block, if NULL it will use default values. All the fields in this structure are RO (read-only).

Returns: A Camera_Handle on success or a NULL on an error or if it has been opened already.

See also: Camera_init(); Camera_close()

§ Camera_Params_init()

void Camera_Params_init ( Camera_Params * params )

Function to initialize the Camera_Params structure to its defaults.

Parameters

params An pointer to Camera_Params structure for initialization

Defaults values are: captureMode = Camera_MODE_BLOCKING; outputClock = 24000000; hsyncPolarity = Camera_HSYNC_POLARITY_HIGH; vsyncPolarity = Camera_VSYNC_POLARITY_HIGH; pixelClkConfig = Camera_PCLK_CONFIG_RISING_EDGE; byteOrder = Camera_BYTE_ORDER_NORMAL; interfaceSync = Camera_INTERFACE_SYNC_ON; stopConfig = Camera_STOP_CAPTURE_FRAME_END; startConfig = Camera_START_CAPTURE_FRAME_START; captureTimeout = Camera_WAIT_FOREVER; captureCallback = NULL;

§ Camera_capture()

int_fast16_t Camera_capture	(	Camera_Handle	handle,
		void *	buffer,
		size_t	bufferlen,
		size_t *	frameLen
	)

Function that handles the Camera capture of a frame.

In Camera_MODE_BLOCKING, Camera_capture will block task execution until the capture is complete.

In Camera_MODE_CALLBACK, Camera_capture does not block task execution and calls a callback function specified by captureCallbackFxn. The Camera buffer must stay persistent until the Camera_capture function has completed!

Parameters

handle	A Camera_Handle
buffer	A pointer to a WO (write-only) buffer into which the captured frame is placed
bufferlen	Length (in bytes) of the capture buffer
frameLen	Pointer to return number of bytes captured.

Returns: CAMERA_STATUS_SUCCESS on successful capture, CAMERA_STATUS_ERROR if if otherwise.

See also: Camera_open

Detailed Description

Overview

Usage

Camera Driver Configuration

Initializing the Camear Driver

Camera Parameters

Camera Modes

Opening the driver

Capturing an Image

Implementation

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

§ Camera_WAIT_FOREVER

Typedef Documentation

§ Camera_Handle

§ Camera_Callback

§ Camera_CloseFxn

§ Camera_ControlFxn

§ Camera_InitFxn

§ Camera_OpenFxn

§ Camera_CaptureFxn

§ Camera_Config

Enumeration Type Documentation

§ Camera_CaptureMode

§ Camera_HSyncPolarity

§ Camera_VSyncPolarity

§ Camera_PixelClkConfig

§ Camera_ByteOrder

§ Camera_IfSynchoronisation

§ Camera_StopCaptureConfig

§ Camera_StartCaptureConfig

Function Documentation

§ Camera_close()

§ Camera_control()

§ Camera_init()

§ Camera_open()

§ Camera_Params_init()

§ Camera_capture()