AM62Px MCU+ SDK  09.02.01

Introduction

This is FVID2 API layer interface.

Sub Modules

 FVID2 IOCTLs
 

Files

file  fvid2_api.h
 FVID2 API.
 

Data Structures

struct  Fvid2_CbParams
 FVID2 callback parameters that are setup during Fvid2_create(). More...
 
struct  Fvid2_TimeStampParams
 Structure used to configure time stamping of frames. More...
 
struct  Fvid2_InitPrms
 FVID2 initialization parameters. More...
 

Functions

int32_t Fvid2_init (const Fvid2_InitPrms *initPrms)
 FVID2 init function. More...
 
int32_t Fvid2_deInit (void *args)
 FVID2 deinit function. More...
 
const char * Fvid2_getVersionString (void)
 Get the version string for FVID2 interface. More...
 
uint32_t Fvid2_getVersionNumber (void)
 Same as Fvid2_getVersionString() except it returns the version in uint32_t form. More...
 
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. More...
 
int32_t Fvid2_delete (Fvid2_Handle handle, void *deleteArgs)
 Deletes a previously created FVID2 driver handle. More...
 
int32_t Fvid2_control (Fvid2_Handle handle, uint32_t cmd, void *cmdArgs, void *cmdStatusArgs)
 Send control commands (IOCTLs) to the driver. More...
 
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. More...
 
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 buffer. More...
 
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. More...
 
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 thus to get the ownership of request back from the driver. More...
 
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 capture operation. This function should be called from task context only and should not be called from ISR context. More...
 
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 capture operation. This function should be called from task context only and should not be called from ISR context. More...
 
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 channel. This function should be called from task context only and should not be called from ISR context. More...
 
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 a given channel. This function should be called from task context only and should not be called from ISR context. More...
 
static void Fvid2InitPrms_init (Fvid2_InitPrms *initPrms)
 Fvid2_InitPrms structure init function. More...
 
static void Fvid2CbParams_init (Fvid2_CbParams *cbPrms)
 Fvid2_CbParams structure init function. More...
 

Typedefs

typedef void * Fvid2_Handle
 FVID2 Driver handle. More...
 
typedef int32_t(* Fvid2_CbFxn) (Fvid2_Handle handle, void *appData)
 FVID2 driver callback function prototype. More...
 
typedef int32_t(* Fvid2_ErrCbFxn) (Fvid2_Handle handle, void *appData, void *errList)
 FVID2 error callback function prototype. More...
 
typedef int32_t(* Fvid2_SubFrameCbFxn) (Fvid2_Handle handle, Fvid2_Frame *subFrame)
 FVID2 callback that is called by subframe mode Capture driver. More...
 
typedef uint64_t(* Fvid2_TimeStampFxn) (void *args)
 Function prototype, to determine the time stamp. More...
 
typedef void(* Fvid2_PrintFxn) (const char *format,...)
 FVID2 info/debug print function prototype. More...
 

Macros

#define FVID2_VERSION_STRING   "FVID_02_02_00_00"
 FVID2 driver version string. Version is of the form mm_nn_xx_yy where, mm - Product version (02 for FVID2). This increments for any new FVID2 versions. nn - Major number - Increments if any backward compatibility is broken or major change within a product version. xx - Minor number - Increments for any minor change or any additions done without breaking backward compatibility. yy - Build number - Increments for every release. More...
 
#define FVID2_VERSION_NUMBER   (0x02020000U)
 FVID2 driver version number. More...
 
#define FVID2_CTRL_BASE   (0x00000000U)
 Control command base address. More...
 
#define FVID2_USER_BASE   (0x10000000U)
 User command base address. More...
 
#define FVID2_DSS_DRV_BASE   (0x00001000U)
 Driver ID base for the DSS driver class. More...
 
#define FVID2_CAL_DRV_BASE   (0x00002000U)
 Driver ID base for the CAL driver class. More...
 
#define FVID2_CSIRX_DRV_BASE   (0x00003000U)
 Driver ID base for the CSIRX driver class. More...
 
#define FVID2_CSITX_DRV_BASE   (0x00004000U)
 Driver ID base for the CSITX driver class. More...
 
#define FVID2_VHWA_DRV_BASE   (0x00005000U)
 Driver ID base for the VHWA driver class. More...
 
#define FVID2_DSS_DRV_IOCTL_BASE   (FVID2_USER_BASE + FVID2_DSS_DRV_BASE)
 IOCTL base for the DSS driver class. More...
 
