include/fvid2_drvMgr.h

   1 /* =============================================================================
   2  *   Copyright (c) Texas Instruments Incorporated 2012-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/fvid2.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
  68
  69 /** \brief FVID2 driver handle returned by individual drivers. */
  70 typedef Ptr Fdrv_Handle;
  71
  72 /** \brief Typedef for callback function parameters. */
  73 typedef struct Fvid2_DrvCbParams_t Fvid2_DrvCbParams;
  74
  75 /**
  76  *  \brief Typedef for FVID2 driver callback function prototype. This will be
  77  *  called by the driver and then the FVID2 driver manager will route the
  78  *  callback to the application.
  79  *
  80  *  fdmData: FVID2 driver manager internal data passed to driver during create
  81  *  call.
  82  *
  83  *  reserved: For future use. Not used currently. This will be set to NULL.
  84  */
  85 typedef Int32 (*Fdm_CbFxn)(Ptr fdmData, Ptr reserved);
  86
  87 /**
  88  *  \brief Typedef for FVID2 driver error callback function prototype.
  89  *  This will be called by the driver and then the FVID2 driver manager
  90  *  will route the error callback to the application.
  91  *
  92  *  fdmData: FVID2 driver manager internal data passed to driver during create
  93  *  call.
  94  *
  95  *  errList: Error data passed to the application.
  96  *
  97  *  reserved: For future use. Not used currently. This will be set to NULL.
  98  */
  99 typedef Int32 (*Fdm_ErrCbFxn)(Ptr fdmData, void *errList, Ptr reserved);
 100
 101 /** \brief Typedef for FVID2 create function pointer. */
 102 typedef Fdrv_Handle (*Fvid2_DrvCreate)(UInt32                   drvId,
 103                                        UInt32                   instanceId,
 104                                        Ptr                      createArgs,
 105                                        Ptr
 106                                        createStatusArgs,
 107                                        const Fvid2_DrvCbParams *fdmCbParams);
 108
 109 /** \brief Typedef for FVID2 delete function pointer. */
 110 typedef Int32 (*Fvid2_DrvDelete)(Fdrv_Handle handle, Ptr deleteArgs);
 111
 112 /** \brief Typedef for FVID2 control function pointer. */
 113 typedef Int32 (*Fvid2_DrvControl)(Fdrv_Handle handle,
 114                                   UInt32      cmd,
 115                                   Ptr         cmdArgs,
 116                                   Ptr         cmdStatusArgs);
 117
 118 /** \brief Typedef for FVID2 queue function pointer. */
 119 typedef Int32 (*Fvid2_DrvQueue)(Fdrv_Handle      handle,
 120                                 Fvid2_FrameList *frameList,
 121                                 UInt32           streamId);
 122
 123 /** \brief Typedef for FVID2 dequeue function pointer. */
 124 typedef Int32 (*Fvid2_DrvDequeue)(Fdrv_Handle      handle,
 125                                   Fvid2_FrameList *frameList,
 126                                   UInt32           streamId,
 127                                   UInt32           timeout);
 128
 129 /** \brief Typedef for FVID2 process frames function pointer. */
 130 typedef Int32 (*Fvid2_DrvProcessRequest)(Fdrv_Handle        handle,
 131                                          Fvid2_FrameList   *inProcessList,
 132                                          Fvid2_FrameList   *outProcessList);
 133
 134 /** \brief Typedef for FVID2 get processed frames function pointer. */
 135 typedef Int32 (*Fvid2_DrvGetProcessedRequest)(Fdrv_Handle        handle,
 136                                               Fvid2_FrameList   *inProcessList,
 137                                               Fvid2_FrameList   *outProcessList,
 138                                               UInt32             timeout);
 139
 140
 141 /* ========================================================================== */
 142 /*                         Structure Declarations                             */
 143 /* ========================================================================== */
 144
 145 /**
 146  *  struct Fvid2_DrvCbParams_t
 147  *  \brief Structure for setting callback function parameters.
 148  */
 149 struct Fvid2_DrvCbParams_t
 150 {
 151     Fdm_CbFxn    fdmCbFxn;
 152     /**< FDM callback function used by the driver to initimate any
 153      *   operation has completed or not. */
 154     Fdm_ErrCbFxn fdmErrCbFxn;
 155     /**< FDM error callback function used by the driver to initimate
 156      *   any error occuring at the time of streaming. */
 157     Fvid2_Handle handle;
 158     /**< FDM layer FVID2 handle. This can be used by the actual driver to call
 159      *   application callback with proper FVID2 handle instead of routining
 160      *   the call through FDM layer. */
 161     void        *errList;
 162     /**< Pointer to a valid framelist or processlist where the driver
 163      *   copies the aborted/error packet. */
 164     Ptr          fdmData;
 165     /**< FDM specific data which is returned in the callback function
 166      *   as it is. */
 167     Ptr          reserved;
 168     /**< For future use. Not used currently. Set this to NULL. */
 169 };
 170
 171 /**
 172  *  struct Fvid2_DrvOps
 173  *  \brief Structure to store driver function pointers.
 174  */
 175 typedef struct
 176 {
 177     UInt32                      drvId;
 178     /**< Unique driver Id. */
 179     Fvid2_DrvCreate             createFxn;
 180     /**< FVID2 create function pointer. */
 181     Fvid2_DrvDelete             deleteFxn;
 182     /**< FVID2 delete function pointer. */
 183     Fvid2_DrvControl            controlFxn;
 184     /**< FVID2 control function pointer. */
 185     Fvid2_DrvQueue              queueFxn;
 186     /**< FVID2 queue function pointer. */
 187     Fvid2_DrvDequeue            dequeueFxn;
 188     /**< FVID2 dequeue function pointer. */
 189     Fvid2_DrvProcessRequest     processRequestFxn;
 190     /**< FVID2 process request function pointer. */
 191     Fvid2_DrvGetProcessedRequest getProcessedRequestFxn;
 192     /**< FVID2 get processed request function pointer. */
 193 } Fvid2_DrvOps;
 194
 195 /* ========================================================================== */
 196 /*                          Function Declarations                             */
 197 /* ========================================================================== */
 198
 199 /**
 200  *  Fvid2_registerDriver
 201  *  \brief FVID2 register driver function.
 202  *
 203  *  This function registers a driver with the FVID2 driver manager.
 204  *
 205  *  \param drvOps       Driver function table pointer containing driver
 206  *                      function pointers and driver name. The driver name
 207  *                      should be unique - two or more drivers can't have the
 208  *                      same driver name.
 209  *
 210  *  \return             Returns 0 on success else returns error value.
 211  */
 212 Int32 Fvid2_registerDriver(const Fvid2_DrvOps *drvOps);
 213
 214 /**
 215  *  Fvid2_unRegisterDriver
 216  *  \brief FVID2 unregister driver function.
 217  *
 218  *  This function unregisters a driver from the FVID2 driver manager.
 219  *
 220  *  \param drvOps       Driver function table pointer containing driver
 221  *                      function pointers and driver name.
 222  *
 223  *  \return             Returns 0 on success else returns error value.
 224  */
 225 Int32 Fvid2_unRegisterDriver(const Fvid2_DrvOps *drvOps);
 226
 227 /**
 228  *  Fvid2_checkFrameList
 229  *  \brief Checks the FVID2 frame list for error and returns appropriate error.
 230  *
 231  *  This is used by the drivers and not by the application.
 232  *
 233  *  \param frameList    Pointer to frame list to check for errors.
 234  *  \param maxFrames    Max frames to be checked against numFrames member
 235  *                      in frame list.
 236  *
 237  *  \return             Returns 0 on success else returns error value.
 238  */
 239 Int32 Fvid2_checkFrameList(const Fvid2_FrameList *frameList, UInt32 maxFrames);
 240
 241 /**
 242  *  Fvid2_checkDqFrameList
 243  *  \brief Checks the FVID2 frame list of dequeue call for error and returns
 244  *  appropriate error. For dequeue operation, the frame pointers in the frames
 245  *  should not be checked as this will be filled by the driver.
 246  *
 247  *  This is used by the drivers and not by the application.
 248  *
 249  *  \param frameList    Pointer to frame list to check for errors.
 250  *  \param maxFrames    Max frames to be checked against numFrames member
 251  *                      in frame list.
 252  *
 253  *  \return             Returns 0 on success else returns error value.
 254  */
 255 Int32 Fvid2_checkDqFrameList(const Fvid2_FrameList *frameList,
 256                              UInt32                 maxFrames);
 257
 258 /**
 259  *  Fvid2_copyFrameList
 260  *  \brief Copies the source frame list to the destination frame list.
 261  *  This also resets the frame pointers from the source frame list.
 262  *
 263  *  This is used by the drivers and not by the application.
 264  *
 265  *  \param dest         Pointer to destination frame list.
 266  *  \param src          Pointer to source frame list.
 267  *
 268  *  \return             Returns 0 on success else returns error value.
 269  */
 270 void Fvid2_copyFrameList(Fvid2_FrameList *dest, Fvid2_FrameList *src);
 271
 272 /**
 273  *  Fvid2_duplicateFrameList
 274  *  \brief Duplicate the source frame list to the destination frame list.
 275  *  This does not reset the frame pointers from the source frame list.
 276  *
 277  *  This is used by the drivers and not by the application.
 278  *
 279  *  \param dest         Pointer to destination frame list.
 280  *  \param src          Pointer to source frame list.
 281  *
 282  *  \return             Returns 0 on success else returns error value.
 283  */
 284 void Fvid2_duplicateFrameList(Fvid2_FrameList       *dest,
 285                               const Fvid2_FrameList *src);
 286
 287 /**
 288  *  \brief Fvid2_DrvOps structure init function.
 289  *
 290  *  \param drvOps   [IN] Pointer to #Fvid2_DrvOps structure.
 291  *
 292  */
 293 static inline void Fvid2DrvOps_init(Fvid2_DrvOps *drvOps);
 294
 295 /* ========================================================================== */
 296 /*                       Static Function Definitions                          */
 297 /* ========================================================================== */
 298
 299 static inline void Fvid2DrvOps_init(Fvid2_DrvOps *drvOps)
 300 {
 301     if (NULL != drvOps)
 302     {
 303         drvOps->drvId                   = 0U;
 304         drvOps->createFxn               = NULL;
 305         drvOps->deleteFxn               = NULL;
 306         drvOps->controlFxn              = NULL;
 307         drvOps->queueFxn                = NULL;
 308         drvOps->dequeueFxn              = NULL;
 309         drvOps->processRequestFxn       = NULL;
 310         drvOps->getProcessedRequestFxn  = NULL;
 311     }
 312
 313     return;
 314 }
 315
 316
 317 #ifdef __cplusplus
 318 }
 319 #endif
 320
 321 #endif /* #ifndef FVID2_DRVMGR_H_ */