include/fvid2_drvMgr.h

   1 /*
   2  *  Copyright (c) Texas Instruments Incorporated 2018
   3  *
   4  *  Redistribution and use in source and binary forms, with or without
   5  *  modification, are permitted provided that the following conditions
   6  *  are met:
   7  *
   8  *    Redistributions of source code must retain the above copyright
   9  *    notice, this list of conditions and the following disclaimer.
  10  *
  11  *    Redistributions in binary form must reproduce the above copyright
  12  *    notice, this list of conditions and the following disclaimer in the
  13  *    documentation and/or other materials provided with the
  14  *    distribution.
  15  *
  16  *    Neither the name of Texas Instruments Incorporated nor the names of
  17  *    its contributors may be used to endorse or promote products derived
  18  *    from this software without specific prior written permission.
  19  *
  20  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  21  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  22  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  23  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  24  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  25  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  26  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  27  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  28  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  30  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31  */
  32
  33 /**
  34  *  \file fvid2_drvMgr.h
  35  *
  36  *  \brief FVID2 driver manager header file.
  37  *
  38  *  This file exposes internal functions of driver management functionality.
  39  *  This is not used by application and is used by video drivers to register
  40  *  itself to the FVID2.
  41  *
  42  */
  43
  44 #ifndef FVID2_DRVMGR_H_
  45 #define FVID2_DRVMGR_H_
  46
  47 /* ========================================================================== */
  48 /*                             Include Files                                  */
  49 /* ========================================================================== */
  50
  51 #include <ti/drv/fvid2/include/fvid2_api.h>
  52
  53 #ifdef __cplusplus
  54 extern "C" {
  55 #endif
  56
  57 /* ========================================================================== */
  58 /*                           Macros & Typedefs                                */
  59 /* ========================================================================== */
  60
  61 /** \brief Number of driver object to allocate in FVID2 library. */
  62 #define FVID2_CFG_FDM_NUM_DRV_OBJS      (40U)
  63
  64 /** \brief Number of channel object to allocate in FVID2 library. */
  65 #define FVID2_CFG_FDM_NUM_CH_OBJS       (80U)
  66
  67 /** \brief FVID2 driver handle returned by individual drivers. */
  68 typedef void *Fdrv_Handle;
  69
  70 /** \brief Typedef for callback function parameters. */
  71 typedef struct Fvid2_DrvCbParams_t      Fvid2_DrvCbParams;
  72
  73 /**
  74  *  \brief Typedef for FVID2 driver callback function prototype. This will be
  75  *  called by the driver and then the FVID2 driver manager will route the
  76  *  callback to the application.
  77  *
  78  *  fdmData: FVID2 driver manager internal data passed to driver during create
  79  *  call.
  80  */
  81 typedef int32_t (*Fdm_CbFxn)(void *fdmData);
  82
  83 /**
  84  *  \brief Typedef for FVID2 driver error callback function prototype.
  85  *  This will be called by the driver and then the FVID2 driver manager
  86  *  will route the error callback to the application.
  87  *
  88  *  fdmData: FVID2 driver manager internal data passed to driver during create
  89  *  call.
  90  *
  91  *  errList: Error data passed to the application.
  92  *
  93  */
  94 typedef int32_t (*Fdm_ErrCbFxn)(void *fdmData, void *errList);
  95
  96 /** \brief Typedef for FVID2 create function pointer. */
  97 typedef Fdrv_Handle (*Fvid2_DrvCreate)(uint32_t      drvId,
  98                                        uint32_t      instanceId,
  99                                        void        *createArgs,
 100                                        void        *createStatusArgs,
 101                                        const Fvid2_DrvCbParams *fdmCbParams);
 102
 103 /** \brief Typedef for FVID2 delete function pointer. */
 104 typedef int32_t (*Fvid2_DrvDelete)(Fdrv_Handle handle, void *deleteArgs);
 105
 106 /** \brief Typedef for FVID2 control function pointer. */
 107 typedef int32_t (*Fvid2_DrvControl)(Fdrv_Handle handle,
 108                                     uint32_t    cmd,
 109                                     void       *cmdArgs,
 110                                     void       *cmdStatusArgs);
 111
 112 /** \brief Typedef for FVID2 queue function pointer. */
 113 typedef int32_t (*Fvid2_DrvQueue)(Fdrv_Handle       handle,
 114                                   Fvid2_FrameList  *frameList,
 115                                   uint32_t          streamId);
 116
 117 /** \brief Typedef for FVID2 dequeue function pointer. */
 118 typedef int32_t (*Fvid2_DrvDequeue)(Fdrv_Handle     handle,
 119                                     Fvid2_FrameList *frameList,
 120                                     uint32_t        streamId,
 121                                     uint32_t        timeout);
 122
 123 /** \brief Typedef for FVID2 process frames function pointer. */
 124 typedef int32_t (*Fvid2_DrvProcessRequest)(Fdrv_Handle      handle,
 125                                            Fvid2_FrameList *inProcessList,
 126                                            Fvid2_FrameList *outProcessList);
 127
 128 /** \brief Typedef for FVID2 get processed frames function pointer. */
 129 typedef int32_t (*Fvid2_DrvGetProcessedRequest)(Fdrv_Handle     handle,
 130                                                 Fvid2_FrameList *inProcessList,
 131                                                 Fvid2_FrameList *outProcessList,
 132                                                 uint32_t        timeout);
 133
 134
 135 /* ========================================================================== */
 136 /*                         Structure Declarations                             */
 137 /* ========================================================================== */
 138
 139 /**
 140  *  struct Fvid2_DrvCbParams_t
 141  *  \brief Structure for setting callback function parameters.
 142  */
 143 struct Fvid2_DrvCbParams_t
 144 {
 145     Fdm_CbFxn    fdmCbFxn;
 146     /**< FDM callback function used by the driver to initimate any
 147      *   operation has completed or not. */
 148     Fdm_ErrCbFxn fdmErrCbFxn;
 149     /**< FDM error callback function used by the driver to initimate
 150      *   any error occuring at the time of streaming. */
 151     Fvid2_Handle handle;
 152     /**< FDM layer FVID2 handle. This can be used by the actual driver to call
 153      *   application callback with proper FVID2 handle instead of routining
 154      *   the call through FDM layer. */
 155     void        *errList;
 156     /**< Pointer to a valid framelist or processlist where the driver
 157      *   copies the aborted/error packet. */
 158     void        *fdmData;
 159     /**< FDM specific data which is returned in the callback function
 160      *   as it is. */
 161 };
 162
 163 /**
 164  *  struct Fvid2_DrvOps
 165  *  \brief Structure to store driver function pointers.
 166  */
 167 typedef struct
 168 {
 169     uint32_t                    drvId;
 170     /**< Unique driver Id. */
 171     Fvid2_DrvCreate             createFxn;
 172     /**< FVID2 create function pointer. */
 173     Fvid2_DrvDelete             deleteFxn;
 174     /**< FVID2 delete function pointer. */
 175     Fvid2_DrvControl            controlFxn;
 176     /**< FVID2 control function pointer. */
 177     Fvid2_DrvQueue              queueFxn;
 178     /**< FVID2 queue function pointer. */
 179     Fvid2_DrvDequeue            dequeueFxn;
 180     /**< FVID2 dequeue function pointer. */
 181     Fvid2_DrvProcessRequest     processRequestFxn;
 182     /**< FVID2 process request function pointer. */
 183     Fvid2_DrvGetProcessedRequest getProcessedRequestFxn;
 184     /**< FVID2 get processed request function pointer. */
 185 } Fvid2_DrvOps;
 186
 187 /* ========================================================================== */
 188 /*                          Function Declarations                             */
 189 /* ========================================================================== */
 190
 191 /**
 192  *  Fvid2_registerDriver
 193  *  \brief FVID2 register driver function.
 194  *
 195  *  This function registers a driver with the FVID2 driver manager.
 196  *
 197  *  \param drvOps       Driver function table pointer containing driver
 198  *                      function pointers and driver name. The driver name
 199  *                      should be unique - two or more drivers can't have the
 200  *                      same driver name.
 201  *
 202  *  \return             Returns 0 on success else returns error value.
 203  */
 204 int32_t Fvid2_registerDriver(const Fvid2_DrvOps *drvOps);
 205
 206 /**
 207  *  Fvid2_unRegisterDriver
 208  *  \brief FVID2 unregister driver function.
 209  *
 210  *  This function unregisters a driver from the FVID2 driver manager.
 211  *
 212  *  \param drvOps       Driver function table pointer containing driver
 213  *                      function pointers and driver name.
 214  *
 215  *  \return             Returns 0 on success else returns error value.
 216  */
 217 int32_t Fvid2_unRegisterDriver(const Fvid2_DrvOps *drvOps);
 218
 219 /**
 220  *  Fvid2_checkFrameList
 221  *  \brief Checks the FVID2 frame list for error and returns appropriate error.
 222  *
 223  *  This is used by the drivers and not by the application.
 224  *
 225  *  \param frameList    Pointer to frame list to check for errors.
 226  *  \param maxFrames    Max frames to be checked against numFrames member
 227  *                      in frame list.
 228  *
 229  *  \return             Returns 0 on success else returns error value.
 230  */
 231 int32_t Fvid2_checkFrameList(const Fvid2_FrameList *frameList,
 232                              uint32_t maxFrames);
 233
 234 /**
 235  *  Fvid2_checkDqFrameList
 236  *  \brief Checks the FVID2 frame list of dequeue call for error and returns
 237  *  appropriate error. For dequeue operation, the frame pointers in the frames
 238  *  should not be checked as this will be filled by the driver.
 239  *
 240  *  This is used by the drivers and not by the application.
 241  *
 242  *  \param frameList    Pointer to frame list to check for errors.
 243  *  \param maxFrames    Max frames to be checked against numFrames member
 244  *                      in frame list.
 245  *
 246  *  \return             Returns 0 on success else returns error value.
 247  */
 248 int32_t Fvid2_checkDqFrameList(const Fvid2_FrameList   *frameList,
 249                                uint32_t                 maxFrames);
 250
 251 /**
 252  *  Fvid2_copyFrameList
 253  *  \brief Copies the source frame list to the destination frame list.
 254  *  This also resets the frame pointers from the source frame list.
 255  *
 256  *  This is used by the drivers and not by the application.
 257  *
 258  *  \param dest         Pointer to destination frame list.
 259  *  \param src          Pointer to source frame list.
 260  *
 261  *  \return             Returns 0 on success else returns error value.
 262  */
 263 void Fvid2_copyFrameList(Fvid2_FrameList *dest, Fvid2_FrameList *src);
 264
 265 /**
 266  *  Fvid2_duplicateFrameList
 267  *  \brief Duplicate the source frame list to the destination frame list.
 268  *  This does not reset the frame pointers from the source frame list.
 269  *
 270  *  This is used by the drivers and not by the application.
 271  *
 272  *  \param dest         Pointer to destination frame list.
 273  *  \param src          Pointer to source frame list.
 274  *
 275  *  \return             Returns 0 on success else returns error value.
 276  */
 277 void Fvid2_duplicateFrameList(Fvid2_FrameList       *dest,
 278                               const Fvid2_FrameList *src);
 279
 280 /**
 281  *  \brief Fvid2_DrvOps structure init function.
 282  *
 283  *  \param drvOps   [IN] Pointer to #Fvid2_DrvOps structure.
 284  *
 285  */
 286 static inline void Fvid2DrvOps_init(Fvid2_DrvOps *drvOps);
 287
 288 /* ========================================================================== */
 289 /*                       Static Function Definitions                          */
 290 /* ========================================================================== */
 291
 292 static inline void Fvid2DrvOps_init(Fvid2_DrvOps *drvOps)
 293 {
 294     if (NULL != drvOps)
 295     {
 296         drvOps->drvId                   = 0U;
 297         drvOps->createFxn               = NULL;
 298         drvOps->deleteFxn               = NULL;
 299         drvOps->controlFxn              = NULL;
 300         drvOps->queueFxn                = NULL;
 301         drvOps->dequeueFxn              = NULL;
 302         drvOps->processRequestFxn       = NULL;
 303         drvOps->getProcessedRequestFxn  = NULL;
 304     }
 305
 306     return;
 307 }
 308
 309
 310 #ifdef __cplusplus
 311 }
 312 #endif
 313
 314 #endif /* #ifndef FVID2_DRVMGR_H_ */