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_ */