1 /* 2 * TxnQueue.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 /** \file TxnQueue.h 36 * \brief TxnQueue module API definition 37 * 38 * \see TxnQueue.c 39 */ 40 41 #ifndef __TXN_QUEUE_API_H__ 42 #define __TXN_QUEUE_API_H__ 43 44 45 #include "TxnDefs.h" 46 #include "BusDrv.h" 47 48 49 50 /************************************************************************ 51 * Defines 52 ************************************************************************/ 53 54 55 /************************************************************************ 56 * Macros 57 ************************************************************************/ 58 59 60 /************************************************************************ 61 * Types 62 ************************************************************************/ 63 64 65 /************************************************************************ 66 * Functions 67 ************************************************************************/ 68 /** \brief Create the TxnQ module 69 * 70 * \param hOs - Handle to Os Abstraction Layer 71 * \return Handle of the allocated object, NULL if allocation failed 72 * 73 * \par Description 74 * Allocate and clear the module's object 75 * 76 * \sa txnQ_Destroy 77 */ 78 TI_HANDLE txnQ_Create (TI_HANDLE hOs); 79 /** \brief Destroy the module 80 * 81 * \param The module's object 82 * \return TI_OK on success or TI_NOK on failure 83 * 84 * \par Description 85 * Destroy bus driver and free the module's object 86 * 87 * \sa txnQ_Create 88 */ 89 TI_STATUS txnQ_Destroy (TI_HANDLE hTxnQ); 90 /** \brief Init module 91 * 92 * \param hTxnQ - The module's object 93 * \param hOs - Handle to Os Abstraction Layer 94 * \param hReport - Handle to report module 95 * \param hContext - Handle to context module 96 * \return void 97 * 98 * \par Description 99 * 100 * \sa 101 */ 102 void txnQ_Init (TI_HANDLE hTxnQ, 103 TI_HANDLE hOs, 104 TI_HANDLE hReport, 105 TI_HANDLE hContext); 106 /** \brief Configure bus driver 107 * 108 * \param hTxnQ - The module's object 109 * \param pBusDrvCfg - A union used for per-bus specific configuration. 110 * \return TI_OK / TI_NOK 111 * 112 * \par Description 113 * Called by DrvMain (future - by Chip-Manager). 114 * Configure the bus driver with its connection configuration (such as baud-rate, bus width etc) 115 * and establish the physical connection. Done once (and not per functional driver startup). 116 * 117 * \sa 118 */ 119 TI_STATUS txnQ_ConnectBus (TI_HANDLE hTxnQ, 120 TBusDrvCfg *pBusDrvCfg, 121 TTxnDoneCb fConnectCb, 122 TI_HANDLE hConnectCb); 123 /** \brief Disconnect bus driver 124 * 125 * \param hTxnQ - The module's object 126 * \return TI_OK / TI_NOK 127 * 128 * \par Description 129 * Called by DrvMain (future - by Chip-Manager). 130 * Disconnect the bus driver. 131 * 132 * \sa 133 */ 134 TI_STATUS txnQ_DisconnectBus (TI_HANDLE hTxnQ); 135 /** \brief Register functional driver to TxnQ 136 * 137 * \param hTxnQ - The module's object 138 * \param uFuncId - The calling functional driver 139 * \param uNumPrios - The number of queues/priorities 140 * \param fTxnQueueDoneCb - The callback to call upon full transaction completion. 141 * \param hCbHandle - The callback handle 142 * \return TI_OK / TI_NOK 143 * 144 * \par Description 145 * Called by each functional driver (WLAN, future-BT) that uses the TxnQ. 146 * Save driver's info and create its queues. 147 * Perform in critical section to prevent preemption from TxnDone. 148 * 149 * \sa txnQ_Close 150 */ 151 TI_STATUS txnQ_Open (TI_HANDLE hTxnQ, 152 TI_UINT32 uFuncId, 153 TI_UINT32 uNumPrios, 154 TTxnQueueDoneCb fTxnQueueDoneCb, 155 TI_HANDLE hCbHandle); 156 /** \brief Unregister functional driver from TxnQ 157 * 158 * \param hTxnQ - The module's object 159 * \param uFuncId - The calling functional driver 160 * \return void 161 * \sa txnQ_Open 162 * 163 * \par Description 164 * Called by registered functional driver that uses the TxnQ to unregister. 165 * Clear the function's data and destroy its queues. 166 * Perform in critical section to prevent preemption from TxnDone. 167 * 168 * \sa txnQ_Open 169 */ 170 void txnQ_Close (TI_HANDLE hTxnQ, TI_UINT32 uFuncId); 171 /** \brief Restart caller's queues 172 * 173 * \param hTxnQ - The module's object 174 * \param uFuncId - The calling functional driver 175 * \return COMPLETE if queues were restarted, PENDING if waiting for TxnDone to restart queues 176 * 177 * \par Description 178 * Called upon functional driver stop command or upon recovery. 179 * If no transaction in progress for the calling function, clear its queues (call the CBs). 180 * If a transaction from this function is in progress, just set state to RESTART and when 181 * called back upon TxnDone clear the queues. 182 * Perform in critical section to prevent preemption from TxnDone. 183 * \note 184 * The Restart applies only to the calling function's queues. 185 * 186 * \sa txnQ_ClearQueues 187 */ 188 ETxnStatus txnQ_Restart (TI_HANDLE hTxnQ, TI_UINT32 uFuncId); 189 /** \brief Run caller's queues 190 * 191 * \param hTxnQ - The module's object 192 * \param uFuncId - The calling functional driver 193 * \return void 194 * 195 * \par Description 196 * Enable TxnQ scheduler to process transactions from the calling function's queues. 197 * Run scheduler to issue transactions as possible. 198 * Run in critical section to protect from preemption by TxnDone. 199 * 200 * \sa txnQ_ClearQueues 201 */ 202 void txnQ_Run (TI_HANDLE hTxnQ, TI_UINT32 uFuncId); 203 /** \brief Stop caller's queues 204 * 205 * \param hTxnQ - The module's object 206 * \param uFuncId - The calling functional driver 207 * \return void 208 * 209 * \par Description 210 * Disable TxnQ scheduler to process transactions from the calling function's queues. 211 * 212 * \sa 213 */ 214 void txnQ_Stop (TI_HANDLE hTxnQ, TI_UINT32 uFuncId); 215 /** \brief Issue a new transaction 216 * 217 * \param hTxnQ - The module's object 218 * \param pTxn - The transaction object 219 * \return COMPLETE if input pTxn completed in this context, PENDING if not, ERROR if failed 220 * 221 * \par Description 222 * Called by the functional driver to initiate a new transaction. 223 * In critical section save transaction and call scheduler. 224 * 225 * \sa 226 */ 227 ETxnStatus txnQ_Transact (TI_HANDLE hTxnQ, TTxnStruct *pTxn); 228 229 #ifdef TI_DBG 230 /** \brief Print Txn Queues 231 * 232 * \param hTxnQ - The module's object 233 * \return void 234 * 235 * \par Description 236 * 237 * \sa 238 */ 239 void txnQ_PrintQueues (TI_HANDLE hTxnQ); 240 #endif 241 242 243 244 #endif /*__TXN_QUEUE_API_H__*/ 245