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