/*

 * CmdQueue_api.h

 *

 * Copyright(c) 1998 - 2010 Texas Instruments. All rights reserved.      

 * All rights reserved.      

 * 

 * This program and the accompanying materials are made available under the 

 * terms of the Eclipse Public License v1.0 or BSD License which accompanies

 * this distribution. The Eclipse Public License is available at

 * http://www.eclipse.org/legal/epl-v10.html and the BSD License is as below.                                   

 *                                                                       

 * Redistribution and use in source and binary forms, with or without    

 * modification, are permitted provided that the following conditions    

 * are met:                                                              

 *                                                                       

 *  * Redistributions of source code must retain the above copyright     

 *    notice, this list of conditions and the following disclaimer.      

 *  * Redistributions in binary form must reproduce the above copyright  

 *    notice, this list of conditions and the following disclaimer in    

 *    the documentation and/or other materials provided with the         

 *    distribution.                                                      

 *  * Neither the name Texas Instruments nor the names of its            

 *    contributors may be used to endorse or promote products derived    

 *    from this software without specific prior written permission.      

 *                                                                       

 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS   

 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT     

 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 

 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT  

 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 

 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT      

 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 

 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 

 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT   

 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 

 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

 */

/** \file CmdQueue_api.h

 *  \brief CmdQueue api

 *

 *  \see CmdQueue.c

 */

#ifndef _CMDQUEUE_API_H_

#define _CMDQUEUE_API_H_

#include "public_commands.h"

/*****************************************************************************

 **         Structures                                                      **

 *****************************************************************************/

/* User Callback for Queue */

typedef void (*TCmdQueueInterrogateCb) (TI_HANDLE handle, TI_UINT16 status, void *pItrBuf);

/*****************************************************************************

 **         APIs definitions                                  **

 *****************************************************************************/

/*

 * \brief	Create the TCmdQueue object

 * 

 * \param  hOs  - OS module object handle

 * \return Handle to the created object

 * 

 * \par Description

 * Calling this function creates a CmdQueue object

 * 

 * \sa cmdQueue_Destroy

 */

TI_HANDLE cmdQueue_Create (TI_HANDLE hOS);

/*

 * \brief	Destroys the cmdQueue object

 * 

 * \param  hCmdMbox  - The object to free

 * \return TI_OK

 * 

 * \par Description

 * Calling this function destroys the cmdQueue object

 * 

 * \sa cmdQueue_Create

 */

TI_STATUS cmdQueue_Destroy (TI_HANDLE hCmdQueue);

/*

 * \brief	Configure the CmdQueue object

 * 

 * \param  hCmdQueue - Handle to CmdQueue

 * \param  hCmdMbox  - Handle to CmdMbox

 * \param  hReport - Handle to report module

 * \param  hTwIf  - Handle to TwIf

 * \param  hTimer  - Handle to os timer

 * \return TI_OK on success or TI_NOK on failure

 * 

 * \par Description

 * 

 * \sa

 */

TI_STATUS cmdQueue_Init   (TI_HANDLE hCmdQueue, 

                           TI_HANDLE hCmdMbox, 

                           TI_HANDLE hReport, 

                           TI_HANDLE hTwIf,

                           TI_HANDLE hTimer);

/*

 * \brief	Prepere the command queue for recovery.

 * 

 * \param  hCmdQueue - Handle to CmdQueue

 * \return TI_OK

 * 

 * \par Description

 * Copy the queue nodes to a recovery list, in order handle 

 * the commands CB's after recovery has finished

 * 

 * \sa cmdQueue_EndReconfig

 */

TI_STATUS cmdQueue_Restart (TI_HANDLE hCmdQueue);

/*

 * \brief	Call the stored CB to end the recovery of the MBox queue

 * 

 * \param  hCmdQueue - Handle to CmdQueue

 * \return TI_OK

 * 

 * \par Description

 * Call the stored CB's with an error status 

 * 

 * \sa cmdQueue_StartReconfig

 */

TI_STATUS cmdQueue_EndReconfig (TI_HANDLE hCmdQueue);

/*

 * \brief	Register for a call back to be called when Command Complete occured and the CmdMboxCB was NULL

 * 

 * \param  hCmdQueue - Handle to CmdQueue

 * \param  fCb - The command's Cb function

 * \param  hCb - The command's Cb handle

 * \return TI_OK

 * 

 * \par Description

 * 

 * \sa

 */

