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 */
53typedef 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 */
71TI_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 */
85TI_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 */
102TI_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 */
121TI_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 */
135TI_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 */
150TI_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 */
165TI_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 */
186TI_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 */
206TI_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 */
220TI_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 */
233TI_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 */
246TI_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 */
259TI_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 */
275void      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 */
290void      cmdQueue_PrintHistory (TI_HANDLE hCmdQueue, TI_UINT32 uNumOfCmd);
291
292
293#endif  /* TI_DBG */
294
295
296#endif  /* _CMDQUEUE_API_H_ */
297