fvid2.h

   1 /*
   2  *  Copyright (c) Texas Instruments Incorporated 2018
   3  *
   4  *  Redistribution and use in source and binary forms, with or without
   5  *  modification, are permitted provided that the following conditions
   6  *  are met:
   7  *
   8  *    Redistributions of source code must retain the above copyright
   9  *    notice, this list of conditions and the following disclaimer.
  10  *
  11  *    Redistributions in binary form must reproduce the above copyright
  12  *    notice, this list of conditions and the following disclaimer in the
  13  *    documentation and/or other materials provided with the
  14  *    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
  21  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  22  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  23  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  24  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  25  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  26  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  27  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  28  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  30  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31  */
  32
  33 /**
  34  *  \file fvid2.h
  35  *
  36  *  \brief FVID2 API
  37  *
  38  *  FVID2 API is an interface which is used to create, control and use different
  39  *  video drivers. FVID2 API is used not only for on-chip
  40  *  peripherals drivers like capture, display but also for external off-chip
  41  *  video device peripherals like video decoders, video encoders and
  42  *  video sensors.
  43  *
  44  *  All video drivers and external video peripherals implement the FVID2
  45  *  API.
  46  *  Many drivers also extend the FVID2 interface by defining their own driver
  47  *  specific IOCTLs.
  48  *
  49  *  <b> All FVID2 API must be called from task context </b>. Some examples
  50  *  in the package maybe calling FVID2 APIs from callback and/or
  51  *  interrupt context. Such examples will be modified in subsequent releases
  52  *  and in order that user application do not have to do special migration it
  53  *  is strongly recommended to use FVID2 APIs only from task context.
  54  *
  55  *  A FVID2 API can be of two kinds,
  56  *
  57  *  - <b> Blocking API </b> <br>
  58  *    Here the FVID2 API call returns only after completing the request or
  59  *    functionality or if timed out or if some other error occurs.
  60  *    The below APIs are always blocking, unless specified otherwise by
  61  *    specific driver.
  62  *    - Fvid2_create()
  63  *    - Fvid2_delete()
  64  *    - Fvid2_start()
  65  *    - Fvid2_stop()
  66  *    - Fvid2_control()
  67  *    - Fvid2_setFormat()
  68  *    - Fvid2_getFormat()
  69  *
  70  *  - <b> Non-blocking API </b> <br>
  71  *    Here FVID2 API call queues the request to the driver and returns
  72  *    immediately before the request is processed or completed.
  73  *    Application should use the completion callback to wait for request
  74  *    completion.
  75  *    The below APIs are always non-blocking, unless specified otherwise by
  76  *    specific driver.
  77  *    - Fvid2_queue()
  78  *    - Fvid2_dequeue()
  79  *    - Fvid2_processFrames()
  80  *    - Fvid2_getProcessedFrames()
  81  *
  82  *  A FVID2 Driver can belong to one the below categories. The FVID2 APIs
  83  *  applicable to driver in a category are also listed below. The below is
  84  *  true for most driver unless specified otherwise by a specific driver.
  85  *  - <b> Streaming interface drivers </b> <br>
  86  *  Examples include, capture, display, graphics.
  87  *  Below FVID2 APIs are implemented by such drivers.
  88  *    - Fvid2_create()
  89  *    - Fvid2_delete()
  90  *    - Fvid2_start()
  91  *    - Fvid2_stop()
  92  *    - Fvid2_queue()
  93  *    - Fvid2_dequeue()
  94  *    - Fvid2_control()
  95  *    - Fvid2_setFormat() - OPTIONAL
  96  *    - Fvid2_getFormat() - OPTIONAL
  97  *
  98  *  - <b> Memory to memory processing interface drivers </b> <br>
  99  *   Examples include, M2M VPE.
 100  *   Below FVID2 APIs are implemented by such drivers.
 101  *    - Fvid2_create()
 102  *    - Fvid2_delete()
 103  *    - Fvid2_processFrames()
 104  *    - Fvid2_getProcessedFrames()
 105  *    - Fvid2_control()
 106  *    - Fvid2_setFormat() - OPTIONAL
 107  *    - Fvid2_getFormat() - OPTIONAL
 108  *
 109  *  - <b> Control interface drivers </b> <br>
 110  *   Examples include, display controller, external video devices.
 111  *   Below FVID2 APIs are implemented by such drivers.
 112  *    - Fvid2_create()
 113  *    - Fvid2_delete()
 114  *    - Fvid2_control()
 115  *    - Fvid2_start()
 116  *    - Fvid2_stop()
 117  *    - Fvid2_setFormat() - OPTIONAL
 118  *    - Fvid2_getFormat() - OPTIONAL
 119  *
 120  *  Before making any FVID2 API calls, Fvid2_init() must be called.
 121  *  Fvid2_deInit() must be called during system shutdown.
 122  *
 123  *  Fvid2_getVersionString() and Fvid2_getVersionNumber() can be used to get
 124  *  information about current driver version number.
 125  *
 126  *  All FVID2 drivers are of type Fvid2_Handle, which gets created when
 127  *  Fvid2_create() is called. This handle is used for all subsequent FVID2
 128  *  API calls. This handle and its associated resources are free'ed when
 129  *  Fvid2_delete() is called.
 130  *
 131  *  All FVID2 APIs make use of Fvid2_Frame, Fvid2_FrameList and/or
 132  *  Fvid2_ProcessList for exchanging and processing video frames via a driver.
 133  *  Further all drivers use a common user callback mechanism via Fvid2_CbParams
 134  *  to indicate to the user that a frame is ready. Many drivers, but not all,
 135  *  use the Fvid2_Format data structure to describe video input, output data
 136  *  formats.
 137  *
 138  *  All drivers use the constants, enum's, error codes defined in this file to
 139  *  control and configure a driver.
 140  *
 141  *  In addition, most drivers define driver specific create time parameters
 142  *  and IOCTLs to allow the user to control and configure the driver in driver
 143  *  specific ways. Further a driver may define driver specific run-time
 144  *  parameters which are passed by user to the driver via
 145  *  Fvid2_Frame.perFrameCfg and/or Fvid2_FrameList.perListCfg.
 146  *
 147  *  Also user application can associate user specific app data with a
 148  *  driver handle via Fvid2_CbParams.appData or with every frame via
 149  *  FIVD2_Frame.appData. The app data set as part of Fvid2_CbParams returned
 150  *  back to user when callback occurs. The app data set as part of Fvid2_Frame
 151  *  is returned back to the user when the Fvid2_Frame itself is returned back to
 152  *  user via Fvid2_dequeue() or Fvid2_getProcessedFrames(). The driver will not
 153  *  modify this app data. This could be used by the application to store any
 154  *  application specific data like application object info and so on.
 155  *
 156  */
 157
 158 /*
 159  *  \version 0.1    Created.
 160  *           0.2    Changes for BIOS 6 and new FVID2 interface.
 161  *           0.2.1  Merged color and data format enums to data format enums.
 162  *                  Added process list structure to support M2M
 163  *                  (memory to memory) drivers.
 164  *                  Removed FVID2_Buf structure and directly used address array
 165  *                  in Fvid2_Frame structure.
 166  *                  Defined proper signature for FVID2 APIs.
 167  *           0.2.2  Added proper comments.
 168  *           0.3    Added subframe callback and added reserved fields in all the
 169  *                  structures.
 170  *           0.4    Made frames pointer to pointer to array of frame pointer in
 171  *                  framelist to simplify application allocation and ease of
 172  *                  use.
 173  *           0.5    Added FVID2 standard enums.
 174  *           0.6    Split into two files. fvid2.h will contain only FVID2 driver
 175  *                  specific defintions/declarations. It will include
 176  *                  fvid2_dataTypes.h for data type defintions
 177  *           1.0    Removed reserved fields as this is not used anywhere and
 178  *                  changed Ptr to void*, changed types to stdint.h types.
 179  *
 180  */
 181
 182 #ifndef FVID2_H_
 183 #define FVID2_H_
 184
 185 /* ========================================================================== */
 186 /*                             Include Files                                  */
 187 /* ========================================================================== */
 188
 189 #include <ti/csl/csl_fvid2_dataTypes.h>
 190 #include <ti/drv/fvid2/include/trace.h>
 191 #include <ti/drv/fvid2/include/fvid2_utils.h>
 192
 193 #ifdef __cplusplus
 194 extern "C" {
 195 #endif
 196
 197 /* ========================================================================== */
 198 /*                           Macros & Typedefs                                */
 199 /* ========================================================================== */
 200
 201 /**
 202  *  \brief FVID2 driver version string.
 203  *  Version is of the form mm_nn_xx_yy where,
 204  *      mm - Product version (02 for FVID2). This increments for any new FVID2
 205  *           versions.
 206  *      nn - Major number - Increments if any backward compatibility is broken
 207  *           or major change within a product version.
 208  *      xx - Minor number - Increments for any minor change or any additions
 209  *           done without breaking backward compatibility.
 210  *      yy - Build number - Increments for every release.
 211  */
 212 #define FVID2_VERSION_STRING            "FVID_02_02_00_00"
 213
 214 /** \brief FVID2 driver version number. */
 215 #define FVID2_VERSION_NUMBER            (0x02020000U)
 216
 217 /** \brief FVID2 Driver handle. */
 218 typedef void *Fvid2_Handle;
 219
 220 /**
 221  *  \brief FVID2 driver callback function prototype.
 222  *
 223  *  This callback is used by the drivers which implement non-blocking
 224  *  FVID2 APIs.
 225  *
 226  *  User should assume that callbacks happen in ISR context and hence should
 227  *  apply rules relevant to ISR context when implementing callback functions,
 228  *  i.e blocking APIs should not be called from callback. Users should also
 229  *  assume that interrupts are enabled when in callback context, i.e other
 230  *  interrupt / callbacks can occur when a callback is under execution.
 231  *  User callback implementation should not be very long, since callback
 232  *  execution may block other drivers from executing. Typically it is
 233  *  recommended to set a semaphore or flag when callback happens and do the
 234  *  more involved callback handling in task context.
 235  *
 236  *  This callback is typically called by the driver as mentioned below,
 237  *  unless specified otherwise by specific drivers.
 238  *
 239  *  In case of display drivers, this callback function will be called
 240  *  when a frame(s) is/are completed displayed. Then the application can
 241  *  dequeue the displayed buffer back from the driver.
 242  *
 243  *  In case of capture drivers, this callback function will be called
 244  *  when a frame(s) is/are captured. Then the application can dequeue the
 245  *  captured buffer back from the driver.
 246  *
 247  *  In case of M2M drivers, this callback function will be called
 248  *  when a request from the application is completed by the driver. Then the
 249  *  application can dequeue the completed request buffers back from the driver.
 250  *
 251  *  In case of control drivers, callbacks are typically not used since mostly
 252  *  FVID2 APIs implemented by control drivers are of blocking nature.
 253  *
 254  *  \param handle   [OUT] FVID2 handle for which the callback has occurred.
 255  *  \param appData  [OUT] Application data provided to the driver at the
 256  *                        time of Fvid2_create().
 257  *
 258  *  \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
 259  */
 260 typedef int32_t (*Fvid2_CbFxn)(Fvid2_Handle handle, void *appData);
 261
 262 /**
 263  *  \brief FVID2 error callback function prototype.
 264  *
 265  *  Error callback is called by driver when it encounters a error during
 266  *  processing of frames in its internal queue.
 267  *
 268  *  When user submits frames to the driver it does minimal error checks and
 269  *  stores the the frames in its internal queues. In case of any error at
 270  *  this point the FVID2 API will simply return error and error callback
 271  *  will not be called.
 272  *
 273  *  The driver will later (depending on how its request queue is full) process
 274  *  these frames submitted by the user. If driver finds any error in either
 275  *  the input frame information or hardware itself then it will call this error
 276  *  callback to notify the user about this error. As part of the callback
 277  *  information it also returns the frames or request for which error happened
 278  *  so that user can take appropriate action.
 279  *
 280  *  Users should apply same rules as that of Fvid2_CbFxn when implementing
 281  *  error callbacks.
 282  *
 283  *  \param handle   [OUT] FVID2 handle for which the callback has occurred.
 284  *  \param appData  [OUT] Application data provided to the driver at the time
 285  *                        of Fvid2_create().
 286  *  \param errList  [OUT] Pointer to a valid framelist (Fvid2_FrameList)
 287  *                        in case of capture and display drivers or a pointer
 288  *                        to a valid processlist (Fvid2_ProcessList) in case of
 289  *                        M2M drivers. The driver copies the aborted/error
 290  *                        frames in this frame list or process list.
 291  *
 292  *  \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
 293  */
 294 typedef int32_t (*Fvid2_ErrCbFxn)(Fvid2_Handle handle,
 295                                   void        *appData,
 296                                   void        *errList);
 297
 298 /**
 299  *  \brief FVID2 callback that is called by subframe mode Capture driver.
 300  *
 301  *  This callback is called for every subframe of frame that
 302  *  is captured. This function is used by Capture Driver and not meant for M2M
 303  *  drivers.
 304  *
 305  *  Users should apply same rules as that of Fvid2_CbFxn when implementing
 306  *  subframe callbacks.
 307  *
 308  *  \param handle       [OUT] FVID2 handle for which this callback happened.
 309  *  \param subFrameInfo [OUT] SubFrame information.
 310  *
 311  *  \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
 312  */
 313 typedef int32_t (*Fvid2_SubFrameCbFxn)(Fvid2_Handle handle,
 314                                        Fvid2_Frame *subFrame);
 315
 316 /**
 317  *  \name FVID2 Max limits
 318  *  @{
 319  */
 320
 321 /** \brief Decide the streamid based on channel number.  */
 322 #define FVID2_STREAM_ID_ANY             (0xFFFFFFFFU)
 323
 324 /* @} */
 325
 326 /*
 327  * =========== Command codes for Submit call =============
 328  */
 329 /** \brief Control command base address. */
 330 #define FVID2_CTRL_BASE                 (0x00000000U)
 331 /** \brief User command base address. */
 332 #define FVID2_USER_BASE                 (0x10000000U)
 333
 334 /**
 335  *  \addtogroup BSP_DRV_IOCTL_FVID2
 336  *  @{
 337  */
 338
 339 /**
 340  *  \brief Control command used by Fvid2_setFormat()
 341  *
 342  *  \param cmdArgs       [IN]  const Fvid2_Format *
 343  *  \param cmdStatusArgs [OUT] NULL
 344  *
 345  *  \return FVID2_SOK on success, else failure.
 346  */
 347 #define FVID2_SET_FORMAT                ((uint32_t) FVID2_CTRL_BASE + 3U)
 348
 349 /**
 350  *  \brief Control command used by Fvid2_getFormat()
 351  *
 352  *  \param cmdArgs       [IN]  Fvid2_Format *
 353  *  \param cmdStatusArgs [OUT] NULL
 354  *
 355  *  \return FVID2_SOK on success, else failure.
 356  */
 357 #define FVID2_GET_FORMAT                ((uint32_t) FVID2_CTRL_BASE + 4U)
 358
 359 /**
 360  *  \brief Control command used by Fvid2_start()
 361  *
 362  *  \param cmdArgs       [IN]  Driver specific
 363  *  \param cmdStatusArgs [OUT] NULL
 364  *
 365  *  \return FVID2_SOK on success, else failure.
 366  */
 367 #define FVID2_START                     ((uint32_t) FVID2_CTRL_BASE + 5U)
 368
 369 /**
 370  *  \brief Control command used by Fvid2_stop()
 371  *
 372  *  \param cmdArgs       [IN]  Driver specific
 373  *  \param cmdStatusArgs [OUT] NULL
 374  *
 375  *  \return FVID2_SOK on success, else failure.
 376  */
 377 #define FVID2_STOP                      ((uint32_t) FVID2_CTRL_BASE + 6U)
 378
 379 /* @} */
 380
 381 /* ========================================================================== */
 382 /*                         Structure Declarations                             */
 383 /* ========================================================================== */
 384
 385 /**
 386  *  \brief FVID2 callback parameters that are setup during Fvid2_create().
 387  */
 388 typedef struct
 389 {
 390     Fvid2_CbFxn    cbFxn;
 391     /**< Application callback function used by the driver to intimate any
 392      *   operation has completed or not. This is an optional parameter
 393      *   in case application decides to use polling method and so could be
 394      *   set to NULL. */
 395
 396     Fvid2_ErrCbFxn errCbFxn;
 397     /**< Application error callback function used by the driver to intimate
 398      *   any error occurs at the time of streaming. This is an optional
 399      *   parameter in case application decides not to get any error callback
 400      *   and so could be set to NULL. */
 401
 402     void           *errList;
 403     /**< Pointer to a valid Fvid2_FrameList in case of capture
 404      *   and display drivers or a pointer to a valid Fvid2_ProcessList
 405      *   in case of M2M drivers where the driver copies
 406      *   the aborted/error packet. The memory of this list should be
 407      *   allocated by the application and provided to the driver at the time
 408      *   of driver creation. When the application gets this callback, it has
 409      *   to empty this list and taken necessary action like freeing up memories
 410      *   etc. The driver will then reuse the same list for future error
 411      *   callback.
 412      *   This could be NULL if errCbFxn is NULL. Otherwise this should be
 413      *   non-NULL. */
 414
 415     void           *appData;
 416     /**< Application specific data which is returned in the callback function
 417      *   as it is. This could be set to NULL if not used. */
 418 } Fvid2_CbParams;
 419
 420 /* ========================================================================== */
 421 /*                          Function Declarations                             */
 422 /* ========================================================================== */
 423
 424 /**
 425  *  \brief FVID2 init function.
 426  *
 427  *  Initializes the FVID2 layer.
 428  *  This function should be called before calling any of FVID2 API's and
 429  *  should be called only once.
 430  *
 431  *  \param args         [IN] Not used currently. Set to NULL.
 432  *
 433  *  \return FVID2_SOK on success else appropriate FVID2 error code on failure.
 434  */
 435 int32_t Fvid2_init(void *args);
 436
 437 /**
 438  *  \brief FVID2 deinit function.
 439  *
 440  *  Uninitializes the FVID2 layer and should be called during system shutdown.
 441  *  Should not be called if Fvid2_init() is not called.
 442  *
 443  *  \param args         [IN] Not used currently. Set to NULL.
 444  *
 445  *  \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
 446  */
 447 int32_t Fvid2_deInit(void *args);
 448
 449 /**
 450  *  \brief Get the version string for FVID2 interface.
 451  *
 452  *  This is the version number for the FVID2 interface. This
 453  *  function can be called prior to #Fvid2_init() to get the version number.
 454  *
 455  *  \return Pointer to FVID2 version string.
 456  */
 457 const char *Fvid2_getVersionString(void);
 458
 459 /**
 460  *  \brief Same as #Fvid2_getVersionString() except it returns the version in
 461  *  uint32_t form.
 462  *
 463  *  Example, v1.0.1.17 will be 0x01000117
 464  *
 465  *  \return FVID2 version number.
 466  */
 467 uint32_t Fvid2_getVersionNumber(void);
 468
 469 /**
 470  *  \brief Creates the driver identified by the driver ID.
 471  *
 472  *  This will allocate HW and/or SW resources and return a Fvid2_Handle
 473  *  for this driver. This handle will be used for subsequent FVID2 API calls
 474  *
 475  *  \param drvId        [IN] Driver to open. Driver ID is driver specific.
 476  *
 477  *  \param instanceId   [IN] Instance of the driver to open and is used
 478  *                      to differentiate multiple instance support on a
 479  *                      single driver. Instance ID is driver specific.
 480  *
 481  *  \param createArgs   [IN] Pointer to the create argument structure. The type
 482  *                      of the structure is defined by the specific driver.
 483  *                      This parameter could be NULL depending on whether the
 484  *                      actual driver forces it or not.
 485  *
 486  *  \param createStatusArgs [OUT] Pointer to status argument structure where the
 487  *                      driver returns any status information. The type
 488  *                      of the structure is defined by the specific driver.
 489  *                      This parameter could be NULL depending on whether the
 490  *                      actual driver forces it or not.
 491  *
 492  *  \param cbParams     [IN] Application callback parameters.
 493  *                      This parameter could be NULL depending on whether the
 494  *                      actual driver forces it or not.
 495  *
 496  *  \return non-NULL Fvid2_Handle object pointer on success else returns NULL
 497  *  on error.
 498  */
 499 Fvid2_Handle Fvid2_create(uint32_t              drvId,
 500                           uint32_t              instanceId,
 501                           void                 *createArgs,
 502                           void                 *createStatusArgs,
 503                           const Fvid2_CbParams *cbParams);
 504
 505 /**
 506  *  \brief Deletes a previously created FVID2 driver handle.
 507  *
 508  *  This free's the HW/SW resources allocated during create
 509  *
 510  *  \param handle       [IN] FVID2 handle returned by create call.
 511  *
 512  *  \param deleteArgs   [IN] Pointer to the delete argument structure. The type
 513  *                      of the structure is defined by the specific driver.
 514  *                      This parameter could be NULL depending on whether the
 515  *                      actual driver forces it or not.
 516  *
 517  *  \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
 518  */
 519 int32_t Fvid2_delete(Fvid2_Handle handle, void *deleteArgs);
 520
 521 /**
 522  *  \brief Send control commands (IOCTLs) to the driver.
 523  *
 524  *  \param handle       [IN] FVID2 handle returned by create call.
 525  *
 526  *  \param cmd          [IN] IOCTL command. The type of command supported
 527  *                      is defined by the specific driver.
 528  *
 529  *  \param cmdArgs      [IN] Pointer to the command argument structure. The type
 530  *                      of the structure is defined by the specific driver
 531  *                      for each of the supported IOCTL.
 532  *                      This parameter could be NULL depending on whether the
 533  *                      actual driver forces it or not.
 534  *
 535  *  \param cmdStatusArgs [OUT] Pointer to status argument structure where the
 536  *                      driver returns any status information. The type
 537  *                      of the structure is defined by the specific driver
 538  *                      for each of the supported IOCTL.
 539  *                      This parameter could be NULL depending on whether the
 540  *                      actual driver forces it or not.
 541  *
 542  *  \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
 543  */
 544 int32_t Fvid2_control(Fvid2_Handle  handle,
 545                       uint32_t      cmd,
 546                       void         *cmdArgs,
 547                       void         *cmdStatusArgs);
 548
 549 /**
 550  *  \brief An application calls Fvid2_queue to submit a video buffer to the
 551  *  video device driver.
 552  *
 553  *  - This is used in capture/display drivers.
 554  *  - This function could be called from task or ISR context unless the specific
 555  *  driver restricts from doing so.
 556  *  - This is a non-blocking API unless the specific driver restricts from
 557  *  doing so.
 558  *
 559  *  \param handle       [IN] FVID2 handle returned by create call.
 560  *  \param frameList    [IN] Pointer to the frame list structure containing the
 561  *                      information about the FVID2 frames that has to be
 562  *                      queued in the driver.
 563  *  \param streamId     [IN] Stream ID to which the frames should be queued
 564  *                      This is used in drivers where they could support
 565  *                      multiple streams for the same handle. Otherwise this
 566  *                      should be set to zero.
 567  *
 568  *  \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
 569  */
 570 int32_t Fvid2_queue(Fvid2_Handle        handle,
 571                     Fvid2_FrameList    *frameList,
 572                     uint32_t            streamId);
 573
 574 /**
 575  *  \brief An application calls Fvid2_dequeue to request the video device
 576  *  driver to give ownership of a video buffer.
 577  *
 578  *  - This is used in capture/display drivers.
 579  *  - This is a non-blocking API if timeout is FVID2_TIMEOUT_NONE and could be
 580  *  called by task and ISR context unless the specific driver restricts from
 581  *  doing so.
 582  *  - This is blocking API if timeout is FVID2_TIMEOUT_FOREVER if supported by
 583  *  specific driver implementation.
 584  *
 585  *  \param handle       [IN] FVID2 handle returned by create call.
 586  *  \param frameList    [OUT] Pointer to the frame list structure where the
 587  *                      dequeued frame pointer will be stored.
 588  *  \param streamId     [IN] Stream ID from where frames should be dequeued.
 589  *                      This is used in drivers where it could support multiple
 590  *                      streams for the same handle. Otherwise this
 591  *                      should be set to zero.
 592  *  \param timeout      [IN] FVID2 timeout in units of OS ticks. This will
 593  *                      determine the timeout value till the driver will block
 594  *                      for a free or completed buffer is available.
 595  *                      For non-blocking drivers this parameter might be
 596  *                      ignored.
 597  *
 598  *  \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
 599  */
 600 int32_t Fvid2_dequeue(Fvid2_Handle      handle,
 601                       Fvid2_FrameList  *frameList,
 602                       uint32_t          streamId,
 603                       uint32_t          timeout);
 604
 605 /**
 606  *  \brief An application calls Fvid2_processRequest to submit a video buffer
 607  *  to the video device driver.
 608  *
 609  *  This API is used for submitting a single channel video processing request
 610  *  to the video device driver. It uses framelist to submit multiple
 611  *  frames of different stream ids of the same request.
 612  *
 613  *  - This function could be called from task or ISR context unless the specific
 614  *  driver restricts from doing so.
 615  *  - This is a non-blocking API unless the specific driver restricts from
 616  *  doing so.
 617  *
 618  *  \param handle       [IN] FVID2 handle returned by create call.
 619  *  \param inFrameList  [IN] Pointer to the array of input frames with
 620  *                           different stream ids.
 621  *  \param outFrameList [IN] Pointer to the array of output frames with
 622  *                           different stream ids
 623  *
 624  *  \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
 625  */
 626 int32_t Fvid2_processRequest(Fvid2_Handle       handle,
 627                              Fvid2_FrameList   *inFrameList,
 628                              Fvid2_FrameList   *outFrameList);
 629
 630 /**
 631  *  \brief An application calls Fvid2_getProcessedRequest to get the
 632  *  processed request back from the driver and thus to get the
 633  *  ownership of request back from the driver.
 634  *
 635  *  - This is a non-blocking API if timeout is FVID2_TIMEOUT_NONE and could be
 636  *  called by task and ISR context unless the specific driver restricts from
 637  *  doing so.
 638  *  - This is blocking API if timeout is FVID2_TIMEOUT_FOREVER if supported by
 639  *  specific driver implementation.
 640  *
 641  *  \param handle       [IN] FVID2 handle returned by create call.
 642  *  \param inFrameList  [OUT] Pointer to frame list in which input frames with
 643  *                            different stream ids will be returned
 644  *                            by the driver.
 645  *  \param outFrameList [OUT] Pointer to frame list in which output frames with
 646  *                            different stream ids will be returned by
 647  *                            the driver.
 648  *  \param timeout      [IN] FVID2 timeout. This will determine the timeout
 649  *                           value till the driver will block for a
 650  *                           free or completed buffer is available.
 651  *                           For non-blocking drivers this parameter
 652  *                           might be ignored.
 653  *
 654  *  \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
 655  */
 656 int32_t Fvid2_getProcessedRequest(Fvid2_Handle      handle,
 657                                   Fvid2_FrameList  *inFrameList,
 658                                   Fvid2_FrameList  *outFrameList,
 659                                   uint32_t          timeout);
 660 /**
 661  *  \brief An application calls Fvid2_start to request the video device
 662  *  driver to start the video display or capture operation.
 663  *  This function should be called from task context only and should not be
 664  *  called from ISR context.
 665  *
 666  *  \param handle       [IN] FVID2 handle returned by create call.
 667  *  \param cmdArgs      [IN] Pointer to the start argument structure. The type
 668  *                      of the structure is defined by the specific driver.
 669  *                      This parameter could be NULL depending on whether the
 670  *                      actual driver forces it or not.
 671  *
 672  *  \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
 673  */
 674 static inline int32_t Fvid2_start(Fvid2_Handle handle, void *cmdArgs);
 675
 676 /**
 677  *  \brief An application calls Fvid2_stop to request the video device
 678  *  driver to stop the video display or capture operation.
 679  *  This function should be called from task context only and should not be
 680  *  called from ISR context.
 681  *
 682  *  \param handle       [IN] FVID2 handle returned by create call.
 683  *  \param cmdArgs      [IN] Pointer to the stop argument structure. The type
 684  *                      of the structure is defined by the specific driver.
 685  *                      This parameter could be NULL depending on whether the
 686  *                      actual driver forces it or not.
 687  *
 688  *  \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
 689  */
 690 static inline int32_t Fvid2_stop(Fvid2_Handle handle, void *cmdArgs);
 691
 692 /**
 693  *  \brief An application calls Fvid2_setFormat to request the video device
 694  *  driver to set the format for a given channel.
 695  *  This function should be called from task context only and should not be
 696  *  called from ISR context.
 697  *
 698  *  \param handle       [IN] FVID2 handle returned by create call.
 699  *  \param fmt          [IN] Pointer to the FVID2 format structure.
 700  *
 701  *  \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
 702  */
 703 static inline int32_t Fvid2_setFormat(Fvid2_Handle handle, Fvid2_Format *fmt);
 704
 705 /**
 706  *  \brief An application calls Fvid2_getFormat to request the video device
 707  *  driver to get the current format for a given channel.
 708  *  This function should be called from task context only and should not be
 709  *  called from ISR context.
 710  *
 711  *  \param handle       [IN] FVID2 handle returned by create call.
 712  *  \param fmt          [OUT] Pointer to the FVID2 format structure.
 713  *
 714  *  \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
 715  */
 716 static inline int32_t Fvid2_getFormat(Fvid2_Handle handle, Fvid2_Format *fmt);
 717
 718 /**
 719  *  \brief Fvid2_CbParams structure init function.
 720  *
 721  *  \param cbPrms       [IN] Pointer to #Fvid2_CbParams structure.
 722  *
 723  */
 724 static inline void Fvid2CbParams_init(Fvid2_CbParams *cbPrms);
 725
 726 /* ========================================================================== */
 727 /*                       Static Function Definitions                          */
 728 /* ========================================================================== */
 729
 730 static inline int32_t Fvid2_start(Fvid2_Handle handle, void *cmdArgs)
 731 {
 732     return Fvid2_control(handle, FVID2_START, cmdArgs, NULL);
 733 }
 734
 735 static inline int32_t Fvid2_stop(Fvid2_Handle handle, void *cmdArgs)
 736 {
 737     return Fvid2_control(handle, FVID2_STOP, cmdArgs, NULL);
 738 }
 739
 740 static inline int32_t Fvid2_setFormat(Fvid2_Handle handle, Fvid2_Format *fmt)
 741 {
 742     return Fvid2_control(handle, FVID2_SET_FORMAT, fmt, NULL);
 743 }
 744
 745 static inline int32_t Fvid2_getFormat(Fvid2_Handle handle, Fvid2_Format *fmt)
 746 {
 747     return Fvid2_control(handle, FVID2_GET_FORMAT, fmt, NULL);
 748 }
 749
 750 static inline void Fvid2CbParams_init(Fvid2_CbParams *cbPrms)
 751 {
 752     if (NULL != cbPrms)
 753     {
 754         cbPrms->cbFxn    = NULL;
 755         cbPrms->errCbFxn = NULL;
 756         cbPrms->errList  = NULL;
 757         cbPrms->appData  = NULL;
 758     }
 759
 760     return;
 761 }
 762
 763 #ifdef __cplusplus
 764 }
 765 #endif
 766
 767 #endif  /* #ifndef FVID2_H_ */
 768
 769 /* @} */