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 44 typedef u16 HTC_SERVICE_ID; 45 46 struct htc_init_info { 47 void *pContext; /* context for target failure notification */ 48 void (*TargetFailure)(void *Instance, int Status); 49 }; 50 51 /* per service connection send completion */ 52 typedef void (*HTC_EP_SEND_PKT_COMPLETE)(void *,struct htc_packet *); 53 /* per service connection callback when a plurality of packets have been sent 54 * The struct 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 *,struct htc_packet_queue *); 60 /* per service connection pkt received */ 61 typedef void (*HTC_EP_RECV_PKT)(void *,struct htc_packet *); 62 /* per service connection callback when a plurality of packets are received 63 * The struct 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 *,struct htc_packet_queue *); 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 * */ 97 typedef struct htc_packet *(*HTC_EP_RECV_ALLOC)(void *, HTC_ENDPOINT_ID Endpoint, int Length); 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. */ 117 typedef HTC_SEND_FULL_ACTION (*HTC_EP_SEND_QUEUE_FULL)(void *, struct htc_packet *pPacket); 118 119 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 138 are empty */ 139 }; 140 141 /* service connection information */ 142 struct htc_service_connect_req { 143 HTC_SERVICE_ID ServiceID; /* service ID to connect to */ 144 u16 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 struct htc_ep_callbacks EpCallbacks; /* endpoint callbacks */ 148 int MaxSendQueueDepth; /* maximum depth of any send queue */ 149 u32 LocalConnectionFlags; /* HTC flags for the host-side (local) connection */ 150 unsigned int MaxSendMsgSize; /* override max message size in send direction */ 151 }; 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 */ 156 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 }; 164 165 /* endpoint distribution structure */ 166 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 u32 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 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 */ 198 }; 199 200 #define HTC_EP_ACTIVE ((u32) (1u << 31)) 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 */ 212 HTC_CREDIT_DIST_ACTIVITY_CHANGE = 1, /* a change in endpoint activity occurred (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; 217 218 typedef void (*HTC_CREDIT_DIST_CALLBACK)(void *Context, 219 struct htc_endpoint_credit_dist *pEPList, 220 HTC_CREDIT_DIST_REASON Reason); 221 222 typedef void (*HTC_CREDIT_INIT_CALLBACK)(void *Context, 223 struct htc_endpoint_credit_dist *pEPList, 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 */ 234 struct htc_endpoint_stats { 235 u32 TxCreditLowIndications; /* number of times the host set the credit-low flag in a send message on 236 this endpoint */ 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 252 found in messages received on this endpoint */ 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 */ 256 u32 RxAllocThreshHit; /* count of the number of times the recv allocation threshold was hit */ 257 u32 RxAllocThreshBytes; /* total number of bytes */ 258 }; 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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ 272 HTC_HANDLE HTCCreate(void *HifDevice, struct 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 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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ 322 int HTCWaitTarget(HTC_HANDLE HTCHandle); 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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ 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 343 @output: 344 @return: 0 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() 347 macro. 348 @example: 349 @see also: 350 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ 351 int HTCAddReceivePkt(HTC_HANDLE HTCHandle, struct 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 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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ 364 int HTCConnectService(HTC_HANDLE HTCHandle, 365 struct htc_service_connect_req *pReq, 366 struct 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 372 @output: 373 @return: 0 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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ 380 int HTCSendPkt(HTC_HANDLE HTCHandle, struct htc_packet *pPacket); 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 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 394 @desc: Destroy HTC service 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 434 Active - true if active, false if it has become inactive 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, 444 bool Active); 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 455 @return: true if statistics profiling is enabled, otherwise false. 456 457 @notes: Statistics is a compile-time option and this function may return false 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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ 472 bool HTCGetEndpointStatistics(HTC_HANDLE HTCHandle, 473 HTC_ENDPOINT_ID Endpoint, 474 HTC_ENDPOINT_STAT_ACTION Action, 475 struct htc_endpoint_stats *pStats); 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: 502 @return: 0 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 struct 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. 511 @example: 512 @see also: HTCFlushEndpoint 513 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ 514 int HTCSendPktsMultiple(HTC_HANDLE HTCHandle, struct htc_packet_queue *pPktQueue); 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: 522 @return: 0 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 struct htc_packet_queue structure holding the recv packet. 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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ 533 int HTCAddReceivePktMultiple(HTC_HANDLE HTCHandle, struct htc_packet_queue *pPktQueue); 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: 541 @return: returns true if Endpoint is Active 542 @notes: 543 @example: 544 @see also: 545 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ 546 bool HTCIsEndpointActive(HTC_HANDLE HTCHandle, 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); 567 int HTCWaitForPendingRecv(HTC_HANDLE HTCHandle, 568 u32 TimeoutInMs, 569 bool *pbIsRecvPending); 570 571 #ifdef __cplusplus 572 } 573 #endif 574 575 #endif /* _HTC_API_H_ */ 576