Added XDC files and added top level include
[keystone-rtos/fvid2.git] / 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  */
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/include/fvid2_api.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)
67 /** \brief FVID2 driver handle returned by individual drivers. */
68 typedef void *Fdrv_Handle;
70 /** \brief Typedef for callback function parameters. */
71 typedef struct Fvid2_DrvCbParams_t      Fvid2_DrvCbParams;
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);
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);
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);
103 /** \brief Typedef for FVID2 delete function pointer. */
104 typedef int32_t (*Fvid2_DrvDelete)(Fdrv_Handle handle, void *deleteArgs);
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);
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);
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);
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);
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);
135 /* ========================================================================== */
136 /*                         Structure Declarations                             */
137 /* ========================================================================== */
139 /**
140  *  struct Fvid2_DrvCbParams_t
141  *  \brief Structure for setting callback function parameters.
142  */
143 struct Fvid2_DrvCbParams_t
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 };
163 /**
164  *  struct Fvid2_DrvOps
165  *  \brief Structure to store driver function pointers.
166  */
167 typedef struct
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;
187 /* ========================================================================== */
188 /*                          Function Declarations                             */
189 /* ========================================================================== */
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);
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);
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);
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);
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);
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);
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);
288 /* ========================================================================== */
289 /*                       Static Function Definitions                          */
290 /* ========================================================================== */
292 static inline void Fvid2DrvOps_init(Fvid2_DrvOps *drvOps)
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     }
306     return;
310 #ifdef __cplusplus
312 #endif
314 #endif /* #ifndef FVID2_DRVMGR_H_ */