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 *, 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. 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 struct 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 *, struct htc_packet *); 81 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) */ 86 }; 87 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; 102 }; 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, struct 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: 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 141 @example: 142 @see also: 143 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ 144 int HCI_TransportAddReceivePkts(HCI_TRANSPORT_HANDLE HciTrans, struct 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: 0 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 int HCI_TransportSendPkt(HCI_TRANSPORT_HANDLE HciTrans, struct htc_packet *pPacket, 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: 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. 193 @example: 194 @see also: 195 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ 196 int 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: 0 on success 205 @notes: This API must be called when HCI recv is handled synchronously 206 @example: 207 @see also: 208 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ 209 int HCI_TransportEnableDisableAsyncRecv(HCI_TRANSPORT_HANDLE HciTrans, 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: 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. 222 @example: 223 @see also: HCI_TransportEnableDisableAsyncRecv 224 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ 225 int HCI_TransportRecvHCIEventSync(HCI_TRANSPORT_HANDLE HciTrans, 226 struct 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: 0 on success 236 @notes: This API should be used only after HCI device initialization 237 @example: 238 @see also: 239 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ 240 int HCI_TransportSetBaudRate(HCI_TRANSPORT_HANDLE HciTrans, u32 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: 0 on success 249 @notes: 250 @example: 251 @see also: 252 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ 253 int HCI_TransportEnablePowerMgmt(HCI_TRANSPORT_HANDLE HciTrans, bool Enable); 254 255 #ifdef __cplusplus 256 } 257 #endif 258 259 #endif /* _HCI_TRANSPORT_API_H_ */ 260