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 } bt_vendor_opcode_t; 171 172 /** Power on/off control states */ 173 typedef 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 */ 181 typedef 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 */ 191 typedef enum { 192 BT_VND_LPM_DISABLE, 193 BT_VND_LPM_ENABLE, 194 } bt_vendor_lpm_mode_t; 195 196 /** LPM WAKE set state request */ 197 typedef 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 */ 203 typedef 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 */ 209 typedef 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 */ 220 typedef 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 */ 260 typedef void* (*malloc_cb)(int size); 261 262 /* datapath buffer deallocation callback (callout) */ 263 typedef 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 */ 271 typedef 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 */ 288 typedef uint8_t (*cmd_xmit_cb)(uint16_t opcode, void *p_buf, tINT_CMD_CBACK p_cback); 289 290 typedef 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 */ 327 typedef 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 */ 359 extern const bt_vendor_interface_t BLUETOOTH_VENDOR_LIB_INTERFACE; 360 361 #endif /* BT_VENDOR_LIB_H */ 362 363