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