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 * \param pRxDmaBufLen - The Rx DMA buffer length in bytes (needed as a limit of the Rx aggregation length) 111 * \param pTxDmaBufLen - The Tx DMA buffer length in bytes (needed as a limit of the Tx aggregation length) 112 * \return TI_OK / TI_NOK 113 * 114 * \par Description 115 * Called by DrvMain (future - by Chip-Manager). 116 * Configure the bus driver with its connection configuration (such as baud-rate, bus width etc) 117 * and establish the physical connection. Done once (and not per functional driver startup). 118 * 119 * \sa 120 */ 121 TI_STATUS txnQ_ConnectBus (TI_HANDLE hTxnQ, 122 TBusDrvCfg *pBusDrvCfg, 123 TTxnDoneCb fConnectCb, 124 TI_HANDLE hConnectCb, 125 TI_UINT32 *pRxDmaBufLen, 126 TI_UINT32 *pTxDmaBufLen); 127 128 /** \brief Disconnect bus driver 129 * 130 * \param hTxnQ - The module's object 131 * \return TI_OK / TI_NOK 132 * 133 * \par Description 134 * Called by DrvMain (future - by Chip-Manager). 135 * Disconnect the bus driver. 136 * 137 * \sa 138 */ 139 TI_STATUS txnQ_DisconnectBus (TI_HANDLE hTxnQ); 140 /** \brief Register functional driver to TxnQ 141 * 142 * \param hTxnQ - The module's object 143 * \param uFuncId - The calling functional driver 144 * \param uNumPrios - The number of queues/priorities 145 * \param fTxnQueueDoneCb - The callback to call upon full transaction completion. 146 * \param hCbHandle - The callback handle 147 * \return TI_OK / TI_NOK 148 * 149 * \par Description 150 * Called by each functional driver (WLAN, future-BT) that uses the TxnQ. 151 * Save driver's info and create its queues. 152 * Perform in critical section to prevent preemption from TxnDone. 153 * 154 * \sa txnQ_Close 155 */ 156 TI_STATUS txnQ_Open (TI_HANDLE hTxnQ, 157 TI_UINT32 uFuncId, 158 TI_UINT32 uNumPrios, 159 TTxnQueueDoneCb fTxnQueueDoneCb, 160 TI_HANDLE hCbHandle); 161 /** \brief Unregister functional driver from TxnQ 162 * 163 * \param hTxnQ - The module's object 164 * \param uFuncId - The calling functional driver 165 * \return void 166 * \sa txnQ_Open 167 * 168 * \par Description 169 * Called by registered functional driver that uses the TxnQ to unregister. 170 * Clear the function's data and destroy its queues. 171 * Perform in critical section to prevent preemption from TxnDone. 172 * 173 * \sa txnQ_Open 174 */ 175 void txnQ_Close (TI_HANDLE hTxnQ, TI_UINT32 uFuncId); 176 /** \brief Restart caller's queues 177 * 178 * \param hTxnQ - The module's object 179 * \param uFuncId - The calling functional driver 180 * \return COMPLETE if queues were restarted, PENDING if waiting for TxnDone to restart queues 181 * 182 * \par Description 183 * Called upon functional driver stop command or upon recovery. 184 * If no transaction in progress for the calling function, clear its queues (call the CBs). 185 * If a transaction from this function is in progress, just set state to RESTART and when 186 * called back upon TxnDone clear the queues. 187 * Perform in critical section to prevent preemption from TxnDone. 188 * \note 189 * The Restart applies only to the calling function's queues. 190 * 191 * \sa txnQ_ClearQueues 192 */ 193 ETxnStatus txnQ_Restart (TI_HANDLE hTxnQ, TI_UINT32 uFuncId); 194 /** \brief Run caller's queues 195 * 196 * \param hTxnQ - The module's object 197 * \param uFuncId - The calling functional driver 198 * \return void 199 * 200 * \par Description 201 * Enable TxnQ scheduler to process transactions from the calling function's queues. 202 * Run scheduler to issue transactions as possible. 203 * Run in critical section to protect from preemption by TxnDone. 204 * 205 * \sa txnQ_ClearQueues 206 */ 207 void txnQ_Run (TI_HANDLE hTxnQ, TI_UINT32 uFuncId); 208 /** \brief Stop caller's queues 209 * 210 * \param hTxnQ - The module's object 211 * \param uFuncId - The calling functional driver 212 * \return void 213 * 214 * \par Description 215 * Disable TxnQ scheduler to process transactions from the calling function's queues. 216 * 217 * \sa 218 */ 219 void txnQ_Stop (TI_HANDLE hTxnQ, TI_UINT32 uFuncId); 220 /** \brief Issue a new transaction 221 * 222 * \param hTxnQ - The module's object 223 * \param pTxn - The transaction object 224 * \return COMPLETE if input pTxn completed in this context, PENDING if not, ERROR if failed 225 * 226 * \par Description 227 * Called by the functional driver to initiate a new transaction. 228 * In critical section save transaction and call scheduler. 229 * 230 * \sa 231 */ 232 ETxnStatus txnQ_Transact (TI_HANDLE hTxnQ, TTxnStruct *pTxn); 233 234 /** 235 * \fn txnQ_ClearQueues 236 * \brief Clear the function queues 237 * 238 * Clear the specified function queues and call its CB for each Txn with status=RECOVERY. 239 * 240 * \note Called in critical section. 241 * \param hTxnQ - The module's object 242 * \param uFuncId - The calling functional driver 243 * \return void 244 * \sa 245 */ 246 void txnQ_ClearQueues (TI_HANDLE hTxnQ, TI_UINT32 uFuncId); 247 248 249 #ifdef TI_DBG 250 /** \brief Print Txn Queues 251 * 252 * \param hTxnQ - The module's object 253 * \return void 254 * 255 * \par Description 256 * 257 * \sa 258 */ 259 void txnQ_PrintQueues (TI_HANDLE hTxnQ); 260 #endif 261 262 263 264 #endif /*__TXN_QUEUE_API_H__*/ 265