#define FVID2_CAL_DRV_IOCTL_BASE   (FVID2_USER_BASE + FVID2_CAL_DRV_BASE)
 IOCTL base for the CAL driver class. More...
 
#define FVID2_CSIRX_DRV_IOCTL_BASE   (FVID2_USER_BASE + FVID2_CSIRX_DRV_BASE)
 IOCTL base for the CSIRX driver class. More...
 
#define FVID2_CSITX_DRV_IOCTL_BASE   (FVID2_USER_BASE + FVID2_CSITX_DRV_BASE)
 IOCTL base for the CSITX driver class. More...
 
#define FVID2_VHWA_DRV_IOCTL_BASE   (FVID2_USER_BASE + FVID2_VHWA_DRV_BASE)
 IOCTL base for the VHWA driver class. More...
 

FVID2 Max limits

#define FVID2_STREAM_ID_ANY   (0xFFFFFFFFU)
 Decide the streamid based on channel number.
More...
 

Macro Definition Documentation

◆ FVID2_VERSION_STRING

#define FVID2_VERSION_STRING   "FVID_02_02_00_00"

FVID2 driver version string. Version is of the form mm_nn_xx_yy where, mm - Product version (02 for FVID2). This increments for any new FVID2 versions. nn - Major number - Increments if any backward compatibility is broken or major change within a product version. xx - Minor number - Increments for any minor change or any additions done without breaking backward compatibility. yy - Build number - Increments for every release.

◆ FVID2_VERSION_NUMBER

#define FVID2_VERSION_NUMBER   (0x02020000U)

FVID2 driver version number.

◆ FVID2_STREAM_ID_ANY

#define FVID2_STREAM_ID_ANY   (0xFFFFFFFFU)

Decide the streamid based on channel number.

◆ FVID2_CTRL_BASE

#define FVID2_CTRL_BASE   (0x00000000U)

Control command base address.

◆ FVID2_USER_BASE

#define FVID2_USER_BASE   (0x10000000U)

User command base address.

◆ FVID2_DSS_DRV_BASE

#define FVID2_DSS_DRV_BASE   (0x00001000U)

Driver ID base for the DSS driver class.

◆ FVID2_CAL_DRV_BASE

#define FVID2_CAL_DRV_BASE   (0x00002000U)

Driver ID base for the CAL driver class.

◆ FVID2_CSIRX_DRV_BASE

#define FVID2_CSIRX_DRV_BASE   (0x00003000U)

Driver ID base for the CSIRX driver class.

◆ FVID2_CSITX_DRV_BASE

#define FVID2_CSITX_DRV_BASE   (0x00004000U)

Driver ID base for the CSITX driver class.

◆ FVID2_VHWA_DRV_BASE

#define FVID2_VHWA_DRV_BASE   (0x00005000U)

Driver ID base for the VHWA driver class.

◆ FVID2_DSS_DRV_IOCTL_BASE

#define FVID2_DSS_DRV_IOCTL_BASE   (FVID2_USER_BASE + FVID2_DSS_DRV_BASE)

IOCTL base for the DSS driver class.

◆ FVID2_CAL_DRV_IOCTL_BASE

#define FVID2_CAL_DRV_IOCTL_BASE   (FVID2_USER_BASE + FVID2_CAL_DRV_BASE)

IOCTL base for the CAL driver class.

◆ FVID2_CSIRX_DRV_IOCTL_BASE

#define FVID2_CSIRX_DRV_IOCTL_BASE   (FVID2_USER_BASE + FVID2_CSIRX_DRV_BASE)

IOCTL base for the CSIRX driver class.

◆ FVID2_CSITX_DRV_IOCTL_BASE

#define FVID2_CSITX_DRV_IOCTL_BASE   (FVID2_USER_BASE + FVID2_CSITX_DRV_BASE)

IOCTL base for the CSITX driver class.

◆ FVID2_VHWA_DRV_IOCTL_BASE

#define FVID2_VHWA_DRV_IOCTL_BASE   (FVID2_USER_BASE + FVID2_VHWA_DRV_BASE)

IOCTL base for the VHWA driver class.

Typedef Documentation

◆ Fvid2_Handle

typedef void* Fvid2_Handle

FVID2 Driver handle.

◆ Fvid2_CbFxn

typedef int32_t(* Fvid2_CbFxn) (Fvid2_Handle handle, void *appData)

