1 //------------------------------------------------------------------------------
2 // Copyright (c) 2009-2010 Atheros Corporation. All rights reserved.
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.
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.
18 //------------------------------------------------------------------------------
19 //==============================================================================
20 // Author(s): ="Atheros"
21 //==============================================================================
22 #ifndef _HCI_TRANSPORT_API_H_
23 #define _HCI_TRANSPORT_API_H_
25 /* Bluetooth HCI packets are stored in HTC packet containers */
26 #include "htc_packet.h"
30 #endif /* __cplusplus */
32 typedef void *HCI_TRANSPORT_HANDLE;
34 typedef HTC_ENDPOINT_ID HCI_TRANSPORT_PACKET_TYPE;
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
42 #define HCI_GET_PACKET_TYPE(pP) (pP)->Endpoint
43 #define HCI_SET_PACKET_TYPE(pP,s) (pP)->Endpoint = (s)
45 /* callback when an HCI packet was completely sent */
46 typedef void (*HCI_TRANSPORT_SEND_PKT_COMPLETE)(void *, struct htc_packet *);
47 /* callback when an HCI packet is received */
48 typedef void (*HCI_TRANSPORT_RECV_PKT)(void *, struct 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.
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.
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.
68 * NOTE*** This callback is mutually exclusive with the the refill callback above.
71 typedef struct htc_packet *(*HCI_TRANSPORT_RECV_ALLOC)(void *, HCI_TRANSPORT_PACKET_TYPE Type, int Length);
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;
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 *, struct htc_packet *);
82 struct hci_transport_properties {
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) */
88 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, int Status); /* transport failure callback */
94 int (*TransportReady)(HCI_TRANSPORT_HANDLE, struct 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;
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
111 @return: HCI_TRANSPORT_HANDLE on success, NULL on failure
112 @notes: The HTC module provides HCI transport services.
114 @see also: HCI_TransportDetach
115 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
116 HCI_TRANSPORT_HANDLE HCI_TransportAttach(void *HTCHandle, struct hci_transport_config_info *pInfo);
118 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
119 @desc: Detach from the HCI transport module
120 @function name: HCI_TransportDetach
121 @input: HciTrans - HCI transport handle
122 pInfo - initialization information
128 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
129 void HCI_TransportDetach(HCI_TRANSPORT_HANDLE HciTrans);
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
137 @return: 0 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
143 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
144 int HCI_TransportAddReceivePkts(HCI_TRANSPORT_HANDLE HciTrans, struct htc_packet_queue *pQueue);
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)
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.
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.
168 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
169 int HCI_TransportSendPkt(HCI_TRANSPORT_HANDLE HciTrans, struct htc_packet *pPacket, bool Synchronous);
172 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
173 @desc: Stop HCI transport
174 @function name: HCI_TransportStop
175 @input: HciTrans - hci transport handle
178 @notes: HCI transport communication will be halted. All receive and pending TX packets will
182 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
183 void HCI_TransportStop(HCI_TRANSPORT_HANDLE HciTrans);
185 /*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
186 @desc: Start the HCI transport
187 @function name: HCI_TransportStart
188 @input: HciTrans - hci transport handle
190 @return: 0 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.
195 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
196 int HCI_TransportStart(HCI_TRANSPORT_HANDLE HciTrans);
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
204 @return: 0 on success
205 @notes: This API must be called when HCI recv is handled synchronously
208 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
209 int HCI_TransportEnableDisableAsyncRecv(HCI_TRANSPORT_HANDLE HciTrans, bool Enable);
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;
218 @return: 0 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.
223 @see also: HCI_TransportEnableDisableAsyncRecv
224 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
225 int HCI_TransportRecvHCIEventSync(HCI_TRANSPORT_HANDLE HciTrans,
226 struct htc_packet *pPacket,
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
235 @return: 0 on success
236 @notes: This API should be used only after HCI device initialization
239 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
240 int HCI_TransportSetBaudRate(HCI_TRANSPORT_HANDLE HciTrans, u32 Baud);
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
248 @return: 0 on success
252 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
253 int HCI_TransportEnablePowerMgmt(HCI_TRANSPORT_HANDLE HciTrans, bool Enable);
259 #endif /* _HCI_TRANSPORT_API_H_ */