• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * CmdQueue_api.h
3  *
4  * Copyright(c) 1998 - 2009 Texas Instruments. All rights reserved.
5  * All rights reserved.
6  *
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted provided that the following conditions
9  * are met:
10  *
11  *  * Redistributions of source code must retain the above copyright
12  *    notice, this list of conditions and the following disclaimer.
13  *  * Redistributions in binary form must reproduce the above copyright
14  *    notice, this list of conditions and the following disclaimer in
15  *    the documentation and/or other materials provided with the
16  *    distribution.
17  *  * Neither the name Texas Instruments nor the names of its
18  *    contributors may be used to endorse or promote products derived
19  *    from this software without specific prior written permission.
20  *
21  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32  */
33 
34 
35 
36 /** \file CmdQueue_api.h
37  *  \brief CmdQueue api
38  *
39  *  \see CmdQueue.c
40  */
41 
42 #ifndef _CMDQUEUE_API_H_
43 #define _CMDQUEUE_API_H_
44 
45 #include "public_commands.h"
46 
47 
48 /*****************************************************************************
49  **         Structures                                                      **
50  *****************************************************************************/
51 
52 /* User Callback for Queue */
53 typedef void (*TCmdQueueInterrogateCb) (TI_HANDLE handle, TI_UINT16 status, void *pItrBuf);
54 
55 
56 /*****************************************************************************
57  **         APIs definitions                                  **
58  *****************************************************************************/
59 
60 /*
61  * \brief	Create the TCmdQueue object
62  *
63  * \param  hOs  - OS module object handle
64  * \return Handle to the created object
65  *
66  * \par Description
67  * Calling this function creates a CmdQueue object
68  *
69  * \sa cmdQueue_Destroy
70  */
71 TI_HANDLE cmdQueue_Create (TI_HANDLE hOS);
72 
73 
74 /*
75  * \brief	Destroys the cmdQueue object
76  *
77  * \param  hCmdMbox  - The object to free
78  * \return TI_OK
79  *
80  * \par Description
81  * Calling this function destroys the cmdQueue object
82  *
83  * \sa cmdQueue_Create
84  */
85 TI_STATUS cmdQueue_Destroy (TI_HANDLE hCmdQueue);
86 
87 
88 /*
89  * \brief	Configure the CmdQueue object
90  *
91  * \param  hCmdQueue - Handle to CmdQueue
92  * \param  hCmdMbox  - Handle to CmdMbox
93  * \param  hReport - Handle to report module
94  * \param  hTwIf  - Handle to TwIf
95  * \param  hTimer  - Handle to os timer
96  * \return TI_OK on success or TI_NOK on failure
97  *
98  * \par Description
99  *
100  * \sa
101  */
102 TI_STATUS cmdQueue_Init   (TI_HANDLE hCmdQueue,
103                            TI_HANDLE hCmdMbox,
104                            TI_HANDLE hReport,
105                            TI_HANDLE hTwIf,
106                            TI_HANDLE hTimer);
107 
108 
109 /*
110  * \brief	Prepere the command queue for recovery.
111  *
112  * \param  hCmdQueue - Handle to CmdQueue
113  * \return TI_OK
114  *
115  * \par Description
116  * Copy the queue nodes to a recovery list, in order handle
117  * the commands CB's after recovery has finished
118  *
119  * \sa cmdQueue_EndReconfig
120  */
121 TI_STATUS cmdQueue_Restart (TI_HANDLE hCmdQueue);
122 
123 
124 /*
125  * \brief	Call the stored CB to end the recovery of the MBox queue
126  *
127  * \param  hCmdQueue - Handle to CmdQueue
128  * \return TI_OK
129  *
130  * \par Description
131  * Call the stored CB's with an error status
132  *
133  * \sa cmdQueue_StartReconfig
134  */
135 TI_STATUS cmdQueue_EndReconfig (TI_HANDLE hCmdQueue);
136 
137 
138 /*
139  * \brief	Register for a call back to be called when Command Complete occured and the CmdMboxCB was NULL
140  *
141  * \param  hCmdQueue - Handle to CmdQueue
142  * \param  fCb - The command's Cb function
143  * \param  hCb - The command's Cb handle
144  * \return TI_OK
145  *
146  * \par Description
147  *
148  * \sa
149  */
150 TI_STATUS cmdQueue_RegisterCmdCompleteGenericCb (TI_HANDLE hCmdQueue, void *fCb, TI_HANDLE hCb);
151 
152 
153 /*
154  * \brief	Register for a call back to be called when an Error (Timeout) occurs
155  *
156  * \param  hCmdQueue - Handle to CmdQueue
157  * \param  fCb - The command's Cb function
158  * \param  hCb - The command's Cb handle
159  * \return TI_OK
160  *
161  * \par Description
162  *
163  * \sa
164  */
165 TI_STATUS cmdQueue_RegisterForErrorCb (TI_HANDLE hCmdQueue, void *fCb, TI_HANDLE hCb);
166 
167 
168 /*
169  * \brief	Sends the command to the cmdMbox
170  *
171  * \param  hCmdQueue - Handle to CmdQueue
172  * \param  eMboxCmdType - The command type
173  * \param  pMboxBuf - The command itself (parameters)
174  * \param  uParamsLen - The command's length
175  * \param  fCb - The command's Cb function
176  * \param  hCb - The command's Cb handle
177  * \param  pCb - Pointer to the results buffer (for interrogate commands)
178  * \return TI_OK on success or TI_NOK on failure
179  *
180  * \par Description
181  * Pushes the command to the command queue, which triggers the
182  * CmdQueue SM.
183  *
184  * \sa cmdQueue_Push
185  */
186 TI_STATUS cmdQueue_SendCommand (TI_HANDLE  hCmdQueue,
187                             Command_e  eMboxCmdType,
188                             void      *pMboxBuf,
189                             TI_UINT32  uParamsLen,
190                             void      *fCb,
191                             TI_HANDLE  hCb,
192                             void      *pCb);
193 
194 
195 /*
196  * \brief	Notify the CmdQueue SM on the result received.
197  *
198  * \param  hCmdQueue - Handle to CmdQueue
199  * \return TI_OK on success or TI_NOK on failure
200  *
201  * \par Description
202  * Call the CmdQueue SM with CMDQUEUE_EVENT_COMPLETE
203  *
204  * \sa cmdQueue_SM
205  */
206 TI_STATUS cmdQueue_ResultReceived (TI_HANDLE hCmdQueue);
207 
208 
209 /*
210  * \brief	Returns maximum number of commands (ever) in TCmdQueue queue
211  *
212  * \param  hCmdQueue - Handle to CmdQueue
213  * \return maximum number of commands (ever) in mailbox queue
214  *
215  * \par Description
216  * Used for debugging purposes
217  *
218  * \sa cmdQueue_Error
219  */
220 TI_UINT32 cmdQueue_GetMaxNumberOfCommands (TI_HANDLE hCmdQueue);
221 
222 
223 /*
224  * \brief	Enables the CmdMbox (on exit from init mode)
225  *
226  * \param  hCmdQueue - Handle to CmdQueue
227  * \return TI_OK
228  *
229  * \par Description
230  *
231  * \sa cmdQueue_DisableMbox
232  */
233 TI_STATUS cmdQueue_EnableMbox (TI_HANDLE hCmdQueue);
234 
235 
236 /*
237  * \brief	Disables the CmdMbox (when stopping the driver)
238  *
239  * \param  hCmdQueue - Handle to CmdQueue
240  * \return TI_OK
241  *
242  * \par Description
243  *
244  * \sa cmdQueue_EnableMbox
245  */
246 TI_STATUS cmdQueue_DisableMbox (TI_HANDLE hCmdQueue);
247 
248 
249 /*
250  * \brief	Called when a command timeout occur
251  *
252  * \param  hCmdQueue - Handle to CmdQueue
253  * \return TI_OK
254  *
255  * \par Description
256  *
257  * \sa cmdQueue_Init, cmdMbox_TimeOut
258  */
259 TI_STATUS cmdQueue_Error (TI_HANDLE hCmdQueue, TI_UINT32 command, TI_UINT32 status, void *param);
260 
261 
262 #ifdef TI_DBG
263 
264 /*
265  * \brief	Print the command queue & statistics
266  *
267  * \param  hCmdQueue - Handle to CmdQueue
268  * \return void
269  *
270  * \par Description
271  * Used for debugging purposes
272  *
273  * \sa cmdQueue_PrintQueue
274  */
275 void      cmdQueue_Print (TI_HANDLE hCmdQueue);
276 
277 
278 /*
279  * \brief	print the last uNumOfCmd commands
280  *
281  * \param  hCmdQueue - Handle to CmdQueue
282  * \param  uNumOfCmd - Number of commands to print
283  * \return void
284  *
285  * \par Description
286  * Used for debugging purposes
287  *
288  * \sa cmdQueue_Error
289  */
290 void      cmdQueue_PrintHistory (TI_HANDLE hCmdQueue, TI_UINT32 uNumOfCmd);
291 
292 
293 #endif  /* TI_DBG */
294 
295 
296 #endif  /* _CMDQUEUE_API_H_ */
297