TI_STATUS cmdQueue_RegisterCmdCompleteGenericCb (TI_HANDLE hCmdQueue, void *fCb, TI_HANDLE hCb);

/*

 * \brief	Register for a call back to be called when an Error (Timeout) occurs

 * 

 * \param  hCmdQueue - Handle to CmdQueue

 * \param  fCb - The command's Cb function

 * \param  hCb - The command's Cb handle

 * \return TI_OK

 * 

 * \par Description

 * 

 * \sa

 */

TI_STATUS cmdQueue_RegisterForErrorCb (TI_HANDLE hCmdQueue, void *fCb, TI_HANDLE hCb);

/*

 * \brief	Sends the command to the cmdMbox

 * 

 * \param  hCmdQueue - Handle to CmdQueue

 * \param  eMboxCmdType - The command type

 * \param  pMboxBuf - The command itself (parameters)

 * \param  uParamsLen - The command's length

 * \param  fCb - The command's Cb function

 * \param  hCb - The command's Cb handle

 * \param  pCb - Pointer to the results buffer (for interrogate commands)

 * \return TI_OK on success or TI_NOK on failure

 * 

 * \par Description

 * Pushes the command to the command queue, which triggers the 

 * CmdQueue SM.

 * 

 * \sa cmdQueue_Push

 */

TI_STATUS cmdQueue_SendCommand (TI_HANDLE  hCmdQueue, 

                            Command_e  eMboxCmdType, 

                            void      *pMboxBuf, 

                            TI_UINT32  uParamsLen, 

                            void      *fCb, 

                            TI_HANDLE  hCb, 

                            void      *pCb);

/*

 * \brief	Notify the CmdQueue SM on the result received.

 * 

 * \param  hCmdQueue - Handle to CmdQueue

 * \return TI_OK on success or TI_NOK on failure

 * 

 * \par Description

 * Call the CmdQueue SM with CMDQUEUE_EVENT_COMPLETE

 * 

 * \sa cmdQueue_SM

 */

TI_STATUS cmdQueue_ResultReceived (TI_HANDLE hCmdQueue);

/*

 * \brief	Returns maximum number of commands (ever) in TCmdQueue queue

 * 

 * \param  hCmdQueue - Handle to CmdQueue

 * \return maximum number of commands (ever) in mailbox queue

 * 

 * \par Description

 * Used for debugging purposes

 *

 * \sa cmdQueue_Error

 */

TI_UINT32 cmdQueue_GetMaxNumberOfCommands (TI_HANDLE hCmdQueue);

/*

 * \brief	Enables the CmdMbox (on exit from init mode)

 * 

 * \param  hCmdQueue - Handle to CmdQueue

 * \return TI_OK

 * 

 * \par Description

 * 

 * \sa cmdQueue_DisableMbox

 */

TI_STATUS cmdQueue_EnableMbox (TI_HANDLE hCmdQueue);

/*

 * \brief	Disables the CmdMbox (when stopping the driver)

 * 

 * \param  hCmdQueue - Handle to CmdQueue

 * \return TI_OK

 * 

 * \par Description

 * 

 * \sa cmdQueue_EnableMbox

 */

TI_STATUS cmdQueue_DisableMbox (TI_HANDLE hCmdQueue);

/*

 * \brief	Called when a command timeout occur

 * 

 * \param  hCmdQueue - Handle to CmdQueue

 * \return TI_OK

 * 

 * \par Description

 * 

 * \sa cmdQueue_Init, cmdMbox_TimeOut

 */

TI_STATUS cmdQueue_Error (TI_HANDLE hCmdQueue, TI_UINT32 command, TI_UINT32 status, void *param);

#ifdef TI_DBG

/*

 * \brief	Print the command queue & statistics

 * 

 * \param  hCmdQueue - Handle to CmdQueue

 * \return void

 * 

 * \par Description

 * Used for debugging purposes

 *

 * \sa cmdQueue_PrintQueue

 */

void      cmdQueue_Print (TI_HANDLE hCmdQueue);

/*

 * \brief	print the last uNumOfCmd commands

 * 

 * \param  hCmdQueue - Handle to CmdQueue

 * \param  uNumOfCmd - Number of commands to print

 * \return void

 * 

 * \par Description

 * Used for debugging purposes

 *

 * \sa cmdQueue_Error

 */

void      cmdQueue_PrintHistory (TI_HANDLE hCmdQueue, TI_UINT32 uNumOfCmd);

#endif  /* TI_DBG */

#endif  /* _CMDQUEUE_API_H_ */