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} bt_vendor_opcode_t;
171
172/** Power on/off control states */
173typedef enum {
174    BT_VND_PWR_OFF,
175    BT_VND_PWR_ON,
176}  bt_vendor_power_state_t;
177
178/** Define HCI channel identifier in the file descriptors array
179    used in BT_VND_OP_USERIAL_OPEN operation.
180 */
181typedef enum {
182    CH_CMD,     // HCI Command channel
183    CH_EVT,     // HCI Event channel
184    CH_ACL_OUT, // HCI ACL downstream channel
185    CH_ACL_IN,  // HCI ACL upstream channel
186
187    CH_MAX      // Total channels
188}  bt_vendor_hci_channels_t;
189
190/** LPM disable/enable request */
191typedef enum {
192    BT_VND_LPM_DISABLE,
193    BT_VND_LPM_ENABLE,
194} bt_vendor_lpm_mode_t;
195
196/** LPM WAKE set state request */
197typedef enum {
198    BT_VND_LPM_WAKE_ASSERT,
199    BT_VND_LPM_WAKE_DEASSERT,
200} bt_vendor_lpm_wake_state_t;
201
202/** Callback result values */
203typedef enum {
204    BT_VND_OP_RESULT_SUCCESS,
205    BT_VND_OP_RESULT_FAIL,
206} bt_vendor_op_result_t;
207
208/** audio (SCO) state changes triggering VS commands for configuration */
209typedef struct {
210    uint16_t    handle;
211    uint16_t    peer_codec;
212    uint16_t    state;
213} bt_vendor_op_audio_state_t;
214
215/*
216 * Bluetooth Host/Controller Vendor callback structure.
217 */
218
219/* vendor initialization/configuration callback */
220typedef void (*cfg_result_cb)(bt_vendor_op_result_t result);
221
222/* datapath buffer allocation callback (callout)
223 *
224 *  Vendor lib needs to request a buffer through the alloc callout function
225 *  from HCI lib if the buffer is for constructing a HCI Command packet which
226 *  will be sent through xmit_cb to BT Controller.
227 *
228 *  For each buffer allocation, the requested size needs to be big enough to
229 *  accommodate the below header plus a complete HCI packet --
230 *      typedef struct
231 *      {
232 *          uint16_t          event;
233 *          uint16_t          len;
234 *          uint16_t          offset;
235 *          uint16_t          layer_specific;
236 *      } HC_BT_HDR;
237 *
238 *  HCI lib returns a pointer to the buffer where Vendor lib should use to
239 *  construct a HCI command packet as below format:
240 *
241 *  --------------------------------------------
242 *  |  HC_BT_HDR  |  HCI command               |
243 *  --------------------------------------------
244 *  where
245 *      HC_BT_HDR.event = 0x2000;
246 *      HC_BT_HDR.len = Length of HCI command;
247 *      HC_BT_HDR.offset = 0;
248 *      HC_BT_HDR.layer_specific = 0;
249 *
250 *  For example, a HCI_RESET Command will be formed as
251 *  ------------------------
252 *  |  HC_BT_HDR  |03|0c|00|
253 *  ------------------------
254 *  with
255 *      HC_BT_HDR.event = 0x2000;
256 *      HC_BT_HDR.len = 3;
257 *      HC_BT_HDR.offset = 0;
258 *      HC_BT_HDR.layer_specific = 0;
259 */
260typedef void* (*malloc_cb)(int size);
261
262/* datapath buffer deallocation callback (callout) */
263typedef void (*mdealloc_cb)(void *p_buf);
264
265/* define callback of the cmd_xmit_cb
266 *
267 *  The callback function which HCI lib will call with the return of command
268 *  complete packet. Vendor lib is responsible for releasing the buffer passed
269 *  in at the p_mem parameter by calling dealloc callout function.
270 */
271typedef void (*tINT_CMD_CBACK)(void *p_mem);
272
273/* hci command packet transmit callback (callout)
274 *
275 *  Vendor lib calls xmit_cb callout function in order to send a HCI Command
276 *  packet to BT Controller. The buffer carrying HCI Command packet content
277 *  needs to be first allocated through the alloc callout function.
278 *  HCI lib will release the buffer for Vendor lib once it has delivered the
279 *  packet content to BT Controller.
280 *
281 *  Vendor lib needs also provide a callback function (p_cback) which HCI lib
282 *  will call with the return of command complete packet.
283 *
284 *  The opcode parameter gives the HCI OpCode (combination of OGF and OCF) of
285 *  HCI Command packet. For example, opcode = 0x0c03 for the HCI_RESET command
286 *  packet.
287 */
288typedef uint8_t (*cmd_xmit_cb)(uint16_t opcode, void *p_buf, tINT_CMD_CBACK p_cback);
289
290typedef struct {
291    /** set to sizeof(bt_vendor_callbacks_t) */
292    size_t         size;
293
294    /*
295     * Callback and callout functions have implemented in HCI libray
296     * (libbt-hci.so).
297     */
298
299    /* notifies caller result of firmware configuration request */
300    cfg_result_cb  fwcfg_cb;
301
302    /* notifies caller result of sco configuration request */
303    cfg_result_cb  scocfg_cb;
304
305    /* notifies caller result of lpm enable/disable */
306    cfg_result_cb  lpm_cb;
307
308    /* notifies the result of codec setting */
309    cfg_result_cb audio_state_cb;
310
311    /* buffer allocation request */
312    malloc_cb   alloc;
313
314    /* buffer deallocation request */
315    mdealloc_cb dealloc;
316
317    /* hci command packet transmit request */
318    cmd_xmit_cb xmit_cb;
319
320    /* notifies caller completion of epilog process */
321    cfg_result_cb epilog_cb;
322} bt_vendor_callbacks_t;
323
324/*
325 * Bluetooth Host/Controller VENDOR Interface
326 */
327typedef struct {
328    /** Set to sizeof(bt_vndor_interface_t) */
329    size_t          size;
330
331    /*
332     * Functions need to be implemented in Vendor libray (libbt-vendor.so).
333     */
334
335    /**
336     * Caller will open the interface and pass in the callback routines
337     * to the implemenation of this interface.
338     */
339    int   (*init)(const bt_vendor_callbacks_t* p_cb, unsigned char *local_bdaddr);
340
341    /**  Vendor specific operations */
342    int (*op)(bt_vendor_opcode_t opcode, void *param);
343
344    /** Closes the interface */
345    void  (*cleanup)(void);
346} bt_vendor_interface_t;
347
348
349/*
350 * External shared lib functions/data
351 */
352
353/* Entry point of DLib --
354 *      Vendor library needs to implement the body of bt_vendor_interface_t
355 *      structure and uses the below name as the variable name. HCI library
356 *      will use this symbol name to get address of the object through the
357 *      dlsym call.
358 */
359extern const bt_vendor_interface_t BLUETOOTH_VENDOR_LIB_INTERFACE;
360
361#endif /* BT_VENDOR_LIB_H */
362
363