1 /* hci_core.h - Bluetooth HCI core access */ 2 3 /* 4 * Copyright (c) 2021 Nordic Semiconductor ASA 5 * Copyright (c) 2015-2016 Intel Corporation 6 * 7 * SPDX-License-Identifier: Apache-2.0 8 */ 9 10 #include <zephyr/devicetree.h> 11 12 /* LL connection parameters */ 13 #define LE_CONN_LATENCY 0x0000 14 #define LE_CONN_TIMEOUT 0x002a 15 16 #if defined(CONFIG_BT_CLASSIC) 17 #define LMP_FEAT_PAGES_COUNT 3 18 #else 19 #define LMP_FEAT_PAGES_COUNT 1 20 #endif 21 22 /* SCO settings */ 23 #define BT_VOICE_CVSD_16BIT 0x0060 24 25 /* k_poll event tags */ 26 enum { 27 BT_EVENT_CMD_TX, 28 BT_EVENT_CONN_TX_QUEUE, 29 BT_EVENT_CONN_FREE_TX, 30 }; 31 32 /* bt_dev flags: the flags defined here represent BT controller state */ 33 enum { 34 BT_DEV_ENABLE, 35 BT_DEV_DISABLE, 36 BT_DEV_READY, 37 BT_DEV_PRESET_ID, 38 BT_DEV_HAS_PUB_KEY, 39 BT_DEV_PUB_KEY_BUSY, 40 41 /** The application explicitly instructed the stack to scan for advertisers 42 * using the API @ref bt_le_scan_start(). 43 */ 44 BT_DEV_EXPLICIT_SCAN, 45 46 /** The application either explicitly or implicitly instructed the stack to scan 47 * for advertisers. 48 * 49 * Examples of such cases 50 * - Explicit scanning, @ref BT_DEV_EXPLICIT_SCAN. 51 * - The application instructed the stack to automatically connect if a given device 52 * is detected. 53 * - The application wants to connect to a peer device using private addresses, but 54 * the controller resolving list is too small. The host will fallback to using 55 * host-based privacy and first scan for the device before it initiates a connection. 56 * - The application wants to synchronize to a periodic advertiser. 57 * The host will implicitly start scanning if it is not already doing so. 58 * 59 * The host needs to keep track of this state to ensure it can restart scanning 60 * when a connection is established/lost, explicit scanning is started or stopped etc. 61 * Also, when the scanner and advertiser share the same identity, the scanner may need 62 * to be restarted upon RPA refresh. 63 */ 64 BT_DEV_SCANNING, 65 66 /* Cached parameters used when initially enabling the scanner. 67 * These are needed to ensure the same parameters are used when restarting 68 * the scanner after refreshing an RPA. 69 */ 70 BT_DEV_ACTIVE_SCAN, 71 BT_DEV_SCAN_FILTER_DUP, 72 BT_DEV_SCAN_FILTERED, 73 BT_DEV_SCAN_LIMITED, 74 75 BT_DEV_INITIATING, 76 77 BT_DEV_RPA_VALID, 78 BT_DEV_RPA_TIMEOUT_CHANGED, 79 80 BT_DEV_ID_PENDING, 81 BT_DEV_STORE_ID, 82 83 #if defined(CONFIG_BT_CLASSIC) 84 BT_DEV_ISCAN, 85 BT_DEV_PSCAN, 86 BT_DEV_INQUIRY, 87 #endif /* CONFIG_BT_CLASSIC */ 88 89 /* Total number of flags - must be at the end of the enum */ 90 BT_DEV_NUM_FLAGS, 91 }; 92 93 /* Flags which should not be cleared upon HCI_Reset */ 94 #define BT_DEV_PERSISTENT_FLAGS (BIT(BT_DEV_ENABLE) | \ 95 BIT(BT_DEV_PRESET_ID)) 96 97 #if defined(CONFIG_BT_EXT_ADV_LEGACY_SUPPORT) 98 /* Check the feature bit for extended or legacy advertising commands */ 99 #define BT_DEV_FEAT_LE_EXT_ADV(feat) BT_FEAT_LE_EXT_ADV(feat) 100 #else 101 /* Always use extended advertising commands. */ 102 #define BT_DEV_FEAT_LE_EXT_ADV(feat) 1 103 #endif 104 105 enum { 106 /* Advertising set has been created in the host. */ 107 BT_ADV_CREATED, 108 /* Advertising parameters has been set in the controller. 109 * This implies that the advertising set has been created in the 110 * controller. 111 */ 112 BT_ADV_PARAMS_SET, 113 /* Advertising data has been set in the controller. */ 114 BT_ADV_DATA_SET, 115 /* Advertising random address pending to be set in the controller. */ 116 BT_ADV_RANDOM_ADDR_PENDING, 117 /* The private random address of the advertiser is valid for this cycle 118 * of the RPA timeout. 119 */ 120 BT_ADV_RPA_VALID, 121 /* The private random address of the advertiser is being updated. */ 122 BT_ADV_RPA_UPDATE, 123 /* The advertiser set is limited by a timeout, or number of advertising 124 * events, or both. 125 */ 126 BT_ADV_LIMITED, 127 /* Advertiser set is currently advertising in the controller. */ 128 BT_ADV_ENABLED, 129 /* Advertiser should include name in advertising data */ 130 BT_ADV_INCLUDE_NAME_AD, 131 /* Advertiser should include name in scan response data */ 132 BT_ADV_INCLUDE_NAME_SD, 133 /* Advertiser set is connectable */ 134 BT_ADV_CONNECTABLE, 135 /* Advertiser set is scannable */ 136 BT_ADV_SCANNABLE, 137 /* Advertiser set is using extended advertising */ 138 BT_ADV_EXT_ADV, 139 /* Advertiser set has disabled the use of private addresses and is using 140 * the identity address instead. 141 */ 142 BT_ADV_USE_IDENTITY, 143 /* Advertiser has been configured to keep advertising after a connection 144 * has been established as long as there are connections available. 145 */ 146 BT_ADV_PERSIST, 147 /* Advertiser has been temporarily disabled. */ 148 BT_ADV_PAUSED, 149 /* Periodic Advertising has been enabled in the controller. */ 150 BT_PER_ADV_ENABLED, 151 /* Periodic Advertising parameters has been set in the controller. */ 152 BT_PER_ADV_PARAMS_SET, 153 /* Periodic Advertising to include AdvDataInfo (ADI) */ 154 BT_PER_ADV_INCLUDE_ADI, 155 /* Constant Tone Extension parameters for Periodic Advertising 156 * has been set in the controller. 157 */ 158 BT_PER_ADV_CTE_PARAMS_SET, 159 /* Constant Tone Extension for Periodic Advertising has been enabled 160 * in the controller. 161 */ 162 BT_PER_ADV_CTE_ENABLED, 163 164 BT_ADV_NUM_FLAGS, 165 }; 166 167 struct bt_le_ext_adv { 168 /* ID Address used for advertising */ 169 uint8_t id; 170 171 /* Advertising handle */ 172 uint8_t handle; 173 174 /* Current local Random Address */ 175 bt_addr_le_t random_addr; 176 177 /* Current target address */ 178 bt_addr_le_t target_addr; 179 180 ATOMIC_DEFINE(flags, BT_ADV_NUM_FLAGS); 181 182 #if defined(CONFIG_BT_EXT_ADV) 183 const struct bt_le_ext_adv_cb *cb; 184 185 /* TX Power in use by the controller */ 186 int8_t tx_power; 187 #endif /* defined(CONFIG_BT_EXT_ADV) */ 188 189 struct k_work_delayable lim_adv_timeout_work; 190 191 /** The options used to set the parameters for this advertising set 192 * @ref bt_le_adv_param 193 */ 194 uint32_t options; 195 }; 196 197 enum { 198 /** Periodic Advertising Sync has been created in the host. */ 199 BT_PER_ADV_SYNC_CREATED, 200 201 /** Periodic Advertising Sync is established and can be terminated */ 202 BT_PER_ADV_SYNC_SYNCED, 203 204 /** Periodic Advertising Sync is attempting to create sync */ 205 BT_PER_ADV_SYNC_SYNCING, 206 207 /** Periodic Advertising Sync is attempting to create sync using 208 * Advertiser List 209 */ 210 BT_PER_ADV_SYNC_SYNCING_USE_LIST, 211 212 /** Periodic Advertising Sync established with reporting disabled */ 213 BT_PER_ADV_SYNC_RECV_DISABLED, 214 215 /** Constant Tone Extension for Periodic Advertising has been enabled 216 * in the Controller. 217 */ 218 BT_PER_ADV_SYNC_CTE_ENABLED, 219 220 BT_PER_ADV_SYNC_NUM_FLAGS, 221 }; 222 223 struct bt_le_per_adv_sync { 224 /** Periodic Advertiser Address */ 225 bt_addr_le_t addr; 226 227 /** Advertiser SID */ 228 uint8_t sid; 229 230 /** Sync handle */ 231 uint16_t handle; 232 233 /** Periodic advertising interval (N * 1.25 ms) */ 234 uint16_t interval; 235 236 /** Periodic advertising advertiser clock accuracy (ppm) */ 237 uint16_t clock_accuracy; 238 239 /** Advertiser PHY */ 240 uint8_t phy; 241 242 #if defined(CONFIG_BT_DF_CONNECTIONLESS_CTE_RX) 243 /** 244 * @brief Bitfield with allowed CTE types. 245 * 246 * Allowed values are defined by @ref bt_df_cte_type, except BT_DF_CTE_TYPE_NONE. 247 */ 248 uint8_t cte_types; 249 #endif /* CONFIG_BT_DF_CONNECTIONLESS_CTE_RX */ 250 251 #if CONFIG_BT_PER_ADV_SYNC_BUF_SIZE > 0 252 /** Reassembly buffer for advertising reports */ 253 struct net_buf_simple reassembly; 254 255 /** Storage for the reassembly buffer */ 256 uint8_t reassembly_data[CONFIG_BT_PER_ADV_SYNC_BUF_SIZE]; 257 #endif /* CONFIG_BT_PER_ADV_SYNC_BUF_SIZE > 0 */ 258 259 /** True if the following periodic adv reports up to and 260 * including the next complete one should be dropped 261 */ 262 bool report_truncated; 263 264 /** Flags */ 265 ATOMIC_DEFINE(flags, BT_PER_ADV_SYNC_NUM_FLAGS); 266 267 #if defined(CONFIG_BT_PER_ADV_SYNC_RSP) 268 /** Number of subevents */ 269 uint8_t num_subevents; 270 271 /** Subevent interval (N * 1.25ms) */ 272 uint8_t subevent_interval; 273 274 /** Response slot delay (N * 1.25ms) */ 275 uint8_t response_slot_delay; 276 277 /** Response slot spacing (N * 1.25ms) */ 278 uint8_t response_slot_spacing; 279 #endif /* CONFIG_BT_PER_ADV_SYNC_RSP */ 280 }; 281 282 struct bt_dev_le { 283 /* LE features */ 284 uint8_t features[8]; 285 /* LE states */ 286 uint64_t states; 287 288 #if defined(CONFIG_BT_CONN) 289 /* Controller buffer information */ 290 uint16_t mtu; 291 struct k_sem pkts; 292 uint16_t acl_mtu; 293 struct k_sem acl_pkts; 294 #endif /* CONFIG_BT_CONN */ 295 #if defined(CONFIG_BT_ISO) 296 uint16_t iso_mtu; 297 uint8_t iso_limit; 298 struct k_sem iso_pkts; 299 #endif /* CONFIG_BT_ISO */ 300 #if defined(CONFIG_BT_BROADCASTER) 301 uint16_t max_adv_data_len; 302 #endif /* CONFIG_BT_BROADCASTER */ 303 304 #if defined(CONFIG_BT_SMP) 305 /* Size of the controller resolving list */ 306 uint8_t rl_size; 307 /* Number of entries in the resolving list. rl_entries > rl_size 308 * means that host-side resolving is used. 309 */ 310 uint8_t rl_entries; 311 #endif /* CONFIG_BT_SMP */ 312 /* List of `struct bt_conn` that have either pending data to send, or 313 * something to process (e.g. a disconnection event). 314 * 315 * Each element in this list contains a reference to its `conn` object. 316 */ 317 sys_slist_t conn_ready; 318 }; 319 320 #if defined(CONFIG_BT_CLASSIC) 321 struct bt_dev_br { 322 /* Max controller's acceptable ACL packet length */ 323 uint16_t mtu; 324 struct k_sem pkts; 325 uint16_t esco_pkt_type; 326 }; 327 #endif 328 329 /* The theoretical max for these is 8 and 64, but there's no point 330 * in allocating the full memory if we only support a small subset. 331 * These values must be updated whenever the host implementation is 332 * extended beyond the current values. 333 */ 334 #define BT_DEV_VS_FEAT_MAX 1 335 #define BT_DEV_VS_CMDS_MAX 2 336 337 /* State tracking for the local Bluetooth controller */ 338 struct bt_dev { 339 /* Local Identity Address(es) */ 340 bt_addr_le_t id_addr[CONFIG_BT_ID_MAX]; 341 uint8_t id_count; 342 343 struct bt_conn_le_create_param create_param; 344 345 #if !defined(CONFIG_BT_EXT_ADV) 346 /* Legacy advertiser */ 347 struct bt_le_ext_adv adv; 348 #else 349 /* Pointer to reserved advertising set */ 350 struct bt_le_ext_adv *adv; 351 #if defined(CONFIG_BT_CONN) && (CONFIG_BT_EXT_ADV_MAX_ADV_SET > 1) 352 /* When supporting multiple concurrent connectable advertising sets 353 * with multiple identities, we need to know the identity of 354 * the terminating advertising set to identify the connection object. 355 * The identity of the advertising set is determined by its 356 * advertising handle, which is part of the 357 * LE Set Advertising Set Terminated event which is always sent 358 * _after_ the LE Enhanced Connection complete event. 359 * Therefore we need cache this event until its identity is known. 360 */ 361 struct { 362 bool valid; 363 struct bt_hci_evt_le_enh_conn_complete evt; 364 } cached_conn_complete[MIN(CONFIG_BT_MAX_CONN, 365 CONFIG_BT_EXT_ADV_MAX_ADV_SET)]; 366 #endif 367 #endif 368 /* Current local Random Address */ 369 bt_addr_le_t random_addr; 370 uint8_t adv_conn_id; 371 372 /* Controller version & manufacturer information */ 373 uint8_t hci_version; 374 uint8_t lmp_version; 375 uint16_t hci_revision; 376 uint16_t lmp_subversion; 377 uint16_t manufacturer; 378 379 /* LMP features (pages 0, 1, 2) */ 380 uint8_t features[LMP_FEAT_PAGES_COUNT][8]; 381 382 /* Supported commands */ 383 uint8_t supported_commands[64]; 384 385 #if defined(CONFIG_BT_HCI_VS) 386 /* Vendor HCI support */ 387 uint8_t vs_features[BT_DEV_VS_FEAT_MAX]; 388 uint8_t vs_commands[BT_DEV_VS_CMDS_MAX]; 389 #endif 390 391 struct k_work init; 392 393 ATOMIC_DEFINE(flags, BT_DEV_NUM_FLAGS); 394 395 /* LE controller specific features */ 396 struct bt_dev_le le; 397 398 #if defined(CONFIG_BT_CLASSIC) 399 /* BR/EDR controller specific features */ 400 struct bt_dev_br br; 401 #endif 402 403 /* Number of commands controller can accept */ 404 struct k_sem ncmd_sem; 405 406 /* Last sent HCI command */ 407 struct net_buf *sent_cmd; 408 409 /* Queue for incoming HCI events & ACL data */ 410 sys_slist_t rx_queue; 411 412 /* Queue for outgoing HCI commands */ 413 struct k_fifo cmd_tx_queue; 414 415 #if DT_HAS_CHOSEN(zephyr_bt_hci) 416 const struct device *hci; 417 #else 418 /* Registered HCI driver */ 419 const struct bt_hci_driver *drv; 420 #endif 421 422 #if defined(CONFIG_BT_PRIVACY) 423 /* Local Identity Resolving Key */ 424 uint8_t irk[CONFIG_BT_ID_MAX][16]; 425 426 #if defined(CONFIG_BT_RPA_SHARING) 427 /* Only 1 RPA per identity */ 428 bt_addr_t rpa[CONFIG_BT_ID_MAX]; 429 #endif 430 431 /* Work used for RPA rotation */ 432 struct k_work_delayable rpa_update; 433 434 /* The RPA timeout value. */ 435 uint16_t rpa_timeout; 436 #endif 437 438 /* Local Name */ 439 #if defined(CONFIG_BT_DEVICE_NAME_DYNAMIC) 440 char name[CONFIG_BT_DEVICE_NAME_MAX + 1]; 441 #endif 442 #if defined(CONFIG_BT_DEVICE_APPEARANCE_DYNAMIC) 443 /* Appearance Value */ 444 uint16_t appearance; 445 #endif 446 }; 447 448 extern struct bt_dev bt_dev; 449 #if defined(CONFIG_BT_SMP) || defined(CONFIG_BT_CLASSIC) 450 extern const struct bt_conn_auth_cb *bt_auth; 451 extern sys_slist_t bt_auth_info_cbs; 452 enum bt_security_err bt_security_err_get(uint8_t hci_err); 453 #endif /* CONFIG_BT_SMP || CONFIG_BT_CLASSIC */ 454 455 #if DT_HAS_CHOSEN(zephyr_bt_hci) 456 int bt_hci_recv(const struct device *dev, struct net_buf *buf); 457 #endif 458 459 /* Data type to store state related with command to be updated 460 * when command completes successfully. 461 */ 462 struct bt_hci_cmd_state_set { 463 /* Target memory to be updated */ 464 atomic_t *target; 465 /* Bit number to be updated in target memory */ 466 int bit; 467 /* Value to determine if enable or disable bit */ 468 bool val; 469 }; 470 471 /* Set command state related with the command buffer */ 472 void bt_hci_cmd_state_set_init(struct net_buf *buf, 473 struct bt_hci_cmd_state_set *state, 474 atomic_t *target, int bit, bool val); 475 476 int bt_hci_disconnect(uint16_t handle, uint8_t reason); 477 478 bool bt_le_conn_params_valid(const struct bt_le_conn_param *param); 479 int bt_le_set_data_len(struct bt_conn *conn, uint16_t tx_octets, uint16_t tx_time); 480 int bt_le_set_phy(struct bt_conn *conn, uint8_t all_phys, 481 uint8_t pref_tx_phy, uint8_t pref_rx_phy, uint8_t phy_opts); 482 uint8_t bt_get_phy(uint8_t hci_phy); 483 /** 484 * @brief Convert CTE type value from HCI format to @ref bt_df_cte_type format. 485 * 486 * @param hci_cte_type CTE type in an HCI format. 487 * 488 * @return CTE type (@ref bt_df_cte_type). 489 */ 490 int bt_get_df_cte_type(uint8_t hci_cte_type); 491 492 /** Start or restart scanner if needed 493 * 494 * Examples of cases where it may be required to start/restart a scanner: 495 * - When the auto-connection establishement feature is used: 496 * - When the host sets a connection context for auto-connection establishment. 497 * - When a connection was established. 498 * The host may now be able to retry to automatically set up a connection. 499 * - When a connection was disconnected/lost. 500 * The host may now be able to retry to automatically set up a connection. 501 * - When the application stops explicit scanning. 502 * The host may now be able to retry to automatically set up a connection. 503 * - The application tries to connect to another device, but fails. 504 * The host may now be able to retry to automatically set up a connection. 505 * - When the application wants to connect to a device, but we need 506 * to fallback to host privacy. 507 * - When the application wants to establish a periodic sync to a device 508 * and the application has not already started scanning. 509 * 510 * @param fast_scan Use fast scan parameters or slow scan parameters 511 * 512 * @return 0 in case of success, or a negative error code on failure. 513 */ 514 int bt_le_scan_update(bool fast_scan); 515 516 int bt_le_create_conn(const struct bt_conn *conn); 517 int bt_le_create_conn_cancel(void); 518 int bt_le_create_conn_synced(const struct bt_conn *conn, const struct bt_le_ext_adv *adv, 519 uint8_t subevent); 520 521 bool bt_addr_le_is_bonded(uint8_t id, const bt_addr_le_t *addr); 522 const bt_addr_le_t *bt_lookup_id_addr(uint8_t id, const bt_addr_le_t *addr); 523 524 int bt_send(struct net_buf *buf); 525 526 /* Don't require everyone to include keys.h */ 527 struct bt_keys; 528 void bt_id_add(struct bt_keys *keys); 529 void bt_id_del(struct bt_keys *keys); 530 531 struct bt_keys *bt_id_find_conflict(struct bt_keys *candidate); 532 533 int bt_setup_random_id_addr(void); 534 int bt_setup_public_id_addr(void); 535 536 void bt_finalize_init(void); 537 538 void bt_hci_host_num_completed_packets(struct net_buf *buf); 539 540 /* HCI event handlers */ 541 void bt_hci_pin_code_req(struct net_buf *buf); 542 void bt_hci_link_key_notify(struct net_buf *buf); 543 void bt_hci_link_key_req(struct net_buf *buf); 544 void bt_hci_io_capa_resp(struct net_buf *buf); 545 void bt_hci_io_capa_req(struct net_buf *buf); 546 void bt_hci_ssp_complete(struct net_buf *buf); 547 void bt_hci_user_confirm_req(struct net_buf *buf); 548 void bt_hci_user_passkey_notify(struct net_buf *buf); 549 void bt_hci_user_passkey_req(struct net_buf *buf); 550 void bt_hci_auth_complete(struct net_buf *buf); 551 552 /* ECC HCI event handlers */ 553 void bt_hci_evt_le_pkey_complete(struct net_buf *buf); 554 void bt_hci_evt_le_dhkey_complete(struct net_buf *buf); 555 556 /* Common HCI event handlers */ 557 void bt_hci_le_enh_conn_complete(struct bt_hci_evt_le_enh_conn_complete *evt); 558 559 /* Scan HCI event handlers */ 560 void bt_hci_le_adv_report(struct net_buf *buf); 561 void bt_hci_le_scan_timeout(struct net_buf *buf); 562 void bt_hci_le_adv_ext_report(struct net_buf *buf); 563 void bt_hci_le_per_adv_sync_established(struct net_buf *buf); 564 void bt_hci_le_per_adv_sync_established_v2(struct net_buf *buf); 565 void bt_hci_le_per_adv_report(struct net_buf *buf); 566 void bt_hci_le_per_adv_report_v2(struct net_buf *buf); 567 void bt_hci_le_per_adv_sync_lost(struct net_buf *buf); 568 void bt_hci_le_biginfo_adv_report(struct net_buf *buf); 569 void bt_hci_le_df_connectionless_iq_report(struct net_buf *buf); 570 void bt_hci_le_vs_df_connectionless_iq_report(struct net_buf *buf); 571 void bt_hci_le_past_received(struct net_buf *buf); 572 void bt_hci_le_past_received_v2(struct net_buf *buf); 573 574 /* Adv HCI event handlers */ 575 void bt_hci_le_adv_set_terminated(struct net_buf *buf); 576 void bt_hci_le_scan_req_received(struct net_buf *buf); 577 578 /* BR/EDR HCI event handlers */ 579 void bt_hci_conn_req(struct net_buf *buf); 580 void bt_hci_conn_complete(struct net_buf *buf); 581 582 583 void bt_hci_inquiry_complete(struct net_buf *buf); 584 void bt_hci_inquiry_result_with_rssi(struct net_buf *buf); 585 void bt_hci_extended_inquiry_result(struct net_buf *buf); 586 void bt_hci_remote_name_request_complete(struct net_buf *buf); 587 588 void bt_hci_read_remote_features_complete(struct net_buf *buf); 589 void bt_hci_read_remote_ext_features_complete(struct net_buf *buf); 590 void bt_hci_role_change(struct net_buf *buf); 591 void bt_hci_synchronous_conn_complete(struct net_buf *buf); 592 593 void bt_hci_le_df_connection_iq_report(struct net_buf *buf); 594 void bt_hci_le_vs_df_connection_iq_report(struct net_buf *buf); 595 void bt_hci_le_df_cte_req_failed(struct net_buf *buf); 596 597 void bt_hci_le_per_adv_subevent_data_request(struct net_buf *buf); 598 void bt_hci_le_per_adv_response_report(struct net_buf *buf); 599 600 void bt_tx_irq_raise(void); 601 void bt_send_one_host_num_completed_packets(uint16_t handle); 602 void bt_acl_set_ncp_sent(struct net_buf *packet, bool value); 603
