drivers/staging/ath6kl/include/hci_transport_api.h

   1 //------------------------------------------------------------------------------
   2 // Copyright (c) 2009-2010 Atheros Corporation.  All rights reserved.
   3 //
   4 //
   5 // Permission to use, copy, modify, and/or distribute this software for any
   6 // purpose with or without fee is hereby granted, provided that the above
   7 // copyright notice and this permission notice appear in all copies.
   8 //
   9 // THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10 // WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11 // MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12 // ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13 // WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14 // ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15 // OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 //
  17 //
  18 //------------------------------------------------------------------------------
  19 //==============================================================================
  20 // Author(s): ="Atheros"
  21 //==============================================================================
  22 #ifndef _HCI_TRANSPORT_API_H_
  23 #define _HCI_TRANSPORT_API_H_
  24
  25     /* Bluetooth HCI packets are stored in HTC packet containers */
  26 #include "htc_packet.h"
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif /* __cplusplus */
  31
  32 typedef void *HCI_TRANSPORT_HANDLE;
  33
  34 typedef HTC_ENDPOINT_ID HCI_TRANSPORT_PACKET_TYPE;
  35
  36     /* we map each HCI packet class to a static Endpoint ID */
  37 #define HCI_COMMAND_TYPE   ENDPOINT_1
  38 #define HCI_EVENT_TYPE     ENDPOINT_2
  39 #define HCI_ACL_TYPE       ENDPOINT_3
  40 #define HCI_PACKET_INVALID ENDPOINT_MAX
  41
  42 #define HCI_GET_PACKET_TYPE(pP)    (pP)->Endpoint
  43 #define HCI_SET_PACKET_TYPE(pP,s)  (pP)->Endpoint = (s)
  44
  45 /* callback when an HCI packet was completely sent */
  46 typedef void   (*HCI_TRANSPORT_SEND_PKT_COMPLETE)(void *, HTC_PACKET *);
  47 /* callback when an HCI packet is received */
  48 typedef void   (*HCI_TRANSPORT_RECV_PKT)(void *, HTC_PACKET *);
  49 /* Optional receive buffer re-fill callback,
  50  * On some OSes (like Linux) packets are allocated from a global pool and indicated up
  51  * to the network stack.  The driver never gets the packets back from the OS.  For these OSes
  52  * a refill callback can be used to allocate and re-queue buffers into HTC.
  53  * A refill callback is used for the reception of ACL and EVENT packets.  The caller must
  54  * set the watermark trigger point to cause a refill.
  55  */
  56 typedef void   (*HCI_TRANSPORT_RECV_REFILL)(void *, HCI_TRANSPORT_PACKET_TYPE Type, int BuffersAvailable);
  57 /* Optional receive packet refill
  58  * On some systems packet buffers are an extremely limited resource.  Rather than
  59  * queue largest-possible-sized buffers to the HCI bridge, some systems would rather
  60  * allocate a specific size as the packet is received.  The trade off is
  61  * slightly more processing (callback invoked for each RX packet)
  62  * for the benefit of committing fewer buffer resources into the bridge.
  63  *
  64  * The callback is provided the length of the pending packet to fetch. This includes the
  65  * full transport header, HCI header, plus the length of payload.  The callback can return a pointer to
  66  * the allocated HTC packet for immediate use.
  67  *
  68  * NOTE*** This callback is mutually exclusive with the the refill callback above.
  69  *
  70  * */
  71 typedef HTC_PACKET *(*HCI_TRANSPORT_RECV_ALLOC)(void *, HCI_TRANSPORT_PACKET_TYPE Type, int Length);
  72
  73 typedef enum _HCI_SEND_FULL_ACTION {
  74     HCI_SEND_FULL_KEEP = 0,  /* packet that overflowed should be kept in the queue */
  75     HCI_SEND_FULL_DROP = 1,  /* packet that overflowed should be dropped */
  76 } HCI_SEND_FULL_ACTION;
  77
  78 /* callback when an HCI send queue exceeds the caller's MaxSendQueueDepth threshold,
  79  * the callback must return the send full action to take (either DROP or KEEP) */
  80 typedef HCI_SEND_FULL_ACTION  (*HCI_TRANSPORT_SEND_FULL)(void *, HTC_PACKET *);
  81
  82 typedef struct {
  83     int    HeadRoom;      /* number of bytes in front of HCI packet for header space */
  84     int    TailRoom;      /* number of bytes at the end of the HCI packet for tail space */
  85     int    IOBlockPad;    /* I/O block padding required (always a power of 2) */
  86 } HCI_TRANSPORT_PROPERTIES;
  87
  88 typedef struct _HCI_TRANSPORT_CONFIG_INFO {
  89     int      ACLRecvBufferWaterMark;     /* low watermark to trigger recv refill */
  90     int      EventRecvBufferWaterMark;   /* low watermark to trigger recv refill */
  91     int      MaxSendQueueDepth;          /* max number of packets in the single send queue */
  92     void     *pContext;                  /* context for all callbacks */
  93     void     (*TransportFailure)(void *pContext, A_STATUS Status); /* transport failure callback */
  94     A_STATUS (*TransportReady)(HCI_TRANSPORT_HANDLE, HCI_TRANSPORT_PROPERTIES *,void *pContext); /* transport is ready */
  95     void     (*TransportRemoved)(void *pContext);                  /* transport was removed */
  96         /* packet processing callbacks */
  97     HCI_TRANSPORT_SEND_PKT_COMPLETE    pHCISendComplete;
  98     HCI_TRANSPORT_RECV_PKT             pHCIPktRecv;
  99     HCI_TRANSPORT_RECV_REFILL          pHCIPktRecvRefill;
 100     HCI_TRANSPORT_RECV_ALLOC           pHCIPktRecvAlloc;
 101     HCI_TRANSPORT_SEND_FULL            pHCISendFull;
 102 } HCI_TRANSPORT_CONFIG_INFO;
 103
 104 /* ------ Function Prototypes ------ */
 105 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 106   @desc: Attach to the HCI transport module
 107   @function name: HCI_TransportAttach
 108   @input:  HTCHandle - HTC handle (see HTC apis)
 109            pInfo - initialization information
 110   @output:
 111   @return: HCI_TRANSPORT_HANDLE on success, NULL on failure
 112   @notes:    The HTC module provides HCI transport services.
 113   @example:
 114   @see also: HCI_TransportDetach
 115 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
 116 HCI_TRANSPORT_HANDLE HCI_TransportAttach(void *HTCHandle, HCI_TRANSPORT_CONFIG_INFO *pInfo);
 117
 118 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 119   @desc: Detach from the HCI transport module
 120   @function name: HCI_TransportDetach
 121   @input:  HciTrans - HCI transport handle
 122            pInfo - initialization information
 123   @output:
 124   @return:
 125   @notes:
 126   @example:
 127   @see also:
 128 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
 129 void HCI_TransportDetach(HCI_TRANSPORT_HANDLE HciTrans);
 130
 131 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 132   @desc: Add receive packets to the HCI transport
 133   @function name: HCI_TransportAddReceivePkts
 134   @input:  HciTrans - HCI transport handle
 135            pQueue - a queue holding one or more packets
 136   @output:
 137   @return: A_OK on success
 138   @notes:  user must supply HTC packets for capturing incomming HCI packets.  The caller
 139            must initialize each HTC packet using the SET_HTC_PACKET_INFO_RX_REFILL()
 140            macro. Each packet in the queue must be of the same type and length
 141   @example:
 142   @see also:
 143 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
 144 A_STATUS    HCI_TransportAddReceivePkts(HCI_TRANSPORT_HANDLE HciTrans, HTC_PACKET_QUEUE *pQueue);
 145
 146 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 147   @desc: Send an HCI packet packet
 148   @function name: HCI_TransportSendPkt
 149   @input:  HciTrans - HCI transport handle
 150            pPacket - packet to send
 151            Synchronous - send the packet synchronously (blocking)
 152   @output:
 153   @return: A_OK
 154   @notes:  Caller must initialize packet using SET_HTC_PACKET_INFO_TX() and
 155            HCI_SET_PACKET_TYPE() macros to prepare the packet.
 156            If Synchronous is set to FALSE the call is fully asynchronous.  On error or completion,
 157            the registered send complete callback will be called.
 158            If Synchronous is set to TRUE, the call will block until the packet is sent, if the
 159            interface cannot send the packet within a 2 second timeout, the function will return
 160            the failure code : A_EBUSY.
 161
 162            Synchronous Mode should only be used at start-up to initialize the HCI device using
 163            custom HCI commands.  It should NOT be mixed with Asynchronous operations.  Mixed synchronous
 164            and asynchronous operation behavior is undefined.
 165
 166   @example:
 167   @see also:
 168 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
 169 A_STATUS    HCI_TransportSendPkt(HCI_TRANSPORT_HANDLE HciTrans, HTC_PACKET *pPacket, A_BOOL Synchronous);
 170
 171
 172 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 173   @desc: Stop HCI transport
 174   @function name: HCI_TransportStop
 175   @input:  HciTrans - hci transport handle
 176   @output:
 177   @return:
 178   @notes: HCI transport communication will be halted.  All receive and pending TX packets will
 179           be flushed.
 180   @example:
 181   @see also:
 182 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
 183 void        HCI_TransportStop(HCI_TRANSPORT_HANDLE HciTrans);
 184
 185 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 186   @desc: Start the HCI transport
 187   @function name: HCI_TransportStart
 188   @input:  HciTrans - hci transport handle
 189   @output:
 190   @return: A_OK on success
 191   @notes: HCI transport communication will begin, the caller can expect the arrival
 192           of HCI recv packets as soon as this call returns.
 193   @example:
 194   @see also:
 195 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
 196 A_STATUS    HCI_TransportStart(HCI_TRANSPORT_HANDLE HciTrans);
 197
 198 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 199   @desc: Enable or Disable Asynchronous Recv
 200   @function name: HCI_TransportEnableDisableAsyncRecv
 201   @input:  HciTrans - hci transport handle
 202            Enable - enable or disable asynchronous recv
 203   @output:
 204   @return: A_OK on success
 205   @notes: This API must be called when HCI recv is handled synchronously
 206   @example:
 207   @see also:
 208 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
 209 A_STATUS    HCI_TransportEnableDisableAsyncRecv(HCI_TRANSPORT_HANDLE HciTrans, A_BOOL Enable);
 210
 211 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 212   @desc: Receive an event packet from the HCI transport synchronously using polling
 213   @function name: HCI_TransportRecvHCIEventSync
 214   @input:  HciTrans - hci transport handle
 215            pPacket - HTC packet to hold the recv data
 216            MaxPollMS - maximum polling duration in Milliseconds;
 217   @output:
 218   @return: A_OK on success
 219   @notes: This API should be used only during HCI device initialization, the caller must call
 220           HCI_TransportEnableDisableAsyncRecv with Enable=FALSE prior to using this API.
 221           This API will only capture HCI Event packets.
 222   @example:
 223   @see also: HCI_TransportEnableDisableAsyncRecv
 224 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
 225 A_STATUS    HCI_TransportRecvHCIEventSync(HCI_TRANSPORT_HANDLE HciTrans,
 226                                           HTC_PACKET           *pPacket,
 227                                           int                  MaxPollMS);
 228
 229 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 230   @desc: Set the desired baud rate for the underlying transport layer
 231   @function name: HCI_TransportSetBaudRate
 232   @input:  HciTrans - hci transport handle
 233            Baud - baud rate in bps
 234   @output:
 235   @return: A_OK on success
 236   @notes: This API should be used only after HCI device initialization
 237   @example:
 238   @see also:
 239 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
 240 A_STATUS    HCI_TransportSetBaudRate(HCI_TRANSPORT_HANDLE HciTrans, A_UINT32 Baud);
 241
 242 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 243   @desc: Enable/Disable HCI Transport Power Management
 244   @function name: HCI_TransportEnablePowerMgmt
 245   @input:  HciTrans - hci transport handle
 246            Enable - 1 = Enable, 0 = Disable
 247   @output:
 248   @return: A_OK on success
 249   @notes:
 250   @example:
 251   @see also:
 252 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
 253 A_STATUS HCI_TransportEnablePowerMgmt(HCI_TRANSPORT_HANDLE HciTrans, A_BOOL Enable);
 254
 255 #ifdef __cplusplus
 256 }
 257 #endif
 258
 259 #endif /* _HCI_TRANSPORT_API_H_ */