J722S MCU+ SDK  09.02.00
fvid2_api.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) Texas Instruments Incorporated 2023
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions
6  * are met:
7  *
8  * Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  *
11  * Redistributions in binary form must reproduce the above copyright
12  * notice, this list of conditions and the following disclaimer in the
13  * documentation and/or other materials provided with the
14  * distribution.
15  *
16  * Neither the name of Texas Instruments Incorporated nor the names of
17  * its contributors may be used to endorse or promote products derived
18  * from this software without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  */
32 
164 #ifndef FVID2_API_H_
165 #define FVID2_API_H_
166 
167 /* ========================================================================== */
168 /* Include Files */
169 /* ========================================================================== */
170 
172 #include <drivers/fvid2/v0/fvid2_trace.h>
173 #include <drivers/fvid2/v0/fvid2_utils.h>
174 
175 #ifdef __cplusplus
176 extern "C" {
177 #endif
178 
179 /* ========================================================================== */
180 /* Macros & Typedefs */
181 /* ========================================================================== */
182 
194 #define FVID2_VERSION_STRING "FVID_02_02_00_00"
195 
197 #define FVID2_VERSION_NUMBER (0x02020000U)
198 
200 typedef void *Fvid2_Handle;
201 
242 typedef int32_t (*Fvid2_CbFxn)(Fvid2_Handle handle, void *appData);
243 
276 typedef int32_t (*Fvid2_ErrCbFxn)(Fvid2_Handle handle,
277  void *appData,
278  void *errList);
279 
295 typedef int32_t (*Fvid2_SubFrameCbFxn)(Fvid2_Handle handle,
296  Fvid2_Frame *subFrame);
297 
305 typedef uint64_t (*Fvid2_TimeStampFxn)(void *args);
306 
314 typedef void (*Fvid2_PrintFxn)(const char *format, ...);
315 
322 #define FVID2_STREAM_ID_ANY (0xFFFFFFFFU)
323 
326 /*
327  * =========== Command codes for Submit call =============
328  */
330 #define FVID2_CTRL_BASE (0x00000000U)
331 
332 #define FVID2_USER_BASE (0x10000000U)
333 
349 #define FVID2_SET_FORMAT ((uint32_t) FVID2_CTRL_BASE + 3U)
350 
359 #define FVID2_GET_FORMAT ((uint32_t) FVID2_CTRL_BASE + 4U)
360 
369 #define FVID2_START ((uint32_t) FVID2_CTRL_BASE + 5U)
370 
379 #define FVID2_STOP ((uint32_t) FVID2_CTRL_BASE + 6U)
380 
393 #define FVID2_REGISTER_TIMESTAMP_FXN ((uint32_t) FVID2_CTRL_BASE + 7U)
394 
397 /*
398  * Driver ID Base.
399  */
401 #define FVID2_DSS_DRV_BASE (0x00001000U)
402 
403 #define FVID2_CAL_DRV_BASE (0x00002000U)
404 
405 #define FVID2_CSIRX_DRV_BASE (0x00003000U)
406 
407 #define FVID2_CSITX_DRV_BASE (0x00004000U)
408 
409 #define FVID2_VHWA_DRV_BASE (0x00005000U)
410 
411 /*
412  * IOCTLs Base.
413  */
415 #define FVID2_DSS_DRV_IOCTL_BASE (FVID2_USER_BASE + FVID2_DSS_DRV_BASE)
416 
417 #define FVID2_CAL_DRV_IOCTL_BASE (FVID2_USER_BASE + FVID2_CAL_DRV_BASE)
418 
419 #define FVID2_CSIRX_DRV_IOCTL_BASE (FVID2_USER_BASE + FVID2_CSIRX_DRV_BASE)
420 
421 #define FVID2_CSITX_DRV_IOCTL_BASE (FVID2_USER_BASE + FVID2_CSITX_DRV_BASE)
422 
423 #define FVID2_VHWA_DRV_IOCTL_BASE (FVID2_USER_BASE + FVID2_VHWA_DRV_BASE)
424 
425 /* ========================================================================== */
426 /* Structure Declarations */
427 /* ========================================================================== */
428 
438 typedef struct
439 {
452  void *errList;
465  void *appData;
469 
473 typedef struct
474 {
489  uint32_t reserved;
492 
496 typedef struct
497 {
502 
503 /* ========================================================================== */
504 /* Function Declarations */
505 /* ========================================================================== */
506 
520 int32_t Fvid2_init(const Fvid2_InitPrms *initPrms);
521 
532 int32_t Fvid2_deInit(void *args);
533 
542 const char *Fvid2_getVersionString(void);
543 
552 uint32_t Fvid2_getVersionNumber(void);
553 
584 Fvid2_Handle Fvid2_create(uint32_t drvId,
585  uint32_t instanceId,
586  void *createArgs,
587  void *createStatusArgs,
588  const Fvid2_CbParams *cbParams);
589 
604 int32_t Fvid2_delete(Fvid2_Handle handle, void *deleteArgs);
605 
630  uint32_t cmd,
631  void *cmdArgs,
632  void *cmdStatusArgs);
633 
655 int32_t Fvid2_queue(Fvid2_Handle handle,
656  Fvid2_FrameList *frameList,
657  uint32_t streamId);
658 
686  Fvid2_FrameList *frameList,
687  uint32_t streamId,
688  uint32_t timeout);
689 
717  Fvid2_FrameList *inFrameList,
718  Fvid2_FrameList *outFrameList,
719  uint32_t timeout);
720 
748  Fvid2_FrameList *inFrameList,
749  Fvid2_FrameList *outFrameList,
750  uint32_t timeout);
765 static inline int32_t Fvid2_start(Fvid2_Handle handle, void *cmdArgs);
766 
781 static inline int32_t Fvid2_stop(Fvid2_Handle handle, void *cmdArgs);
782 
794 static inline int32_t Fvid2_setFormat(Fvid2_Handle handle, Fvid2_Format *fmt);
795 
807 static inline int32_t Fvid2_getFormat(Fvid2_Handle handle, Fvid2_Format *fmt);
808 
809 /*
810  * Structure Init functions
811  */
818 static inline void Fvid2InitPrms_init(Fvid2_InitPrms *initPrms);
819 
826 static inline void Fvid2CbParams_init(Fvid2_CbParams *cbPrms);
827 
828 /* ========================================================================== */
829 /* Static Function Definitions */
830 /* ========================================================================== */
831 
832 static inline int32_t Fvid2_start(Fvid2_Handle handle, void *cmdArgs)
833 {
834  return Fvid2_control(handle, FVID2_START, cmdArgs, NULL);
835 }
836 
837 static inline int32_t Fvid2_stop(Fvid2_Handle handle, void *cmdArgs)
838 {
839  return Fvid2_control(handle, FVID2_STOP, cmdArgs, NULL);
840 }
841 
842 static inline int32_t Fvid2_setFormat(Fvid2_Handle handle, Fvid2_Format *fmt)
843 {
844  return Fvid2_control(handle, FVID2_SET_FORMAT, fmt, NULL);
845 }
846 
847 static inline int32_t Fvid2_getFormat(Fvid2_Handle handle, Fvid2_Format *fmt)
848 {
849  return Fvid2_control(handle, FVID2_GET_FORMAT, fmt, NULL);
850 }
851 
852 static inline void Fvid2InitPrms_init(Fvid2_InitPrms *initPrms)
853 {
854  if (NULL != initPrms)
855  {
856  initPrms->printFxn = NULL;
857  }
858 
859  return;
860 }
861 
862 static inline void Fvid2CbParams_init(Fvid2_CbParams *cbPrms)
863 {
864  if (NULL != cbPrms)
865  {
866  cbPrms->cbFxn = NULL;
867  cbPrms->errCbFxn = NULL;
868  cbPrms->errList = NULL;
869  cbPrms->appData = NULL;
870  }
871 
872  return;
873 }
874 
875 #ifdef __cplusplus
876 }
877 #endif
878 
879 #endif /* #ifndef FVID2_API_H_ */
880 
Fvid2_deInit
int32_t Fvid2_deInit(void *args)
FVID2 deinit function.
Fvid2_ErrCbFxn
int32_t(* Fvid2_ErrCbFxn)(Fvid2_Handle handle, void *appData, void *errList)
FVID2 error callback function prototype.
Definition: fvid2_api.h:276
FVID2_SET_FORMAT
#define FVID2_SET_FORMAT
Control command used by Fvid2_setFormat()
Definition: fvid2_api.h:349
Fvid2InitPrms_init
static void Fvid2InitPrms_init(Fvid2_InitPrms *initPrms)
Fvid2_InitPrms structure init function.
Definition: fvid2_api.h:852
Fvid2_getProcessedRequest
int32_t Fvid2_getProcessedRequest(Fvid2_Handle handle, Fvid2_FrameList *inFrameList, Fvid2_FrameList *outFrameList, uint32_t timeout)
An application calls Fvid2_getProcessedRequest to get the processed request back from the driver and ...
fvid2_dataTypes.h
FVID2 Datatypes.
Fvid2_control
int32_t Fvid2_control(Fvid2_Handle handle, uint32_t cmd, void *cmdArgs, void *cmdStatusArgs)
Send control commands (IOCTLs) to the driver.
Fvid2_processRequest
int32_t Fvid2_processRequest(Fvid2_Handle handle, Fvid2_FrameList *inFrameList, Fvid2_FrameList *outFrameList, uint32_t timeout)
An application calls Fvid2_processRequest to submit a video buffer to the video device driver.
Fvid2_TimeStampParams
Structure used to configure time stamping of frames.
Definition: fvid2_api.h:474
Fvid2_CbParams::cbFxn
Fvid2_CbFxn cbFxn
Definition: fvid2_api.h:440
Fvid2_create
Fvid2_Handle Fvid2_create(uint32_t drvId, uint32_t instanceId, void *createArgs, void *createStatusArgs, const Fvid2_CbParams *cbParams)
Creates the driver identified by the driver ID.
NULL
#define NULL
Define NULL if not defined.
Definition: csl_types.h:100
Fvid2_CbParams::appData
void * appData
Definition: fvid2_api.h:465
Fvid2CbParams_init
static void Fvid2CbParams_init(Fvid2_CbParams *cbPrms)
Fvid2_CbParams structure init function.
Definition: fvid2_api.h:862
Fvid2_CbParams
FVID2 callback parameters that are setup during Fvid2_create().
Definition: fvid2_api.h:439
Fvid2_dequeue
int32_t Fvid2_dequeue(Fvid2_Handle handle, Fvid2_FrameList *frameList, uint32_t streamId, uint32_t timeout)
An application calls Fvid2_dequeue to request the video device driver to give ownership of a video bu...
Fvid2_TimeStampParams::reserved
uint32_t reserved
Definition: fvid2_api.h:489
Fvid2_TimeStampFxn
uint64_t(* Fvid2_TimeStampFxn)(void *args)
Function prototype, to determine the time stamp.
Definition: fvid2_api.h:305
Fvid2_Handle
void * Fvid2_Handle
FVID2 Driver handle.
Definition: fvid2_api.h:200
Fvid2_delete
int32_t Fvid2_delete(Fvid2_Handle handle, void *deleteArgs)
Deletes a previously created FVID2 driver handle.
Fvid2_setFormat
static int32_t Fvid2_setFormat(Fvid2_Handle handle, Fvid2_Format *fmt)
An application calls Fvid2_setFormat to request the video device driver to set the format for a given...
Definition: fvid2_api.h:842
Fvid2_FrameList
FVID2 frame buffer list used to exchange multiple FVID2 frames in a single driver call.
Definition: fvid2_dataTypes.h:1275
Fvid2_Format
FVID2 video buffer format specification.
Definition: fvid2_dataTypes.h:1109
Fvid2_stop
static int32_t Fvid2_stop(Fvid2_Handle handle, void *cmdArgs)
An application calls Fvid2_stop to request the video device driver to stop the video display or captu...
Definition: fvid2_api.h:837
Fvid2_start
static int32_t Fvid2_start(Fvid2_Handle handle, void *cmdArgs)
An application calls Fvid2_start to request the video device driver to start the video display or cap...
Definition: fvid2_api.h:832
Fvid2_PrintFxn
void(* Fvid2_PrintFxn)(const char *format,...)
FVID2 info/debug print function prototype.
Definition: fvid2_api.h:314
Fvid2_CbFxn
int32_t(* Fvid2_CbFxn)(Fvid2_Handle handle, void *appData)
FVID2 driver callback function prototype.
Definition: fvid2_api.h:242
Fvid2_getVersionNumber
uint32_t Fvid2_getVersionNumber(void)
Same as Fvid2_getVersionString() except it returns the version in uint32_t form.
Fvid2_Frame
FVID2 frame buffer structure.
Definition: fvid2_dataTypes.h:1178
Fvid2_CbParams::errCbFxn
Fvid2_ErrCbFxn errCbFxn
Definition: fvid2_api.h:446
Fvid2_CbParams::errList
void * errList
Definition: fvid2_api.h:452
Fvid2_SubFrameCbFxn
int32_t(* Fvid2_SubFrameCbFxn)(Fvid2_Handle handle, Fvid2_Frame *subFrame)
FVID2 callback that is called by subframe mode Capture driver.
Definition: fvid2_api.h:295
Fvid2_queue
int32_t Fvid2_queue(Fvid2_Handle handle, Fvid2_FrameList *frameList, uint32_t streamId)
An application calls Fvid2_queue to submit a video buffer to the video device driver.
Fvid2_InitPrms::printFxn
Fvid2_PrintFxn printFxn
Definition: fvid2_api.h:498
Fvid2_TimeStampParams::timeStampFxn
Fvid2_TimeStampFxn timeStampFxn
Definition: fvid2_api.h:475
Fvid2_InitPrms
FVID2 initialization parameters.
Definition: fvid2_api.h:497
FVID2_START
#define FVID2_START
Control command used by Fvid2_start()
Definition: fvid2_api.h:369
Fvid2_getFormat
static int32_t Fvid2_getFormat(Fvid2_Handle handle, Fvid2_Format *fmt)
An application calls Fvid2_getFormat to request the video device driver to get the current format for...
Definition: fvid2_api.h:847
FVID2_GET_FORMAT
#define FVID2_GET_FORMAT
Control command used by Fvid2_getFormat()
Definition: fvid2_api.h:359
Fvid2_getVersionString
const char * Fvid2_getVersionString(void)
Get the version string for FVID2 interface.
FVID2_STOP
#define FVID2_STOP
Control command used by Fvid2_stop()
Definition: fvid2_api.h:379
Fvid2_init
int32_t Fvid2_init(const Fvid2_InitPrms *initPrms)
FVID2 init function.