include/hardware/bluetooth.h

   1 /*
   2  * Copyright (C) 2012 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef ANDROID_INCLUDE_BLUETOOTH_H
  18 #define ANDROID_INCLUDE_BLUETOOTH_H
  19
  20 #include <stdbool.h>
  21 #include <stdint.h>
  22 #include <sys/cdefs.h>
  23 #include <sys/types.h>
  24
  25 #include <hardware/hardware.h>
  26
  27 __BEGIN_DECLS
  28
  29 /**
  30  * The Bluetooth Hardware Module ID
  31  */
  32
  33 #define BT_HARDWARE_MODULE_ID "bluetooth"
  34 #define BT_STACK_MODULE_ID "bluetooth"
  35 #define BT_STACK_TEST_MODULE_ID "bluetooth_test"
  36
  37
  38 /* Bluetooth profile interface IDs */
  39
  40 #define BT_PROFILE_HANDSFREE_ID "handsfree"
  41 #define BT_PROFILE_HANDSFREE_CLIENT_ID "handsfree_client"
  42 #define BT_PROFILE_ADVANCED_AUDIO_ID "a2dp"
  43 #define BT_PROFILE_ADVANCED_AUDIO_SINK_ID "a2dp_sink"
  44 #define BT_PROFILE_HEALTH_ID "health"
  45 #define BT_PROFILE_SOCKETS_ID "socket"
  46 #define BT_PROFILE_HIDHOST_ID "hidhost"
  47 #define BT_PROFILE_PAN_ID "pan"
  48 #define BT_PROFILE_MAP_CLIENT_ID "map_client"
  49 #define BT_PROFILE_SDP_CLIENT_ID "sdp"
  50 #define BT_PROFILE_GATT_ID "gatt"
  51 #define BT_PROFILE_AV_RC_ID "avrcp"
  52 #define BT_PROFILE_AV_RC_CTRL_ID "avrcp_ctrl"
  53
  54 /** Bluetooth Address */
  55 typedef struct {
  56     uint8_t address[6];
  57 } __attribute__((packed))bt_bdaddr_t;
  58
  59 /** Bluetooth Device Name */
  60 typedef struct {
  61     uint8_t name[249];
  62 } __attribute__((packed))bt_bdname_t;
  63
  64 /** Bluetooth Adapter Visibility Modes*/
  65 typedef enum {
  66     BT_SCAN_MODE_NONE,
  67     BT_SCAN_MODE_CONNECTABLE,
  68     BT_SCAN_MODE_CONNECTABLE_DISCOVERABLE
  69 } bt_scan_mode_t;
  70
  71 /** Bluetooth Adapter State */
  72 typedef enum {
  73     BT_STATE_OFF,
  74     BT_STATE_ON
  75 }   bt_state_t;
  76
  77 /** Bluetooth Error Status */
  78 /** We need to build on this */
  79
  80 typedef enum {
  81     BT_STATUS_SUCCESS,
  82     BT_STATUS_FAIL,
  83     BT_STATUS_NOT_READY,
  84     BT_STATUS_NOMEM,
  85     BT_STATUS_BUSY,
  86     BT_STATUS_DONE,        /* request already completed */
  87     BT_STATUS_UNSUPPORTED,
  88     BT_STATUS_PARM_INVALID,
  89     BT_STATUS_UNHANDLED,
  90     BT_STATUS_AUTH_FAILURE,
  91     BT_STATUS_RMT_DEV_DOWN,
  92     BT_STATUS_AUTH_REJECTED
  93
  94 } bt_status_t;
  95
  96 /** Bluetooth PinKey Code */
  97 typedef struct {
  98     uint8_t pin[16];
  99 } __attribute__((packed))bt_pin_code_t;
 100
 101 typedef struct {
 102     uint8_t status;
 103     uint8_t ctrl_state;     /* stack reported state */
 104     uint64_t tx_time;       /* in ms */
 105     uint64_t rx_time;       /* in ms */
 106     uint64_t idle_time;     /* in ms */
 107     uint64_t energy_used;   /* a product of mA, V and ms */
 108 } __attribute__((packed))bt_activity_energy_info;
 109
 110 /** Bluetooth Adapter Discovery state */
 111 typedef enum {
 112     BT_DISCOVERY_STOPPED,
 113     BT_DISCOVERY_STARTED
 114 } bt_discovery_state_t;
 115
 116 /** Bluetooth ACL connection state */
 117 typedef enum {
 118     BT_ACL_STATE_CONNECTED,
 119     BT_ACL_STATE_DISCONNECTED
 120 } bt_acl_state_t;
 121
 122 /** Bluetooth 128-bit UUID */
 123 typedef struct {
 124    uint8_t uu[16];
 125 } bt_uuid_t;
 126
 127 /** Bluetooth SDP service record */
 128 typedef struct
 129 {
 130    bt_uuid_t uuid;
 131    uint16_t channel;
 132    char name[256]; // what's the maximum length
 133 } bt_service_record_t;
 134
 135
 136 /** Bluetooth Remote Version info */
 137 typedef struct
 138 {
 139    int version;
 140    int sub_ver;
 141    int manufacturer;
 142 } bt_remote_version_t;
 143
 144 typedef struct
 145 {
 146     uint16_t version_supported;
 147     uint8_t local_privacy_enabled;
 148     uint8_t max_adv_instance;
 149     uint8_t rpa_offload_supported;
 150     uint8_t max_irk_list_size;
 151     uint8_t max_adv_filter_supported;
 152     uint8_t activity_energy_info_supported;
 153     uint16_t scan_result_storage_size;
 154     uint16_t total_trackable_advertisers;
 155     bool extended_scan_support;
 156     bool debug_logging_supported;
 157 }bt_local_le_features_t;
 158
 159 /* Bluetooth Adapter and Remote Device property types */
 160 typedef enum {
 161     /* Properties common to both adapter and remote device */
 162     /**
 163      * Description - Bluetooth Device Name
 164      * Access mode - Adapter name can be GET/SET. Remote device can be GET
 165      * Data type   - bt_bdname_t
 166      */
 167     BT_PROPERTY_BDNAME = 0x1,
 168     /**
 169      * Description - Bluetooth Device Address
 170      * Access mode - Only GET.
 171      * Data type   - bt_bdaddr_t
 172      */
 173     BT_PROPERTY_BDADDR,
 174     /**
 175      * Description - Bluetooth Service 128-bit UUIDs
 176      * Access mode - Only GET.
 177      * Data type   - Array of bt_uuid_t (Array size inferred from property length).
 178      */
 179     BT_PROPERTY_UUIDS,
 180     /**
 181      * Description - Bluetooth Class of Device as found in Assigned Numbers
 182      * Access mode - Only GET.
 183      * Data type   - uint32_t.
 184      */
 185     BT_PROPERTY_CLASS_OF_DEVICE,
 186     /**
 187      * Description - Device Type - BREDR, BLE or DUAL Mode
 188      * Access mode - Only GET.
 189      * Data type   - bt_device_type_t
 190      */
 191     BT_PROPERTY_TYPE_OF_DEVICE,
 192     /**
 193      * Description - Bluetooth Service Record
 194      * Access mode - Only GET.
 195      * Data type   - bt_service_record_t
 196      */
 197     BT_PROPERTY_SERVICE_RECORD,
 198
 199     /* Properties unique to adapter */
 200     /**
 201      * Description - Bluetooth Adapter scan mode
 202      * Access mode - GET and SET
 203      * Data type   - bt_scan_mode_t.
 204      */
 205     BT_PROPERTY_ADAPTER_SCAN_MODE,
 206     /**
 207      * Description - List of bonded devices
 208      * Access mode - Only GET.
 209      * Data type   - Array of bt_bdaddr_t of the bonded remote devices
 210      *               (Array size inferred from property length).
 211      */
 212     BT_PROPERTY_ADAPTER_BONDED_DEVICES,
 213     /**
 214      * Description - Bluetooth Adapter Discovery timeout (in seconds)
 215      * Access mode - GET and SET
 216      * Data type   - uint32_t
 217      */
 218     BT_PROPERTY_ADAPTER_DISCOVERY_TIMEOUT,
 219
 220     /* Properties unique to remote device */
 221     /**
 222      * Description - User defined friendly name of the remote device
 223      * Access mode - GET and SET
 224      * Data type   - bt_bdname_t.
 225      */
 226     BT_PROPERTY_REMOTE_FRIENDLY_NAME,
 227     /**
 228      * Description - RSSI value of the inquired remote device
 229      * Access mode - Only GET.
 230      * Data type   - int32_t.
 231      */
 232     BT_PROPERTY_REMOTE_RSSI,
 233     /**
 234      * Description - Remote version info
 235      * Access mode - SET/GET.
 236      * Data type   - bt_remote_version_t.
 237      */
 238
 239     BT_PROPERTY_REMOTE_VERSION_INFO,
 240
 241     /**
 242      * Description - Local LE features
 243      * Access mode - GET.
 244      * Data type   - bt_local_le_features_t.
 245      */
 246     BT_PROPERTY_LOCAL_LE_FEATURES,
 247
 248     BT_PROPERTY_REMOTE_DEVICE_TIMESTAMP = 0xFF,
 249 } bt_property_type_t;
 250
 251 /** Bluetooth Adapter Property data structure */
 252 typedef struct
 253 {
 254     bt_property_type_t type;
 255     int len;
 256     void *val;
 257 } bt_property_t;
 258
 259
 260 /** Bluetooth Device Type */
 261 typedef enum {
 262     BT_DEVICE_DEVTYPE_BREDR = 0x1,
 263     BT_DEVICE_DEVTYPE_BLE,
 264     BT_DEVICE_DEVTYPE_DUAL
 265 } bt_device_type_t;
 266 /** Bluetooth Bond state */
 267 typedef enum {
 268     BT_BOND_STATE_NONE,
 269     BT_BOND_STATE_BONDING,
 270     BT_BOND_STATE_BONDED
 271 } bt_bond_state_t;
 272
 273 /** Bluetooth SSP Bonding Variant */
 274 typedef enum {
 275     BT_SSP_VARIANT_PASSKEY_CONFIRMATION,
 276     BT_SSP_VARIANT_PASSKEY_ENTRY,
 277     BT_SSP_VARIANT_CONSENT,
 278     BT_SSP_VARIANT_PASSKEY_NOTIFICATION
 279 } bt_ssp_variant_t;
 280
 281 #define BT_MAX_NUM_UUIDS 32
 282
 283 /** Bluetooth Interface callbacks */
 284
 285 /** Bluetooth Enable/Disable Callback. */
 286 typedef void (*adapter_state_changed_callback)(bt_state_t state);
 287
 288 /** GET/SET Adapter Properties callback */
 289 /* TODO: For the GET/SET property APIs/callbacks, we may need a session
 290  * identifier to associate the call with the callback. This would be needed
 291  * whenever more than one simultaneous instance of the same adapter_type
 292  * is get/set.
 293  *
 294  * If this is going to be handled in the Java framework, then we do not need
 295  * to manage sessions here.
 296  */
 297 typedef void (*adapter_properties_callback)(bt_status_t status,
 298                                                int num_properties,
 299                                                bt_property_t *properties);
 300
 301 /** GET/SET Remote Device Properties callback */
 302 /** TODO: For remote device properties, do not see a need to get/set
 303  * multiple properties - num_properties shall be 1
 304  */
 305 typedef void (*remote_device_properties_callback)(bt_status_t status,
 306                                                        bt_bdaddr_t *bd_addr,
 307                                                        int num_properties,
 308                                                        bt_property_t *properties);
 309
 310 /** New device discovered callback */
 311 /** If EIR data is not present, then BD_NAME and RSSI shall be NULL and -1
 312  * respectively */
 313 typedef void (*device_found_callback)(int num_properties,
 314                                          bt_property_t *properties);
 315
 316 /** Discovery state changed callback */
 317 typedef void (*discovery_state_changed_callback)(bt_discovery_state_t state);
 318
 319 /** Bluetooth Legacy PinKey Request callback */
 320 typedef void (*pin_request_callback)(bt_bdaddr_t *remote_bd_addr,
 321                                         bt_bdname_t *bd_name, uint32_t cod, bool min_16_digit);
 322
 323 /** Bluetooth SSP Request callback - Just Works & Numeric Comparison*/
 324 /** pass_key - Shall be 0 for BT_SSP_PAIRING_VARIANT_CONSENT &
 325  *  BT_SSP_PAIRING_PASSKEY_ENTRY */
 326 /* TODO: Passkey request callback shall not be needed for devices with display
 327  * capability. We still need support this in the stack for completeness */
 328 typedef void (*ssp_request_callback)(bt_bdaddr_t *remote_bd_addr,
 329                                         bt_bdname_t *bd_name,
 330                                         uint32_t cod,
 331                                         bt_ssp_variant_t pairing_variant,
 332                                      uint32_t pass_key);
 333
 334 /** Bluetooth Bond state changed callback */
 335 /* Invoked in response to create_bond, cancel_bond or remove_bond */
 336 typedef void (*bond_state_changed_callback)(bt_status_t status,
 337                                                bt_bdaddr_t *remote_bd_addr,
 338                                                bt_bond_state_t state);
 339
 340 /** Bluetooth ACL connection state changed callback */
 341 typedef void (*acl_state_changed_callback)(bt_status_t status, bt_bdaddr_t *remote_bd_addr,
 342                                             bt_acl_state_t state);
 343
 344 typedef enum {
 345     ASSOCIATE_JVM,
 346     DISASSOCIATE_JVM
 347 } bt_cb_thread_evt;
 348
 349 /** Thread Associate/Disassociate JVM Callback */
 350 /* Callback that is invoked by the callback thread to allow upper layer to attach/detach to/from
 351  * the JVM */
 352 typedef void (*callback_thread_event)(bt_cb_thread_evt evt);
 353
 354 /** Bluetooth Test Mode Callback */
 355 /* Receive any HCI event from controller. Must be in DUT Mode for this callback to be received */
 356 typedef void (*dut_mode_recv_callback)(uint16_t opcode, uint8_t *buf, uint8_t len);
 357
 358 /* LE Test mode callbacks
 359 * This callback shall be invoked whenever the le_tx_test, le_rx_test or le_test_end is invoked
 360 * The num_packets is valid only for le_test_end command */
 361 typedef void (*le_test_mode_callback)(bt_status_t status, uint16_t num_packets);
 362
 363 /** Callback invoked when energy details are obtained */
 364 /* Ctrl_state-Current controller state-Active-1,scan-2,or idle-3 state as defined by HCI spec.
 365  * If the ctrl_state value is 0, it means the API call failed
 366  * Time values-In milliseconds as returned by the controller
 367  * Energy used-Value as returned by the controller
 368  * Status-Provides the status of the read_energy_info API call */
 369 typedef void (*energy_info_callback)(bt_activity_energy_info *energy_info);
 370
 371 /** TODO: Add callbacks for Link Up/Down and other generic
 372   *  notifications/callbacks */
 373
 374 /** Bluetooth DM callback structure. */
 375 typedef struct {
 376     /** set to sizeof(bt_callbacks_t) */
 377     size_t size;
 378     adapter_state_changed_callback adapter_state_changed_cb;
 379     adapter_properties_callback adapter_properties_cb;
 380     remote_device_properties_callback remote_device_properties_cb;
 381     device_found_callback device_found_cb;
 382     discovery_state_changed_callback discovery_state_changed_cb;
 383     pin_request_callback pin_request_cb;
 384     ssp_request_callback ssp_request_cb;
 385     bond_state_changed_callback bond_state_changed_cb;
 386     acl_state_changed_callback acl_state_changed_cb;
 387     callback_thread_event thread_evt_cb;
 388     dut_mode_recv_callback dut_mode_recv_cb;
 389     le_test_mode_callback le_test_mode_cb;
 390     energy_info_callback energy_info_cb;
 391 } bt_callbacks_t;
 392
 393 typedef void (*alarm_cb)(void *data);
 394 typedef bool (*set_wake_alarm_callout)(uint64_t delay_millis, bool should_wake, alarm_cb cb, void *data);
 395 typedef int (*acquire_wake_lock_callout)(const char *lock_name);
 396 typedef int (*release_wake_lock_callout)(const char *lock_name);
 397
 398 /** The set of functions required by bluedroid to set wake alarms and
 399   * grab wake locks. This struct is passed into the stack through the
 400   * |set_os_callouts| function on |bt_interface_t|.
 401   */
 402 typedef struct {
 403   /* set to sizeof(bt_os_callouts_t) */
 404   size_t size;
 405
 406   set_wake_alarm_callout set_wake_alarm;
 407   acquire_wake_lock_callout acquire_wake_lock;
 408   release_wake_lock_callout release_wake_lock;
 409 } bt_os_callouts_t;
 410
 411 /** NOTE: By default, no profiles are initialized at the time of init/enable.
 412  *  Whenever the application invokes the 'init' API of a profile, then one of
 413  *  the following shall occur:
 414  *
 415  *    1.) If Bluetooth is not enabled, then the Bluetooth core shall mark the
 416  *        profile as enabled. Subsequently, when the application invokes the
 417  *        Bluetooth 'enable', as part of the enable sequence the profile that were
 418  *        marked shall be enabled by calling appropriate stack APIs. The
 419  *        'adapter_properties_cb' shall return the list of UUIDs of the
 420  *        enabled profiles.
 421  *
 422  *    2.) If Bluetooth is enabled, then the Bluetooth core shall invoke the stack
 423  *        profile API to initialize the profile and trigger a
 424  *        'adapter_properties_cb' with the current list of UUIDs including the
 425  *        newly added profile's UUID.
 426  *
 427  *   The reverse shall occur whenever the profile 'cleanup' APIs are invoked
 428  */
 429
 430 /** Represents the standard Bluetooth DM interface. */
 431 typedef struct {
 432     /** set to sizeof(bt_interface_t) */
 433     size_t size;
 434     /**
 435      * Opens the interface and provides the callback routines
 436      * to the implemenation of this interface.
 437      */
 438     int (*init)(bt_callbacks_t* callbacks );
 439
 440     /** Enable Bluetooth. */
 441     int (*enable)(void);
 442
 443     /** Disable Bluetooth. */
 444     int (*disable)(void);
 445
 446     /** Closes the interface. */
 447     void (*cleanup)(void);
 448
 449     /** Get all Bluetooth Adapter properties at init */
 450     int (*get_adapter_properties)(void);
 451
 452     /** Get Bluetooth Adapter property of 'type' */
 453     int (*get_adapter_property)(bt_property_type_t type);
 454
 455     /** Set Bluetooth Adapter property of 'type' */
 456     /* Based on the type, val shall be one of
 457      * bt_bdaddr_t or bt_bdname_t or bt_scanmode_t etc
 458      */
 459     int (*set_adapter_property)(const bt_property_t *property);
 460
 461     /** Get all Remote Device properties */
 462     int (*get_remote_device_properties)(bt_bdaddr_t *remote_addr);
 463
 464     /** Get Remote Device property of 'type' */
 465     int (*get_remote_device_property)(bt_bdaddr_t *remote_addr,
 466                                       bt_property_type_t type);
 467
 468     /** Set Remote Device property of 'type' */
 469     int (*set_remote_device_property)(bt_bdaddr_t *remote_addr,
 470                                       const bt_property_t *property);
 471
 472     /** Get Remote Device's service record  for the given UUID */
 473     int (*get_remote_service_record)(bt_bdaddr_t *remote_addr,
 474                                      bt_uuid_t *uuid);
 475
 476     /** Start SDP to get remote services */
 477     int (*get_remote_services)(bt_bdaddr_t *remote_addr);
 478
 479     /** Start Discovery */
 480     int (*start_discovery)(void);
 481
 482     /** Cancel Discovery */
 483     int (*cancel_discovery)(void);
 484
 485     /** Create Bluetooth Bonding */
 486     int (*create_bond)(const bt_bdaddr_t *bd_addr, int transport);
 487
 488     /** Remove Bond */
 489     int (*remove_bond)(const bt_bdaddr_t *bd_addr);
 490
 491     /** Cancel Bond */
 492     int (*cancel_bond)(const bt_bdaddr_t *bd_addr);
 493
 494     /**
 495      * Get the connection status for a given remote device.
 496      * return value of 0 means the device is not connected,
 497      * non-zero return status indicates an active connection.
 498      */
 499     int (*get_connection_state)(const bt_bdaddr_t *bd_addr);
 500
 501     /** BT Legacy PinKey Reply */
 502     /** If accept==FALSE, then pin_len and pin_code shall be 0x0 */
 503     int (*pin_reply)(const bt_bdaddr_t *bd_addr, uint8_t accept,
 504                      uint8_t pin_len, bt_pin_code_t *pin_code);
 505
 506     /** BT SSP Reply - Just Works, Numeric Comparison and Passkey
 507      * passkey shall be zero for BT_SSP_VARIANT_PASSKEY_COMPARISON &
 508      * BT_SSP_VARIANT_CONSENT
 509      * For BT_SSP_VARIANT_PASSKEY_ENTRY, if accept==FALSE, then passkey
 510      * shall be zero */
 511     int (*ssp_reply)(const bt_bdaddr_t *bd_addr, bt_ssp_variant_t variant,
 512                      uint8_t accept, uint32_t passkey);
 513
 514     /** Get Bluetooth profile interface */
 515     const void* (*get_profile_interface) (const char *profile_id);
 516
 517     /** Bluetooth Test Mode APIs - Bluetooth must be enabled for these APIs */
 518     /* Configure DUT Mode - Use this mode to enter/exit DUT mode */
 519     int (*dut_mode_configure)(uint8_t enable);
 520
 521     /* Send any test HCI (vendor-specific) command to the controller. Must be in DUT Mode */
 522     int (*dut_mode_send)(uint16_t opcode, uint8_t *buf, uint8_t len);
 523     /** BLE Test Mode APIs */
 524     /* opcode MUST be one of: LE_Receiver_Test, LE_Transmitter_Test, LE_Test_End */
 525     int (*le_test_mode)(uint16_t opcode, uint8_t *buf, uint8_t len);
 526
 527     /* enable or disable bluetooth HCI snoop log */
 528     int (*config_hci_snoop_log)(uint8_t enable);
 529
 530     /** Sets the OS call-out functions that bluedroid needs for alarms and wake locks.
 531       * This should be called immediately after a successful |init|.
 532       */
 533     int (*set_os_callouts)(bt_os_callouts_t *callouts);
 534
 535     /** Read Energy info details - return value indicates BT_STATUS_SUCCESS or BT_STATUS_NOT_READY
 536       * Success indicates that the VSC command was sent to controller
 537       */
 538     int (*read_energy_info)();
 539
 540     /**
 541      * Native support for dumpsys function
 542      * Function is synchronous and |fd| is owned by caller.
 543      */
 544     void (*dump)(int fd);
 545
 546     /**
 547      * Clear /data/misc/bt_config.conf and erase all stored connections
 548      */
 549     int (*config_clear)(void);
 550
 551     /**
 552      * Clear (reset) the dynamic portion of the device interoperability database.
 553      */
 554     void (*interop_database_clear)(void);
 555
 556     /**
 557      * Add a new device interoperability workaround for a remote device whose
 558      * first |len| bytes of the its device address match |addr|.
 559      * NOTE: |feature| has to match an item defined in interop_feature_t (interop.h).
 560      */
 561     void (*interop_database_add)(uint16_t feature, const bt_bdaddr_t *addr, size_t len);
 562 } bt_interface_t;
 563
 564 /** TODO: Need to add APIs for Service Discovery, Service authorization and
 565   *       connection management. Also need to add APIs for configuring
 566   *       properties of remote bonded devices such as name, UUID etc. */
 567
 568 typedef struct {
 569     struct hw_device_t common;
 570     const bt_interface_t* (*get_bluetooth_interface)();
 571 } bluetooth_device_t;
 572
 573 typedef bluetooth_device_t bluetooth_module_t;
 574
 575
 576 __END_DECLS
 577
 578 #endif /* ANDROID_INCLUDE_BLUETOOTH_H */