FVID2 driver callback function prototype.

This callback is used by the drivers which implement non-blocking FVID2 APIs.

User should assume that callbacks happen in ISR context and hence should apply rules relevant to ISR context when implementing callback functions, i.e blocking APIs should not be called from callback. Users should also assume that interrupts are enabled when in callback context, i.e other interrupt / callbacks can occur when a callback is under execution. User callback implementation should not be very long, since callback execution may block other drivers from executing. Typically it is recommended to set a semaphore or flag when callback happens and do the more involved callback handling in task context.

This callback is typically called by the driver as mentioned below, unless specified otherwise by specific drivers.

In case of display drivers, this callback function will be called when a frame(s) is/are completed displayed. Then the application can dequeue the displayed buffer back from the driver.

In case of capture drivers, this callback function will be called when a frame(s) is/are captured. Then the application can dequeue the captured buffer back from the driver.

In case of M2M drivers, this callback function will be called when a request from the application is completed by the driver. Then the application can dequeue the completed request buffers back from the driver.

In case of control drivers, callbacks are typically not used since mostly FVID2 APIs implemented by control drivers are of blocking nature.

Parameters
handle[OUT] FVID2 handle for which the callback has occurred.
appData[OUT] Application data provided to the driver at the time of Fvid2_create().
Returns
FVID2_SOK on success, else appropriate FVID2 error code on failure.

◆ Fvid2_ErrCbFxn

typedef int32_t(* Fvid2_ErrCbFxn) (Fvid2_Handle handle, void *appData, void *errList)

FVID2 error callback function prototype.

Error callback is called by driver when it encounters a error during processing of frames in its internal queue.

When user submits frames to the driver it does minimal error checks and stores the the frames in its internal queues. In case of any error at this point the FVID2 API will simply return error and error callback will not be called.

The driver will later (depending on how its request queue is full) process these frames submitted by the user. If driver finds any error in either the input frame information or hardware itself then it will call this error callback to notify the user about this error. As part of the callback information it also returns the frames or request for which error happened so that user can take appropriate action.

Users should apply same rules as that of Fvid2_CbFxn when implementing error callbacks.

Parameters
handle[OUT] FVID2 handle for which the callback has occurred.
appData[OUT] Application data provided to the driver at the time of Fvid2_create().
errList[OUT] Pointer to a valid framelist (Fvid2_FrameList) in case of capture and display drivers or a pointer to a valid processlist (Fvid2_ProcessList) in case of M2M drivers. The driver copies the aborted/error frames in this frame list or process list.
Returns
FVID2_SOK on success, else appropriate FVID2 error code on failure.

◆ Fvid2_SubFrameCbFxn

typedef int32_t(* Fvid2_SubFrameCbFxn) (Fvid2_Handle handle, Fvid2_Frame *subFrame)

FVID2 callback that is called by subframe mode Capture driver.

This callback is called for every subframe of frame that is captured. This function is used by Capture Driver and not meant for M2M drivers.

Users should apply same rules as that of Fvid2_CbFxn when implementing subframe callbacks.

Parameters
handle[OUT] FVID2 handle for which this callback happened.
subFrameInfo[OUT] SubFrame information.
Returns
FVID2_SOK on success, else appropriate FVID2 error code on failure.

◆ Fvid2_TimeStampFxn

typedef uint64_t(* Fvid2_TimeStampFxn) (void *args)

Function prototype, to determine the time stamp.

Parameters
args[IN] Not used as of now.
Returns
An unsigned int 64 value, that represents the current time in usec.

◆ Fvid2_PrintFxn

typedef void(* Fvid2_PrintFxn) (const char *format,...)

FVID2 info/debug print function prototype.

This function is used by the driver to print info/debug messages.

Parameters
format[OUT] Info string to print.

Function Documentation

◆ Fvid2_init()

int32_t Fvid2_init ( const Fvid2_InitPrms initPrms)

FVID2 init function.

Initializes the FVID2 layer. This function should be called before calling any of FVID2 API's and should be called only once.

Parameters
initPrms[IN] FVID2 Initialization parameters. If NULL is passed, the default parameters will be assumed - no print will be enabled
Returns
FVID2_SOK on success else appropriate FVID2 error code on failure.

◆ Fvid2_deInit()

int32_t Fvid2_deInit ( void *  args)

FVID2 deinit function.

