path: root/drivers/ar6000/include/htc_api.h

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