NOTICE OF RELOCATION
[keystone-rtos/fvid2.git] / include / fvid2_api.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  */
33 /**
34  *  \file fvid2_api.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  */
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  */
182 #ifndef FVID2_API_H_
183 #define FVID2_API_H_
185 /* ========================================================================== */
186 /*                             Include Files                                  */
187 /* ========================================================================== */
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>
193 #ifdef __cplusplus
194 extern "C" {
195 #endif
197 /* ========================================================================== */
198 /*                           Macros & Typedefs                                */
199 /* ========================================================================== */
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"
214 /** \brief FVID2 driver version number. */
215 #define FVID2_VERSION_NUMBER            (0x02020000U)
217 /** \brief FVID2 Driver handle. */
218 typedef void *Fvid2_Handle;
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);
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);
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);
316 /**
317  *  \brief Function prototype, to determine the time stamp.
318  *
319  *  \param args  [IN]  Not used as of now.
320  *
321  *  \return An unsigned int 64 value, that represents the current time in usec.
322  */
323 typedef uint64_t (*Fvid2_TimeStampFxn)(void *args);
325 /**
326  *  \brief FVID2 info/debug print function prototype.
327  *
328  *  This function is used by the driver to print info/debug messages.
329  *
330  *  \param format   [OUT] Info string to print.
331  */
332 typedef void (*Fvid2_PrintFxn)(const char *format, ...);
334 /**
335  *  \name FVID2 Max limits
336  *  @{
337  */
339 /** \brief Decide the streamid based on channel number.  */
340 #define FVID2_STREAM_ID_ANY             (0xFFFFFFFFU)
342 /* @} */
344 /*
345  * =========== Command codes for Submit call =============
346  */
347 /** \brief Control command base address. */
348 #define FVID2_CTRL_BASE                 (0x00000000U)
349 /** \brief User command base address. */
350 #define FVID2_USER_BASE                 (0x10000000U)
352 /**
353  *  \addtogroup BSP_DRV_IOCTL_FVID2
354  *  @{
355  */
357 /**
358  *  \brief Control command used by Fvid2_setFormat()
359  *
360  *  \param cmdArgs       [IN]  const Fvid2_Format *
361  *  \param cmdStatusArgs [OUT] NULL
362  *
363  *  \return FVID2_SOK on success, else failure.
364  */
365 #define FVID2_SET_FORMAT                ((uint32_t) FVID2_CTRL_BASE + 3U)
367 /**
368  *  \brief Control command used by Fvid2_getFormat()
369  *
370  *  \param cmdArgs       [IN]  Fvid2_Format *
371  *  \param cmdStatusArgs [OUT] NULL
372  *
373  *  \return FVID2_SOK on success, else failure.
374  */
375 #define FVID2_GET_FORMAT                ((uint32_t) FVID2_CTRL_BASE + 4U)
377 /**
378  *  \brief Control command used by Fvid2_start()
379  *
380  *  \param cmdArgs       [IN]  Driver specific
381  *  \param cmdStatusArgs [OUT] NULL
382  *
383  *  \return FVID2_SOK on success, else failure.
384  */
385 #define FVID2_START                     ((uint32_t) FVID2_CTRL_BASE + 5U)
387 /**
388  *  \brief Control command used by Fvid2_stop()
389  *
390  *  \param cmdArgs       [IN]  Driver specific
391  *  \param cmdStatusArgs [OUT] NULL
392  *
393  *  \return FVID2_SOK on success, else failure.
394  */
395 #define FVID2_STOP                      ((uint32_t) FVID2_CTRL_BASE + 6U)
397 /**
398  *  \brief Register an application function (pointer) for getting the
399  *  time stamp value used at the frame completion time.
400  *
401  *  The same IOCTL could be used to un-register the existing time stamp
402  *  function by passing NULL to the function pointer.
403  *
404  *  \param cmdArgs       [IN]  const Fvid2_TimeStampParams *
405  *  \param cmdArgsStatus       NULL
406  *
407  *  \return FVID2_SOK on success, else failure.
408  */
409 #define FVID2_REGISTER_TIMESTAMP_FXN    ((uint32_t) FVID2_CTRL_BASE + 7U)
411 /* @} */
413 /*
414  *  Driver ID Base.
415  */
416 /** \brief Driver ID base for the DSS driver class. */
417 #define FVID2_DSS_DRV_BASE              (0x00001000U)
418 /** \brief Driver ID base for the CAL driver class. */
419 #define FVID2_CAL_DRV_BASE              (0x00002000U)
420 /** \brief Driver ID base for the CSIRX driver class. */
421 #define FVID2_CSIRX_DRV_BASE            (0x00003000U)
422 /** \brief Driver ID base for the CSITX driver class. */
423 #define FVID2_CSITX_DRV_BASE            (0x00004000U)
424 /** \brief Driver ID base for the VHWA driver class. */
425 #define FVID2_VHWA_DRV_BASE             (0x00005000U)
427 /*
428  *  IOCTLs Base.
429  */
430 /** \brief IOCTL base for the DSS driver class. */
431 #define FVID2_DSS_DRV_IOCTL_BASE        (FVID2_USER_BASE + FVID2_DSS_DRV_BASE)
432 /** \brief IOCTL base for the CAL driver class. */
433 #define FVID2_CAL_DRV_IOCTL_BASE        (FVID2_USER_BASE + FVID2_CAL_DRV_BASE)
434 /** \brief IOCTL base for the CSIRX driver class. */
435 #define FVID2_CSIRX_DRV_IOCTL_BASE      (FVID2_USER_BASE + FVID2_CSIRX_DRV_BASE)
436 /** \brief IOCTL base for the CSITX driver class. */
437 #define FVID2_CSITX_DRV_IOCTL_BASE      (FVID2_USER_BASE + FVID2_CSITX_DRV_BASE)
438 /** \brief IOCTL base for the VHWA driver class. */
439 #define FVID2_VHWA_DRV_IOCTL_BASE       (FVID2_USER_BASE + FVID2_VHWA_DRV_BASE)
441 /* ========================================================================== */
442 /*                         Structure Declarations                             */
443 /* ========================================================================== */
445 /**
446  *  \brief FVID2 callback parameters that are setup during Fvid2_create().
447  */
448 typedef struct
450     Fvid2_CbFxn    cbFxn;
451     /**< Application callback function used by the driver to intimate any
452      *   operation has completed or not. This is an optional parameter
453      *   in case application decides to use polling method and so could be
454      *   set to NULL. */
456     Fvid2_ErrCbFxn errCbFxn;
457     /**< Application error callback function used by the driver to intimate
458      *   any error occurs at the time of streaming. This is an optional
459      *   parameter in case application decides not to get any error callback
460      *   and so could be set to NULL. */
462     void           *errList;
463     /**< Pointer to a valid Fvid2_FrameList in case of capture
464      *   and display drivers or a pointer to a valid Fvid2_ProcessList
465      *   in case of M2M drivers where the driver copies
466      *   the aborted/error packet. The memory of this list should be
467      *   allocated by the application and provided to the driver at the time
468      *   of driver creation. When the application gets this callback, it has
469      *   to empty this list and taken necessary action like freeing up memories
470      *   etc. The driver will then reuse the same list for future error
471      *   callback.
472      *   This could be NULL if errCbFxn is NULL. Otherwise this should be
473      *   non-NULL. */
475     void           *appData;
476     /**< Application specific data which is returned in the callback function
477      *   as it is. This could be set to NULL if not used. */
478 } Fvid2_CbParams;
480 /**
481  *  \brief Structure used to configure time stamping of frames.
482  */
483 typedef struct
485     Fvid2_TimeStampFxn  timeStampFxn;
486     /**< By default, OSAL (BIOS) API is used to time stamp frames.
487      *
488      *   Applications could over-ride the same, by providing a
489      *   function that would return an unsigned int 64 value representing the
490      *   timestamp in usec.
491      *   The driver would call this function and update the 'timeStamp'
492      *   and 'timeStamp64' member of #Fvid2_Frame with the return
493      *   value of this function.
494      *
495      *   Note: The 64-bit value / 1000 is used to update the 'timeStamp'
496      *   member.
497      *
498      *   Passing a value of NULL un-registers the time stamp function. */
499     uint32_t reserved;
500     /**< Not used now. Set to zero. */
501 } Fvid2_TimeStampParams;
503 /**
504  *  \brief FVID2 initialization parameters.
505  */
506 typedef struct
508     Fvid2_PrintFxn      printFxn;
509     /**< If not NULL, this function will be called to print debug/info message
510      *   with appropriate string. */
511 } Fvid2_InitPrms;
513 /* ========================================================================== */
514 /*                          Function Declarations                             */
515 /* ========================================================================== */
517 /**
518  *  \brief FVID2 init function.
519  *
520  *  Initializes the FVID2 layer.
521  *  This function should be called before calling any of FVID2 API's and
522  *  should be called only once.
523  *
524  *  \param initPrms     [IN] FVID2 Initialization parameters.
525  *                           If NULL is passed, the default parameters will be
526  *                           assumed - no print will be enabled
527  *
528  *  \return FVID2_SOK on success else appropriate FVID2 error code on failure.
529  */
530 int32_t Fvid2_init(const Fvid2_InitPrms *initPrms);
532 /**
533  *  \brief FVID2 deinit function.
534  *
535  *  Uninitializes the FVID2 layer and should be called during system shutdown.
536  *  Should not be called if Fvid2_init() is not called.
537  *
538  *  \param args         [IN] Not used currently. Set to NULL.
539  *
540  *  \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
541  */
542 int32_t Fvid2_deInit(void *args);
544 /**
545  *  \brief Get the version string for FVID2 interface.
546  *
547  *  This is the version number for the FVID2 interface. This
548  *  function can be called prior to #Fvid2_init() to get the version number.
549  *
550  *  \return Pointer to FVID2 version string.
551  */
552 const char *Fvid2_getVersionString(void);
554 /**
555  *  \brief Same as #Fvid2_getVersionString() except it returns the version in
556  *  uint32_t form.
557  *
558  *  Example, v1.0.1.17 will be 0x01000117
559  *
560  *  \return FVID2 version number.
561  */
562 uint32_t Fvid2_getVersionNumber(void);
564 /**
565  *  \brief Creates the driver identified by the driver ID.
566  *
567  *  This will allocate HW and/or SW resources and return a Fvid2_Handle
568  *  for this driver. This handle will be used for subsequent FVID2 API calls
569  *
570  *  \param drvId        [IN] Driver to open. Driver ID is driver specific.
571  *
572  *  \param instanceId   [IN] Instance of the driver to open and is used
573  *                      to differentiate multiple instance support on a
574  *                      single driver. Instance ID is driver specific.
575  *
576  *  \param createArgs   [IN] Pointer to the create argument structure. The type
577  *                      of the structure is defined by the specific driver.
578  *                      This parameter could be NULL depending on whether the
579  *                      actual driver forces it or not.
580  *
581  *  \param createStatusArgs [OUT] Pointer to status argument structure where the
582  *                      driver returns any status information. The type
583  *                      of the structure is defined by the specific driver.
584  *                      This parameter could be NULL depending on whether the
585  *                      actual driver forces it or not.
586  *
587  *  \param cbParams     [IN] Application callback parameters.
588  *                      This parameter could be NULL depending on whether the
589  *                      actual driver forces it or not.
590  *
591  *  \return non-NULL Fvid2_Handle object pointer on success else returns NULL
592  *  on error.
593  */
594 Fvid2_Handle Fvid2_create(uint32_t              drvId,
595                           uint32_t              instanceId,
596                           void                 *createArgs,
597                           void                 *createStatusArgs,
598                           const Fvid2_CbParams *cbParams);
600 /**
601  *  \brief Deletes a previously created FVID2 driver handle.
602  *
603  *  This free's the HW/SW resources allocated during create
604  *
605  *  \param handle       [IN] FVID2 handle returned by create call.
606  *
607  *  \param deleteArgs   [IN] Pointer to the delete argument structure. The type
608  *                      of the structure is defined by the specific driver.
609  *                      This parameter could be NULL depending on whether the
610  *                      actual driver forces it or not.
611  *
612  *  \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
613  */
614 int32_t Fvid2_delete(Fvid2_Handle handle, void *deleteArgs);
616 /**
617  *  \brief Send control commands (IOCTLs) to the driver.
618  *
619  *  \param handle       [IN] FVID2 handle returned by create call.
620  *
621  *  \param cmd          [IN] IOCTL command. The type of command supported
622  *                      is defined by the specific driver.
623  *
624  *  \param cmdArgs      [IN] Pointer to the command argument structure. The type
625  *                      of the structure is defined by the specific driver
626  *                      for each of the supported IOCTL.
627  *                      This parameter could be NULL depending on whether the
628  *                      actual driver forces it or not.
629  *
630  *  \param cmdStatusArgs [OUT] Pointer to status argument structure where the
631  *                      driver returns any status information. The type
632  *                      of the structure is defined by the specific driver
633  *                      for each of the supported IOCTL.
634  *                      This parameter could be NULL depending on whether the
635  *                      actual driver forces it or not.
636  *
637  *  \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
638  */
639 int32_t Fvid2_control(Fvid2_Handle  handle,
640                       uint32_t      cmd,
641                       void         *cmdArgs,
642                       void         *cmdStatusArgs);
644 /**
645  *  \brief An application calls Fvid2_queue to submit a video buffer to the
646  *  video device driver.
647  *
648  *  - This is used in capture/display drivers.
649  *  - This function could be called from task or ISR context unless the specific
650  *  driver restricts from doing so.
651  *  - This is a non-blocking API unless the specific driver restricts from
652  *  doing so.
653  *
654  *  \param handle       [IN] FVID2 handle returned by create call.
655  *  \param frameList    [IN] Pointer to the frame list structure containing the
656  *                      information about the FVID2 frames that has to be
657  *                      queued in the driver.
658  *  \param streamId     [IN] Stream ID to which the frames should be queued
659  *                      This is used in drivers where they could support
660  *                      multiple streams for the same handle. Otherwise this
661  *                      should be set to zero.
662  *
663  *  \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
664  */
665 int32_t Fvid2_queue(Fvid2_Handle        handle,
666                     Fvid2_FrameList    *frameList,
667                     uint32_t            streamId);
669 /**
670  *  \brief An application calls Fvid2_dequeue to request the video device
671  *  driver to give ownership of a video buffer.
672  *
673  *  - This is used in capture/display drivers.
674  *  - This is a non-blocking API if timeout is FVID2_TIMEOUT_NONE and could be
675  *  called by task and ISR context unless the specific driver restricts from
676  *  doing so.
677  *  - This is blocking API if timeout is FVID2_TIMEOUT_FOREVER if supported by
678  *  specific driver implementation.
679  *
680  *  \param handle       [IN] FVID2 handle returned by create call.
681  *  \param frameList    [OUT] Pointer to the frame list structure where the
682  *                      dequeued frame pointer will be stored.
683  *  \param streamId     [IN] Stream ID from where frames should be dequeued.
684  *                      This is used in drivers where it could support multiple
685  *                      streams for the same handle. Otherwise this
686  *                      should be set to zero.
687  *  \param timeout      [IN] FVID2 timeout in units of OS ticks. This will
688  *                      determine the timeout value till the driver will block
689  *                      for a free or completed buffer is available.
690  *                      For non-blocking drivers this parameter might be
691  *                      ignored.
692  *
693  *  \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
694  */
695 int32_t Fvid2_dequeue(Fvid2_Handle      handle,
696                       Fvid2_FrameList  *frameList,
697                       uint32_t          streamId,
698                       uint32_t          timeout);
700 /**
701  *  \brief An application calls Fvid2_processRequest to submit a video buffer
702  *  to the video device driver.
703  *
704  *  This API is used for submitting a single channel video processing request
705  *  to the video device driver. It uses framelist to submit multiple
706  *  frames of different stream ids of the same request.
707  *
708  *  - This function could be called from task or ISR context unless the specific
709  *  driver restricts from doing so.
710  *  - This is a non-blocking API unless the specific driver restricts from
711  *  doing so.
712  *
713  *  \param handle       [IN] FVID2 handle returned by create call.
714  *  \param inFrameList  [IN] Pointer to the array of input frames with
715  *                           different stream ids.
716  *  \param outFrameList [IN] Pointer to the array of output frames with
717  *                           different stream ids
718  *  \param timeout      [IN] FVID2 timeout. This will determine the timeout
719  *                           value till the driver will block for a
720  *                           free or completed buffer is available.
721  *                           For non-blocking drivers this parameter
722  *                           might be ignored.
723  *
724  *  \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
725  */
726 int32_t Fvid2_processRequest(Fvid2_Handle       handle,
727                              Fvid2_FrameList   *inFrameList,
728                              Fvid2_FrameList   *outFrameList,
729                              uint32_t           timeout);
731 /**
732  *  \brief An application calls Fvid2_getProcessedRequest to get the
733  *  processed request back from the driver and thus to get the
734  *  ownership of request back from the driver.
735  *
736  *  - This is a non-blocking API if timeout is FVID2_TIMEOUT_NONE and could be
737  *  called by task and ISR context unless the specific driver restricts from
738  *  doing so.
739  *  - This is blocking API if timeout is FVID2_TIMEOUT_FOREVER if supported by
740  *  specific driver implementation.
741  *
742  *  \param handle       [IN] FVID2 handle returned by create call.
743  *  \param inFrameList  [OUT] Pointer to frame list in which input frames with
744  *                            different stream ids will be returned
745  *                            by the driver.
746  *  \param outFrameList [OUT] Pointer to frame list in which output frames with
747  *                            different stream ids will be returned by
748  *                            the driver.
749  *  \param timeout      [IN] FVID2 timeout. This will determine the timeout
750  *                           value till the driver will block for a
751  *                           free or completed buffer is available.
752  *                           For non-blocking drivers this parameter
753  *                           might be ignored.
754  *
755  *  \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
756  */
757 int32_t Fvid2_getProcessedRequest(Fvid2_Handle      handle,
758                                   Fvid2_FrameList  *inFrameList,
759                                   Fvid2_FrameList  *outFrameList,
760                                   uint32_t          timeout);
761 /**
762  *  \brief An application calls Fvid2_start to request the video device
763  *  driver to start the video display or capture operation.
764  *  This function should be called from task context only and should not be
765  *  called from ISR context.
766  *
767  *  \param handle       [IN] FVID2 handle returned by create call.
768  *  \param cmdArgs      [IN] Pointer to the start argument structure. The type
769  *                      of the structure is defined by the specific driver.
770  *                      This parameter could be NULL depending on whether the
771  *                      actual driver forces it or not.
772  *
773  *  \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
774  */
775 static inline int32_t Fvid2_start(Fvid2_Handle handle, void *cmdArgs);
777 /**
778  *  \brief An application calls Fvid2_stop to request the video device
779  *  driver to stop the video display or capture operation.
780  *  This function should be called from task context only and should not be
781  *  called from ISR context.
782  *
783  *  \param handle       [IN] FVID2 handle returned by create call.
784  *  \param cmdArgs      [IN] Pointer to the stop argument structure. The type
785  *                      of the structure is defined by the specific driver.
786  *                      This parameter could be NULL depending on whether the
787  *                      actual driver forces it or not.
788  *
789  *  \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
790  */
791 static inline int32_t Fvid2_stop(Fvid2_Handle handle, void *cmdArgs);
793 /**
794  *  \brief An application calls Fvid2_setFormat to request the video device
795  *  driver to set the format for a given channel.
796  *  This function should be called from task context only and should not be
797  *  called from ISR context.
798  *
799  *  \param handle       [IN] FVID2 handle returned by create call.
800  *  \param fmt          [IN] Pointer to the FVID2 format structure.
801  *
802  *  \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
803  */
804 static inline int32_t Fvid2_setFormat(Fvid2_Handle handle, Fvid2_Format *fmt);
806 /**
807  *  \brief An application calls Fvid2_getFormat to request the video device
808  *  driver to get the current format for a given channel.
809  *  This function should be called from task context only and should not be
810  *  called from ISR context.
811  *
812  *  \param handle       [IN] FVID2 handle returned by create call.
813  *  \param fmt          [OUT] Pointer to the FVID2 format structure.
814  *
815  *  \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
816  */
817 static inline int32_t Fvid2_getFormat(Fvid2_Handle handle, Fvid2_Format *fmt);
819 /*
820  * Structure Init functions
821  */
822 /**
823  *  \brief Fvid2_InitPrms structure init function.
824  *
825  *  \param initPrms     [IN] Pointer to #Fvid2_InitPrms structure.
826  *
827  */
828 static inline void Fvid2InitPrms_init(Fvid2_InitPrms *initPrms);
830 /**
831  *  \brief Fvid2_CbParams structure init function.
832  *
833  *  \param cbPrms       [IN] Pointer to #Fvid2_CbParams structure.
834  *
835  */
836 static inline void Fvid2CbParams_init(Fvid2_CbParams *cbPrms);
838 /* ========================================================================== */
839 /*                       Static Function Definitions                          */
840 /* ========================================================================== */
842 static inline int32_t Fvid2_start(Fvid2_Handle handle, void *cmdArgs)
844     return Fvid2_control(handle, FVID2_START, cmdArgs, NULL);
847 static inline int32_t Fvid2_stop(Fvid2_Handle handle, void *cmdArgs)
849     return Fvid2_control(handle, FVID2_STOP, cmdArgs, NULL);
852 static inline int32_t Fvid2_setFormat(Fvid2_Handle handle, Fvid2_Format *fmt)
854     return Fvid2_control(handle, FVID2_SET_FORMAT, fmt, NULL);
857 static inline int32_t Fvid2_getFormat(Fvid2_Handle handle, Fvid2_Format *fmt)
859     return Fvid2_control(handle, FVID2_GET_FORMAT, fmt, NULL);
862 static inline void Fvid2InitPrms_init(Fvid2_InitPrms *initPrms)
864     if (NULL != initPrms)
865     {
866         initPrms->printFxn  = NULL;
867     }
869     return;
872 static inline void Fvid2CbParams_init(Fvid2_CbParams *cbPrms)
874     if (NULL != cbPrms)
875     {
876         cbPrms->cbFxn    = NULL;
877         cbPrms->errCbFxn = NULL;
878         cbPrms->errList  = NULL;
879         cbPrms->appData  = NULL;
880     }
882     return;
885 #ifdef __cplusplus
887 #endif
889 #endif  /* #ifndef FVID2_API_H_ */
891 /* @} */