b49288c93305bc8e0f826f62b317500332baab5a
[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 <ti/drv/fvid2/fvid2.h>
53 #ifdef __cplusplus
54 extern "C" {
55 #endif
57 /* ========================================================================== */
58 /*                           Macros & Typedefs                                */
59 /* ========================================================================== */
61 /** \brief Number of driver object to allocate in FVID2 library. */
62 #define FVID2_CFG_FDM_NUM_DRV_OBJS          (40U)
64 /** \brief Number of channel object to allocate in FVID2 library. */
65 #define FVID2_CFG_FDM_NUM_CH_OBJS           (80U)
69 /** \brief FVID2 driver handle returned by individual drivers. */
70 typedef Ptr Fdrv_Handle;
72 /** \brief Typedef for callback function parameters. */
73 typedef struct Fvid2_DrvCbParams_t Fvid2_DrvCbParams;
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);
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);
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);
109 /** \brief Typedef for FVID2 delete function pointer. */
110 typedef Int32 (*Fvid2_DrvDelete)(Fdrv_Handle handle, Ptr deleteArgs);
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);
118 /** \brief Typedef for FVID2 queue function pointer. */
119 typedef Int32 (*Fvid2_DrvQueue)(Fdrv_Handle      handle,
120                                 Fvid2_FrameList *frameList,
121                                 UInt32           streamId);
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);
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);
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);
141 /* ========================================================================== */
142 /*                         Structure Declarations                             */
143 /* ========================================================================== */
145 /**
146  *  struct Fvid2_DrvCbParams_t
147  *  \brief Structure for setting callback function parameters.
148  */
149 struct Fvid2_DrvCbParams_t
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 };
171 /**
172  *  struct Fvid2_DrvOps
173  *  \brief Structure to store driver function pointers.
174  */
175 typedef struct
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;
195 /* ========================================================================== */
196 /*                          Function Declarations                             */
197 /* ========================================================================== */
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);
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);
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);
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);
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);
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);
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);
295 /* ========================================================================== */
296 /*                       Static Function Definitions                          */
297 /* ========================================================================== */
299 static inline void Fvid2DrvOps_init(Fvid2_DrvOps *drvOps)
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     }
313     return;
317 #ifdef __cplusplus
319 #endif
321 #endif /* #ifndef FVID2_DRVMGR_H_ */