+++ /dev/null
-/*
- *
- * Copyright (c) 2007 Atheros Communications Inc.
- * All rights reserved.
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2 as
- * published by the Free Software Foundation;
- *
- * Software distributed under the License is distributed on an "AS
- * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
- * implied. See the License for the specific language governing
- * rights and limitations under the License.
- *
- *
- *
- */
-
-#ifndef _HTC_API_H_
-#define _HTC_API_H_
-
-#include <htc.h>
-#include <htc_services.h>
-#include "htc_packet.h"
-
-#ifdef __cplusplus
-extern "C" {
-#endif /* __cplusplus */
-
-/* TODO.. for BMI */
-#define ENDPOINT1 0
-// TODO -remove me, but we have to fix BMI first
-#define HTC_MAILBOX_NUM_MAX 4
-
-
-/* ------ Endpoint IDS ------ */
-typedef enum
-{
- ENDPOINT_UNUSED = -1,
- ENDPOINT_0 = 0,
- ENDPOINT_1 = 1,
- ENDPOINT_2 = 2,
- ENDPOINT_3,
- ENDPOINT_4,
- ENDPOINT_5,
- ENDPOINT_6,
- ENDPOINT_7,
- ENDPOINT_8,
- ENDPOINT_MAX,
-} HTC_ENDPOINT_ID;
-
-/* this is the amount of header room required by users of HTC */
-#define HTC_HEADER_LEN HTC_HDR_LENGTH
-
-typedef void *HTC_HANDLE;
-
-typedef A_UINT16 HTC_SERVICE_ID;
-
-typedef struct _HTC_INIT_INFO {
- void (*AddInstance)(HTC_HANDLE);
- void (*DeleteInstance)(void *Instance);
- void (*TargetFailure)(void *Instance, A_STATUS Status);
-} HTC_INIT_INFO;
-
-/* per service connection send completion */
-typedef void (*HTC_EP_SEND_PKT_COMPLETE)(void *,HTC_PACKET *);
-/* per service connection pkt received */
-typedef void (*HTC_EP_RECV_PKT)(void *,HTC_PACKET *);
-
-/* Optional per service connection receive buffer re-fill callback,
- * On some OSes (like Linux) packets are allocated from a global pool and indicated up
- * to the network stack. The driver never gets the packets back from the OS. For these OSes
- * a refill callback can be used to allocate and re-queue buffers into HTC.
- *
- * On other OSes, the network stack can call into the driver's OS-specifc "return_packet" handler and
- * the driver can re-queue these buffers into HTC. In this regard a refill callback is
- * unnecessary */
-typedef void (*HTC_EP_RECV_REFILL)(void *, HTC_ENDPOINT_ID Endpoint);
-
-/* Optional per service connection callback when a send queue is full. This can occur if the
- * host continues queueing up TX packets faster than credits can arrive
- * To prevent the host (on some Oses like Linux) from continuously queueing packets
- * and consuming resources, this callback is provided so that that the host
- * can disable TX in the subsystem (i.e. network stack)
- * Other OSes require a "per-packet" indication_RAW_STREAM_NUM_MAX for each completed TX packet, this
- * closed loop mechanism will prevent the network stack from overunning the NIC */
-typedef void (*HTC_EP_SEND_QUEUE_FULL)(void *, HTC_ENDPOINT_ID Endpoint);
-/* Optional per service connection callback when a send queue is available for receive new packet. */
-typedef void (*HTC_EP_SEND_QUEUE_AVAIL)(void *, HTC_ENDPOINT_ID Endpoint);
-
-typedef struct _HTC_EP_CALLBACKS {
- void *pContext; /* context for each callback */
- HTC_EP_SEND_PKT_COMPLETE EpTxComplete; /* tx completion callback for connected endpoint */
- HTC_EP_RECV_PKT EpRecv; /* receive callback for connected endpoint */
- HTC_EP_RECV_REFILL EpRecvRefill; /* OPTIONAL receive re-fill callback for connected endpoint */
- HTC_EP_SEND_QUEUE_FULL EpSendFull; /* OPTIONAL send full callback */
- HTC_EP_SEND_QUEUE_AVAIL EpSendAvail; /* OPTIONAL send available callback */
-} HTC_EP_CALLBACKS;
-
-/* service connection information */
-typedef struct _HTC_SERVICE_CONNECT_REQ {
- HTC_SERVICE_ID ServiceID; /* service ID to connect to */
- A_UINT16 ConnectionFlags; /* connection flags, see htc protocol definition */
- A_UINT8 *pMetaData; /* ptr to optional service-specific meta-data */
- A_UINT8 MetaDataLength; /* optional meta data length */
- HTC_EP_CALLBACKS EpCallbacks; /* endpoint callbacks */
- int MaxSendQueueDepth; /* maximum depth of any send queue */
-} HTC_SERVICE_CONNECT_REQ;
-
-/* service connection response information */
-typedef struct _HTC_SERVICE_CONNECT_RESP {
- A_UINT8 *pMetaData; /* caller supplied buffer to optional meta-data */
- A_UINT8 BufferLength; /* length of caller supplied buffer */
- A_UINT8 ActualLength; /* actual length of meta data */
- HTC_ENDPOINT_ID Endpoint; /* endpoint to communicate over */
- int MaxMsgLength; /* max length of all messages over this endpoint */
- A_UINT8 ConnectRespCode; /* connect response code from target */
-} HTC_SERVICE_CONNECT_RESP;
-
-/* endpoint distribution structure */
-typedef struct _HTC_ENDPOINT_CREDIT_DIST {
- struct _HTC_ENDPOINT_CREDIT_DIST *pNext;
- struct _HTC_ENDPOINT_CREDIT_DIST *pPrev;
- HTC_SERVICE_ID ServiceID; /* Service ID (set by HTC) */
- HTC_ENDPOINT_ID Endpoint; /* endpoint for this distribution struct (set by HTC) */
- A_UINT32 DistFlags; /* distribution flags, distribution function can
- set default activity using SET_EP_ACTIVE() macro */
- int TxCreditsNorm; /* credits for normal operation, anything above this
- indicates the endpoint is over-subscribed, this field
- is only relevant to the credit distribution function */
- int TxCreditsMin; /* floor for credit distribution, this field is
- only relevant to the credit distribution function */
- int TxCreditsAssigned; /* number of credits assigned to this EP, this field
- is only relevant to the credit dist function */
- int TxCredits; /* current credits available, this field is used by
- HTC to determine whether a message can be sent or
- must be queued */
- int TxCreditsToDist; /* pending credits to distribute on this endpoint, this
- is set by HTC when credit reports arrive.
- The credit distribution functions sets this to zero
- when it distributes the credits */
- int TxCreditsSeek; /* this is the number of credits that the current pending TX
- packet needs to transmit. This is set by HTC when
- and endpoint needs credits in order to transmit */
- int TxCreditSize; /* size in bytes of each credit (set by HTC) */
- int TxCreditsPerMaxMsg; /* credits required for a maximum sized messages (set by HTC) */
- void *pHTCReserved; /* reserved for HTC use */
-} HTC_ENDPOINT_CREDIT_DIST;
-
-#define HTC_EP_ACTIVE (1 << 31)
-
-/* macro to check if an endpoint has gone active, useful for credit
- * distributions */
-#define IS_EP_ACTIVE(epDist) ((epDist)->DistFlags & HTC_EP_ACTIVE)
-#define SET_EP_ACTIVE(epDist) (epDist)->DistFlags |= HTC_EP_ACTIVE
-
- /* credit distibution code that is passed into the distrbution function,
- * there are mandatory and optional codes that must be handled */
-typedef enum _HTC_CREDIT_DIST_REASON {
- HTC_CREDIT_DIST_SEND_COMPLETE = 0, /* credits available as a result of completed
- send operations (MANDATORY) resulting in credit reports */
- HTC_CREDIT_DIST_ACTIVITY_CHANGE = 1, /* a change in endpoint activity occured (OPTIONAL) */
- HTC_CREDIT_DIST_SEEK_CREDITS, /* an endpoint needs to "seek" credits (OPTIONAL) */
- HTC_DUMP_CREDIT_STATE /* for debugging, dump any state information that is kept by
- the distribution function */
-} HTC_CREDIT_DIST_REASON;
-
-typedef void (*HTC_CREDIT_DIST_CALLBACK)(void *Context,
- HTC_ENDPOINT_CREDIT_DIST *pEPList,
- HTC_CREDIT_DIST_REASON Reason);
-
-typedef void (*HTC_CREDIT_INIT_CALLBACK)(void *Context,
- HTC_ENDPOINT_CREDIT_DIST *pEPList,
- int TotalCredits);
-
- /* endpoint statistics action */
-typedef enum _HTC_ENDPOINT_STAT_ACTION {
- HTC_EP_STAT_SAMPLE = 0, /* only read statistics */
- HTC_EP_STAT_SAMPLE_AND_CLEAR = 1, /* sample and immediately clear statistics */
- HTC_EP_STAT_CLEAR /* clear only */
-} HTC_ENDPOINT_STAT_ACTION;
-
- /* endpoint statistics */
-typedef struct _HTC_ENDPOINT_STATS {
- A_UINT32 TxCreditLowIndications; /* number of times the host set the credit-low flag in a send message on
- this endpoint */
- A_UINT32 TxIssued; /* running count of TX packets issued */
- A_UINT32 TxCreditRpts; /* running count of total credit reports received for this endpoint */
- A_UINT32 TxCreditRptsFromRx;
- A_UINT32 TxCreditRptsFromOther;
- A_UINT32 TxCreditRptsFromEp0;
- A_UINT32 TxCreditsFromRx; /* count of credits received via Rx packets on this endpoint */
- A_UINT32 TxCreditsFromOther; /* count of credits received via another endpoint */
- A_UINT32 TxCreditsFromEp0; /* count of credits received via another endpoint */
- A_UINT32 TxCreditsConsummed; /* count of consummed credits */
- A_UINT32 TxCreditsReturned; /* count of credits returned */
- A_UINT32 RxReceived; /* count of RX packets received */
- A_UINT32 RxLookAheads; /* count of lookahead records
- found in messages received on this endpoint */
-} HTC_ENDPOINT_STATS;
-
-/* ------ Function Prototypes ------ */
-/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
- @desc: Initialize HTC
- @function name: HTCInit
- @input: pInfo - initialization information
- @output:
- @return: A_OK on success
- @notes: The caller initializes global HTC state and registers various instance
- notification callbacks (see HTC_INIT_INFO).
-
- @example:
- @see also: HTCShutdown
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
-A_STATUS HTCInit(HTC_INIT_INFO *pInfo);
-/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
- @desc: Get the underlying HIF device handle
- @function name: HTCGetHifDevice
- @input: HTCHandle - handle passed into the AddInstance callback
- @output:
- @return: opaque HIF device handle usable in HIF API calls.
- @notes:
- @example:
- @see also:
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
-void *HTCGetHifDevice(HTC_HANDLE HTCHandle);
-/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
- @desc: Set the associated instance for the HTC handle
- @function name: HTCSetInstance
- @input: HTCHandle - handle passed into the AddInstance callback
- Instance - caller supplied instance object
- @output:
- @return:
- @notes: Caller must set the instance information for the HTC handle in order to receive
- notifications for instance deletion (DeleteInstance callback is called) and for target
- failure notification.
- @example:
- @see also:
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
-void HTCSetInstance(HTC_HANDLE HTCHandle, void *Instance);
-/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
- @desc: Set credit distribution parameters
- @function name: HTCSetCreditDistribution
- @input: HTCHandle - HTC handle
- pCreditDistCont - caller supplied context to pass into distribution functions
- CreditDistFunc - Distribution function callback
- CreditDistInit - Credit Distribution initialization callback
- ServicePriorityOrder - Array containing list of service IDs, lowest index is highest
- priority
- ListLength - number of elements in ServicePriorityOrder
- @output:
- @return:
- @notes: The user can set a custom credit distribution function to handle special requirements
- for each endpoint. A default credit distribution routine can be used by setting
- CreditInitFunc to NULL. The default credit distribution is only provided for simple
- "fair" credit distribution without regard to any prioritization.
-
- @example:
- @see also:
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
-void HTCSetCreditDistribution(HTC_HANDLE HTCHandle,
- void *pCreditDistContext,
- HTC_CREDIT_DIST_CALLBACK CreditDistFunc,
- HTC_CREDIT_INIT_CALLBACK CreditInitFunc,
- HTC_SERVICE_ID ServicePriorityOrder[],
- int ListLength);
-/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
- @desc: Wait for the target to indicate the HTC layer is ready
- @function name: HTCWaitTarget
- @input: HTCHandle - HTC handle
- @output:
- @return:
- @notes: This API blocks until the target responds with an HTC ready message.
- The caller should not connect services until the target has indicated it is
- ready.
- @example:
- @see also: HTCConnectService
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
-A_STATUS HTCWaitTarget(HTC_HANDLE HTCHandle);
-/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
- @desc: Start target service communications
- @function name: HTCStart
- @input: HTCHandle - HTC handle
- @output:
- @return:
- @notes: This API indicates to the target that the service connection phase is complete
- and the target can freely start all connected services. This API should only be
- called AFTER all service connections have been made. TCStart will issue a
- SETUP_COMPLETE message to the target to indicate that all service connections
- have been made and the target can start communicating over the endpoints.
- @example:
- @see also: HTCConnectService
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
-A_STATUS HTCStart(HTC_HANDLE HTCHandle);
-/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
- @desc: Add receive packet to HTC
- @function name: HTCAddReceivePkt
- @input: HTCHandle - HTC handle
- pPacket - HTC receive packet to add
- @output:
- @return: A_OK on success
- @notes: user must supply HTC packets for capturing incomming HTC frames. The caller
- must initialize each HTC packet using the SET_HTC_PACKET_INFO_RX_REFILL()
- macro.
- @example:
- @see also:
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
-A_STATUS HTCAddReceivePkt(HTC_HANDLE HTCHandle, HTC_PACKET *pPacket);
-/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
- @desc: Connect to an HTC service
- @function name: HTCConnectService
- @input: HTCHandle - HTC handle
- pReq - connection details
- @output: pResp - connection response
- @return:
- @notes: Service connections must be performed before HTCStart. User provides callback handlers
- for various endpoint events.
- @example:
- @see also: HTCStart
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
-A_STATUS HTCConnectService(HTC_HANDLE HTCHandle,
- HTC_SERVICE_CONNECT_REQ *pReq,
- HTC_SERVICE_CONNECT_RESP *pResp);
-/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
- @desc: Send an HTC packet
- @function name: HTCSendPkt
- @input: HTCHandle - HTC handle
- pPacket - packet to send
- @output:
- @return: A_OK
- @notes: Caller must initialize packet using SET_HTC_PACKET_INFO_TX() macro.
- This interface is fully asynchronous. On error, HTC SendPkt will
- call the registered Endpoint callback to cleanup the packet.
- @example:
- @see also: HTCFlushEndpoint
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
-A_STATUS HTCSendPkt(HTC_HANDLE HTCHandle, HTC_PACKET *pPacket);
-/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
- @desc: Stop HTC service communications
- @function name: HTCStop
- @input: HTCHandle - HTC handle
- @output:
- @return:
- @notes: HTC communications is halted. All receive and pending TX packets will
- be flushed.
- @example:
- @see also:
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
-void HTCStop(HTC_HANDLE HTCHandle);
-/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
- @desc: Shutdown HTC
- @function name: HTCShutdown
- @input:
- @output:
- @return:
- @notes: This cleans up all resources allocated by HTCInit().
- @example:
- @see also: HTCInit
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
-void HTCShutDown(void);
-/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
- @desc: Flush pending TX packets
- @function name: HTCFlushEndpoint
- @input: HTCHandle - HTC handle
- Endpoint - Endpoint to flush
- Tag - flush tag
- @output:
- @return:
- @notes: The Tag parameter is used to selectively flush packets with matching tags.
- The value of 0 forces all packets to be flush regardless of tag.
- @example:
- @see also: HTCSendPkt
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
-void HTCFlushEndpoint(HTC_HANDLE HTCHandle, HTC_ENDPOINT_ID Endpoint, HTC_TX_TAG Tag);
-/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
- @desc: Dump credit distribution state
- @function name: HTCDumpCreditStates
- @input: HTCHandle - HTC handle
- @output:
- @return:
- @notes: This dumps all credit distribution information to the debugger
- @example:
- @see also:
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
-void HTCDumpCreditStates(HTC_HANDLE HTCHandle);
-/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
- @desc: Indicate a traffic activity change on an endpoint
- @function name: HTCIndicateActivityChange
- @input: HTCHandle - HTC handle
- Endpoint - endpoint in which activity has changed
- Active - TRUE if active, FALSE if it has become inactive
- @output:
- @return:
- @notes: This triggers the registered credit distribution function to
- re-adjust credits for active/inactive endpoints.
- @example:
- @see also:
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
-void HTCIndicateActivityChange(HTC_HANDLE HTCHandle,
- HTC_ENDPOINT_ID Endpoint,
- A_BOOL Active);
-
-/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
- @desc: Get endpoint statistics
- @function name: HTCGetEndpointStatistics
- @input: HTCHandle - HTC handle
- Endpoint - Endpoint identifier
- Action - action to take with statistics
- @output:
- pStats - statistics that were sampled (can be NULL if Action is HTC_EP_STAT_CLEAR)
-
- @return: TRUE if statistics profiling is enabled, otherwise FALSE.
-
- @notes: Statistics is a compile-time option and this function may return FALSE
- if HTC is not compiled with profiling.
-
- The caller can specify the statistic "action" to take when sampling
- the statistics. This includes:
-
- HTC_EP_STAT_SAMPLE: The pStats structure is filled with the current values.
- HTC_EP_STAT_SAMPLE_AND_CLEAR: The structure is filled and the current statistics
- are cleared.
- HTC_EP_STAT_CLEA : the statistics are cleared, the called can pass a NULL value for
- pStats
-
- @example:
- @see also:
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
-A_BOOL HTCGetEndpointStatistics(HTC_HANDLE HTCHandle,
- HTC_ENDPOINT_ID Endpoint,
- HTC_ENDPOINT_STAT_ACTION Action,
- HTC_ENDPOINT_STATS *pStats);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* _HTC_API_H_ */
projects / openwrt / svn-archive / archive.git / blobdiff