2 * Copyright (c) 2015-2016, Texas Instruments Incorporated
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
12 * * Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
16 * * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 /*!*****************************************************************************
35 * @brief Camera driver interface
37 * The Camera header file should be included in an application as follows:
39 * #include <ti/drivers/Camera.h>
43 * The Camera driver is used to retrieve the data being transferred by the
45 * This driver provides an API for capturing the image from the Camera sensor.
46 * The camera sensor control and implementation are the responsibility of the
47 * application using the interface.
49 * The Camera driver has been designed to operate in an RTOS environment. It
50 * protects its transactions with OS primitives supplied by the underlying
55 * The Camera driver includes the following APIs:
56 * - Camera_init(): Initialize the Camera driver.
57 * - Camera_Params_init(): Initialize a #Camera_Params structure with default
59 * - Camera_open(): Open an instance of the Camera driver.
60 * - Camera_control(): Performs implemenation-specific features on a given
62 * - Camera_capture(): Capture a frame.
63 * - Camera_close(): De-initialize a given Camera instance.
66 * ### Camera Driver Configuration #
68 * In order to use the Camera APIs, the application is required
69 * to provide device-specific Camera configuration in the Board.c file.
70 * The Camera driver interface defines a configuration data structure:
73 * typedef struct Camera_Config_ {
74 * Camera_FxnTable const *fxnTablePtr;
76 * void const *hwAttrs;
80 * The application must declare an array of Camera_Config elements, named
81 * Camera_config[]. Each element of Camera_config[] must be populated with
82 * pointers to a device specific Camera driver implementation's function
83 * table, driver object, and hardware attributes. The hardware attributes
84 * define properties such as the Camera peripheral's base address.
85 * Each element in Camera_config[] corresponds to
86 * a Camera instance, and none of the elements should have NULL pointers.
87 * There is no correlation between the index and the
88 * peripheral designation (such as Camera0 or Camera1). For example, it
89 * is possible to use Camera_config[0] for Camera1.
91 * Because the Camera configuration is very device dependent, you will need to
92 * check the doxygen for the device specific Camera implementation. There you
93 * will find a description of the Camera hardware attributes. Please also
94 * refer to the Board.c file of any of your examples to see the Camera
97 * ### Initializing the Camear Driver #
98 * The application initializes the Camera driver by calling Camera_init().
99 * This function must be called before any other Camera API. Camera_init()
100 * iterates through the elements of the Camera_config[] array, calling
101 * the element's device implementation Camera initialization function.
102 * ### Camera Parameters
104 * The #Camera_Params structure is passed to Camera_open(). If NULL
105 * is passed for the parameters, Camera_open() uses default parameters.
106 * A #Camera_Params structure is initialized with default values by passing
107 * it to Camera_Params_init().
108 * Some of the Camera parameters are described below. To see brief descriptions
109 * of all the parameters, see #Camera_Params.
112 * The Camera driver operates in either blocking mode or callback mode:
113 * - #Camera_MODE_BLOCKING: The call to Camera_capture() blocks until the
114 * capture has completed.
115 * - #Camera_MODE_CALLBACK: The call to Camera_capture() returns immediately.
116 * When the capture completes, the Camera driver will call a user-
117 * specified callback function.
119 * The capture mode is determined by the #Camera_Params.captureMode parameter
120 * passed to Camera_open(). The Camera driver defaults to blocking mode, if the
121 * application does not set it.
123 * Once a Camera driver instance is opened, the only way
124 * to change the capture mode is to close and re-open the Camera
125 * instance with the new capture mode.
127 * ### Opening the driver #
128 * The following example opens a Camera driver instance in blocking mode:
130 * Camera_Handle handle;
131 * Camera_Params params;
133 * Camera_Params_init(¶ms);
134 * params.captureMode = Camera_MODE_BLOCKING;
135 * < Change any other params as required >
137 * handle = Camera_open(someCamera_configIndexValue, ¶ms);
139 * // Error opening the Camera driver
143 * ### Capturing an Image #
145 * The following code example captures a frame.
148 * unsigned char captureBuffer[1920];
150 * ret = Camera_capture(handle, &captureBuffer, sizeof(captureBuffer));
155 * This module serves as the main interface for RTOS
156 * applications. Its purpose is to redirect the module's APIs to specific
157 * peripheral implementations which are specified using a pointer to a
160 * The Camera driver interface module is joined (at link time) to an
161 * array of #Camera_Config data structures named *Camera_config*.
162 * *Camera_config* is implemented in the application with each entry being an
163 * instance of a Camera peripheral. Each entry in *Camera_config* contains a:
164 * - (Camera_FxnTable *) to a set of functions that implement a Camera
166 * - (void *) data object that is associated with the Camera_FxnTable
167 * - (void *) hardware attributes that are associated to the Camera_FxnTable
169 *******************************************************************************
172 #ifndef ti_drivers_Camera__include
173 #define ti_drivers_Camera__include
183 * @defgroup CAMERA_CONTROL Camera_control command and status codes
184 * These Camera macros are reservations for Camera.h
189 * Common Camera_control command code reservation offset.
190 * Camera driver implementations should offset command codes with
191 * CAMERA_CMD_RESERVED growing positively
193 * Example implementation specific command codes:
195 * #define CAMERAXYZ_CMD_COMMAND0 CAMERA_CMD_RESERVED + 0
196 * #define CAMERAXYZ_CMD_COMMAND1 CAMERA_CMD_RESERVED + 1
199 #define CAMERA_CMD_RESERVED (32)
202 * Common Camera_control status code reservation offset.
203 * Camera driver implementations should offset status codes with
204 * CAMERA_STATUS_RESERVED growing negatively.
206 * Example implementation specific status codes:
208 * #define CAMERAXYZ_STATUS_ERROR0 CAMERA_STATUS_RESERVED - 0
209 * #define CAMERAXYZ_STATUS_ERROR1 CAMERA_STATUS_RESERVED - 1
210 * #define CAMERAXYZ_STATUS_ERROR2 CAMERA_STATUS_RESERVED - 2
213 #define CAMERA_STATUS_RESERVED (-32)
216 * @defgroup Camera_STATUS Status Codes
217 * Camera_STATUS_* macros are general status codes returned by Camera_control()
219 * @ingroup Camera_CONTROL
223 * @brief Successful status code returned by Camera_control().
225 * Camera_control() returns CAMERA_STATUS_SUCCESS if the control code was
226 * executed successfully.
228 #define CAMERA_STATUS_SUCCESS (0)
231 * @brief Generic error status code returned by Camera_control().
233 * Camera_control() returns CAMERA_STATUS_ERROR if the control code was not
234 * executed successfully.
236 #define CAMERA_STATUS_ERROR (-1)
239 * @brief An error status code returned by Camera_control() for undefined
242 * Camera_control() returns CAMERA_STATUS_UNDEFINEDCMD if the control code is
243 * not recognized by the driver implementation.
245 #define CAMERA_STATUS_UNDEFINEDCMD (-2)
249 * @defgroup Camera_CMD Command Codes
250 * Camera_CMD_* macros are general command codes for Camera_control(). Not all
251 * Camera driver implementations support these command codes.
253 * @ingroup Camera_CONTROL
256 /* Add Camera_CMD_<commands> here */
263 * @brief Wait forever define
265 #define Camera_WAIT_FOREVER (~(0U))
268 * @brief A handle that is returned from a Camera_open() call.
270 typedef struct Camera_Config_ *Camera_Handle;
273 * @brief The definition of a callback function used by the Camera driver
274 * when used in ::Camera_MODE_CALLBACK
276 * @param Camera_Handle Camera_Handle
278 * @param buf Pointer to capture buffer
280 * @param frameLength length of frame
283 typedef void (*Camera_Callback) (Camera_Handle handle, void *buf,
287 * @brief Camera capture mode settings
289 * This enum defines the capture mode for the
292 typedef enum Camera_CaptureMode_ {
294 * Uses a semaphore to block while data is being sent. Context of
295 * the call must be a Task.
297 Camera_MODE_BLOCKING,
300 * Non-blocking and will return immediately. When the capture
301 * by the interrupt is finished the configured callback function
305 } Camera_CaptureMode;
308 * @brief Camera HSync polarity
310 * This enum defines the polarity of the HSync signal.
312 typedef enum Camera_HSyncPolarity_ {
313 Camera_HSYNC_POLARITY_HIGH = 0,
314 Camera_HSYNC_POLARITY_LOW
315 } Camera_HSyncPolarity;
318 * @brief Camera VSync polarity
320 * This enum defines the polarity of the VSync signal.
322 typedef enum Camera_VSyncPolarity_ {
323 Camera_VSYNC_POLARITY_HIGH = 0,
324 Camera_VSYNC_POLARITY_LOW
325 } Camera_VSyncPolarity;
328 * @brief Camera pixel clock configuration
330 * This enum defines the pixel clock configuration.
332 typedef enum Camera_PixelClkConfig_ {
333 Camera_PCLK_CONFIG_RISING_EDGE = 0,
334 Camera_PCLK_CONFIG_FALLING_EDGE
335 } Camera_PixelClkConfig;
338 * @brief Camera byte order
340 * This enum defines the byte order of camera capture.
342 * In normal mode, the byte order is:
343 * | byte3 | byte2 | byte1 | byte0 |
345 * In swap mode, the bytes are ordered as:
346 * | byte2 | byte3 | byte0 | byte1 |
348 typedef enum Camera_ByteOrder_ {
349 Camera_BYTE_ORDER_NORMAL = 0,
350 Camera_BYTE_ORDER_SWAP
354 * @brief Camera interface synchronization
356 * This enum defines the sensor to camera interface synchronization
359 typedef enum Camera_IfSynchoronisation_ {
360 Camera_INTERFACE_SYNC_OFF = 0,
361 Camera_INTERFACE_SYNC_ON
362 } Camera_IfSynchoronisation;
365 * @brief Camera stop capture configuration
367 * This enum defines the stop capture configuration.
369 typedef enum Camera_StopCaptureConfig_ {
370 Camera_STOP_CAPTURE_IMMEDIATE = 0,
371 Camera_STOP_CAPTURE_FRAME_END
372 } Camera_StopCaptureConfig;
375 * @brief Camera start capture configuration
377 * This enum defines the start capture configuration.
379 typedef enum Camera_StartCaptureConfig_ {
380 Camera_START_CAPTURE_IMMEDIATE = 0,
381 Camera_START_CAPTURE_FRAME_START
382 } Camera_StartCaptureConfig;
385 * @brief Camera Parameters
387 * Camera parameters are used to with the Camera_open() call.
388 * Default values for these parameters are set using Camera_Params_init().
390 * If Camera_CaptureMode is set to Camera_MODE_BLOCKING then Camera_capture
391 * function calls will block thread execution until the capture has completed.
393 * If Camera_CaptureMode is set to Camera_MODE_CALLBACK then Camera_capture
394 * will not block thread execution and it will call the function specified by
395 * captureCallbackFxn.
397 * @sa Camera_Params_init()
399 typedef struct Camera_Params_ {
400 /*!< Mode for camera capture */
401 Camera_CaptureMode captureMode;
403 /*!< Output clock to set divider */
404 uint32_t outputClock;
406 /*!< Polarity of Hsync */
407 Camera_HSyncPolarity hsyncPolarity;
409 /*!< Polarity of VSync */
410 Camera_VSyncPolarity vsyncPolarity;
412 /*!< Pixel clock configuration */
413 Camera_PixelClkConfig pixelClkConfig;
415 /*!< camera capture byte order */
416 Camera_ByteOrder byteOrder;
418 /*!< Camera-Sensor synchronization */
419 Camera_IfSynchoronisation interfaceSync;
421 /*!< Camera stop configuration */
422 Camera_StopCaptureConfig stopConfig;
424 /*!< Camera start configuration */
425 Camera_StartCaptureConfig startConfig;
427 /*!< Timeout for capture semaphore */
428 uint32_t captureTimeout;
430 /*!< Pointer to capture callback */
431 Camera_Callback captureCallback;
433 /*!< Custom argument used by driver implementation */
438 * @brief A function pointer to a driver specific implementation of
441 typedef void (*Camera_CloseFxn) (Camera_Handle handle);
444 * @brief A function pointer to a driver specific implementation of
447 typedef int_fast16_t (*Camera_ControlFxn) (Camera_Handle handle,
452 * @brief A function pointer to a driver specific implementation of
455 typedef void (*Camera_InitFxn) (Camera_Handle handle);
458 * @brief A function pointer to a driver specific implementation of
461 typedef Camera_Handle (*Camera_OpenFxn) (Camera_Handle handle,
462 Camera_Params *params);
465 * @brief A function pointer to a driver specific implementation of
468 typedef int_fast16_t (*Camera_CaptureFxn) (Camera_Handle handle, void *buffer,
469 size_t bufferlen, size_t *frameLen);
472 * @brief The definition of a Camera function table that contains the
473 * required set of functions to control a specific Camera driver
476 typedef struct Camera_FxnTable_ {
477 /*! Function to close the specified peripheral */
478 Camera_CloseFxn closeFxn;
480 /*! Function to implementation specific control function */
481 Camera_ControlFxn controlFxn;
483 /*! Function to initialize the given data object */
484 Camera_InitFxn initFxn;
486 /*! Function to open the specified peripheral */
487 Camera_OpenFxn openFxn;
489 /*! Function to initiate a Camera capture */
490 Camera_CaptureFxn captureFxn;
494 * @brief Camera Global configuration
496 * The Camera_Config structure contains a set of pointers used to characterize
497 * the Camera driver implementation.
499 * This structure needs to be defined before calling Camera_init() and it must
500 * not be changed thereafter.
504 typedef struct Camera_Config_ {
505 /*! Pointer to a table of driver-specific implementations of Camera APIs */
506 Camera_FxnTable const *fxnTablePtr;
508 /*! Pointer to a driver specific data object */
511 /*! Pointer to a driver specific hardware attributes structure */
516 * @brief Function to close a Camera peripheral specified by the Camera handle
518 * @pre Camera_open() had to be called first.
520 * @param handle A Camera_Handle returned from Camera_open
524 extern void Camera_close(Camera_Handle handle);
527 * @brief Function performs implementation specific features on a given
530 * Commands for Camera_control can originate from Camera.h or from
531 * implementation specific Camera*.h (_CameraCC32XX.h_, etc.. ) files.
532 * While commands from Camera.h are API portable across driver implementations,
533 * not all implementations may support all these commands.
534 * Conversely, commands from driver implementation specific Camera*.h files add
535 * unique driver capabilities but are not API portable across all Camera driver
538 * Commands supported by Camera.h follow a Camera_CMD_\<cmd\> naming
540 * Commands supported by Camera*.h follow a Camera*_CMD_\<cmd\> naming
542 * Each control command defines @b arg differently. The types of @b arg are
543 * documented with each command.
545 * See @ref Camera_CMD "Camera_control command codes" for command codes.
547 * See @ref Camera_STATUS "Camera_control return status codes" for status codes.
549 * @pre Camera_open() has to be called first.
551 * @param handle A Camera handle returned from Camera_open()
553 * @param cmd Camera.h or Camera*.h commands.
555 * @param arg An optional R/W (read/write) command argument
556 * accompanied with cmd
558 * @return Implementation specific return codes. Negative values indicate
559 * unsuccessful operations.
563 extern int_fast16_t Camera_control(Camera_Handle handle, uint_fast16_t cmd,
567 * @brief Function to initializes the Camera module
569 * @pre The Camera_config structure must exist and be persistent before this
570 * function can be called. This function must also be called before
571 * any other Camera driver APIs. This function call does not modify any
572 * peripheral registers.
574 extern void Camera_init(void);
577 * @brief Function to initialize a given Camera peripheral specified by the
578 * particular index value. The parameter specifies which mode the
579 * Camera will operate.
581 * @pre Camera controller has been initialized
583 * @param index Logical peripheral number for the Camera indexed into
584 * the Camera_config table
586 * @param params Pointer to an parameter block, if NULL it will use
587 * default values. All the fields in this structure are
590 * @return A Camera_Handle on success or a NULL on an error or if it has been
596 extern Camera_Handle Camera_open(uint_least8_t index, Camera_Params *params);
599 * @brief Function to initialize the Camera_Params structure to its defaults
601 * @param params An pointer to Camera_Params structure for
604 * Defaults values are:
605 * captureMode = Camera_MODE_BLOCKING;
606 * outputClock = 24000000;
607 * hsyncPolarity = Camera_HSYNC_POLARITY_HIGH;
608 * vsyncPolarity = Camera_VSYNC_POLARITY_HIGH;
609 * pixelClkConfig = Camera_PCLK_CONFIG_RISING_EDGE;
610 * byteOrder = Camera_BYTE_ORDER_NORMAL;
611 * interfaceSync = Camera_INTERFACE_SYNC_ON;
612 * stopConfig = Camera_STOP_CAPTURE_FRAME_END;
613 * startConfig = Camera_START_CAPTURE_FRAME_START;
614 * captureTimeout = Camera_WAIT_FOREVER;
615 * captureCallback = NULL;
617 extern void Camera_Params_init(Camera_Params *params);
620 * @brief Function that handles the Camera capture of a frame.
622 * In Camera_MODE_BLOCKING, Camera_capture will block task execution until
623 * the capture is complete.
625 * In Camera_MODE_CALLBACK, Camera_capture does not block task execution
626 * and calls a callback function specified by captureCallbackFxn.
627 * The Camera buffer must stay persistent until the Camera_capture
628 * function has completed!
630 * @param handle A Camera_Handle
632 * @param buffer A pointer to a WO (write-only) buffer into which the
633 * captured frame is placed
635 * @param bufferlen Length (in bytes) of the capture buffer
637 * @param frameLen Pointer to return number of bytes captured.
639 * @return CAMERA_STATUS_SUCCESS on successful capture, CAMERA_STATUS_ERROR if
644 extern int_fast16_t Camera_capture(Camera_Handle handle, void *buffer,
645 size_t bufferlen, size_t *frameLen);
651 #endif /* ti_drivers_Camera__include */