drivers/staging/ath6kl/include/htc_api.h

   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 A_UINT16 HTC_SERVICE_ID;
  45
  46 typedef struct _HTC_INIT_INFO {
  47     void   *pContext;           /* context for target failure notification */
  48     void   (*TargetFailure)(void *Instance, int Status);
  49 } HTC_INIT_INFO;
  50
  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 *);
  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 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 *, HTC_PACKET *pPacket);
 118
 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
 138                                                        are empty */
 139 } HTC_EP_CALLBACKS;
 140
 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     A_UINT8         *pMetaData;                 /* ptr to optional service-specific meta-data */
 146     A_UINT8          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;
 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 typedef struct _HTC_SERVICE_CONNECT_RESP {
 157     A_UINT8         *pMetaData;         /* caller supplied buffer to optional meta-data */
 158     A_UINT8         BufferLength;       /* length of caller supplied buffer */
 159     A_UINT8         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     A_UINT8         ConnectRespCode;    /* connect response code from target */
 163 } HTC_SERVICE_CONNECT_RESP;
 164
 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
 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 } HTC_ENDPOINT_CREDIT_DIST;
 199
 200 #define HTC_EP_ACTIVE                            ((A_UINT32) (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 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;
 217
 218 typedef void (*HTC_CREDIT_DIST_CALLBACK)(void                     *Context,
 219                                          HTC_ENDPOINT_CREDIT_DIST *pEPList,
 220                                          HTC_CREDIT_DIST_REASON   Reason);
 221
 222 typedef void (*HTC_CREDIT_INIT_CALLBACK)(void *Context,
 223                                          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 typedef struct _HTC_ENDPOINT_STATS {
 235     A_UINT32  TxCreditLowIndications;  /* number of times the host set the credit-low flag in a send message on
 236                                         this endpoint */
 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;
 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, 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: 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()
 347            macro.
 348   @example:
 349   @see also:
 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
 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                               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
 372   @output:
 373   @return: A_OK
 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, 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: Destory 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                                       A_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 A_BOOL       HTCGetEndpointStatistics(HTC_HANDLE               HTCHandle,
 473                                       HTC_ENDPOINT_ID          Endpoint,
 474                                       HTC_ENDPOINT_STAT_ACTION Action,
 475                                       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: A_OK
 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.
 511   @example:
 512   @see also: HTCFlushEndpoint
 513 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
 514 int    HTCSendPktsMultiple(HTC_HANDLE HTCHandle, 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: 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
 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, 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 A_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                                A_UINT32     TimeoutInMs,
 569                                A_BOOL      *pbIsRecvPending);
 570
 571 #ifdef __cplusplus
 572 }
 573 #endif
 574
 575 #endif /* _HTC_API_H_ */