1 //------------------------------------------------------------------------------
2 // <copyright file="htc_api.h" company="Atheros">
3 // Copyright (c) 2007-2010 Atheros Corporation. All rights reserved.
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.
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.
19 //------------------------------------------------------------------------------
20 //==============================================================================
21 // Author(s): ="Atheros"
22 //==============================================================================
26 #include "htc_packet.h"
28 #include <htc_services.h>
32 #endif /* __cplusplus */
36 // TODO -remove me, but we have to fix BMI first
37 #define HTC_MAILBOX_NUM_MAX 4
39 /* this is the amount of header room required by users of HTC */
40 #define HTC_HEADER_LEN HTC_HDR_LENGTH
42 typedef void *HTC_HANDLE;
44 typedef A_UINT16 HTC_SERVICE_ID;
46 typedef struct _HTC_INIT_INFO {
47 void *pContext; /* context for target failure notification */
48 void (*TargetFailure)(void *Instance, int Status);
51 /* per service connection send completion */
52 typedef void (*HTC_EP_SEND_PKT_COMPLETE)(void *,HTC_PACKET *);
53 /* per service connection callback when a plurality of packets have been sent
54 * The HTC_PACKET_QUEUE is a temporary queue object (e.g. freed on return from the callback)
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() */
59 typedef void (*HTC_EP_SEND_PKT_COMP_MULTIPLE)(void *,HTC_PACKET_QUEUE *);
60 /* per service connection pkt received */
61 typedef void (*HTC_EP_RECV_PKT)(void *,HTC_PACKET *);
62 /* per service connection callback when a plurality of packets are received
63 * The HTC_PACKET_QUEUE is a temporary queue object (e.g. freed on return from the callback)
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() */
68 typedef void (*HTC_EP_RECV_PKT_MULTIPLE)(void *,HTC_PACKET_QUEUE *);
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.
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
78 typedef void (*HTC_EP_RECV_REFILL)(void *, HTC_ENDPOINT_ID Endpoint);
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.
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.
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.
97 typedef HTC_PACKET *(*HTC_EP_RECV_ALLOC)(void *, HTC_ENDPOINT_ID Endpoint, int Length);
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;
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. */
117 typedef HTC_SEND_FULL_ACTION (*HTC_EP_SEND_QUEUE_FULL)(void *, HTC_PACKET *pPacket);
119 typedef struct _HTC_EP_CALLBACKS {
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
141 /* service connection information */
142 typedef struct _HTC_SERVICE_CONNECT_REQ {
143 HTC_SERVICE_ID ServiceID; /* service ID to connect to */
144 A_UINT16 ConnectionFlags; /* connection flags, see htc protocol definition */
145 u8 *pMetaData; /* ptr to optional service-specific meta-data */
146 u8 MetaDataLength; /* optional meta data length */
147 HTC_EP_CALLBACKS EpCallbacks; /* endpoint callbacks */
148 int MaxSendQueueDepth; /* maximum depth of any send queue */
149 A_UINT32 LocalConnectionFlags; /* HTC flags for the host-side (local) connection */
150 unsigned int MaxSendMsgSize; /* override max message size in send direction */
151 } HTC_SERVICE_CONNECT_REQ;
153 #define HTC_LOCAL_CONN_FLAGS_ENABLE_SEND_BUNDLE_PADDING (1 << 0) /* enable send bundle padding for this endpoint */
155 /* service connection response information */
156 typedef struct _HTC_SERVICE_CONNECT_RESP {
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 */
160 HTC_ENDPOINT_ID Endpoint; /* endpoint to communicate over */
161 unsigned int MaxMsgLength; /* max length of all messages over this endpoint */
162 u8 ConnectRespCode; /* connect response code from target */
163 } HTC_SERVICE_CONNECT_RESP;
165 /* endpoint distribution structure */
166 typedef struct _HTC_ENDPOINT_CREDIT_DIST {
167 struct _HTC_ENDPOINT_CREDIT_DIST *pNext;
168 struct _HTC_ENDPOINT_CREDIT_DIST *pPrev;
169 HTC_SERVICE_ID ServiceID; /* Service ID (set by HTC) */
170 HTC_ENDPOINT_ID Endpoint; /* endpoint for this distribution struct (set by HTC) */
171 A_UINT32 DistFlags; /* distribution flags, distribution function can
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
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
198 } HTC_ENDPOINT_CREDIT_DIST;
200 #define HTC_EP_ACTIVE ((A_UINT32) (1u << 31))
202 /* macro to check if an endpoint has gone active, useful for credit
204 #define IS_EP_ACTIVE(epDist) ((epDist)->DistFlags & HTC_EP_ACTIVE)
205 #define SET_EP_ACTIVE(epDist) (epDist)->DistFlags |= HTC_EP_ACTIVE
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 */
212 HTC_CREDIT_DIST_ACTIVITY_CHANGE = 1, /* a change in endpoint activity occured (OPTIONAL) */
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;
218 typedef void (*HTC_CREDIT_DIST_CALLBACK)(void *Context,
219 HTC_ENDPOINT_CREDIT_DIST *pEPList,
220 HTC_CREDIT_DIST_REASON Reason);
222 typedef void (*HTC_CREDIT_INIT_CALLBACK)(void *Context,
223 HTC_ENDPOINT_CREDIT_DIST *pEPList,
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;
233 /* endpoint statistics */
234 typedef struct _HTC_ENDPOINT_STATS {
235 A_UINT32 TxCreditLowIndications; /* number of times the host set the credit-low flag in a send message on
237 A_UINT32 TxIssued; /* running count of total TX packets issued */
238 A_UINT32 TxPacketsBundled; /* running count of TX packets that were issued in bundles */
239 A_UINT32 TxBundles; /* running count of TX bundles that were issued */
240 A_UINT32 TxDropped; /* tx packets that were dropped */
241 A_UINT32 TxCreditRpts; /* running count of total credit reports received for this endpoint */
242 A_UINT32 TxCreditRptsFromRx; /* credit reports received from this endpoint's RX packets */
243 A_UINT32 TxCreditRptsFromOther; /* credit reports received from RX packets of other endpoints */
244 A_UINT32 TxCreditRptsFromEp0; /* credit reports received from endpoint 0 RX packets */
245 A_UINT32 TxCreditsFromRx; /* count of credits received via Rx packets on this endpoint */
246 A_UINT32 TxCreditsFromOther; /* count of credits received via another endpoint */
247 A_UINT32 TxCreditsFromEp0; /* count of credits received via another endpoint */
248 A_UINT32 TxCreditsConsummed; /* count of consummed credits */
249 A_UINT32 TxCreditsReturned; /* count of credits returned */
250 A_UINT32 RxReceived; /* count of RX packets received */
251 A_UINT32 RxLookAheads; /* count of lookahead records
252 found in messages received on this endpoint */
253 A_UINT32 RxPacketsBundled; /* count of recv packets received in a bundle */
254 A_UINT32 RxBundleLookAheads; /* count of number of bundled lookaheads */
255 A_UINT32 RxBundleIndFromHdr; /* count of the number of bundle indications from the HTC header */
256 A_UINT32 RxAllocThreshHit; /* count of the number of times the recv allocation threshhold was hit */
257 A_UINT32 RxAllocThreshBytes; /* total number of bytes */
258 } HTC_ENDPOINT_STATS;
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
267 @return: HTC_HANDLE on success, NULL on failure
270 @see also: HTCDestroy
271 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
272 HTC_HANDLE HTCCreate(void *HifDevice, HTC_INIT_INFO *pInfo);
273 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
274 @desc: Get the underlying HIF device handle
275 @function name: HTCGetHifDevice
276 @input: HTCHandle - handle passed into the AddInstance callback
278 @return: opaque HIF device handle usable in HIF API calls.
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
293 ListLength - number of elements in ServicePriorityOrder
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.
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[],
310 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
311 @desc: Wait for the target to indicate the HTC layer is ready
312 @function name: HTCWaitTarget
313 @input: HTCHandle - HTC handle
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
320 @see also: HTCConnectService
321 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
322 int HTCWaitTarget(HTC_HANDLE HTCHandle);
323 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
324 @desc: Start target service communications
325 @function name: HTCStart
326 @input: HTCHandle - HTC handle
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.
335 @see also: HTCConnectService
336 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
337 int HTCStart(HTC_HANDLE HTCHandle);
338 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
339 @desc: Add receive packet to HTC
340 @function name: HTCAddReceivePkt
341 @input: HTCHandle - HTC handle
342 pPacket - HTC receive packet to add
344 @return: A_OK on success
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()
350 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
351 int HTCAddReceivePkt(HTC_HANDLE HTCHandle, HTC_PACKET *pPacket);
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
359 @notes: Service connections must be performed before HTCStart. User provides callback handlers
360 for various endpoint events.
363 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
364 int HTCConnectService(HTC_HANDLE HTCHandle,
365 HTC_SERVICE_CONNECT_REQ *pReq,
366 HTC_SERVICE_CONNECT_RESP *pResp);
367 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
368 @desc: Send an HTC packet
369 @function name: HTCSendPkt
370 @input: HTCHandle - HTC handle
371 pPacket - packet to send
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.
378 @see also: HTCFlushEndpoint
379 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
380 int HTCSendPkt(HTC_HANDLE HTCHandle, HTC_PACKET *pPacket);
381 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
382 @desc: Stop HTC service communications
383 @function name: HTCStop
384 @input: HTCHandle - HTC handle
387 @notes: HTC communications is halted. All receive and pending TX packets will
391 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
392 void HTCStop(HTC_HANDLE HTCHandle);
393 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
394 @desc: Destory HTC service
395 @function name: HTCDestroy
399 @notes: This cleans up all resources allocated by 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
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.
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
424 @notes: This dumps all credit distribution information to the debugger
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
434 Active - true if active, false if it has become inactive
437 @notes: This triggers the registered credit distribution function to
438 re-adjust credits for active/inactive endpoints.
441 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
442 void HTCIndicateActivityChange(HTC_HANDLE HTCHandle,
443 HTC_ENDPOINT_ID Endpoint,
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
453 pStats - statistics that were sampled (can be NULL if Action is HTC_EP_STAT_CLEAR)
455 @return: true if statistics profiling is enabled, otherwise false.
457 @notes: Statistics is a compile-time option and this function may return false
458 if HTC is not compiled with profiling.
460 The caller can specify the statistic "action" to take when sampling
461 the statistics. This includes:
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
466 HTC_EP_STAT_CLEA : the statistics are cleared, the called can pass a NULL value for
471 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
472 bool HTCGetEndpointStatistics(HTC_HANDLE HTCHandle,
473 HTC_ENDPOINT_ID Endpoint,
474 HTC_ENDPOINT_STAT_ACTION Action,
475 HTC_ENDPOINT_STATS *pStats);
477 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
478 @desc: Unblock HTC message reception
479 @function name: HTCUnblockRecv
480 @input: HTCHandle - HTC handle
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.
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.
493 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
494 void HTCUnblockRecv(HTC_HANDLE HTCHandle);
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
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.
505 Caller supplies a pointer to an HTC_PACKET_QUEUE structure holding the TX packets in FIFO order.
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.
512 @see also: HTCFlushEndpoint
513 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
514 int HTCSendPktsMultiple(HTC_HANDLE HTCHandle, HTC_PACKET_QUEUE *pPktQueue);
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
522 @return: A_OK on success
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.
526 Caller supplies a pointer to an HTC_PACKET_QUEUE structure holding the recv packet.
527 This API will remove the packets from the pkt queue and place them into internal
529 The caller may allocate the pkt queue on the stack to hold the packets.
532 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
533 int HTCAddReceivePktMultiple(HTC_HANDLE HTCHandle, HTC_PACKET_QUEUE *pPktQueue);
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
541 @return: returns true if Endpoint is Active
545 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
546 bool HTCIsEndpointActive(HTC_HANDLE HTCHandle,
547 HTC_ENDPOINT_ID Endpoint);
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
556 @return: returns number of buffers in queue
560 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
561 int HTCGetNumRecvBuffers(HTC_HANDLE HTCHandle,
562 HTC_ENDPOINT_ID Endpoint);
564 /* internally used functions for testing... */
565 void HTCEnableRecv(HTC_HANDLE HTCHandle);
566 void HTCDisableRecv(HTC_HANDLE HTCHandle);
567 int HTCWaitForPendingRecv(HTC_HANDLE HTCHandle,
568 A_UINT32 TimeoutInMs,
569 bool *pbIsRecvPending);
575 #endif /* _HTC_API_H_ */