264 lines
12 KiB
C
264 lines
12 KiB
C
|
//------------------------------------------------------------------------------
|
||
|
|
// ISC License (ISC)
|
||
|
|
//
|
||
|
|
// Copyright (c) 2009-2010, The Linux Foundation
|
||
|
|
// All rights reserved.
|
||
|
|
// Software was previously licensed under ISC license by Qualcomm Atheros, Inc.
|
||
|
|
//
|
||
|
|
//
|
||
|
|
// Permission to use, copy, modify, and/or distribute this software for any
|
||
|
|
// purpose with or without fee is hereby granted, provided that the above
|
||
|
|
// copyright notice and this permission notice appear in all copies.
|
||
|
|
//
|
||
|
|
// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
||
|
|
// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
||
|
|
// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
||
|
|
// ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
||
|
|
// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
||
|
|
// ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
||
|
|
// OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||
|
|
//
|
||
|
|
//
|
||
|
|
//------------------------------------------------------------------------------
|
||
|
|
//==============================================================================
|
||
|
|
// Author(s): ="Atheros"
|
||
|
|
//==============================================================================
|
||
|
|
#ifndef _HCI_TRANSPORT_API_H_
|
||
|
|
#define _HCI_TRANSPORT_API_H_
|
||
|
|
|
||
|
|
/* Bluetooth HCI packets are stored in HTC packet containers */
|
||
|
|
#include "htc_packet.h"
|
||
|
|
|
||
|
|
#ifdef __cplusplus
|
||
|
|
extern "C" {
|
||
|
|
#endif /* __cplusplus */
|
||
|
|
|
||
|
|
typedef void *HCI_TRANSPORT_HANDLE;
|
||
|
|
|
||
|
|
typedef HTC_ENDPOINT_ID HCI_TRANSPORT_PACKET_TYPE;
|
||
|
|
|
||
|
|
/* we map each HCI packet class to a static Endpoint ID */
|
||
|
|
#define HCI_COMMAND_TYPE ENDPOINT_1
|
||
|
|
#define HCI_EVENT_TYPE ENDPOINT_2
|
||
|
|
#define HCI_ACL_TYPE ENDPOINT_3
|
||
|
|
#define HCI_PACKET_INVALID ENDPOINT_MAX
|
||
|
|
|
||
|
|
#define HCI_GET_PACKET_TYPE(pP) (pP)->Endpoint
|
||
|
|
#define HCI_SET_PACKET_TYPE(pP,s) (pP)->Endpoint = (s)
|
||
|
|
|
||
|
|
/* callback when an HCI packet was completely sent */
|
||
|
|
typedef void (*HCI_TRANSPORT_SEND_PKT_COMPLETE)(void *, HTC_PACKET *);
|
||
|
|
/* callback when an HCI packet is received */
|
||
|
|
typedef void (*HCI_TRANSPORT_RECV_PKT)(void *, HTC_PACKET *);
|
||
|
|
/* Optional 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.
|
||
|
|
* A refill callback is used for the reception of ACL and EVENT packets. The caller must
|
||
|
|
* set the watermark trigger point to cause a refill.
|
||
|
|
*/
|
||
|
|
typedef void (*HCI_TRANSPORT_RECV_REFILL)(void *, HCI_TRANSPORT_PACKET_TYPE Type, int BuffersAvailable);
|
||
|
|
/* Optional receive packet refill
|
||
|
|
* On some systems packet buffers are an extremely limited resource. Rather than
|
||
|
|
* queue largest-possible-sized buffers to the HCI bridge, some systems would rather
|
||
|
|
* allocate a specific size as the packet is received. The trade off is
|
||
|
|
* slightly more processing (callback invoked for each RX packet)
|
||
|
|
* for the benefit of committing fewer buffer resources into the bridge.
|
||
|
|
*
|
||
|
|
* The callback is provided the length of the pending packet to fetch. This includes the
|
||
|
|
* full transport header, HCI header, plus the length of payload. The callback can return a pointer to
|
||
|
|
* the allocated HTC packet for immediate use.
|
||
|
|
*
|
||
|
|
* NOTE*** This callback is mutually exclusive with the the refill callback above.
|
||
|
|
*
|
||
|
|
* */
|
||
|
|
typedef HTC_PACKET *(*HCI_TRANSPORT_RECV_ALLOC)(void *, HCI_TRANSPORT_PACKET_TYPE Type, int Length);
|
||
|
|
|
||
|
|
typedef enum _HCI_SEND_FULL_ACTION {
|
||
|
|
HCI_SEND_FULL_KEEP = 0, /* packet that overflowed should be kept in the queue */
|
||
|
|
HCI_SEND_FULL_DROP = 1, /* packet that overflowed should be dropped */
|
||
|
|
} HCI_SEND_FULL_ACTION;
|
||
|
|
|
||
|
|
/* callback when an HCI send queue exceeds the caller's MaxSendQueueDepth threshold,
|
||
|
|
* the callback must return the send full action to take (either DROP or KEEP) */
|
||
|
|
typedef HCI_SEND_FULL_ACTION (*HCI_TRANSPORT_SEND_FULL)(void *, HTC_PACKET *);
|
||
|
|
|
||
|
|
typedef struct {
|
||
|
|
int HeadRoom; /* number of bytes in front of HCI packet for header space */
|
||
|
|
int TailRoom; /* number of bytes at the end of the HCI packet for tail space */
|
||
|
|
int IOBlockPad; /* I/O block padding required (always a power of 2) */
|
||
|
|
} HCI_TRANSPORT_PROPERTIES;
|
||
|
|
|
||
|
|
typedef struct _HCI_TRANSPORT_CONFIG_INFO {
|
||
|
|
int ACLRecvBufferWaterMark; /* low watermark to trigger recv refill */
|
||
|
|
int EventRecvBufferWaterMark; /* low watermark to trigger recv refill */
|
||
|
|
int MaxSendQueueDepth; /* max number of packets in the single send queue */
|
||
|
|
void *pContext; /* context for all callbacks */
|
||
|
|
void (*TransportFailure)(void *pContext, A_STATUS Status); /* transport failure callback */
|
||
|
|
A_STATUS (*TransportReady)(HCI_TRANSPORT_HANDLE, HCI_TRANSPORT_PROPERTIES *,void *pContext); /* transport is ready */
|
||
|
|
void (*TransportRemoved)(void *pContext); /* transport was removed */
|
||
|
|
/* packet processing callbacks */
|
||
|
|
HCI_TRANSPORT_SEND_PKT_COMPLETE pHCISendComplete;
|
||
|
|
HCI_TRANSPORT_RECV_PKT pHCIPktRecv;
|
||
|
|
HCI_TRANSPORT_RECV_REFILL pHCIPktRecvRefill;
|
||
|
|
HCI_TRANSPORT_RECV_ALLOC pHCIPktRecvAlloc;
|
||
|
|
HCI_TRANSPORT_SEND_FULL pHCISendFull;
|
||
|
|
} HCI_TRANSPORT_CONFIG_INFO;
|
||
|
|
|
||
|
|
/* ------ Function Prototypes ------ */
|
||
|
|
/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||
|
|
@desc: Attach to the HCI transport module
|
||
|
|
@function name: HCI_TransportAttach
|
||
|
|
@input: HTCHandle - HTC handle (see HTC apis)
|
||
|
|
pInfo - initialization information
|
||
|
|
@output:
|
||
|
|
@return: HCI_TRANSPORT_HANDLE on success, NULL on failure
|
||
|
|
@notes: The HTC module provides HCI transport services.
|
||
|
|
@example:
|
||
|
|
@see also: HCI_TransportDetach
|
||
|
|
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
|
||
|
|
HCI_TRANSPORT_HANDLE HCI_TransportAttach(void *HTCHandle, HCI_TRANSPORT_CONFIG_INFO *pInfo);
|
||
|
|
|
||
|
|
/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||
|
|
@desc: Detach from the HCI transport module
|
||
|
|
@function name: HCI_TransportDetach
|
||
|
|
@input: HciTrans - HCI transport handle
|
||
|
|
pInfo - initialization information
|
||
|
|
@output:
|
||
|
|
@return:
|
||
|
|
@notes:
|
||
|
|
@example:
|
||
|
|
@see also:
|
||
|
|
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
|
||
|
|
void HCI_TransportDetach(HCI_TRANSPORT_HANDLE HciTrans);
|
||
|
|
|
||
|
|
/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||
|
|
@desc: Add receive packets to the HCI transport
|
||
|
|
@function name: HCI_TransportAddReceivePkts
|
||
|
|
@input: HciTrans - HCI transport handle
|
||
|
|
pQueue - a queue holding one or more packets
|
||
|
|
@output:
|
||
|
|
@return: A_OK on success
|
||
|
|
@notes: user must supply HTC packets for capturing incomming HCI packets. The caller
|
||
|
|
must initialize each HTC packet using the SET_HTC_PACKET_INFO_RX_REFILL()
|
||
|
|
macro. Each packet in the queue must be of the same type and length
|
||
|
|
@example:
|
||
|
|
@see also:
|
||
|
|
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
|
||
|
|
A_STATUS HCI_TransportAddReceivePkts(HCI_TRANSPORT_HANDLE HciTrans, HTC_PACKET_QUEUE *pQueue);
|
||
|
|
|
||
|
|
/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||
|
|
@desc: Send an HCI packet packet
|
||
|
|
@function name: HCI_TransportSendPkt
|
||
|
|
@input: HciTrans - HCI transport handle
|
||
|
|
pPacket - packet to send
|
||
|
|
Synchronous - send the packet synchronously (blocking)
|
||
|
|
@output:
|
||
|
|
@return: A_OK
|
||
|
|
@notes: Caller must initialize packet using SET_HTC_PACKET_INFO_TX() and
|
||
|
|
HCI_SET_PACKET_TYPE() macros to prepare the packet.
|
||
|
|
If Synchronous is set to FALSE the call is fully asynchronous. On error or completion,
|
||
|
|
the registered send complete callback will be called.
|
||
|
|
If Synchronous is set to TRUE, the call will block until the packet is sent, if the
|
||
|
|
interface cannot send the packet within a 2 second timeout, the function will return
|
||
|
|
the failure code : A_EBUSY.
|
||
|
|
|
||
|
|
Synchronous Mode should only be used at start-up to initialize the HCI device using
|
||
|
|
custom HCI commands. It should NOT be mixed with Asynchronous operations. Mixed synchronous
|
||
|
|
and asynchronous operation behavior is undefined.
|
||
|
|
|
||
|
|
@example:
|
||
|
|
@see also:
|
||
|
|
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
|
||
|
|
A_STATUS HCI_TransportSendPkt(HCI_TRANSPORT_HANDLE HciTrans, HTC_PACKET *pPacket, A_BOOL Synchronous);
|
||
|
|
|
||
|
|
|
||
|
|
/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||
|
|
@desc: Stop HCI transport
|
||
|
|
@function name: HCI_TransportStop
|
||
|
|
@input: HciTrans - hci transport handle
|
||
|
|
@output:
|
||
|
|
@return:
|
||
|
|
@notes: HCI transport communication will be halted. All receive and pending TX packets will
|
||
|
|
be flushed.
|
||
|
|
@example:
|
||
|
|
@see also:
|
||
|
|
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
|
||
|
|
void HCI_TransportStop(HCI_TRANSPORT_HANDLE HciTrans);
|
||
|
|
|
||
|
|
/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||
|
|
@desc: Start the HCI transport
|
||
|
|
@function name: HCI_TransportStart
|
||
|
|
@input: HciTrans - hci transport handle
|
||
|
|
@output:
|
||
|
|
@return: A_OK on success
|
||
|
|
@notes: HCI transport communication will begin, the caller can expect the arrival
|
||
|
|
of HCI recv packets as soon as this call returns.
|
||
|
|
@example:
|
||
|
|
@see also:
|
||
|
|
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
|
||
|
|
A_STATUS HCI_TransportStart(HCI_TRANSPORT_HANDLE HciTrans);
|
||
|
|
|
||
|
|
/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||
|
|
@desc: Enable or Disable Asynchronous Recv
|
||
|
|
@function name: HCI_TransportEnableDisableAsyncRecv
|
||
|
|
@input: HciTrans - hci transport handle
|
||
|
|
Enable - enable or disable asynchronous recv
|
||
|
|
@output:
|
||
|
|
@return: A_OK on success
|
||
|
|
@notes: This API must be called when HCI recv is handled synchronously
|
||
|
|
@example:
|
||
|
|
@see also:
|
||
|
|
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
|
||
|
|
A_STATUS HCI_TransportEnableDisableAsyncRecv(HCI_TRANSPORT_HANDLE HciTrans, A_BOOL Enable);
|
||
|
|
|
||
|
|
/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||
|
|
@desc: Receive an event packet from the HCI transport synchronously using polling
|
||
|
|
@function name: HCI_TransportRecvHCIEventSync
|
||
|
|
@input: HciTrans - hci transport handle
|
||
|
|
pPacket - HTC packet to hold the recv data
|
||
|
|
MaxPollMS - maximum polling duration in Milliseconds;
|
||
|
|
@output:
|
||
|
|
@return: A_OK on success
|
||
|
|
@notes: This API should be used only during HCI device initialization, the caller must call
|
||
|
|
HCI_TransportEnableDisableAsyncRecv with Enable=FALSE prior to using this API.
|
||
|
|
This API will only capture HCI Event packets.
|
||
|
|
@example:
|
||
|
|
@see also: HCI_TransportEnableDisableAsyncRecv
|
||
|
|
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
|
||
|
|
A_STATUS HCI_TransportRecvHCIEventSync(HCI_TRANSPORT_HANDLE HciTrans,
|
||
|
|
HTC_PACKET *pPacket,
|
||
|
|
int MaxPollMS);
|
||
|
|
|
||
|
|
/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||
|
|
@desc: Set the desired baud rate for the underlying transport layer
|
||
|
|
@function name: HCI_TransportSetBaudRate
|
||
|
|
@input: HciTrans - hci transport handle
|
||
|
|
Baud - baud rate in bps
|
||
|
|
@output:
|
||
|
|
@return: A_OK on success
|
||
|
|
@notes: This API should be used only after HCI device initialization
|
||
|
|
@example:
|
||
|
|
@see also:
|
||
|
|
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
|
||
|
|
A_STATUS HCI_TransportSetBaudRate(HCI_TRANSPORT_HANDLE HciTrans, A_UINT32 Baud);
|
||
|
|
|
||
|
|
/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||
|
|
@desc: Enable/Disable HCI Transport Power Management
|
||
|
|
@function name: HCI_TransportEnablePowerMgmt
|
||
|
|
@input: HciTrans - hci transport handle
|
||
|
|
Enable - 1 = Enable, 0 = Disable
|
||
|
|
@output:
|
||
|
|
@return: A_OK on success
|
||
|
|
@notes:
|
||
|
|
@example:
|
||
|
|
@see also:
|
||
|
|
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/
|
||
|
|
A_STATUS HCI_TransportEnablePowerMgmt(HCI_TRANSPORT_HANDLE HciTrans, A_BOOL Enable);
|
||
|
|
|
||
|
|
#ifdef __cplusplus
|
||
|
|
}
|
||
|
|
#endif
|
||
|
|
|
||
|
|
#endif /* _HCI_TRANSPORT_API_H_ */
|