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