Uninitializes the FVID2 layer and should be called during system shutdown. Should not be called if Fvid2_init() is not called.

Parameters
args[IN] Not used currently. Set to NULL.
Returns
FVID2_SOK on success, else appropriate FVID2 error code on failure.

◆ Fvid2_getVersionString()

const char* Fvid2_getVersionString ( void  )

Get the version string for FVID2 interface.

This is the version number for the FVID2 interface. This function can be called prior to Fvid2_init() to get the version number.

Returns
Pointer to FVID2 version string.

◆ Fvid2_getVersionNumber()

uint32_t Fvid2_getVersionNumber ( void  )

Same as Fvid2_getVersionString() except it returns the version in uint32_t form.

Example, v1.0.1.17 will be 0x01000117

Returns
FVID2 version number.

◆ 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.

This will allocate HW and/or SW resources and return a Fvid2_Handle for this driver. This handle will be used for subsequent FVID2 API calls

Parameters
drvId[IN] Driver to open. Driver ID is driver specific.
instanceId[IN] Instance of the driver to open and is used to differentiate multiple instance support on a single driver. Instance ID is driver specific.
createArgs[IN] Pointer to the create argument structure. The type of the structure is defined by the specific driver. This parameter could be NULL depending on whether the actual driver forces it or not.
createStatusArgs[OUT] Pointer to status argument structure where the driver returns any status information. The type of the structure is defined by the specific driver. This parameter could be NULL depending on whether the actual driver forces it or not.
cbParams[IN] Application callback parameters. This parameter could be NULL depending on whether the actual driver forces it or not.
Returns
non-NULL Fvid2_Handle object pointer on success else returns NULL on error.

◆ Fvid2_delete()

int32_t Fvid2_delete ( Fvid2_Handle  handle,
void *  deleteArgs 
)

Deletes a previously created FVID2 driver handle.

This free's the HW/SW resources allocated during create

Parameters
handle[IN] FVID2 handle returned by create call.
deleteArgs[IN] Pointer to the delete argument structure. The type of the structure is defined by the specific driver. This parameter could be NULL depending on whether the actual driver forces it or not.
Returns
FVID2_SOK on success, else appropriate FVID2 error code on failure.

◆ Fvid2_control()

int32_t Fvid2_control ( Fvid2_Handle  handle,
uint32_t  cmd,
void *  cmdArgs,
void *  cmdStatusArgs 
)

Send control commands (IOCTLs) to the driver.

Parameters
handle[IN] FVID2 handle returned by create call.
cmd[IN] IOCTL command. The type of command supported is defined by the specific driver.
cmdArgs[IN] Pointer to the command argument structure. The type of the structure is defined by the specific driver for each of the supported IOCTL. This parameter could be NULL depending on whether the actual driver forces it or not.
cmdStatusArgs[OUT] Pointer to status argument structure where the driver returns any status information. The type of the structure is defined by the specific driver for each of the supported IOCTL. This parameter could be NULL depending on whether the actual driver forces it or not.
Returns
FVID2_SOK on success, else appropriate FVID2 error code on failure.

◆ 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.

  • This is used in capture/display drivers.
  • This function could be called from task or ISR context unless the specific driver restricts from doing so.
  • This is a non-blocking API unless the specific driver restricts from doing so.
Parameters
handle[IN] FVID2 handle returned by create call.
frameList[IN] Pointer to the frame list structure containing the information about the FVID2 frames that has to be queued in the driver.
streamId[IN] Stream ID to which the frames should be queued This is used in drivers where they could support multiple streams for the same handle. Otherwise this should be set to zero.
Returns
FVID2_SOK on success, else appropriate FVID2 error code on failure.

◆ 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 buffer.

  • This is used in capture/display drivers.
  • This is a non-blocking API if timeout is FVID2_TIMEOUT_NONE and could be called by task and ISR context unless the specific driver restricts from doing so.
  • This is blocking API if timeout is FVID2_TIMEOUT_FOREVER if supported by specific driver implementation.
Parameters
handle[IN] FVID2 handle returned by create call.
frameList[OUT] Pointer to the frame list structure where the dequeued frame pointer will be stored.
streamId[IN] Stream ID from where frames should be dequeued. This is used in drivers where it could support multiple streams for the same handle. Otherwise this should be set to zero.
timeout[IN] FVID2 timeout in units of OS ticks. This will determine the timeout value till the driver will block for a free or completed buffer is available. For non-blocking drivers this parameter might be ignored.
Returns
FVID2_SOK on success, else appropriate FVID2 error code on failure.

