when changing the mac address of a bridge interface, keep member interface addresses...
[openwrt.git] / target / linux / s3c24xx / files-2.6.30 / drivers / ar6000 / include / htc_api.h
1 /*
2 *
3 * Copyright (c) 2007 Atheros Communications Inc.
4 * All rights reserved.
5 *
6 *
7 * This program is free software; you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License version 2 as
9 * published by the Free Software Foundation;
10 *
11 * Software distributed under the License is distributed on an "AS
12 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
13 * implied. See the License for the specific language governing
14 * rights and limitations under the License.
15 *
16 *
17 *
18 */
19
20 #ifndef _HTC_API_H_
21 #define _HTC_API_H_
22
23 #include <htc.h>
24 #include <htc_services.h>
25 #include "htc_packet.h"
26
27 #ifdef __cplusplus
28 extern "C" {
29 #endif /* __cplusplus */
30
31 /* TODO.. for BMI */
32 #define ENDPOINT1 0
33 // TODO -remove me, but we have to fix BMI first
34 #define HTC_MAILBOX_NUM_MAX 4
35
36
37 /* ------ Endpoint IDS ------ */
38 typedef enum
39 {
40 ENDPOINT_UNUSED = -1,
41 ENDPOINT_0 = 0,
42 ENDPOINT_1 = 1,
43 ENDPOINT_2 = 2,
44 ENDPOINT_3,
45 ENDPOINT_4,
46 ENDPOINT_5,
47 ENDPOINT_6,
48 ENDPOINT_7,
49 ENDPOINT_8,
50 ENDPOINT_MAX,
51 } HTC_ENDPOINT_ID;
52
53 /* this is the amount of header room required by users of HTC */
54 #define HTC_HEADER_LEN HTC_HDR_LENGTH
55
56 typedef void *HTC_HANDLE;
57
58 typedef A_UINT16 HTC_SERVICE_ID;
59
60 typedef struct _HTC_INIT_INFO {
61 void (*AddInstance)(HTC_HANDLE);
62 void (*DeleteInstance)(void *Instance);
63 void (*TargetFailure)(void *Instance, A_STATUS Status);
64 } HTC_INIT_INFO;
65
66 /* per service connection send completion */
67 typedef void (*HTC_EP_SEND_PKT_COMPLETE)(void *,HTC_PACKET *);
68 /* per service connection pkt received */
69 typedef void (*HTC_EP_RECV_PKT)(void *,HTC_PACKET *);
70
71 /* Optional per service connection receive buffer re-fill callback,
72 * On some OSes (like Linux) packets are allocated from a global pool and indicated up
73 * to the network stack. The driver never gets the packets back from the OS. For these OSes
74 * a refill callback can be used to allocate and re-queue buffers into HTC.
75 *
76 * On other OSes, the network stack can call into the driver's OS-specifc "return_packet" handler and
77 * the driver can re-queue these buffers into HTC. In this regard a refill callback is
78 * unnecessary */
79 typedef void (*HTC_EP_RECV_REFILL)(void *, HTC_ENDPOINT_ID Endpoint);
80
81 /* Optional per service connection callback when a send queue is full. This can occur if the
82 * host continues queueing up TX packets faster than credits can arrive
83 * To prevent the host (on some Oses like Linux) from continuously queueing packets
84 * and consuming resources, this callback is provided so that that the host
85 * can disable TX in the subsystem (i.e. network stack)
86 * Other OSes require a "per-packet" indication_RAW_STREAM_NUM_MAX for each completed TX packet, this
87 * closed loop mechanism will prevent the network stack from overunning the NIC */
88 typedef void (*HTC_EP_SEND_QUEUE_FULL)(void *, HTC_ENDPOINT_ID Endpoint);
89 /* Optional per service connection callback when a send queue is available for receive new packet. */
90 typedef void (*HTC_EP_SEND_QUEUE_AVAIL)(void *, HTC_ENDPOINT_ID Endpoint);
91
92 typedef struct _HTC_EP_CALLBACKS {
93 void *pContext; /* context for each callback */
94 HTC_EP_SEND_PKT_COMPLETE EpTxComplete; /* tx completion callback for connected endpoint */
95 HTC_EP_RECV_PKT EpRecv; /* receive callback for connected endpoint */
96 HTC_EP_RECV_REFILL EpRecvRefill; /* OPTIONAL receive re-fill callback for connected endpoint */
97 HTC_EP_SEND_QUEUE_FULL EpSendFull; /* OPTIONAL send full callback */
98 HTC_EP_SEND_QUEUE_AVAIL EpSendAvail; /* OPTIONAL send available callback */
99 } HTC_EP_CALLBACKS;
100
101 /* service connection information */
102 typedef struct _HTC_SERVICE_CONNECT_REQ {
103 HTC_SERVICE_ID ServiceID; /* service ID to connect to */
104 A_UINT16 ConnectionFlags; /* connection flags, see htc protocol definition */
105 A_UINT8 *pMetaData; /* ptr to optional service-specific meta-data */
106 A_UINT8 MetaDataLength; /* optional meta data length */
107 HTC_EP_CALLBACKS EpCallbacks; /* endpoint callbacks */
108 int MaxSendQueueDepth; /* maximum depth of any send queue */
109 } HTC_SERVICE_CONNECT_REQ;
110
111 /* service connection response information */
112 typedef struct _HTC_SERVICE_CONNECT_RESP {
113 A_UINT8 *pMetaData; /* caller supplied buffer to optional meta-data */
114 A_UINT8 BufferLength; /* length of caller supplied buffer */
115 A_UINT8 ActualLength; /* actual length of meta data */
116 HTC_ENDPOINT_ID Endpoint; /* endpoint to communicate over */
117 int MaxMsgLength; /* max length of all messages over this endpoint */
118 A_UINT8 ConnectRespCode; /* connect response code from target */
119 } HTC_SERVICE_CONNECT_RESP;
120
121 /* endpoint distribution structure */
122 typedef struct _HTC_ENDPOINT_CREDIT_DIST {
123 struct _HTC_ENDPOINT_CREDIT_DIST *pNext;
124 struct _HTC_ENDPOINT_CREDIT_DIST *pPrev;
125 HTC_SERVICE_ID ServiceID; /* Service ID (set by HTC) */
126 HTC_ENDPOINT_ID Endpoint; /* endpoint for this distribution struct (set by HTC) */
127 A_UINT32 DistFlags; /* distribution flags, distribution function can
128 set default activity using SET_EP_ACTIVE() macro */
129 int TxCreditsNorm; /* credits for normal operation, anything above this
130 indicates the endpoint is over-subscribed, this field
131 is only relevant to the credit distribution function */
132 int TxCreditsMin; /* floor for credit distribution, this field is
133 only relevant to the credit distribution function */
134 int TxCreditsAssigned; /* number of credits assigned to this EP, this field
135 is only relevant to the credit dist function */
136 int TxCredits; /* current credits available, this field is used by
137 HTC to determine whether a message can be sent or
138 must be queued */
139 int TxCreditsToDist; /* pending credits to distribute on this endpoint, this
140 is set by HTC when credit reports arrive.
141 The credit distribution functions sets this to zero
142 when it distributes the credits */
143 int TxCreditsSeek; /* this is the number of credits that the current pending TX
144 packet needs to transmit. This is set by HTC when
145 and endpoint needs credits in order to transmit */
146 int TxCreditSize; /* size in bytes of each credit (set by HTC) */
147 int TxCreditsPerMaxMsg; /* credits required for a maximum sized messages (set by HTC) */
148 void *pHTCReserved; /* reserved for HTC use */
149 } HTC_ENDPOINT_CREDIT_DIST;
150
151 #define HTC_EP_ACTIVE (1 << 31)
152
153 /* macro to check if an endpoint has gone active, useful for credit
154 * distributions */
155 #define IS_EP_ACTIVE(epDist) ((epDist)->DistFlags & HTC_EP_ACTIVE)
156 #define SET_EP_ACTIVE(epDist) (epDist)->DistFlags |= HTC_EP_ACTIVE
157
158 /* credit distibution code that is passed into the distrbution function,
159 * there are mandatory and optional codes that must be handled */
160 typedef enum _HTC_CREDIT_DIST_REASON {
161 HTC_CREDIT_DIST_SEND_COMPLETE = 0, /* credits available as a result of completed
162 send operations (MANDATORY) resulting in credit reports */
163 HTC_CREDIT_DIST_ACTIVITY_CHANGE = 1, /* a change in endpoint activity occured (OPTIONAL) */
164 HTC_CREDIT_DIST_SEEK_CREDITS, /* an endpoint needs to "seek" credits (OPTIONAL) */
165 HTC_DUMP_CREDIT_STATE /* for debugging, dump any state information that is kept by
166 the distribution function */
167 } HTC_CREDIT_DIST_REASON;
168
169 typedef void (*HTC_CREDIT_DIST_CALLBACK)(void *Context,
170 HTC_ENDPOINT_CREDIT_DIST *pEPList,
171 HTC_CREDIT_DIST_REASON Reason);
172
173 typedef void (*HTC_CREDIT_INIT_CALLBACK)(void *Context,
174 HTC_ENDPOINT_CREDIT_DIST *pEPList,
175 int TotalCredits);
176
177 /* endpoint statistics action */
178 typedef enum _HTC_ENDPOINT_STAT_ACTION {
179 HTC_EP_STAT_SAMPLE = 0, /* only read statistics */
180 HTC_EP_STAT_SAMPLE_AND_CLEAR = 1, /* sample and immediately clear statistics */
181 HTC_EP_STAT_CLEAR /* clear only */
182 } HTC_ENDPOINT_STAT_ACTION;
183
184 /* endpoint statistics */
185 typedef struct _HTC_ENDPOINT_STATS {
186 A_UINT32 TxCreditLowIndications; /* number of times the host set the credit-low flag in a send message on
187 this endpoint */
188 A_UINT32 TxIssued; /* running count of TX packets issued */
189 A_UINT32 TxCreditRpts; /* running count of total credit reports received for this endpoint */
190 A_UINT32 TxCreditRptsFromRx;
191 A_UINT32 TxCreditRptsFromOther;
192 A_UINT32 TxCreditRptsFromEp0;
193 A_UINT32 TxCreditsFromRx; /* count of credits received via Rx packets on this endpoint */
194 A_UINT32 TxCreditsFromOther; /* count of credits received via another endpoint */
195 A_UINT32 TxCreditsFromEp0; /* count of credits received via another endpoint */
196 A_UINT32 TxCreditsConsummed; /* count of consummed credits */
197 A_UINT32 TxCreditsReturned; /* count of credits returned */
198 A_UINT32 RxReceived; /* count of RX packets received */
199 A_UINT32 RxLookAheads; /* count of lookahead records
200 found in messages received on this endpoint */
201 } HTC_ENDPOINT_STATS;
202
203 /* ------ Function Prototypes ------ */
204 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
205 @desc: Initialize HTC
206 @function name: HTCInit
207 @input: pInfo - initialization information
208 @output:
209 @return: A_OK on success
210 @notes: The caller initializes global HTC state and registers various instance
211 notification callbacks (see HTC_INIT_INFO).
212
213 @example:
214 @see also: HTCShutdown
215 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
216 A_STATUS HTCInit(HTC_INIT_INFO *pInfo);
217 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
218 @desc: Get the underlying HIF device handle
219 @function name: HTCGetHifDevice
220 @input: HTCHandle - handle passed into the AddInstance callback
221 @output:
222 @return: opaque HIF device handle usable in HIF API calls.
223 @notes:
224 @example:
225 @see also:
226 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
227 void *HTCGetHifDevice(HTC_HANDLE HTCHandle);
228 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
229 @desc: Set the associated instance for the HTC handle
230 @function name: HTCSetInstance
231 @input: HTCHandle - handle passed into the AddInstance callback
232 Instance - caller supplied instance object
233 @output:
234 @return:
235 @notes: Caller must set the instance information for the HTC handle in order to receive
236 notifications for instance deletion (DeleteInstance callback is called) and for target
237 failure notification.
238 @example:
239 @see also:
240 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
241 void HTCSetInstance(HTC_HANDLE HTCHandle, void *Instance);
242 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
243 @desc: Set credit distribution parameters
244 @function name: HTCSetCreditDistribution
245 @input: HTCHandle - HTC handle
246 pCreditDistCont - caller supplied context to pass into distribution functions
247 CreditDistFunc - Distribution function callback
248 CreditDistInit - Credit Distribution initialization callback
249 ServicePriorityOrder - Array containing list of service IDs, lowest index is highest
250 priority
251 ListLength - number of elements in ServicePriorityOrder
252 @output:
253 @return:
254 @notes: The user can set a custom credit distribution function to handle special requirements
255 for each endpoint. A default credit distribution routine can be used by setting
256 CreditInitFunc to NULL. The default credit distribution is only provided for simple
257 "fair" credit distribution without regard to any prioritization.
258
259 @example:
260 @see also:
261 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
262 void HTCSetCreditDistribution(HTC_HANDLE HTCHandle,
263 void *pCreditDistContext,
264 HTC_CREDIT_DIST_CALLBACK CreditDistFunc,
265 HTC_CREDIT_INIT_CALLBACK CreditInitFunc,
266 HTC_SERVICE_ID ServicePriorityOrder[],
267 int ListLength);
268 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
269 @desc: Wait for the target to indicate the HTC layer is ready
270 @function name: HTCWaitTarget
271 @input: HTCHandle - HTC handle
272 @output:
273 @return:
274 @notes: This API blocks until the target responds with an HTC ready message.
275 The caller should not connect services until the target has indicated it is
276 ready.
277 @example:
278 @see also: HTCConnectService
279 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
280 A_STATUS HTCWaitTarget(HTC_HANDLE HTCHandle);
281 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
282 @desc: Start target service communications
283 @function name: HTCStart
284 @input: HTCHandle - HTC handle
285 @output:
286 @return:
287 @notes: This API indicates to the target that the service connection phase is complete
288 and the target can freely start all connected services. This API should only be
289 called AFTER all service connections have been made. TCStart will issue a
290 SETUP_COMPLETE message to the target to indicate that all service connections
291 have been made and the target can start communicating over the endpoints.
292 @example:
293 @see also: HTCConnectService
294 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
295 A_STATUS HTCStart(HTC_HANDLE HTCHandle);
296 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
297 @desc: Add receive packet to HTC
298 @function name: HTCAddReceivePkt
299 @input: HTCHandle - HTC handle
300 pPacket - HTC receive packet to add
301 @output:
302 @return: A_OK on success
303 @notes: user must supply HTC packets for capturing incomming HTC frames. The caller
304 must initialize each HTC packet using the SET_HTC_PACKET_INFO_RX_REFILL()
305 macro.
306 @example:
307 @see also:
308 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
309 A_STATUS HTCAddReceivePkt(HTC_HANDLE HTCHandle, HTC_PACKET *pPacket);
310 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
311 @desc: Connect to an HTC service
312 @function name: HTCConnectService
313 @input: HTCHandle - HTC handle
314 pReq - connection details
315 @output: pResp - connection response
316 @return:
317 @notes: Service connections must be performed before HTCStart. User provides callback handlers
318 for various endpoint events.
319 @example:
320 @see also: HTCStart
321 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
322 A_STATUS HTCConnectService(HTC_HANDLE HTCHandle,
323 HTC_SERVICE_CONNECT_REQ *pReq,
324 HTC_SERVICE_CONNECT_RESP *pResp);
325 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
326 @desc: Send an HTC packet
327 @function name: HTCSendPkt
328 @input: HTCHandle - HTC handle
329 pPacket - packet to send
330 @output:
331 @return: A_OK
332 @notes: Caller must initialize packet using SET_HTC_PACKET_INFO_TX() macro.
333 This interface is fully asynchronous. On error, HTC SendPkt will
334 call the registered Endpoint callback to cleanup the packet.
335 @example:
336 @see also: HTCFlushEndpoint
337 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
338 A_STATUS HTCSendPkt(HTC_HANDLE HTCHandle, HTC_PACKET *pPacket);
339 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
340 @desc: Stop HTC service communications
341 @function name: HTCStop
342 @input: HTCHandle - HTC handle
343 @output:
344 @return:
345 @notes: HTC communications is halted. All receive and pending TX packets will
346 be flushed.
347 @example:
348 @see also:
349 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
350 void HTCStop(HTC_HANDLE HTCHandle);
351 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
352 @desc: Shutdown HTC
353 @function name: HTCShutdown
354 @input:
355 @output:
356 @return:
357 @notes: This cleans up all resources allocated by HTCInit().
358 @example:
359 @see also: HTCInit
360 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
361 void HTCShutDown(void);
362 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
363 @desc: Flush pending TX packets
364 @function name: HTCFlushEndpoint
365 @input: HTCHandle - HTC handle
366 Endpoint - Endpoint to flush
367 Tag - flush tag
368 @output:
369 @return:
370 @notes: The Tag parameter is used to selectively flush packets with matching tags.
371 The value of 0 forces all packets to be flush regardless of tag.
372 @example:
373 @see also: HTCSendPkt
374 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
375 void HTCFlushEndpoint(HTC_HANDLE HTCHandle, HTC_ENDPOINT_ID Endpoint, HTC_TX_TAG Tag);
376 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
377 @desc: Dump credit distribution state
378 @function name: HTCDumpCreditStates
379 @input: HTCHandle - HTC handle
380 @output:
381 @return:
382 @notes: This dumps all credit distribution information to the debugger
383 @example:
384 @see also:
385 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
386 void HTCDumpCreditStates(HTC_HANDLE HTCHandle);
387 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
388 @desc: Indicate a traffic activity change on an endpoint
389 @function name: HTCIndicateActivityChange
390 @input: HTCHandle - HTC handle
391 Endpoint - endpoint in which activity has changed
392 Active - TRUE if active, FALSE if it has become inactive
393 @output:
394 @return:
395 @notes: This triggers the registered credit distribution function to
396 re-adjust credits for active/inactive endpoints.
397 @example:
398 @see also:
399 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
400 void HTCIndicateActivityChange(HTC_HANDLE HTCHandle,
401 HTC_ENDPOINT_ID Endpoint,
402 A_BOOL Active);
403
404 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
405 @desc: Get endpoint statistics
406 @function name: HTCGetEndpointStatistics
407 @input: HTCHandle - HTC handle
408 Endpoint - Endpoint identifier
409 Action - action to take with statistics
410 @output:
411 pStats - statistics that were sampled (can be NULL if Action is HTC_EP_STAT_CLEAR)
412
413 @return: TRUE if statistics profiling is enabled, otherwise FALSE.
414
415 @notes: Statistics is a compile-time option and this function may return FALSE
416 if HTC is not compiled with profiling.
417
418 The caller can specify the statistic "action" to take when sampling
419 the statistics. This includes:
420
421 HTC_EP_STAT_SAMPLE: The pStats structure is filled with the current values.
422 HTC_EP_STAT_SAMPLE_AND_CLEAR: The structure is filled and the current statistics
423 are cleared.
424 HTC_EP_STAT_CLEA : the statistics are cleared, the called can pass a NULL value for
425 pStats
426
427 @example:
428 @see also:
429 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
430 A_BOOL HTCGetEndpointStatistics(HTC_HANDLE HTCHandle,
431 HTC_ENDPOINT_ID Endpoint,
432 HTC_ENDPOINT_STAT_ACTION Action,
433 HTC_ENDPOINT_STATS *pStats);
434
435 #ifdef __cplusplus
436 }
437 #endif
438
439 #endif /* _HTC_API_H_ */
This page took 0.068417 seconds and 5 git commands to generate.