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 */
78TI_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 */
89TI_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 */
102void        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 */
119TI_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 */
134TI_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 */
151TI_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 */
170void        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 */
188ETxnStatus  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 */
202void        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 */
214void        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 */
227ETxnStatus  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 */
239void txnQ_PrintQueues (TI_HANDLE hTxnQ);
240#endif
241
242
243
244#endif /*__TXN_QUEUE_API_H__*/
245