1/******************************************************************************
2 *
3 *  Copyright (C) 2009-2012 Broadcom Corporation
4 *
5 *  Licensed under the Apache License, Version 2.0 (the "License");
6 *  you may not use this file except in compliance with the License.
7 *  You may obtain a copy of the License at:
8 *
9 *  http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *  Unless required by applicable law or agreed to in writing, software
12 *  distributed under the License is distributed on an "AS IS" BASIS,
13 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *  See the License for the specific language governing permissions and
15 *  limitations under the License.
16 *
17 ******************************************************************************/
18
19#ifndef BT_VENDOR_LIB_H
20#define BT_VENDOR_LIB_H
21
22#include <stdint.h>
23#include <sys/cdefs.h>
24#include <sys/types.h>
25
26/** Struct types */
27
28
29/** Typedefs and defines */
30
31/** Vendor specific operations OPCODE */
32typedef enum {
33/*  [operation]
34 *      Power on or off the BT Controller.
35 *  [input param]
36 *      A pointer to int type with content of bt_vendor_power_state_t.
37 *      Typecasting conversion: (int *) param.
38 *  [return]
39 *      0 - default, don't care.
40 *  [callback]
41 *      None.
42 */
43    BT_VND_OP_POWER_CTRL,
44
45/*  [operation]
46 *      Perform any vendor specific initialization or configuration
47 *      on the BT Controller. This is called before stack initialization.
48 *  [input param]
49 *      None.
50 *  [return]
51 *      0 - default, don't care.
52 *  [callback]
53 *      Must call fwcfg_cb to notify the stack of the completion of vendor
54 *      specific initialization once it has been done.
55 */
56    BT_VND_OP_FW_CFG,
57
58/*  [operation]
59 *      Perform any vendor specific SCO/PCM configuration on the BT Controller.
60 *      This is called after stack initialization.
61 *  [input param]
62 *      None.
63 *  [return]
64 *      0 - default, don't care.
65 *  [callback]
66 *      Must call scocfg_cb to notify the stack of the completion of vendor
67 *      specific SCO configuration once it has been done.
68 */
69    BT_VND_OP_SCO_CFG,
70
71/*  [operation]
72 *      Open UART port on where the BT Controller is attached.
73 *      This is called before stack initialization.
74 *  [input param]
75 *      A pointer to int array type for open file descriptors.
76 *      The mapping of HCI channel to fd slot in the int array is given in
77 *      bt_vendor_hci_channels_t.
78 *      And, it requires the vendor lib to fill up the content before returning
79 *      the call.
80 *      Typecasting conversion: (int (*)[]) param.
81 *  [return]
82 *      Numbers of opened file descriptors.
83 *      Valid number:
84 *          1 - CMD/EVT/ACL-In/ACL-Out via the same fd (e.g. UART)
85 *          2 - CMD/EVT on one fd, and ACL-In/ACL-Out on the other fd
86 *          4 - CMD, EVT, ACL-In, ACL-Out are on their individual fd
87 *  [callback]
88 *      None.
89 */
90    BT_VND_OP_USERIAL_OPEN,
91
92/*  [operation]
93 *      Close the previously opened UART port.
94 *  [input param]
95 *      None.
96 *  [return]
97 *      0 - default, don't care.
98 *  [callback]
99 *      None.
100 */
101    BT_VND_OP_USERIAL_CLOSE,
102
103/*  [operation]
104 *      Get the LPM idle timeout in milliseconds.
105 *      The stack uses this information to launch a timer delay before it
106 *      attempts to de-assert LPM WAKE signal once downstream HCI packet
107 *      has been delivered.
108 *  [input param]
109 *      A pointer to uint32_t type which is passed in by the stack. And, it
110 *      requires the vendor lib to fill up the content before returning
111 *      the call.
112 *      Typecasting conversion: (uint32_t *) param.
113 *  [return]
114 *      0 - default, don't care.
115 *  [callback]
116 *      None.
117 */
118    BT_VND_OP_GET_LPM_IDLE_TIMEOUT,
119
120/*  [operation]
121 *      Enable or disable LPM mode on BT Controller.
122 *  [input param]
123 *      A pointer to uint8_t type with content of bt_vendor_lpm_mode_t.
124 *      Typecasting conversion: (uint8_t *) param.
125 *  [return]
126 *      0 - default, don't care.
127 *  [callback]
128 *      Must call lpm_cb to notify the stack of the completion of LPM
129 *      disable/enable process once it has been done.
130 */
131    BT_VND_OP_LPM_SET_MODE,
132
133/*  [operation]
134 *      Assert or Deassert LPM WAKE on BT Controller.
135 *  [input param]
136 *      A pointer to uint8_t type with content of bt_vendor_lpm_wake_state_t.
137 *      Typecasting conversion: (uint8_t *) param.
138 *  [return]
139 *      0 - default, don't care.
140 *  [callback]
141 *      None.
142 */
143    BT_VND_OP_LPM_WAKE_SET_STATE,
144
145/*  [operation]
146 *      Perform any vendor specific commands related to audio state changes.
147 *  [input param]
148 *      a pointer to bt_vendor_op_audio_state_t indicating what audio state is
149 *      set.
150 *  [return]
151 *      0 - default, don't care.
152 *  [callback]
153 *      None.
154 */
155    BT_VND_OP_SET_AUDIO_STATE,
156
157/*  [operation]
158 *      The epilog call to the vendor module so that it can perform any
159 *      vendor-specific processes (e.g. send a HCI_RESET to BT Controller)
160 *      before the caller calls for cleanup().
161 *  [input param]
162 *      None.
163 *  [return]
164 *      0 - default, don't care.
165 *  [callback]
166 *      Must call epilog_cb to notify the stack of the completion of vendor
167 *      specific epilog process once it has been done.
168 */
169    BT_VND_OP_EPILOG,
170
171/*  [operation]
172 *      Call to the vendor module so that it can perform all vendor-specific
173 *      operations to start offloading a2dp media encode & tx.
174 *  [input param]
175 *      pointer to bt_vendor_op_a2dp_offload_start_t containing elements
176 *      required for VND FW to setup a2dp offload.
177 *  [return]
178 *      0  - default, dont care.
179 *  [callback]
180 *      Must call a2dp_offload_start_cb to notify the stack of the
181 *      completion of vendor specific setup process once it has been done.
182 */
183    BT_VND_OP_A2DP_OFFLOAD_START,
184
185/*  [operation]
186 *      Call to the vendor module so that it can perform all vendor-specific
187 *      operations to suspend offloading a2dp media encode & tx.
188 *  [input param]
189 *      pointer to bt_vendor_op_a2dp_offload_t containing elements
190 *      required for VND FW to setup a2dp offload.
191 *  [return]
192 *      0  - default, dont care.
193 *  [callback]
194 *      Must call a2dp_offload_cb to notify the stack of the
195 *      completion of vendor specific setup process once it has been done.
196 */
197    BT_VND_OP_A2DP_OFFLOAD_STOP,
198
199} bt_vendor_opcode_t;
200
201/** Power on/off control states */
202typedef enum {
203    BT_VND_PWR_OFF,
204    BT_VND_PWR_ON,
205}  bt_vendor_power_state_t;
206
207/** Define HCI channel identifier in the file descriptors array
208    used in BT_VND_OP_USERIAL_OPEN operation.
209 */
210typedef enum {
211    CH_CMD,     // HCI Command channel
212    CH_EVT,     // HCI Event channel
213    CH_ACL_OUT, // HCI ACL downstream channel
214    CH_ACL_IN,  // HCI ACL upstream channel
215
216    CH_MAX      // Total channels
217}  bt_vendor_hci_channels_t;
218
219/** LPM disable/enable request */
220typedef enum {
221    BT_VND_LPM_DISABLE,
222    BT_VND_LPM_ENABLE,
223} bt_vendor_lpm_mode_t;
224
225/** LPM WAKE set state request */
226typedef enum {
227    BT_VND_LPM_WAKE_ASSERT,
228    BT_VND_LPM_WAKE_DEASSERT,
229} bt_vendor_lpm_wake_state_t;
230
231/** Callback result values */
232typedef enum {
233    BT_VND_OP_RESULT_SUCCESS,
234    BT_VND_OP_RESULT_FAIL,
235} bt_vendor_op_result_t;
236
237/** audio (SCO) state changes triggering VS commands for configuration */
238typedef struct {
239    uint16_t    handle;
240    uint16_t    peer_codec;
241    uint16_t    state;
242} bt_vendor_op_audio_state_t;
243
244/*
245 * Bluetooth Host/Controller Vendor callback structure.
246 */
247
248/* vendor initialization/configuration callback */
249typedef void (*cfg_result_cb)(bt_vendor_op_result_t result);
250
251/* datapath buffer allocation callback (callout)
252 *
253 *  Vendor lib needs to request a buffer through the alloc callout function
254 *  from HCI lib if the buffer is for constructing a HCI Command packet which
255 *  will be sent through xmit_cb to BT Controller.
256 *
257 *  For each buffer allocation, the requested size needs to be big enough to
258 *  accommodate the below header plus a complete HCI packet --
259 *      typedef struct
260 *      {
261 *          uint16_t          event;
262 *          uint16_t          len;
263 *          uint16_t          offset;
264 *          uint16_t          layer_specific;
265 *      } HC_BT_HDR;
266 *
267 *  HCI lib returns a pointer to the buffer where Vendor lib should use to
268 *  construct a HCI command packet as below format:
269 *
270 *  --------------------------------------------
271 *  |  HC_BT_HDR  |  HCI command               |
272 *  --------------------------------------------
273 *  where
274 *      HC_BT_HDR.event = 0x2000;
275 *      HC_BT_HDR.len = Length of HCI command;
276 *      HC_BT_HDR.offset = 0;
277 *      HC_BT_HDR.layer_specific = 0;
278 *
279 *  For example, a HCI_RESET Command will be formed as
280 *  ------------------------
281 *  |  HC_BT_HDR  |03|0c|00|
282 *  ------------------------
283 *  with
284 *      HC_BT_HDR.event = 0x2000;
285 *      HC_BT_HDR.len = 3;
286 *      HC_BT_HDR.offset = 0;
287 *      HC_BT_HDR.layer_specific = 0;
288 */
289typedef void* (*malloc_cb)(int size);
290
291/* datapath buffer deallocation callback (callout) */
292typedef void (*mdealloc_cb)(void *p_buf);
293
294/* define callback of the cmd_xmit_cb
295 *
296 *  The callback function which HCI lib will call with the return of command
297 *  complete packet. Vendor lib is responsible for releasing the buffer passed
298 *  in at the p_mem parameter by calling dealloc callout function.
299 */
300typedef void (*tINT_CMD_CBACK)(void *p_mem);
301
302/* hci command packet transmit callback (callout)
303 *
304 *  Vendor lib calls xmit_cb callout function in order to send a HCI Command
305 *  packet to BT Controller. The buffer carrying HCI Command packet content
306 *  needs to be first allocated through the alloc callout function.
307 *  HCI lib will release the buffer for Vendor lib once it has delivered the
308 *  packet content to BT Controller.
309 *
310 *  Vendor lib needs also provide a callback function (p_cback) which HCI lib
311 *  will call with the return of command complete packet.
312 *
313 *  The opcode parameter gives the HCI OpCode (combination of OGF and OCF) of
314 *  HCI Command packet. For example, opcode = 0x0c03 for the HCI_RESET command
315 *  packet.
316 */
317typedef uint8_t (*cmd_xmit_cb)(uint16_t opcode, void *p_buf, tINT_CMD_CBACK p_cback);
318
319typedef void (*cfg_a2dp_cb)(bt_vendor_op_result_t result, bt_vendor_opcode_t op, uint8_t bta_av_handle);
320
321typedef struct {
322    /** set to sizeof(bt_vendor_callbacks_t) */
323    size_t         size;
324
325    /*
326     * Callback and callout functions have implemented in HCI libray
327     * (libbt-hci.so).
328     */
329
330    /* notifies caller result of firmware configuration request */
331    cfg_result_cb  fwcfg_cb;
332
333    /* notifies caller result of sco configuration request */
334    cfg_result_cb  scocfg_cb;
335
336    /* notifies caller result of lpm enable/disable */
337    cfg_result_cb  lpm_cb;
338
339    /* notifies the result of codec setting */
340    cfg_result_cb audio_state_cb;
341
342    /* buffer allocation request */
343    malloc_cb   alloc;
344
345    /* buffer deallocation request */
346    mdealloc_cb dealloc;
347
348    /* hci command packet transmit request */
349    cmd_xmit_cb xmit_cb;
350
351    /* notifies caller completion of epilog process */
352    cfg_result_cb epilog_cb;
353
354    /* notifies status of a2dp offload cmd's */
355    cfg_a2dp_cb a2dp_offload_cb;
356} bt_vendor_callbacks_t;
357
358/** A2DP offload request */
359typedef struct {
360    uint8_t   bta_av_handle;                 /* BTA_AV Handle for callbacks */
361    uint16_t  xmit_quota;                    /* Total ACL quota for light stack */
362    uint16_t  acl_data_size;                 /* Max ACL data size across HCI transport */
363    uint16_t  stream_mtu;
364    uint16_t  local_cid;
365    uint16_t  remote_cid;
366    uint16_t  lm_handle;
367    uint8_t   is_flushable;                  /* TRUE if flushable channel */
368    uint32_t  stream_source;
369    uint8_t   codec_info[10];                /* Codec capabilities array */
370} bt_vendor_op_a2dp_offload_t;
371
372/*
373 * Bluetooth Host/Controller VENDOR Interface
374 */
375typedef struct {
376    /** Set to sizeof(bt_vndor_interface_t) */
377    size_t          size;
378
379    /*
380     * Functions need to be implemented in Vendor libray (libbt-vendor.so).
381     */
382
383    /**
384     * Caller will open the interface and pass in the callback routines
385     * to the implemenation of this interface.
386     */
387    int   (*init)(const bt_vendor_callbacks_t* p_cb, unsigned char *local_bdaddr);
388
389    /**  Vendor specific operations */
390    int (*op)(bt_vendor_opcode_t opcode, void *param);
391
392    /** Closes the interface */
393    void  (*cleanup)(void);
394} bt_vendor_interface_t;
395
396
397/*
398 * External shared lib functions/data
399 */
400
401/* Entry point of DLib --
402 *      Vendor library needs to implement the body of bt_vendor_interface_t
403 *      structure and uses the below name as the variable name. HCI library
404 *      will use this symbol name to get address of the object through the
405 *      dlsym call.
406 */
407extern const bt_vendor_interface_t BLUETOOTH_VENDOR_LIB_INTERFACE;
408
409#endif /* BT_VENDOR_LIB_H */
410
411