c46a2ecbd0a7cc453ff4acf4725f358b1b2c6557
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
449 {
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
484 {
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
507 {
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 *
719 * \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
720 */
721 int32_t Fvid2_processRequest(Fvid2_Handle handle,
722 Fvid2_FrameList *inFrameList,
723 Fvid2_FrameList *outFrameList);
725 /**
726 * \brief An application calls Fvid2_getProcessedRequest to get the
727 * processed request back from the driver and thus to get the
728 * ownership of request back from the driver.
729 *
730 * - This is a non-blocking API if timeout is FVID2_TIMEOUT_NONE and could be
731 * called by task and ISR context unless the specific driver restricts from
732 * doing so.
733 * - This is blocking API if timeout is FVID2_TIMEOUT_FOREVER if supported by
734 * specific driver implementation.
735 *
736 * \param handle [IN] FVID2 handle returned by create call.
737 * \param inFrameList [OUT] Pointer to frame list in which input frames with
738 * different stream ids will be returned
739 * by the driver.
740 * \param outFrameList [OUT] Pointer to frame list in which output frames with
741 * different stream ids will be returned by
742 * the driver.
743 * \param timeout [IN] FVID2 timeout. This will determine the timeout
744 * value till the driver will block for a
745 * free or completed buffer is available.
746 * For non-blocking drivers this parameter
747 * might be ignored.
748 *
749 * \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
750 */
751 int32_t Fvid2_getProcessedRequest(Fvid2_Handle handle,
752 Fvid2_FrameList *inFrameList,
753 Fvid2_FrameList *outFrameList,
754 uint32_t timeout);
755 /**
756 * \brief An application calls Fvid2_start to request the video device
757 * driver to start the video display or capture operation.
758 * This function should be called from task context only and should not be
759 * called from ISR context.
760 *
761 * \param handle [IN] FVID2 handle returned by create call.
762 * \param cmdArgs [IN] Pointer to the start argument structure. The type
763 * of the structure is defined by the specific driver.
764 * This parameter could be NULL depending on whether the
765 * actual driver forces it or not.
766 *
767 * \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
768 */
769 static inline int32_t Fvid2_start(Fvid2_Handle handle, void *cmdArgs);
771 /**
772 * \brief An application calls Fvid2_stop to request the video device
773 * driver to stop the video display or capture operation.
774 * This function should be called from task context only and should not be
775 * called from ISR context.
776 *
777 * \param handle [IN] FVID2 handle returned by create call.
778 * \param cmdArgs [IN] Pointer to the stop argument structure. The type
779 * of the structure is defined by the specific driver.
780 * This parameter could be NULL depending on whether the
781 * actual driver forces it or not.
782 *
783 * \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
784 */
785 static inline int32_t Fvid2_stop(Fvid2_Handle handle, void *cmdArgs);
787 /**
788 * \brief An application calls Fvid2_setFormat to request the video device
789 * driver to set the format for a given channel.
790 * This function should be called from task context only and should not be
791 * called from ISR context.
792 *
793 * \param handle [IN] FVID2 handle returned by create call.
794 * \param fmt [IN] Pointer to the FVID2 format structure.
795 *
796 * \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
797 */
798 static inline int32_t Fvid2_setFormat(Fvid2_Handle handle, Fvid2_Format *fmt);
800 /**
801 * \brief An application calls Fvid2_getFormat to request the video device
802 * driver to get the current format for a given channel.
803 * This function should be called from task context only and should not be
804 * called from ISR context.
805 *
806 * \param handle [IN] FVID2 handle returned by create call.
807 * \param fmt [OUT] Pointer to the FVID2 format structure.
808 *
809 * \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
810 */
811 static inline int32_t Fvid2_getFormat(Fvid2_Handle handle, Fvid2_Format *fmt);
813 /*
814 * Structure Init functions
815 */
816 /**
817 * \brief Fvid2_InitPrms structure init function.
818 *
819 * \param initPrms [IN] Pointer to #Fvid2_InitPrms structure.
820 *
821 */
822 static inline void Fvid2InitPrms_init(Fvid2_InitPrms *initPrms);
824 /**
825 * \brief Fvid2_CbParams structure init function.
826 *
827 * \param cbPrms [IN] Pointer to #Fvid2_CbParams structure.
828 *
829 */
830 static inline void Fvid2CbParams_init(Fvid2_CbParams *cbPrms);
832 /* ========================================================================== */
833 /* Static Function Definitions */
834 /* ========================================================================== */
836 static inline int32_t Fvid2_start(Fvid2_Handle handle, void *cmdArgs)
837 {
838 return Fvid2_control(handle, FVID2_START, cmdArgs, NULL);
839 }
841 static inline int32_t Fvid2_stop(Fvid2_Handle handle, void *cmdArgs)
842 {
843 return Fvid2_control(handle, FVID2_STOP, cmdArgs, NULL);
844 }
846 static inline int32_t Fvid2_setFormat(Fvid2_Handle handle, Fvid2_Format *fmt)
847 {
848 return Fvid2_control(handle, FVID2_SET_FORMAT, fmt, NULL);
849 }
851 static inline int32_t Fvid2_getFormat(Fvid2_Handle handle, Fvid2_Format *fmt)
852 {
853 return Fvid2_control(handle, FVID2_GET_FORMAT, fmt, NULL);
854 }
856 static inline void Fvid2InitPrms_init(Fvid2_InitPrms *initPrms)
857 {
858 if (NULL != initPrms)
859 {
860 initPrms->printFxn = NULL;
861 }
863 return;
864 }
866 static inline void Fvid2CbParams_init(Fvid2_CbParams *cbPrms)
867 {
868 if (NULL != cbPrms)
869 {
870 cbPrms->cbFxn = NULL;
871 cbPrms->errCbFxn = NULL;
872 cbPrms->errList = NULL;
873 cbPrms->appData = NULL;
874 }
876 return;
877 }
879 #ifdef __cplusplus
880 }
881 #endif
883 #endif /* #ifndef FVID2_API_H_ */
885 /* @} */