◆ 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.

This API is used for submitting a single channel video processing request to the video device driver. It uses framelist to submit multiple frames of different stream ids of the same request.

  • This function could be called from task or ISR context unless the specific driver restricts from doing so.
  • This is a non-blocking API unless the specific driver restricts from doing so.
Parameters
handle[IN] FVID2 handle returned by create call.
inFrameList[IN] Pointer to the array of input frames with different stream ids.
outFrameList[IN] Pointer to the array of output frames with different stream ids
timeout[IN] FVID2 timeout. This will determine the timeout value till the driver will block for a free or completed buffer is available. For non-blocking drivers this parameter might be ignored.
Returns
FVID2_SOK on success, else appropriate FVID2 error code on failure.

◆ 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 thus to get the ownership of request back from the driver.

  • This is a non-blocking API if timeout is FVID2_TIMEOUT_NONE and could be called by task and ISR context unless the specific driver restricts from doing so.
  • This is blocking API if timeout is FVID2_TIMEOUT_FOREVER if supported by specific driver implementation.
Parameters
handle[IN] FVID2 handle returned by create call.
inFrameList[OUT] Pointer to frame list in which input frames with different stream ids will be returned by the driver.
outFrameList[OUT] Pointer to frame list in which output frames with different stream ids will be returned by the driver.
timeout[IN] FVID2 timeout. This will determine the timeout value till the driver will block for a free or completed buffer is available. For non-blocking drivers this parameter might be ignored.
Returns
FVID2_SOK on success, else appropriate FVID2 error code on failure.

◆ Fvid2_start()

static int32_t Fvid2_start ( Fvid2_Handle  handle,
void *  cmdArgs 
)
inlinestatic

An application calls Fvid2_start to request the video device driver to start the video display or capture operation. This function should be called from task context only and should not be called from ISR context.

Parameters
handle[IN] FVID2 handle returned by create call.
cmdArgs[IN] Pointer to the start argument structure. The type of the structure is defined by the specific driver. This parameter could be NULL depending on whether the actual driver forces it or not.
Returns
FVID2_SOK on success, else appropriate FVID2 error code on failure.

◆ Fvid2_stop()

static int32_t Fvid2_stop ( Fvid2_Handle  handle,
void *  cmdArgs 
)
inlinestatic

An application calls Fvid2_stop to request the video device driver to stop the video display or capture operation. This function should be called from task context only and should not be called from ISR context.

Parameters
handle[IN] FVID2 handle returned by create call.
cmdArgs[IN] Pointer to the stop argument structure. The type of the structure is defined by the specific driver. This parameter could be NULL depending on whether the actual driver forces it or not.
Returns
FVID2_SOK on success, else appropriate FVID2 error code on failure.

◆ Fvid2_setFormat()

static int32_t Fvid2_setFormat ( Fvid2_Handle  handle,
Fvid2_Format fmt 
)
inlinestatic

An application calls Fvid2_setFormat to request the video device driver to set the format for a given channel. This function should be called from task context only and should not be called from ISR context.

Parameters
handle[IN] FVID2 handle returned by create call.
fmt[IN] Pointer to the FVID2 format structure.
Returns
FVID2_SOK on success, else appropriate FVID2 error code on failure.

◆ Fvid2_getFormat()

static int32_t Fvid2_getFormat ( Fvid2_Handle  handle,
Fvid2_Format fmt 
)
inlinestatic

An application calls Fvid2_getFormat to request the video device driver to get the current format for a given channel. This function should be called from task context only and should not be called from ISR context.

Parameters
handle[IN] FVID2 handle returned by create call.
fmt[OUT] Pointer to the FVID2 format structure.
Returns
FVID2_SOK on success, else appropriate FVID2 error code on failure.

◆ Fvid2InitPrms_init()

static void Fvid2InitPrms_init ( Fvid2_InitPrms initPrms)
inlinestatic

Fvid2_InitPrms structure init function.

Parameters
initPrms[IN] Pointer to Fvid2_InitPrms structure.

◆ Fvid2CbParams_init()

static void Fvid2CbParams_init ( Fvid2_CbParams cbPrms)
inlinestatic

Fvid2_CbParams structure init function.

Parameters
cbPrms[IN] Pointer to Fvid2_CbParams structure.