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