1 /* 2 * Copyright (c) 2015-2019, Texas Instruments Incorporated 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 9 * * Redistributions of source code must retain the above copyright 10 * notice, this list of conditions and the following disclaimer. 11 * 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. 15 * 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. 19 * 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. 31 */ 32 /*!***************************************************************************** 33 * @file Camera.h 34 * 35 * @brief Camera driver interface 36 * 37 * The Camera header file should be included in an application as follows: 38 * @code 39 * #include <ti/drivers/Camera.h> 40 * @endcode 41 * 42 * # Overview # 43 * The Camera driver is used to retrieve the data being transferred by the 44 * Camera sensor. 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. 48 * 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 51 * RTOS. 52 * 53 * # Usage # 54 * 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 58 * vaules. 59 * - Camera_open(): Open an instance of the Camera driver. 60 * - Camera_control(): Performs implemenation-specific features on a given 61 * Camera peripheral. 62 * - Camera_capture(): Capture a frame. 63 * - Camera_close(): De-initialize a given Camera instance. 64 * 65 * 66 * ### Camera Driver Configuration # 67 * 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: 71 * 72 * @code 73 * typedef struct { 74 * Camera_FxnTable const *fxnTablePtr; 75 * void *object; 76 * void const *hwAttrs; 77 * } Camera_Config; 78 * @endcode 79 * 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. 90 * 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 95 * configuration. 96 * 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 103 * 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. 110 * 111 * #### Camera Modes 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. 118 * 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. 122 * 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. 126 * 127 * ### Opening the driver # 128 * The following example opens a Camera driver instance in blocking mode: 129 * @code 130 * Camera_Handle handle; 131 * Camera_Params params; 132 * 133 * Camera_Params_init(¶ms); 134 * params.captureMode = Camera_MODE_BLOCKING; 135 * < Change any other params as required > 136 * 137 * handle = Camera_open(someCamera_configIndexValue, ¶ms); 138 * if (!handle) { 139 * // Error opening the Camera driver 140 * } 141 * @endcode 142 * 143 * ### Capturing an Image # 144 * 145 * The following code example captures a frame. 146 * 147 * @code 148 * unsigned char captureBuffer[1920]; 149 * 150 * ret = Camera_capture(handle, &captureBuffer, sizeof(captureBuffer)); 151 * @endcode 152 * 153 * # Implementation # 154 * 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 158 * #Camera_FxnTable. 159 * 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 165 * peripheral 166 * - (void *) data object that is associated with the Camera_FxnTable 167 * - (void *) hardware attributes that are associated to the Camera_FxnTable 168 * 169 ******************************************************************************* 170 */ 171 172 #ifndef ti_drivers_Camera__include 173 #define ti_drivers_Camera__include 174 175 #include <stdint.h> 176 #include <stddef.h> 177 178 #ifdef __cplusplus 179 extern "C" { 180 #endif 181 182 /** 183 * @defgroup CAMERA_CONTROL Camera_control command and status codes 184 * These Camera macros are reservations for Camera.h 185 * @{ 186 */ 187 188 /*! 189 * Common Camera_control command code reservation offset. 190 * Camera driver implementations should offset command codes with 191 * CAMERA_CMD_RESERVED growing positively 192 * 193 * Example implementation specific command codes: 194 * @code 195 * #define CAMERAXYZ_CMD_COMMAND0 CAMERA_CMD_RESERVED + 0 196 * #define CAMERAXYZ_CMD_COMMAND1 CAMERA_CMD_RESERVED + 1 197 * @endcode 198 */ 199 #define CAMERA_CMD_RESERVED (32) 200 201 /*! 202 * Common Camera_control status code reservation offset. 203 * Camera driver implementations should offset status codes with 204 * CAMERA_STATUS_RESERVED growing negatively. 205 * 206 * Example implementation specific status codes: 207 * @code 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 211 * @endcode 212 */ 213 #define CAMERA_STATUS_RESERVED (-32) 214 215 /** 216 * @defgroup Camera_STATUS Status Codes 217 * Camera_STATUS_* macros are general status codes returned by Camera_control() 218 * @{ 219 * @ingroup Camera_CONTROL 220 */ 221 222 /*! 223 * @brief Successful status code returned by Camera_control(). 224 * 225 * Camera_control() returns CAMERA_STATUS_SUCCESS if the control code was 226 * executed successfully. 227 */ 228 #define CAMERA_STATUS_SUCCESS (0) 229 230 /*! 231 * @brief Generic error status code returned by Camera_control(). 232 * 233 * Camera_control() returns CAMERA_STATUS_ERROR if the control code was not 234 * executed successfully. 235 */ 236 #define CAMERA_STATUS_ERROR (-1) 237 238 /*! 239 * @brief An error status code returned by Camera_control() for undefined 240 * command codes. 241 * 242 * Camera_control() returns CAMERA_STATUS_UNDEFINEDCMD if the control code is 243 * not recognized by the driver implementation. 244 */ 245 #define CAMERA_STATUS_UNDEFINEDCMD (-2) 246 /** @}*/ 247 248 /** 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. 252 * @{ 253 * @ingroup Camera_CONTROL 254 */ 255 256 /* Add Camera_CMD_<commands> here */ 257 258 /** @}*/ 259 260 /** @}*/ 261 262 /*! 263 * @brief Wait forever define 264 */ 265 #define Camera_WAIT_FOREVER (~(0U)) 266 267 /*! 268 * @brief A handle that is returned from a Camera_open() call. 269 */ 270 typedef struct Camera_Config_ *Camera_Handle; 271 272 /*! 273 * @brief The definition of a callback function used by the Camera driver 274 * when used in ::Camera_MODE_CALLBACK 275 * 276 * @param Camera_Handle Camera_Handle 277 * 278 * @param buf Pointer to capture buffer 279 * 280 * @param frameLength length of frame 281 * 282 */ 283 typedef void (*Camera_Callback) (Camera_Handle handle, void *buf, 284 size_t frameLength); 285 286 /*! 287 * @brief Camera capture mode settings 288 * 289 * This enum defines the capture mode for the 290 * configured Camera. 291 */ 292 typedef enum { 293 /*! 294 * Uses a semaphore to block while data is being sent. Context of 295 * the call must be a Task. 296 */ 297 Camera_MODE_BLOCKING, 298 299 /*! 300 * Non-blocking and will return immediately. When the capture 301 * by the interrupt is finished the configured callback function 302 * is called. 303 */ 304 Camera_MODE_CALLBACK 305 } Camera_CaptureMode; 306 307 /*! 308 * @brief Camera HSync polarity 309 * 310 * This enum defines the polarity of the HSync signal. 311 */ 312 typedef enum { 313 Camera_HSYNC_POLARITY_HIGH = 0, 314 Camera_HSYNC_POLARITY_LOW 315 } Camera_HSyncPolarity; 316 317 /*! 318 * @brief Camera VSync polarity 319 * 320 * This enum defines the polarity of the VSync signal. 321 */ 322 typedef enum { 323 Camera_VSYNC_POLARITY_HIGH = 0, 324 Camera_VSYNC_POLARITY_LOW 325 } Camera_VSyncPolarity; 326 327 /*! 328 * @brief Camera pixel clock configuration 329 * 330 * This enum defines the pixel clock configuration. 331 */ 332 typedef enum { 333 Camera_PCLK_CONFIG_RISING_EDGE = 0, 334 Camera_PCLK_CONFIG_FALLING_EDGE 335 } Camera_PixelClkConfig; 336 337 /*! 338 * @brief Camera byte order 339 * 340 * This enum defines the byte order of camera capture. 341 * 342 * In normal mode, the byte order is: 343 * | byte3 | byte2 | byte1 | byte0 | 344 * 345 * In swap mode, the bytes are ordered as: 346 * | byte2 | byte3 | byte0 | byte1 | 347 */ 348 typedef enum { 349 Camera_BYTE_ORDER_NORMAL = 0, 350 Camera_BYTE_ORDER_SWAP 351 } Camera_ByteOrder; 352 353 /*! 354 * @brief Camera interface synchronization 355 * 356 * This enum defines the sensor to camera interface synchronization 357 * configuration. 358 */ 359 typedef enum { 360 Camera_INTERFACE_SYNC_OFF = 0, 361 Camera_INTERFACE_SYNC_ON 362 } Camera_IfSynchoronisation; 363 364 /*! 365 * @brief Camera stop capture configuration 366 * 367 * This enum defines the stop capture configuration. 368 */ 369 typedef enum { 370 Camera_STOP_CAPTURE_IMMEDIATE = 0, 371 Camera_STOP_CAPTURE_FRAME_END 372 } Camera_StopCaptureConfig; 373 374 /*! 375 * @brief Camera start capture configuration 376 * 377 * This enum defines the start capture configuration. 378 */ 379 typedef enum { 380 Camera_START_CAPTURE_IMMEDIATE = 0, 381 Camera_START_CAPTURE_FRAME_START 382 } Camera_StartCaptureConfig; 383 384 /*! 385 * @brief Camera Parameters 386 * 387 * Camera parameters are used to with the Camera_open() call. 388 * Default values for these parameters are set using Camera_Params_init(). 389 * 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. 392 * 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. 396 * 397 * @sa Camera_Params_init() 398 */ 399 typedef struct { 400 /*!< Mode for camera capture */ 401 Camera_CaptureMode captureMode; 402 403 /*!< Output clock to set divider */ 404 uint32_t outputClock; 405 406 /*!< Polarity of Hsync */ 407 Camera_HSyncPolarity hsyncPolarity; 408 409 /*!< Polarity of VSync */ 410 Camera_VSyncPolarity vsyncPolarity; 411 412 /*!< Pixel clock configuration */ 413 Camera_PixelClkConfig pixelClkConfig; 414 415 /*!< camera capture byte order */ 416 Camera_ByteOrder byteOrder; 417 418 /*!< Camera-Sensor synchronization */ 419 Camera_IfSynchoronisation interfaceSync; 420 421 /*!< Camera stop configuration */ 422 Camera_StopCaptureConfig stopConfig; 423 424 /*!< Camera start configuration */ 425 Camera_StartCaptureConfig startConfig; 426 427 /*!< Timeout for capture semaphore */ 428 uint32_t captureTimeout; 429 430 /*!< Pointer to capture callback */ 431 Camera_Callback captureCallback; 432 433 /*!< Custom argument used by driver implementation */ 434 void *custom; 435 } Camera_Params; 436 437 /*! 438 * @brief A function pointer to a driver specific implementation of 439 * Camera_close(). 440 */ 441 typedef void (*Camera_CloseFxn) (Camera_Handle handle); 442 443 /*! 444 * @brief A function pointer to a driver specific implementation of 445 * Camera_control(). 446 */ 447 typedef int_fast16_t (*Camera_ControlFxn) (Camera_Handle handle, 448 uint_fast16_t cmd, 449 void *arg); 450 451 /*! 452 * @brief A function pointer to a driver specific implementation of 453 * Camera_init(). 454 */ 455 typedef void (*Camera_InitFxn) (Camera_Handle handle); 456 457 /*! 458 * @brief A function pointer to a driver specific implementation of 459 * Camera_open(). 460 */ 461 typedef Camera_Handle (*Camera_OpenFxn) (Camera_Handle handle, 462 Camera_Params *params); 463 464 /*! 465 * @brief A function pointer to a driver specific implementation of 466 * Camera_capture(). 467 */ 468 typedef int_fast16_t (*Camera_CaptureFxn) (Camera_Handle handle, void *buffer, 469 size_t bufferlen, size_t *frameLen); 470 471 /*! 472 * @brief The definition of a Camera function table that contains the 473 * required set of functions to control a specific Camera driver 474 * implementation. 475 */ 476 typedef struct { 477 /*! Function to close the specified peripheral */ 478 Camera_CloseFxn closeFxn; 479 480 /*! Function to implementation specific control function */ 481 Camera_ControlFxn controlFxn; 482 483 /*! Function to initialize the given data object */ 484 Camera_InitFxn initFxn; 485 486 /*! Function to open the specified peripheral */ 487 Camera_OpenFxn openFxn; 488 489 /*! Function to initiate a Camera capture */ 490 Camera_CaptureFxn captureFxn; 491 } Camera_FxnTable; 492 493 /*! 494 * @brief Camera Global configuration 495 * 496 * The Camera_Config structure contains a set of pointers used to characterize 497 * the Camera driver implementation. 498 * 499 * This structure needs to be defined before calling Camera_init() and it must 500 * not be changed thereafter. 501 * 502 * @sa Camera_init() 503 */ 504 typedef struct Camera_Config_ { 505 /*! Pointer to a table of driver-specific implementations of Camera APIs */ 506 Camera_FxnTable const *fxnTablePtr; 507 508 /*! Pointer to a driver specific data object */ 509 void *object; 510 511 /*! Pointer to a driver specific hardware attributes structure */ 512 void const *hwAttrs; 513 } Camera_Config; 514 515 /*! 516 * @brief Function to close a Camera peripheral specified by the Camera handle 517 * 518 * @pre Camera_open() had to be called first. 519 * 520 * @param handle A Camera_Handle returned from Camera_open 521 * 522 * @sa Camera_open() 523 */ 524 extern void Camera_close(Camera_Handle handle); 525 526 /*! 527 * @brief Function performs implementation specific features on a given 528 * Camera_Handle. 529 * 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 536 * implementations. 537 * 538 * Commands supported by Camera.h follow a Camera_CMD_\<cmd\> naming 539 * convention.<br> 540 * Commands supported by Camera*.h follow a Camera*_CMD_\<cmd\> naming 541 * convention.<br> 542 * Each control command defines @b arg differently. The types of @b arg are 543 * documented with each command. 544 * 545 * See @ref Camera_CMD "Camera_control command codes" for command codes. 546 * 547 * See @ref Camera_STATUS "Camera_control return status codes" for status codes. 548 * 549 * @pre Camera_open() has to be called first. 550 * 551 * @param handle A Camera handle returned from Camera_open() 552 * 553 * @param cmd Camera.h or Camera*.h commands. 554 * 555 * @param arg An optional R/W (read/write) command argument 556 * accompanied with cmd 557 * 558 * @return Implementation specific return codes. Negative values indicate 559 * unsuccessful operations. 560 * 561 * @sa Camera_open() 562 */ 563 extern int_fast16_t Camera_control(Camera_Handle handle, uint_fast16_t cmd, 564 void *arg); 565 566 /*! 567 * @brief Function to initializes the Camera module 568 * 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. 573 */ 574 extern void Camera_init(void); 575 576 /*! 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. 580 * 581 * @pre Camera controller has been initialized 582 * 583 * @param index Logical peripheral number for the Camera indexed into 584 * the Camera_config table 585 * 586 * @param params Pointer to an parameter block, if NULL it will use 587 * default values. All the fields in this structure are 588 * RO (read-only). 589 * 590 * @return A Camera_Handle on success or a NULL on an error or if it has been 591 * opened already. 592 * 593 * @sa Camera_init() 594 * @sa Camera_close() 595 */ 596 extern Camera_Handle Camera_open(uint_least8_t index, Camera_Params *params); 597 598 /*! 599 * @brief Function to initialize the Camera_Params structure to its defaults 600 * 601 * @param params An pointer to Camera_Params structure for 602 * initialization 603 * 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; 616 */ 617 extern void Camera_Params_init(Camera_Params *params); 618 619 /*! 620 * @brief Function that handles the Camera capture of a frame. 621 * 622 * In Camera_MODE_BLOCKING, Camera_capture will block task execution until 623 * the capture is complete. 624 * 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! 629 * 630 * @param handle A Camera_Handle 631 * 632 * @param buffer A pointer to a WO (write-only) buffer into which the 633 * captured frame is placed 634 * 635 * @param bufferlen Length (in bytes) of the capture buffer 636 * 637 * @param frameLen Pointer to return number of bytes captured. 638 * 639 * @return CAMERA_STATUS_SUCCESS on successful capture, CAMERA_STATUS_ERROR if 640 * if otherwise. 641 * 642 * @sa Camera_open 643 */ 644 extern int_fast16_t Camera_capture(Camera_Handle handle, void *buffer, 645 size_t bufferlen, size_t *frameLen); 646 647 #ifdef __cplusplus 648 } 649 #endif 650 651 #endif /* ti_drivers_Camera__include */ 652
