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 */ 32 typedef 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 */ 202 typedef 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 */ 210 typedef 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 */ 220 typedef enum { 221 BT_VND_LPM_DISABLE, 222 BT_VND_LPM_ENABLE, 223 } bt_vendor_lpm_mode_t; 224 225 /** LPM WAKE set state request */ 226 typedef 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 */ 232 typedef 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 */ 238 typedef 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 */ 249 typedef 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 */ 289 typedef void* (*malloc_cb)(int size); 290 291 /* datapath buffer deallocation callback (callout) */ 292 typedef 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 */ 300 typedef 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 */ 317 typedef uint8_t (*cmd_xmit_cb)(uint16_t opcode, void *p_buf, tINT_CMD_CBACK p_cback); 318 319 typedef void (*cfg_a2dp_cb)(bt_vendor_op_result_t result, bt_vendor_opcode_t op, uint8_t bta_av_handle); 320 321 typedef 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 */ 359 typedef 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 */ 375 typedef 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 */ 407 extern const bt_vendor_interface_t BLUETOOTH_VENDOR_LIB_INTERFACE; 408 409 #endif /* BT_VENDOR_LIB_H */ 410 411