Commit | Line | Data |
---|---|---|
30295c89 VM |
1 | //------------------------------------------------------------------------------ |
2 | // <copyright file="htc_api.h" company="Atheros"> | |
3 | // Copyright (c) 2007-2010 Atheros Corporation. All rights reserved. | |
4 | // | |
5 | // | |
6 | // Permission to use, copy, modify, and/or distribute this software for any | |
7 | // purpose with or without fee is hereby granted, provided that the above | |
8 | // copyright notice and this permission notice appear in all copies. | |
9 | // | |
10 | // THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES | |
11 | // WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | |
12 | // MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | |
13 | // ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | |
14 | // WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | |
15 | // ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | |
16 | // OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | |
17 | // | |
18 | // | |
19 | //------------------------------------------------------------------------------ | |
20 | //============================================================================== | |
21 | // Author(s): ="Atheros" | |
22 | //============================================================================== | |
23 | #ifndef _HTC_API_H_ | |
24 | #define _HTC_API_H_ | |
25 | ||
26 | #include "htc_packet.h" | |
27 | #include <htc.h> | |
28 | #include <htc_services.h> | |
29 | ||
30 | #ifdef __cplusplus | |
31 | extern "C" { | |
32 | #endif /* __cplusplus */ | |
33 | ||
34 | /* TODO.. for BMI */ | |
35 | #define ENDPOINT1 0 | |
36 | // TODO -remove me, but we have to fix BMI first | |
37 | #define HTC_MAILBOX_NUM_MAX 4 | |
38 | ||
39 | /* this is the amount of header room required by users of HTC */ | |
40 | #define HTC_HEADER_LEN HTC_HDR_LENGTH | |
41 | ||
42 | typedef void *HTC_HANDLE; | |
43 | ||
4853ac05 | 44 | typedef u16 HTC_SERVICE_ID; |
30295c89 | 45 | |
4f0cce96 | 46 | struct htc_init_info { |
30295c89 | 47 | void *pContext; /* context for target failure notification */ |
1f4c34bd | 48 | void (*TargetFailure)(void *Instance, int Status); |
4f0cce96 | 49 | }; |
30295c89 VM |
50 | |
51 | /* per service connection send completion */ | |
c6528e2f | 52 | typedef void (*HTC_EP_SEND_PKT_COMPLETE)(void *,struct htc_packet *); |
30295c89 | 53 | /* per service connection callback when a plurality of packets have been sent |
6ca0f664 | 54 | * The struct htc_packet_queue is a temporary queue object (e.g. freed on return from the callback) |
30295c89 VM |
55 | * to hold a list of completed send packets. |
56 | * If the handler cannot fully traverse the packet queue before returning, it should | |
57 | * transfer the items of the queue into the caller's private queue using: | |
58 | * HTC_PACKET_ENQUEUE() */ | |
6ca0f664 | 59 | typedef void (*HTC_EP_SEND_PKT_COMP_MULTIPLE)(void *,struct htc_packet_queue *); |
30295c89 | 60 | /* per service connection pkt received */ |
c6528e2f | 61 | typedef void (*HTC_EP_RECV_PKT)(void *,struct htc_packet *); |
30295c89 | 62 | /* per service connection callback when a plurality of packets are received |
6ca0f664 | 63 | * The struct htc_packet_queue is a temporary queue object (e.g. freed on return from the callback) |
30295c89 VM |
64 | * to hold a list of recv packets. |
65 | * If the handler cannot fully traverse the packet queue before returning, it should | |
66 | * transfer the items of the queue into the caller's private queue using: | |
67 | * HTC_PACKET_ENQUEUE() */ | |
6ca0f664 | 68 | typedef void (*HTC_EP_RECV_PKT_MULTIPLE)(void *,struct htc_packet_queue *); |
30295c89 VM |
69 | |
70 | /* Optional per service connection receive buffer re-fill callback, | |
71 | * On some OSes (like Linux) packets are allocated from a global pool and indicated up | |
72 | * to the network stack. The driver never gets the packets back from the OS. For these OSes | |
73 | * a refill callback can be used to allocate and re-queue buffers into HTC. | |
74 | * | |
75 | * On other OSes, the network stack can call into the driver's OS-specifc "return_packet" handler and | |
76 | * the driver can re-queue these buffers into HTC. In this regard a refill callback is | |
77 | * unnecessary */ | |
78 | typedef void (*HTC_EP_RECV_REFILL)(void *, HTC_ENDPOINT_ID Endpoint); | |
79 | ||
80 | /* Optional per service connection receive buffer allocation callback. | |
81 | * On some systems packet buffers are an extremely limited resource. Rather than | |
82 | * queue largest-possible-sized buffers to HTC, some systems would rather | |
83 | * allocate a specific size as the packet is received. The trade off is | |
84 | * slightly more processing (callback invoked for each RX packet) | |
85 | * for the benefit of committing fewer buffer resources into HTC. | |
86 | * | |
87 | * The callback is provided the length of the pending packet to fetch. This includes the | |
88 | * HTC header length plus the length of payload. The callback can return a pointer to | |
89 | * the allocated HTC packet for immediate use. | |
90 | * | |
91 | * Alternatively a variant of this handler can be used to allocate large receive packets as needed. | |
92 | * For example an application can use the refill mechanism for normal packets and the recv-alloc mechanism to | |
93 | * handle the case where a large packet buffer is required. This can significantly reduce the | |
94 | * amount of "committed" memory used to receive packets. | |
95 | * | |
96 | * */ | |
c6528e2f | 97 | typedef struct htc_packet *(*HTC_EP_RECV_ALLOC)(void *, HTC_ENDPOINT_ID Endpoint, int Length); |
30295c89 VM |
98 | |
99 | typedef enum _HTC_SEND_FULL_ACTION { | |
100 | HTC_SEND_FULL_KEEP = 0, /* packet that overflowed should be kept in the queue */ | |
101 | HTC_SEND_FULL_DROP = 1, /* packet that overflowed should be dropped */ | |
102 | } HTC_SEND_FULL_ACTION; | |
103 | ||
104 | /* Optional per service connection callback when a send queue is full. This can occur if the | |
105 | * host continues queueing up TX packets faster than credits can arrive | |
106 | * To prevent the host (on some Oses like Linux) from continuously queueing packets | |
107 | * and consuming resources, this callback is provided so that that the host | |
108 | * can disable TX in the subsystem (i.e. network stack). | |
109 | * This callback is invoked for each packet that "overflows" the HTC queue. The callback can | |
110 | * determine whether the new packet that overflowed the queue can be kept (HTC_SEND_FULL_KEEP) or | |
111 | * dropped (HTC_SEND_FULL_DROP). If a packet is dropped, the EpTxComplete handler will be called | |
112 | * and the packet's status field will be set to A_NO_RESOURCE. | |
113 | * Other OSes require a "per-packet" indication for each completed TX packet, this | |
114 | * closed loop mechanism will prevent the network stack from overunning the NIC | |
115 | * The packet to keep or drop is passed for inspection to the registered handler the handler | |
116 | * must ONLY inspect the packet, it may not free or reclaim the packet. */ | |
c6528e2f | 117 | typedef HTC_SEND_FULL_ACTION (*HTC_EP_SEND_QUEUE_FULL)(void *, struct htc_packet *pPacket); |
30295c89 | 118 | |
80ab2899 | 119 | struct htc_ep_callbacks { |
30295c89 VM |
120 | void *pContext; /* context for each callback */ |
121 | HTC_EP_SEND_PKT_COMPLETE EpTxComplete; /* tx completion callback for connected endpoint */ | |
122 | HTC_EP_RECV_PKT EpRecv; /* receive callback for connected endpoint */ | |
123 | HTC_EP_RECV_REFILL EpRecvRefill; /* OPTIONAL receive re-fill callback for connected endpoint */ | |
124 | HTC_EP_SEND_QUEUE_FULL EpSendFull; /* OPTIONAL send full callback */ | |
125 | HTC_EP_RECV_ALLOC EpRecvAlloc; /* OPTIONAL recv allocation callback */ | |
126 | HTC_EP_RECV_ALLOC EpRecvAllocThresh; /* OPTIONAL recv allocation callback based on a threshold */ | |
127 | HTC_EP_SEND_PKT_COMP_MULTIPLE EpTxCompleteMultiple; /* OPTIONAL completion handler for multiple complete | |
128 | indications (EpTxComplete must be NULL) */ | |
129 | HTC_EP_RECV_PKT_MULTIPLE EpRecvPktMultiple; /* OPTIONAL completion handler for multiple | |
130 | recv packet indications (EpRecv must be NULL) */ | |
131 | int RecvAllocThreshold; /* if EpRecvAllocThresh is non-NULL, HTC will compare the | |
132 | threshold value to the current recv packet length and invoke | |
133 | the EpRecvAllocThresh callback to acquire a packet buffer */ | |
134 | int RecvRefillWaterMark; /* if a EpRecvRefill handler is provided, this value | |
135 | can be used to set a trigger refill callback | |
136 | when the recv queue drops below this value | |
137 | if set to 0, the refill is only called when packets | |
138 | are empty */ | |
80ab2899 | 139 | }; |
30295c89 VM |
140 | |
141 | /* service connection information */ | |
3d82b15e | 142 | struct htc_service_connect_req { |
30295c89 | 143 | HTC_SERVICE_ID ServiceID; /* service ID to connect to */ |
4853ac05 | 144 | u16 ConnectionFlags; /* connection flags, see htc protocol definition */ |
ab3655da JP |
145 | u8 *pMetaData; /* ptr to optional service-specific meta-data */ |
146 | u8 MetaDataLength; /* optional meta data length */ | |
80ab2899 | 147 | struct htc_ep_callbacks EpCallbacks; /* endpoint callbacks */ |
30295c89 | 148 | int MaxSendQueueDepth; /* maximum depth of any send queue */ |
e1ce2a3a | 149 | u32 LocalConnectionFlags; /* HTC flags for the host-side (local) connection */ |
30295c89 | 150 | unsigned int MaxSendMsgSize; /* override max message size in send direction */ |
3d82b15e | 151 | }; |
30295c89 VM |
152 | |
153 | #define HTC_LOCAL_CONN_FLAGS_ENABLE_SEND_BUNDLE_PADDING (1 << 0) /* enable send bundle padding for this endpoint */ | |
154 | ||
155 | /* service connection response information */ | |
cb3ea094 | 156 | struct htc_service_connect_resp { |
ab3655da JP |
157 | u8 *pMetaData; /* caller supplied buffer to optional meta-data */ |
158 | u8 BufferLength; /* length of caller supplied buffer */ | |
159 | u8 ActualLength; /* actual length of meta data */ | |
30295c89 VM |
160 | HTC_ENDPOINT_ID Endpoint; /* endpoint to communicate over */ |
161 | unsigned int MaxMsgLength; /* max length of all messages over this endpoint */ | |
ab3655da | 162 | u8 ConnectRespCode; /* connect response code from target */ |
cb3ea094 | 163 | }; |
30295c89 VM |
164 | |
165 | /* endpoint distribution structure */ | |
57c9d5b3 LR |
166 | struct htc_endpoint_credit_dist { |
167 | struct htc_endpoint_credit_dist *pNext; | |
168 | struct htc_endpoint_credit_dist *pPrev; | |
30295c89 VM |
169 | HTC_SERVICE_ID ServiceID; /* Service ID (set by HTC) */ |
170 | HTC_ENDPOINT_ID Endpoint; /* endpoint for this distribution struct (set by HTC) */ | |
e1ce2a3a | 171 | u32 DistFlags; /* distribution flags, distribution function can |
30295c89 VM |
172 | set default activity using SET_EP_ACTIVE() macro */ |
173 | int TxCreditsNorm; /* credits for normal operation, anything above this | |
174 | indicates the endpoint is over-subscribed, this field | |
175 | is only relevant to the credit distribution function */ | |
176 | int TxCreditsMin; /* floor for credit distribution, this field is | |
177 | only relevant to the credit distribution function */ | |
178 | int TxCreditsAssigned; /* number of credits assigned to this EP, this field | |
179 | is only relevant to the credit dist function */ | |
180 | int TxCredits; /* current credits available, this field is used by | |
181 | HTC to determine whether a message can be sent or | |
182 | must be queued */ | |
183 | int TxCreditsToDist; /* pending credits to distribute on this endpoint, this | |
184 | is set by HTC when credit reports arrive. | |
185 | The credit distribution functions sets this to zero | |
186 | when it distributes the credits */ | |
187 | int TxCreditsSeek; /* this is the number of credits that the current pending TX | |
188 | packet needs to transmit. This is set by HTC when | |
189 | and endpoint needs credits in order to transmit */ | |
190 | int TxCreditSize; /* size in bytes of each credit (set by HTC) */ | |
191 | int TxCreditsPerMaxMsg; /* credits required for a maximum sized messages (set by HTC) */ | |
192 | void *pHTCReserved; /* reserved for HTC use */ | |
193 | int TxQueueDepth; /* current depth of TX queue , i.e. messages waiting for credits | |
194 | This field is valid only when HTC_CREDIT_DIST_ACTIVITY_CHANGE | |
195 | or HTC_CREDIT_DIST_SEND_COMPLETE is indicated on an endpoint | |
196 | that has non-zero credits to recover | |
197 | */ | |
57c9d5b3 | 198 | }; |
30295c89 | 199 | |
e1ce2a3a | 200 | #define HTC_EP_ACTIVE ((u32) (1u << 31)) |
30295c89 VM |
201 | |
202 | /* macro to check if an endpoint has gone active, useful for credit | |
203 | * distributions */ | |
204 | #define IS_EP_ACTIVE(epDist) ((epDist)->DistFlags & HTC_EP_ACTIVE) | |
205 | #define SET_EP_ACTIVE(epDist) (epDist)->DistFlags |= HTC_EP_ACTIVE | |
206 | ||
207 | /* credit distibution code that is passed into the distrbution function, | |
208 | * there are mandatory and optional codes that must be handled */ | |
209 | typedef enum _HTC_CREDIT_DIST_REASON { | |
210 | HTC_CREDIT_DIST_SEND_COMPLETE = 0, /* credits available as a result of completed | |
211 | send operations (MANDATORY) resulting in credit reports */ | |
25985edc | 212 | HTC_CREDIT_DIST_ACTIVITY_CHANGE = 1, /* a change in endpoint activity occurred (OPTIONAL) */ |
30295c89 VM |
213 | HTC_CREDIT_DIST_SEEK_CREDITS, /* an endpoint needs to "seek" credits (OPTIONAL) */ |
214 | HTC_DUMP_CREDIT_STATE /* for debugging, dump any state information that is kept by | |
215 | the distribution function */ | |
216 | } HTC_CREDIT_DIST_REASON; | |
217 | ||
218 | typedef void (*HTC_CREDIT_DIST_CALLBACK)(void *Context, | |
57c9d5b3 | 219 | struct htc_endpoint_credit_dist *pEPList, |
30295c89 VM |
220 | HTC_CREDIT_DIST_REASON Reason); |
221 | ||
222 | typedef void (*HTC_CREDIT_INIT_CALLBACK)(void *Context, | |
57c9d5b3 | 223 | struct htc_endpoint_credit_dist *pEPList, |
30295c89 VM |
224 | int TotalCredits); |
225 | ||
226 | /* endpoint statistics action */ | |
227 | typedef enum _HTC_ENDPOINT_STAT_ACTION { | |
228 | HTC_EP_STAT_SAMPLE = 0, /* only read statistics */ | |
229 | HTC_EP_STAT_SAMPLE_AND_CLEAR = 1, /* sample and immediately clear statistics */ | |
230 | HTC_EP_STAT_CLEAR /* clear only */ | |
231 | } HTC_ENDPOINT_STAT_ACTION; | |
232 | ||
233 | /* endpoint statistics */ | |
84efc7ff | 234 | struct htc_endpoint_stats { |
e1ce2a3a | 235 | u32 TxCreditLowIndications; /* number of times the host set the credit-low flag in a send message on |
30295c89 | 236 | this endpoint */ |
e1ce2a3a JP |
237 | u32 TxIssued; /* running count of total TX packets issued */ |
238 | u32 TxPacketsBundled; /* running count of TX packets that were issued in bundles */ | |
239 | u32 TxBundles; /* running count of TX bundles that were issued */ | |
240 | u32 TxDropped; /* tx packets that were dropped */ | |
241 | u32 TxCreditRpts; /* running count of total credit reports received for this endpoint */ | |
242 | u32 TxCreditRptsFromRx; /* credit reports received from this endpoint's RX packets */ | |
243 | u32 TxCreditRptsFromOther; /* credit reports received from RX packets of other endpoints */ | |
244 | u32 TxCreditRptsFromEp0; /* credit reports received from endpoint 0 RX packets */ | |
245 | u32 TxCreditsFromRx; /* count of credits received via Rx packets on this endpoint */ | |
246 | u32 TxCreditsFromOther; /* count of credits received via another endpoint */ | |
247 | u32 TxCreditsFromEp0; /* count of credits received via another endpoint */ | |
248 | u32 TxCreditsConsummed; /* count of consummed credits */ | |
249 | u32 TxCreditsReturned; /* count of credits returned */ | |
250 | u32 RxReceived; /* count of RX packets received */ | |
251 | u32 RxLookAheads; /* count of lookahead records | |
30295c89 | 252 | found in messages received on this endpoint */ |
e1ce2a3a JP |
253 | u32 RxPacketsBundled; /* count of recv packets received in a bundle */ |
254 | u32 RxBundleLookAheads; /* count of number of bundled lookaheads */ | |
255 | u32 RxBundleIndFromHdr; /* count of the number of bundle indications from the HTC header */ | |
25985edc | 256 | u32 RxAllocThreshHit; /* count of the number of times the recv allocation threshold was hit */ |
e1ce2a3a | 257 | u32 RxAllocThreshBytes; /* total number of bytes */ |
84efc7ff | 258 | }; |
30295c89 VM |
259 | |
260 | /* ------ Function Prototypes ------ */ | |
261 | /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | |
262 | @desc: Create an instance of HTC over the underlying HIF device | |
263 | @function name: HTCCreate | |
264 | @input: HifDevice - hif device handle, | |
265 | pInfo - initialization information | |
266 | @output: | |
267 | @return: HTC_HANDLE on success, NULL on failure | |
268 | @notes: | |
269 | @example: | |
270 | @see also: HTCDestroy | |
271 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ | |
4f0cce96 | 272 | HTC_HANDLE HTCCreate(void *HifDevice, struct htc_init_info *pInfo); |
30295c89 VM |
273 | /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
274 | @desc: Get the underlying HIF device handle | |
275 | @function name: HTCGetHifDevice | |
276 | @input: HTCHandle - handle passed into the AddInstance callback | |
277 | @output: | |
278 | @return: opaque HIF device handle usable in HIF API calls. | |
279 | @notes: | |
280 | @example: | |
281 | @see also: | |
282 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ | |
283 | void *HTCGetHifDevice(HTC_HANDLE HTCHandle); | |
284 | /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | |
285 | @desc: Set credit distribution parameters | |
286 | @function name: HTCSetCreditDistribution | |
287 | @input: HTCHandle - HTC handle | |
288 | pCreditDistCont - caller supplied context to pass into distribution functions | |
289 | CreditDistFunc - Distribution function callback | |
290 | CreditDistInit - Credit Distribution initialization callback | |
291 | ServicePriorityOrder - Array containing list of service IDs, lowest index is highest | |
292 | priority | |
293 | ListLength - number of elements in ServicePriorityOrder | |
294 | @output: | |
295 | @return: | |
296 | @notes: The user can set a custom credit distribution function to handle special requirements | |
297 | for each endpoint. A default credit distribution routine can be used by setting | |
298 | CreditInitFunc to NULL. The default credit distribution is only provided for simple | |
299 | "fair" credit distribution without regard to any prioritization. | |
300 | ||
301 | @example: | |
302 | @see also: | |
303 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ | |
304 | void HTCSetCreditDistribution(HTC_HANDLE HTCHandle, | |
305 | void *pCreditDistContext, | |
306 | HTC_CREDIT_DIST_CALLBACK CreditDistFunc, | |
307 | HTC_CREDIT_INIT_CALLBACK CreditInitFunc, | |
308 | HTC_SERVICE_ID ServicePriorityOrder[], | |
309 | int ListLength); | |
310 | /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | |
311 | @desc: Wait for the target to indicate the HTC layer is ready | |
312 | @function name: HTCWaitTarget | |
313 | @input: HTCHandle - HTC handle | |
314 | @output: | |
315 | @return: | |
316 | @notes: This API blocks until the target responds with an HTC ready message. | |
317 | The caller should not connect services until the target has indicated it is | |
318 | ready. | |
319 | @example: | |
320 | @see also: HTCConnectService | |
321 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ | |
1f4c34bd | 322 | int HTCWaitTarget(HTC_HANDLE HTCHandle); |
30295c89 VM |
323 | /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
324 | @desc: Start target service communications | |
325 | @function name: HTCStart | |
326 | @input: HTCHandle - HTC handle | |
327 | @output: | |
328 | @return: | |
329 | @notes: This API indicates to the target that the service connection phase is complete | |
330 | and the target can freely start all connected services. This API should only be | |
331 | called AFTER all service connections have been made. TCStart will issue a | |
332 | SETUP_COMPLETE message to the target to indicate that all service connections | |
333 | have been made and the target can start communicating over the endpoints. | |
334 | @example: | |
335 | @see also: HTCConnectService | |
336 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ | |
1f4c34bd | 337 | int HTCStart(HTC_HANDLE HTCHandle); |
30295c89 VM |
338 | /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
339 | @desc: Add receive packet to HTC | |
340 | @function name: HTCAddReceivePkt | |
341 | @input: HTCHandle - HTC handle | |
342 | pPacket - HTC receive packet to add | |
343 | @output: | |
4f69cef0 | 344 | @return: 0 on success |
30295c89 VM |
345 | @notes: user must supply HTC packets for capturing incomming HTC frames. The caller |
346 | must initialize each HTC packet using the SET_HTC_PACKET_INFO_RX_REFILL() | |
347 | macro. | |
348 | @example: | |
349 | @see also: | |
350 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ | |
c6528e2f | 351 | int HTCAddReceivePkt(HTC_HANDLE HTCHandle, struct htc_packet *pPacket); |
30295c89 VM |
352 | /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
353 | @desc: Connect to an HTC service | |
354 | @function name: HTCConnectService | |
355 | @input: HTCHandle - HTC handle | |
356 | pReq - connection details | |
357 | @output: pResp - connection response | |
358 | @return: | |
359 | @notes: Service connections must be performed before HTCStart. User provides callback handlers | |
360 | for various endpoint events. | |
361 | @example: | |
362 | @see also: HTCStart | |
363 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ | |
1f4c34bd | 364 | int HTCConnectService(HTC_HANDLE HTCHandle, |
3d82b15e | 365 | struct htc_service_connect_req *pReq, |
cb3ea094 | 366 | struct htc_service_connect_resp *pResp); |
30295c89 VM |
367 | /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
368 | @desc: Send an HTC packet | |
369 | @function name: HTCSendPkt | |
370 | @input: HTCHandle - HTC handle | |
371 | pPacket - packet to send | |
372 | @output: | |
4f69cef0 | 373 | @return: 0 |
30295c89 VM |
374 | @notes: Caller must initialize packet using SET_HTC_PACKET_INFO_TX() macro. |
375 | This interface is fully asynchronous. On error, HTC SendPkt will | |
376 | call the registered Endpoint callback to cleanup the packet. | |
377 | @example: | |
378 | @see also: HTCFlushEndpoint | |
379 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ | |
c6528e2f | 380 | int HTCSendPkt(HTC_HANDLE HTCHandle, struct htc_packet *pPacket); |
30295c89 VM |
381 | /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
382 | @desc: Stop HTC service communications | |
383 | @function name: HTCStop | |
384 | @input: HTCHandle - HTC handle | |
385 | @output: | |
386 | @return: | |
387 | @notes: HTC communications is halted. All receive and pending TX packets will | |
388 | be flushed. | |
389 | @example: | |
390 | @see also: | |
391 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ | |
392 | void HTCStop(HTC_HANDLE HTCHandle); | |
393 | /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | |
25985edc | 394 | @desc: Destroy HTC service |
30295c89 VM |
395 | @function name: HTCDestroy |
396 | @input: HTCHandle | |
397 | @output: | |
398 | @return: | |
399 | @notes: This cleans up all resources allocated by HTCCreate(). | |
400 | @example: | |
401 | @see also: HTCCreate | |
402 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ | |
403 | void HTCDestroy(HTC_HANDLE HTCHandle); | |
404 | /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | |
405 | @desc: Flush pending TX packets | |
406 | @function name: HTCFlushEndpoint | |
407 | @input: HTCHandle - HTC handle | |
408 | Endpoint - Endpoint to flush | |
409 | Tag - flush tag | |
410 | @output: | |
411 | @return: | |
412 | @notes: The Tag parameter is used to selectively flush packets with matching tags. | |
413 | The value of 0 forces all packets to be flush regardless of tag. | |
414 | @example: | |
415 | @see also: HTCSendPkt | |
416 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ | |
417 | void HTCFlushEndpoint(HTC_HANDLE HTCHandle, HTC_ENDPOINT_ID Endpoint, HTC_TX_TAG Tag); | |
418 | /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | |
419 | @desc: Dump credit distribution state | |
420 | @function name: HTCDumpCreditStates | |
421 | @input: HTCHandle - HTC handle | |
422 | @output: | |
423 | @return: | |
424 | @notes: This dumps all credit distribution information to the debugger | |
425 | @example: | |
426 | @see also: | |
427 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ | |
428 | void HTCDumpCreditStates(HTC_HANDLE HTCHandle); | |
429 | /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | |
430 | @desc: Indicate a traffic activity change on an endpoint | |
431 | @function name: HTCIndicateActivityChange | |
432 | @input: HTCHandle - HTC handle | |
433 | Endpoint - endpoint in which activity has changed | |
1071a134 | 434 | Active - true if active, false if it has become inactive |
30295c89 VM |
435 | @output: |
436 | @return: | |
437 | @notes: This triggers the registered credit distribution function to | |
438 | re-adjust credits for active/inactive endpoints. | |
439 | @example: | |
440 | @see also: | |
441 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ | |
442 | void HTCIndicateActivityChange(HTC_HANDLE HTCHandle, | |
443 | HTC_ENDPOINT_ID Endpoint, | |
1071a134 | 444 | bool Active); |
30295c89 VM |
445 | |
446 | /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | |
447 | @desc: Get endpoint statistics | |
448 | @function name: HTCGetEndpointStatistics | |
449 | @input: HTCHandle - HTC handle | |
450 | Endpoint - Endpoint identifier | |
451 | Action - action to take with statistics | |
452 | @output: | |
453 | pStats - statistics that were sampled (can be NULL if Action is HTC_EP_STAT_CLEAR) | |
454 | ||
1071a134 | 455 | @return: true if statistics profiling is enabled, otherwise false. |
30295c89 | 456 | |
1071a134 | 457 | @notes: Statistics is a compile-time option and this function may return false |
30295c89 VM |
458 | if HTC is not compiled with profiling. |
459 | ||
460 | The caller can specify the statistic "action" to take when sampling | |
461 | the statistics. This includes: | |
462 | ||
463 | HTC_EP_STAT_SAMPLE: The pStats structure is filled with the current values. | |
464 | HTC_EP_STAT_SAMPLE_AND_CLEAR: The structure is filled and the current statistics | |
465 | are cleared. | |
466 | HTC_EP_STAT_CLEA : the statistics are cleared, the called can pass a NULL value for | |
467 | pStats | |
468 | ||
469 | @example: | |
470 | @see also: | |
471 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ | |
1071a134 | 472 | bool HTCGetEndpointStatistics(HTC_HANDLE HTCHandle, |
30295c89 VM |
473 | HTC_ENDPOINT_ID Endpoint, |
474 | HTC_ENDPOINT_STAT_ACTION Action, | |
84efc7ff | 475 | struct htc_endpoint_stats *pStats); |
30295c89 VM |
476 | |
477 | /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | |
478 | @desc: Unblock HTC message reception | |
479 | @function name: HTCUnblockRecv | |
480 | @input: HTCHandle - HTC handle | |
481 | @output: | |
482 | @return: | |
483 | @notes: | |
484 | HTC will block the receiver if the EpRecvAlloc callback fails to provide a packet. | |
485 | The caller can use this API to indicate to HTC when resources (buffers) are available | |
486 | such that the receiver can be unblocked and HTC may re-attempt fetching the pending message. | |
487 | ||
488 | This API is not required if the user uses the EpRecvRefill callback or uses the HTCAddReceivePacket() | |
489 | API to recycle or provide receive packets to HTC. | |
490 | ||
491 | @example: | |
492 | @see also: | |
493 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ | |
494 | void HTCUnblockRecv(HTC_HANDLE HTCHandle); | |
495 | ||
496 | /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | |
497 | @desc: send a series of HTC packets | |
498 | @function name: HTCSendPktsMultiple | |
499 | @input: HTCHandle - HTC handle | |
500 | pPktQueue - local queue holding packets to send | |
501 | @output: | |
4f69cef0 | 502 | @return: 0 |
30295c89 VM |
503 | @notes: Caller must initialize each packet using SET_HTC_PACKET_INFO_TX() macro. |
504 | The queue must only contain packets directed at the same endpoint. | |
6ca0f664 | 505 | Caller supplies a pointer to an struct htc_packet_queue structure holding the TX packets in FIFO order. |
30295c89 VM |
506 | This API will remove the packets from the pkt queue and place them into the HTC Tx Queue |
507 | and bundle messages where possible. | |
508 | The caller may allocate the pkt queue on the stack to hold the packets. | |
509 | This interface is fully asynchronous. On error, HTCSendPkts will | |
510 | call the registered Endpoint callback to cleanup the packet. | |
511 | @example: | |
512 | @see also: HTCFlushEndpoint | |
513 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ | |
6ca0f664 | 514 | int HTCSendPktsMultiple(HTC_HANDLE HTCHandle, struct htc_packet_queue *pPktQueue); |
30295c89 VM |
515 | |
516 | /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | |
517 | @desc: Add multiple receive packets to HTC | |
518 | @function name: HTCAddReceivePktMultiple | |
519 | @input: HTCHandle - HTC handle | |
520 | pPktQueue - HTC receive packet queue holding packets to add | |
521 | @output: | |
4f69cef0 | 522 | @return: 0 on success |
30295c89 VM |
523 | @notes: user must supply HTC packets for capturing incomming HTC frames. The caller |
524 | must initialize each HTC packet using the SET_HTC_PACKET_INFO_RX_REFILL() | |
525 | macro. The queue must only contain recv packets for the same endpoint. | |
6ca0f664 | 526 | Caller supplies a pointer to an struct htc_packet_queue structure holding the recv packet. |
30295c89 VM |
527 | This API will remove the packets from the pkt queue and place them into internal |
528 | recv packet list. | |
529 | The caller may allocate the pkt queue on the stack to hold the packets. | |
530 | @example: | |
531 | @see also: | |
532 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ | |
6ca0f664 | 533 | int HTCAddReceivePktMultiple(HTC_HANDLE HTCHandle, struct htc_packet_queue *pPktQueue); |
30295c89 VM |
534 | |
535 | /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | |
536 | @desc: Check if an endpoint is marked active | |
537 | @function name: HTCIsEndpointActive | |
538 | @input: HTCHandle - HTC handle | |
539 | Endpoint - endpoint to check for active state | |
540 | @output: | |
1071a134 | 541 | @return: returns true if Endpoint is Active |
30295c89 VM |
542 | @notes: |
543 | @example: | |
544 | @see also: | |
545 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ | |
1071a134 | 546 | bool HTCIsEndpointActive(HTC_HANDLE HTCHandle, |
30295c89 VM |
547 | HTC_ENDPOINT_ID Endpoint); |
548 | ||
549 | ||
550 | /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | |
551 | @desc: Get the number of recv buffers currently queued into an HTC endpoint | |
552 | @function name: HTCGetNumRecvBuffers | |
553 | @input: HTCHandle - HTC handle | |
554 | Endpoint - endpoint to check | |
555 | @output: | |
556 | @return: returns number of buffers in queue | |
557 | @notes: | |
558 | @example: | |
559 | @see also: | |
560 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ | |
561 | int HTCGetNumRecvBuffers(HTC_HANDLE HTCHandle, | |
562 | HTC_ENDPOINT_ID Endpoint); | |
563 | ||
564 | /* internally used functions for testing... */ | |
565 | void HTCEnableRecv(HTC_HANDLE HTCHandle); | |
566 | void HTCDisableRecv(HTC_HANDLE HTCHandle); | |
1f4c34bd | 567 | int HTCWaitForPendingRecv(HTC_HANDLE HTCHandle, |
e1ce2a3a | 568 | u32 TimeoutInMs, |
1071a134 | 569 | bool *pbIsRecvPending); |
30295c89 VM |
570 | |
571 | #ifdef __cplusplus | |
572 | } | |
573 | #endif | |
574 | ||
575 | #endif /* _HTC_API_H_ */ |