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