a9bcd5f44986cf66b7587d344f18774e89571cb5
1 /* =============================================================================
2 * Copyright (c) Texas Instruments Incorporated 2012-2017
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.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 * Many FVID2 APIs define 'reserved' fields. These are meant for future use
157 * and should be set to NULL/zero by user.
158 *
159 */
161 /*
162 * \version 0.1 Created.
163 * 0.2 Changes for BIOS 6 and new FVID2 interface.
164 * 0.2.1 Merged color and data format enums to data format enums.
165 * Added process list structure to support M2M
166 * (memory to memory) drivers.
167 * Removed FVID2_Buf structure and directly used address array
168 * in Fvid2_Frame structure.
169 * Defined proper signature for FVID2 APIs.
170 * 0.2.2 Added proper comments.
171 * 0.3 Added subframe callback and added reserved fields in all the
172 * structures.
173 * 0.4 Made frames pointer to pointer to array of frame pointer in
174 * framelist to simplify application allocation and ease of
175 * use.
176 * 0.5 Added FVID2 standard enums.
177 * 0.6 Split into two files. fvid2.h will contain only FVID2 driver
178 * specific defintions/declarations. It will include
179 * fvid2_dataTypes.h for data type defintions
180 *
181 */
183 #ifndef FVID2_H_
184 #define FVID2_H_
186 /* ========================================================================== */
187 /* Include Files */
188 /* ========================================================================== */
190 #include <ti/csl/csl_fvid2_dataTypes.h>
192 #ifdef __cplusplus
193 extern "C" {
194 #endif
196 /* ========================================================================== */
197 /* Macros & Typedefs */
198 /* ========================================================================== */
200 /**
201 * \brief FVID2 driver version string.
202 * Version is of the form mm_nn_xx_yy where,
203 * mm - Product version (02 for FVID2). This increments for any new FVID2
204 * versions.
205 * nn - Major number - Increments if any backward compatibility is broken
206 * or major change within a product version.
207 * xx - Minor number - Increments for any minor change or any additions
208 * done without breaking backward compatibility.
209 * yy - Build number - Increments for every release.
210 */
211 #define FVID2_VERSION_STRING "FVID_02_01_00_02"
213 /** \brief FVID2 driver version number. */
214 #define FVID2_VERSION_NUMBER (0x02010002U)
216 /** \brief FVID2 Driver handle. */
217 typedef Ptr Fvid2_Handle;
219 /**
220 * \brief FVID2 driver callback function prototype.
221 *
222 * This callback is used by the drivers which implement non-blocking
223 * FVID2 APIs.
224 *
225 * User should assume that callbacks happen in ISR context and hence should
226 * apply rules relevant to ISR context when implementing callback functions,
227 * i.e blocking APIs should not be called from callback. Users should also
228 * assume that interrupts are enabled when in callback context, i.e other
229 * interrupt / callbacks can occur when a callback is under execution.
230 * User callback implementation should not be very long, since callback
231 * execution may block other drivers from executing. Typically it is
232 * recommended to set a semaphore or flag when callback happens and do the
233 * more involved callback handling in task context.
234 *
235 * This callback is typically called by the driver as mentioned below,
236 * unless specified otherwise by specific drivers.
237 *
238 * In case of display drivers, this callback function will be called
239 * when a frame(s) is/are completed displayed. Then the application can
240 * dequeue the displayed buffer back from the driver.
241 *
242 * In case of capture drivers, this callback function will be called
243 * when a frame(s) is/are captured. Then the application can dequeue the
244 * captured buffer back from the driver.
245 *
246 * In case of M2M drivers, this callback function will be called
247 * when a request from the application is completed by the driver. Then the
248 * application can dequeue the completed request buffers back from the driver.
249 *
250 * In case of control drivers, callbacks are typically not used since mostly
251 * FVID2 APIs implemented by control drivers are of blocking nature.
252 *
253 * \param handle [OUT] FVID2 handle for which the callback has occurred.
254 * \param appData [OUT] Application data provided to the driver at the
255 * time of Fvid2_create().
256 * \param reserved [OUT] For future use. Set to NULL.
257 *
258 * \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
259 */
260 typedef Int32 (*Fvid2_CbFxn)(Fvid2_Handle handle, Ptr appData, Ptr reserved);
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 * \param reserved [OUT] For future use. Set to NULL.
292 *
293 * \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
294 */
295 typedef Int32 (*Fvid2_ErrCbFxn)(Fvid2_Handle handle,
296 Ptr appData,
297 Ptr errList,
298 Ptr reserved);
300 /**
301 * \brief FVID2 callback that is called by subframe mode Capture driver.
302 *
303 * This callback is called for every subframe of frame that
304 * is captured. This function is used by Capture Driver and not meant for M2M
305 * drivers.
306 *
307 * Users should apply same rules as that of Fvid2_CbFxn when implementing
308 * subframe callbacks.
309 *
310 * \param handle [OUT] FVID2 handle for which this callback happened.
311 * \param subFrameInfo [OUT] SubFrame information.
312 *
313 * \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
314 */
315 typedef Int32 (*Fvid2_SubFrameCbFxn)(Fvid2_Handle handle,
316 Fvid2_Frame *subFrame);
318 /**
319 * \name FVID2 Max limits
320 * @{
321 */
323 /** \brief Decide the streamid based on channel number. */
324 #define FVID2_STREAM_ID_ANY (0xFFFFFFFFU)
326 /* @} */
328 /*
329 * =========== Command codes for Submit call =============
330 */
331 /** \brief Control command base address. */
332 #define FVID2_CTRL_BASE (0x00000000U)
333 /** \brief User command base address. */
334 #define FVID2_USER_BASE (0x10000000U)
336 /**
337 * \addtogroup BSP_DRV_IOCTL_FVID2
338 * @{
339 */
341 /**
342 * \brief Control command used by Fvid2_setFormat()
343 *
344 * \param cmdArgs [IN] const Fvid2_Format *
345 * \param cmdStatusArgs [OUT] NULL
346 *
347 * \return FVID2_SOK on success, else failure.
348 */
349 #define FVID2_SET_FORMAT ((UInt32)FVID2_CTRL_BASE + 3U)
351 /**
352 * \brief Control command used by Fvid2_getFormat()
353 *
354 * \param cmdArgs [IN] Fvid2_Format *
355 * \param cmdStatusArgs [OUT] NULL
356 *
357 * \return FVID2_SOK on success, else failure.
358 */
359 #define FVID2_GET_FORMAT ((UInt32)FVID2_CTRL_BASE + 4U)
361 /**
362 * \brief Control command used by Fvid2_start()
363 *
364 * \param cmdArgs [IN] Driver specific
365 * \param cmdStatusArgs [OUT] NULL
366 *
367 * \return FVID2_SOK on success, else failure.
368 */
369 #define FVID2_START ((UInt32)FVID2_CTRL_BASE + 5U)
371 /**
372 * \brief Control command used by Fvid2_stop()
373 *
374 * \param cmdArgs [IN] Driver specific
375 * \param cmdStatusArgs [OUT] NULL
376 *
377 * \return FVID2_SOK on success, else failure.
378 */
379 #define FVID2_STOP ((UInt32)FVID2_CTRL_BASE + 6U)
381 /* @} */
383 /* ========================================================================== */
384 /* Structure Declarations */
385 /* ========================================================================== */
387 /**
388 * \brief FVID2 callback parameters that are setup during Fvid2_create().
389 */
390 typedef struct
391 {
392 Fvid2_CbFxn cbFxn;
393 /**< Application callback function used by the driver to intimate any
394 * operation has completed or not. This is an optional parameter
395 * in case application decides to use polling method and so could be
396 * set to NULL. */
398 Fvid2_ErrCbFxn errCbFxn;
399 /**< Application error callback function used by the driver to intimate
400 * any error occurs at the time of streaming. This is an optional
401 * parameter in case application decides not to get any error callback
402 * and so could be set to NULL. */
404 Ptr errList;
405 /**< Pointer to a valid Fvid2_FrameList in case of capture
406 * and display drivers or a pointer to a valid Fvid2_ProcessList
407 * in case of M2M drivers where the driver copies
408 * the aborted/error packet. The memory of this list should be
409 * allocated by the application and provided to the driver at the time
410 * of driver creation. When the application gets this callback, it has
411 * to empty this list and taken necessary action like freeing up memories
412 * etc. The driver will then reuse the same list for future error
413 * callback.
414 * This could be NULL if errCbFxn is NULL. Otherwise this should be
415 * non-NULL. */
417 Ptr appData;
418 /**< Application specific data which is returned in the callback function
419 * as it is. This could be set to NULL if not used. */
420 Ptr reserved;
421 /**< For future use. Not used currently. Set this to NULL. */
422 } Fvid2_CbParams;
424 /* ========================================================================== */
425 /* Function Declarations */
426 /* ========================================================================== */
428 /**
429 * \brief FVID2 init function.
430 *
431 * Initializes the FVID2 layer.
432 * This function should be called before calling any of FVID2 API's and
433 * should be called only once.
434 *
435 * \param args [IN] Not used currently. Set to NULL.
436 *
437 * \return FVID2_SOK on success else appropriate FVID2 error code on failure.
438 */
439 Int32 Fvid2_init(Ptr args);
441 /**
442 * \brief FVID2 deinit function.
443 *
444 * Uninitializes the FVID2 layer and should be called during system shutdown.
445 * Should not be called if Fvid2_init() is not called.
446 *
447 * \param args [IN] Not used currently. Set to NULL.
448 *
449 * \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
450 */
451 Int32 Fvid2_deInit(Ptr args);
453 /**
454 * \brief Get the version string for FVID2 interface.
455 *
456 * This is the version number for the FVID2 interface. This
457 * function can be called prior to #Fvid2_init() to get the version number.
458 *
459 * \return Pointer to FVID2 version string.
460 */
461 const Char *Fvid2_getVersionString(void);
463 /**
464 * \brief Same as #Fvid2_getVersionString() except it returns the version in
465 * UInt32 form.
466 *
467 * Example, v1.0.1.17 will be 0x01000117
468 *
469 * \return FVID2 version number.
470 */
471 UInt32 Fvid2_getVersionNumber(void);
473 /**
474 * \brief Creates the driver identified by the driver ID.
475 *
476 * This will allocate HW and/or SW resources and return a Fvid2_Handle
477 * for this driver. This handle will be used for subsequent FVID2 API calls
478 *
479 * \param drvId [IN] Driver to open. Driver ID is driver specific.
480 *
481 * \param instanceId [IN] Instance of the driver to open and is used
482 * to differentiate multiple instance support on a
483 * single driver. Instance ID is driver specific.
484 *
485 * \param createArgs [IN] Pointer to the create argument structure. The type
486 * of the structure is defined by the specific driver.
487 * This parameter could be NULL depending on whether the
488 * actual driver forces it or not.
489 *
490 * \param createStatusArgs [OUT] Pointer to status argument structure where the
491 * driver returns any status information. The type
492 * of the structure is defined by the specific driver.
493 * This parameter could be NULL depending on whether the
494 * actual driver forces it or not.
495 *
496 * \param cbParams [IN] Application callback parameters.
497 * This parameter could be NULL depending on whether the
498 * actual driver forces it or not.
499 *
500 * \return non-NULL Fvid2_Handle object pointer on success else returns NULL
501 * on error.
502 */
503 Fvid2_Handle Fvid2_create(UInt32 drvId,
504 UInt32 instanceId,
505 Ptr createArgs,
506 Ptr createStatusArgs,
507 const Fvid2_CbParams *cbParams);
509 /**
510 * \brief Deletes a previously created FVID2 driver handle.
511 *
512 * This free's the HW/SW resources allocated during create
513 *
514 * \param handle [IN] FVID2 handle returned by create call.
515 *
516 * \param deleteArgs [IN] Pointer to the delete argument structure. The type
517 * of the structure is defined by the specific driver.
518 * This parameter could be NULL depending on whether the
519 * actual driver forces it or not.
520 *
521 * \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
522 */
523 Int32 Fvid2_delete(Fvid2_Handle handle, Ptr deleteArgs);
525 /**
526 * \brief Send control commands (IOCTLs) to the driver.
527 *
528 * \param handle [IN] FVID2 handle returned by create call.
529 *
530 * \param cmd [IN] IOCTL command. The type of command supported
531 * is defined by the specific driver.
532 *
533 * \param cmdArgs [IN] Pointer to the command argument structure. The type
534 * of the structure is defined by the specific driver
535 * for each of the supported IOCTL.
536 * This parameter could be NULL depending on whether the
537 * actual driver forces it or not.
538 *
539 * \param cmdStatusArgs [OUT] Pointer to status argument structure where the
540 * driver returns any status information. The type
541 * of the structure is defined by the specific driver
542 * for each of the supported IOCTL.
543 * This parameter could be NULL depending on whether the
544 * actual driver forces it or not.
545 *
546 * \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
547 */
548 Int32 Fvid2_control(Fvid2_Handle handle,
549 UInt32 cmd,
550 Ptr cmdArgs,
551 Ptr cmdStatusArgs);
553 /**
554 * \brief An application calls Fvid2_queue to submit a video buffer to the
555 * video device driver.
556 *
557 * - This is used in capture/display drivers.
558 * - This function could be called from task or ISR context unless the specific
559 * driver restricts from doing so.
560 * - This is a non-blocking API unless the specific driver restricts from
561 * doing so.
562 *
563 * \param handle [IN] FVID2 handle returned by create call.
564 * \param frameList [IN] Pointer to the frame list structure containing the
565 * information about the FVID2 frames that has to be
566 * queued in the driver.
567 * \param streamId [IN] Stream ID to which the frames should be queued
568 * This is used in drivers where they could support
569 * multiple streams for the same handle. Otherwise this
570 * should be set to zero.
571 *
572 * \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
573 */
574 Int32 Fvid2_queue(Fvid2_Handle handle,
575 Fvid2_FrameList *frameList,
576 UInt32 streamId);
578 /**
579 * \brief An application calls Fvid2_dequeue to request the video device
580 * driver to give ownership of a video buffer.
581 *
582 * - This is used in capture/display drivers.
583 * - This is a non-blocking API if timeout is FVID2_TIMEOUT_NONE and could be
584 * called by task and ISR context unless the specific driver restricts from
585 * doing so.
586 * - This is blocking API if timeout is FVID2_TIMEOUT_FOREVER if supported by
587 * specific driver implementation.
588 *
589 * \param handle [IN] FVID2 handle returned by create call.
590 * \param frameList [OUT] Pointer to the frame list structure where the
591 * dequeued frame pointer will be stored.
592 * \param streamId [IN] Stream ID from where frames should be dequeued.
593 * This is used in drivers where it could support multiple
594 * streams for the same handle. Otherwise this
595 * should be set to zero.
596 * \param timeout [IN] FVID2 timeout in units of OS ticks. This will
597 * determine the timeout value till the driver will block
598 * for a free or completed buffer is available.
599 * For non-blocking drivers this parameter might be
600 * ignored.
601 *
602 * \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
603 */
604 Int32 Fvid2_dequeue(Fvid2_Handle handle,
605 Fvid2_FrameList *frameList,
606 UInt32 streamId,
607 UInt32 timeout);
609 /**
610 * \brief An application calls Fvid2_processRequest to submit a video buffer
611 * to the video device driver.
612 *
613 * This API is used for submitting a single channel video processing request
614 * to the video device driver. It uses framelist to submit multiple
615 * frames of different stream ids of the same request.
616 *
617 * - This function could be called from task or ISR context unless the specific
618 * driver restricts from doing so.
619 * - This is a non-blocking API unless the specific driver restricts from
620 * doing so.
621 *
622 * \param handle [IN] FVID2 handle returned by create call.
623 * \param inFrameList [IN] Pointer to the array of input frames with
624 * different stream ids.
625 * \param outFrameList [IN] Pointer to the array of output frames with
626 * different stream ids
627 *
628 * \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
629 */
630 Int32 Fvid2_processRequest(Fvid2_Handle handle,
631 Fvid2_FrameList *inFrameList,
632 Fvid2_FrameList *outFrameList);
634 /**
635 * \brief An application calls Fvid2_getProcessedRequest to get the
636 * processed request back from the driver and thus to get the
637 * ownership of request back from the driver.
638 *
639 * - This is a non-blocking API if timeout is FVID2_TIMEOUT_NONE and could be
640 * called by task and ISR context unless the specific driver restricts from
641 * doing so.
642 * - This is blocking API if timeout is FVID2_TIMEOUT_FOREVER if supported by
643 * specific driver implementation.
644 *
645 * \param handle [IN] FVID2 handle returned by create call.
646 * \param inFrameList [OUT] Pointer to frame list in which input frames with
647 * different stream ids will be returned
648 * by the driver.
649 * \param outFrameList [OUT] Pointer to frame list in which output frames with
650 * different stream ids will be returned by
651 * the driver.
652 * \param timeout [IN] FVID2 timeout. This will determine the timeout
653 * value till the driver will block for a
654 * free or completed buffer is available.
655 * For non-blocking drivers this parameter
656 * might be ignored.
657 *
658 * \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
659 */
660 Int32 Fvid2_getProcessedRequest(Fvid2_Handle handle,
661 Fvid2_FrameList *inFrameList,
662 Fvid2_FrameList *outFrameList,
663 UInt32 timeout);
664 /**
665 * \brief An application calls Fvid2_start to request the video device
666 * driver to start the video display or capture operation.
667 * This function should be called from task context only and should not be
668 * called from ISR context.
669 *
670 * \param handle [IN] FVID2 handle returned by create call.
671 * \param cmdArgs [IN] Pointer to the start argument structure. The type
672 * of the structure is defined by the specific driver.
673 * This parameter could be NULL depending on whether the
674 * actual driver forces it or not.
675 *
676 * \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
677 */
678 static inline Int32 Fvid2_start(Fvid2_Handle handle, Ptr cmdArgs);
680 /**
681 * \brief An application calls Fvid2_stop to request the video device
682 * driver to stop the video display or capture operation.
683 * This function should be called from task context only and should not be
684 * called from ISR context.
685 *
686 * \param handle [IN] FVID2 handle returned by create call.
687 * \param cmdArgs [IN] Pointer to the stop argument structure. The type
688 * of the structure is defined by the specific driver.
689 * This parameter could be NULL depending on whether the
690 * actual driver forces it or not.
691 *
692 * \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
693 */
694 static inline Int32 Fvid2_stop(Fvid2_Handle handle, Ptr cmdArgs);
696 /**
697 * \brief An application calls Fvid2_setFormat to request the video device
698 * driver to set the format for a given channel.
699 * This function should be called from task context only and should not be
700 * called from ISR context.
701 *
702 * \param handle [IN] FVID2 handle returned by create call.
703 * \param fmt [IN] Pointer to the FVID2 format structure.
704 *
705 * \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
706 */
707 static inline Int32 Fvid2_setFormat(Fvid2_Handle handle, Fvid2_Format *fmt);
709 /**
710 * \brief An application calls Fvid2_getFormat to request the video device
711 * driver to get the current format for a given channel.
712 * This function should be called from task context only and should not be
713 * called from ISR context.
714 *
715 * \param handle [IN] FVID2 handle returned by create call.
716 * \param fmt [OUT] Pointer to the FVID2 format structure.
717 *
718 * \return FVID2_SOK on success, else appropriate FVID2 error code on failure.
719 */
720 static inline Int32 Fvid2_getFormat(Fvid2_Handle handle, Fvid2_Format *fmt);
722 /**
723 * \brief Fvid2_CbParams structure init function.
724 *
725 * \param cbPrms [IN] Pointer to #Fvid2_CbParams structure.
726 *
727 */
728 static inline void Fvid2CbParams_init(Fvid2_CbParams *cbPrms);
730 /* ========================================================================== */
731 /* Static Function Definitions */
732 /* ========================================================================== */
734 static inline Int32 Fvid2_start(Fvid2_Handle handle, Ptr cmdArgs)
735 {
736 return Fvid2_control(handle, FVID2_START, cmdArgs, NULL);
737 }
739 static inline Int32 Fvid2_stop(Fvid2_Handle handle, Ptr cmdArgs)
740 {
741 return Fvid2_control(handle, FVID2_STOP, cmdArgs, NULL);
742 }
744 static inline Int32 Fvid2_setFormat(Fvid2_Handle handle, Fvid2_Format *fmt)
745 {
746 return Fvid2_control(handle, FVID2_SET_FORMAT, fmt, NULL);
747 }
749 static inline Int32 Fvid2_getFormat(Fvid2_Handle handle, Fvid2_Format *fmt)
750 {
751 return Fvid2_control(handle, FVID2_GET_FORMAT, fmt, NULL);
752 }
754 static inline void Fvid2CbParams_init(Fvid2_CbParams *cbPrms)
755 {
756 if (NULL != cbPrms)
757 {
758 cbPrms->cbFxn = NULL;
759 cbPrms->errCbFxn = NULL;
760 cbPrms->errList = NULL;
761 cbPrms->appData = NULL;
762 cbPrms->reserved = NULL;
763 }
765 return;
766 }
768 /*
769 * The deprecated structures and API FVID2_* has been replaced with
770 * Fvid2_*.
771 * This has been done to follow coding guidelines and have a uniform
772 * naming convention.
773 * If backward compatibility is required, use could enable the below
774 * macro.
775 * By default this macro is not enabled.
776 */
777 #ifdef FVID2_BACKWARD_COMPATIBLE
779 /*
780 * Deprecated structures.
781 */
782 /** \brief Macro for deprecated structure FVID2_Handle. */
783 #define FVID2_Handle Fvid2_Handle
784 /** \brief Macro for deprecated structure FVID2_CbFxn. */
785 #define FVID2_CbFxn Fvid2_CbFxn
786 /** \brief Macro for deprecated structure FVID2_ErrCbFxn. */
787 #define FVID2_ErrCbFxn Fvid2_ErrCbFxn
788 /** \brief Macro for deprecated structure FVID2_DataFormat. */
789 #define FVID2_DataFormat Fvid2_DataFormat
790 /** \brief Macro for deprecated structure FVID2_ScanFormat. */
791 #define FVID2_ScanFormat Fvid2_ScanFormat
792 /** \brief Macro for deprecated structure FVID2_Standard. */
793 #define FVID2_Standard Fvid2_Standard
794 /** \brief Macro for deprecated structure FVID2_Fid. */
795 #define FVID2_Fid Fvid2_Fid
796 /** \brief Macro for deprecated structure FVID2_Polarity. */
797 #define FVID2_Polarity Fvid2_Polarity
798 /** \brief Macro for deprecated structure FVID2_EdgePolarity. */
799 #define FVID2_EdgePolarity Fvid2_EdgePolarity
800 /** \brief Macro for deprecated structure FVID2_BufferFormat. */
801 #define FVID2_BufferFormat Fvid2_BufferFormat
802 /** \brief Macro for deprecated structure FVID2_BitsPerPixel. */
803 #define FVID2_BitsPerPixel Fvid2_BitsPerPixel
804 /** \brief Macro for deprecated structure FVID2_CbParams. */
805 #define FVID2_CbParams Fvid2_CbParams
806 /** \brief Macro for deprecated structure FVID2_Format. */
807 #define FVID2_Format Fvid2_Format
808 /** \brief Macro for deprecated structure FVID2_Frame. */
809 #define FVID2_Frame Fvid2_Frame
810 /** \brief Macro for deprecated structure FVID2_FrameList. */
811 #define FVID2_FrameList Fvid2_FrameList
812 /** \brief Macro for deprecated structure FVID2_ProcessList. */
813 #define FVID2_ProcessList Fvid2_ProcessList
814 /** \brief Macro for deprecated structure FVID2_ModeInfo. */
815 #define FVID2_ModeInfo Fvid2_ModeInfo
817 /*
818 * Deprecated functions.
819 */
820 /** \brief Macro for deprecated function FVID2_init. */
821 #define FVID2_init Fvid2_init
822 /** \brief Macro for deprecated function FVID2_deInit. */
823 #define FVID2_deInit Fvid2_deInit
824 /** \brief Macro for deprecated function FVID2_getVersionString. */
825 #define FVID2_getVersionString Fvid2_getVersionString
826 /** \brief Macro for deprecated function FVID2_getVersionNumber. */
827 #define FVID2_getVersionNumber Fvid2_getVersionNumber
828 /** \brief Macro for deprecated function FVID2_create. */
829 #define FVID2_create Fvid2_create
830 /** \brief Macro for deprecated function FVID2_delete. */
831 #define FVID2_delete Fvid2_delete
832 /** \brief Macro for deprecated function FVID2_control. */
833 #define FVID2_control Fvid2_control
834 /** \brief Macro for deprecated function FVID2_queue. */
835 #define FVID2_queue Fvid2_queue
836 /** \brief Macro for deprecated function FVID2_dequeue. */
837 #define FVID2_dequeue Fvid2_dequeue
838 /** \brief Macro for deprecated function FVID2_processFrames. */
839 #define FVID2_processFrames Fvid2_processFrames
840 /** \brief Macro for deprecated function FVID2_getProcessedFrames. */
841 #define FVID2_getProcessedFrames Fvid2_getProcessedFrames
842 /** \brief Macro for deprecated function FVID2_start. */
843 #define FVID2_start Fvid2_start
844 /** \brief Macro for deprecated function FVID2_stop. */
845 #define FVID2_stop Fvid2_stop
846 /** \brief Macro for deprecated function FVID2_setFormat. */
847 #define FVID2_setFormat Fvid2_setFormat
848 /** \brief Macro for deprecated function FVID2_getFormat. */
849 #define FVID2_getFormat Fvid2_getFormat
850 /** \brief Macro for deprecated function FVID2_getModeInfo. */
851 #define FVID2_getModeInfo Fvid2_getModeInfo
852 /** \brief Macro for deprecated function FVID2_getDataFmtString. */
853 #define FVID2_getDataFmtString Fvid2_getDataFmtString
854 /** \brief Macro for deprecated function FVID2_getStandardString. */
855 #define FVID2_getStandardString Fvid2_getStandardString
856 /** \brief Macro for deprecated function FVID2_isDataFmtYuv422. */
857 #define FVID2_isDataFmtYuv422 Fvid2_isDataFmtYuv422
858 /** \brief Macro for deprecated function FVID2_isDataFmtYuv420. */
859 #define FVID2_isDataFmtYuv420 Fvid2_isDataFmtYuv420
860 /** \brief Macro for deprecated function FVID2_isDataFmtSemiPlanar. */
861 #define FVID2_isDataFmtSemiPlanar Fvid2_isDataFmtSemiPlanar
862 /** \brief Macro for deprecated function FVID2_isDataFmtYuv422I. */
863 #define FVID2_isDataFmtYuv422I Fvid2_isDataFmtYuv422I
864 /** \brief Macro for deprecated function FVID2_isStandardVesa. */
865 #define FVID2_isStandardVesa Fvid2_isStandardVesa
866 /** \brief Macro for deprecated function FVID2CbParams_init. */
867 #define FVID2CbParams_init Fvid2CbParams_init
868 /** \brief Macro for deprecated function FVID2Format_init. */
869 #define FVID2Format_init Fvid2Format_init
870 /** \brief Macro for deprecated function FVID2SubFrameInfo_init. */
871 #define FVID2SubFrameInfo_init Fvid2SubFrameInfo_init
872 /** \brief Macro for deprecated function FVID2Frame_init. */
873 #define FVID2Frame_init Fvid2Frame_init
874 /** \brief Macro for deprecated function FVID2FrameList_init. */
875 #define FVID2FrameList_init Fvid2FrameList_init
876 /** \brief Macro for deprecated function FVID2ProcessList_init. */
877 #define FVID2ModeInfo_init Fvid2ModeInfo_init
879 #endif /* #ifdef FVID2_BACKWARD_COMPATIBLE */
881 #ifdef __cplusplus
882 }
883 #endif
885 #endif /* #ifndef FVID2_H_ */
887 /* @} */