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
