1 /* hci_core.h - Bluetooth HCI core access */ 2 3 /* 4 * Copyright (c) 2021-2025 Nordic Semiconductor ASA 5 * Copyright (c) 2015-2016 Intel Corporation 6 * 7 * SPDX-License-Identifier: Apache-2.0 8 */ 9 #include <stdbool.h> 10 #include <stdint.h> 11 12 #include <zephyr/autoconf.h> 13 #include <zephyr/bluetooth/addr.h> 14 #include <zephyr/bluetooth/bluetooth.h> 15 #include <zephyr/bluetooth/conn.h> 16 #include <zephyr/bluetooth/hci_types.h> 17 #include <zephyr/devicetree.h> 18 #include <zephyr/kernel.h> 19 #include <zephyr/net_buf.h> 20 #include <zephyr/sys/atomic.h> 21 #include <zephyr/sys/slist.h> 22 #include <zephyr/sys/util_macro.h> 23 24 /* LL connection parameters */ 25 #define LE_CONN_LATENCY 0x0000 26 #define LE_CONN_TIMEOUT 0x002a 27 28 #if defined(CONFIG_BT_CLASSIC) 29 #define LMP_FEAT_PAGES_COUNT 3 30 #else 31 #define LMP_FEAT_PAGES_COUNT 1 32 #endif 33 34 /* SCO settings */ 35 #define BT_VOICE_CVSD_16BIT 0x0060 36 37 /* k_poll event tags */ 38 enum { 39 BT_EVENT_CMD_TX, 40 BT_EVENT_CONN_TX_QUEUE, 41 BT_EVENT_CONN_FREE_TX, 42 }; 43 44 /* bt_dev flags: the flags defined here represent BT controller state */ 45 enum { 46 BT_DEV_ENABLE, 47 BT_DEV_DISABLE, 48 BT_DEV_READY, 49 BT_DEV_PRESET_ID, 50 BT_DEV_HAS_PUB_KEY, 51 52 /** The application either explicitly or implicitly instructed the stack to scan 53 * for advertisers. 54 * 55 * Examples of such cases 56 * - Explicit scanning, @ref BT_LE_SCAN_USER_EXPLICIT_SCAN. 57 * - The application instructed the stack to automatically connect if a given device 58 * is detected. 59 * - The application wants to connect to a peer device using private addresses, but 60 * the controller resolving list is too small. The host will fallback to using 61 * host-based privacy and first scan for the device before it initiates a connection. 62 * - The application wants to synchronize to a periodic advertiser. 63 * The host will implicitly start scanning if it is not already doing so. 64 * 65 * The host needs to keep track of this state to ensure it can restart scanning 66 * when a connection is established/lost, explicit scanning is started or stopped etc. 67 * Also, when the scanner and advertiser share the same identity, the scanner may need 68 * to be restarted upon RPA refresh. 69 */ 70 BT_DEV_SCANNING, 71 72 /** 73 * Scanner is configured with a timeout. 74 */ 75 BT_DEV_SCAN_LIMITED, 76 77 BT_DEV_INITIATING, 78 79 BT_DEV_RPA_VALID, 80 BT_DEV_RPA_TIMEOUT_CHANGED, 81 82 BT_DEV_ID_PENDING, 83 BT_DEV_STORE_ID, 84 85 #if defined(CONFIG_BT_CLASSIC) 86 BT_DEV_ISCAN, 87 BT_DEV_PSCAN, 88 BT_DEV_INQUIRY, 89 BT_DEV_LIMITED_DISCOVERABLE_MODE, 90 #endif /* CONFIG_BT_CLASSIC */ 91 92 /* Total number of flags - must be at the end of the enum */ 93 BT_DEV_NUM_FLAGS, 94 }; 95 96 /* Flags which should not be cleared upon HCI_Reset */ 97 #define BT_DEV_PERSISTENT_FLAGS (BIT(BT_DEV_ENABLE) | \ 98 BIT(BT_DEV_PRESET_ID) | \ 99 BIT(BT_DEV_DISABLE)) 100 101 #if defined(CONFIG_BT_EXT_ADV_LEGACY_SUPPORT) 102 /* Check the feature bit for extended or legacy advertising commands */ 103 #define BT_DEV_FEAT_LE_EXT_ADV(feat) BT_FEAT_LE_EXT_ADV(feat) 104 #else 105 /* Always use extended advertising commands. */ 106 #define BT_DEV_FEAT_LE_EXT_ADV(feat) 1 107 #endif 108 109 enum { 110 /* Advertising set has been created in the host. */ 111 BT_ADV_CREATED, 112 /* Advertising parameters has been set in the controller. 113 * This implies that the advertising set has been created in the 114 * controller. 115 */ 116 BT_ADV_PARAMS_SET, 117 /* Advertising data has been set in the controller. */ 118 BT_ADV_DATA_SET, 119 /* Advertising random address pending to be set in the controller. */ 120 BT_ADV_RANDOM_ADDR_PENDING, 121 /* The private random address of the advertiser is valid for this cycle 122 * of the RPA timeout. 123 */ 124 BT_ADV_RPA_VALID, 125 /* The private random address of the advertiser is being updated. */ 126 BT_ADV_RPA_UPDATE, 127 /* The advertiser set is limited by a timeout, or number of advertising 128 * events, or both. 129 */ 130 BT_ADV_LIMITED, 131 /* Advertiser set is currently advertising in the controller. */ 132 BT_ADV_ENABLED, 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[BT_LE_LOCAL_SUPPORTED_FEATURES_SIZE]; 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 struct bt_dev_br { 321 /* Max controller's acceptable ACL packet length */ 322 uint16_t mtu; 323 struct k_sem pkts; 324 uint16_t esco_pkt_type; 325 }; 326 327 /* The theoretical max for these is 8 and 64, but there's no point 328 * in allocating the full memory if we only support a small subset. 329 * These values must be updated whenever the host implementation is 330 * extended beyond the current values. 331 */ 332 #define BT_DEV_VS_FEAT_MAX 1 333 #define BT_DEV_VS_CMDS_MAX 2 334 335 /* State tracking for the local Bluetooth controller */ 336 struct bt_dev { 337 /* Local Identity Address(es) */ 338 bt_addr_le_t id_addr[CONFIG_BT_ID_MAX]; 339 uint8_t id_count; 340 341 struct bt_conn_le_create_param create_param; 342 343 #if !defined(CONFIG_BT_EXT_ADV) 344 /* Legacy advertiser */ 345 struct bt_le_ext_adv adv; 346 #else 347 /* Pointer to reserved advertising set */ 348 struct bt_le_ext_adv *adv; 349 #if defined(CONFIG_BT_CONN) && (CONFIG_BT_EXT_ADV_MAX_ADV_SET > 1) 350 /* When supporting multiple concurrent connectable advertising sets 351 * with multiple identities, we need to know the identity of 352 * the terminating advertising set to identify the connection object. 353 * The identity of the advertising set is determined by its 354 * advertising handle, which is part of the 355 * LE Set Advertising Set Terminated event which is always sent 356 * _after_ the LE Enhanced Connection complete event. 357 * Therefore we need cache this event until its identity is known. 358 */ 359 struct { 360 bool valid; 361 struct bt_hci_evt_le_enh_conn_complete evt; 362 } cached_conn_complete[MIN(CONFIG_BT_MAX_CONN, 363 CONFIG_BT_EXT_ADV_MAX_ADV_SET)]; 364 #endif 365 #endif 366 /* Current local Random Address */ 367 bt_addr_le_t random_addr; 368 uint8_t adv_conn_id; 369 370 /* Controller version & manufacturer information */ 371 uint8_t hci_version; 372 uint8_t lmp_version; 373 uint16_t hci_revision; 374 uint16_t lmp_subversion; 375 uint16_t manufacturer; 376 377 /* LMP features (pages 0, 1, 2) */ 378 uint8_t features[LMP_FEAT_PAGES_COUNT][8]; 379 380 /* Supported commands */ 381 uint8_t supported_commands[64]; 382 383 #if defined(CONFIG_BT_HCI_VS) 384 /* Vendor HCI support */ 385 uint8_t vs_features[BT_DEV_VS_FEAT_MAX]; 386 uint8_t vs_commands[BT_DEV_VS_CMDS_MAX]; 387 #endif 388 389 struct k_work init; 390 391 ATOMIC_DEFINE(flags, BT_DEV_NUM_FLAGS); 392 393 /* LE controller specific features */ 394 struct bt_dev_le le; 395 396 #if defined(CONFIG_BT_CLASSIC) 397 /* BR/EDR controller specific features */ 398 struct bt_dev_br br; 399 #endif 400 401 /* Number of commands controller can accept */ 402 struct k_sem ncmd_sem; 403 404 /* Last sent HCI command */ 405 struct net_buf *sent_cmd; 406 407 /* Queue for incoming HCI events & ACL data */ 408 sys_slist_t rx_queue; 409 410 /* Queue for outgoing HCI commands */ 411 struct k_fifo cmd_tx_queue; 412 413 const struct device *hci; 414 415 #if defined(CONFIG_BT_PRIVACY) 416 /* Local Identity Resolving Key */ 417 uint8_t irk[CONFIG_BT_ID_MAX][16]; 418 419 #if defined(CONFIG_BT_RPA_SHARING) 420 /* Only 1 RPA per identity */ 421 bt_addr_t rpa[CONFIG_BT_ID_MAX]; 422 #endif 423 424 /* Work used for RPA rotation */ 425 struct k_work_delayable rpa_update; 426 427 /* The RPA timeout value. */ 428 uint16_t rpa_timeout; 429 #endif 430 431 /* Local Name */ 432 #if defined(CONFIG_BT_DEVICE_NAME_DYNAMIC) 433 char name[CONFIG_BT_DEVICE_NAME_MAX + 1]; 434 #endif 435 #if defined(CONFIG_BT_DEVICE_APPEARANCE_DYNAMIC) 436 /* Appearance Value */ 437 uint16_t appearance; 438 #endif 439 }; 440 441 extern struct bt_dev bt_dev; 442 extern const struct bt_conn_auth_cb *bt_auth; 443 extern sys_slist_t bt_auth_info_cbs; 444 enum bt_security_err bt_security_err_get(uint8_t hci_err); 445 446 int bt_hci_recv(const struct device *dev, struct net_buf *buf); 447 448 /* Data type to store state related with command to be updated 449 * when command completes successfully. 450 */ 451 struct bt_hci_cmd_state_set { 452 /* Target memory to be updated */ 453 atomic_t *target; 454 /* Bit number to be updated in target memory */ 455 int bit; 456 /* Value to determine if enable or disable bit */ 457 bool val; 458 }; 459 460 /* Set command state related with the command buffer */ 461 void bt_hci_cmd_state_set_init(struct net_buf *buf, 462 struct bt_hci_cmd_state_set *state, 463 atomic_t *target, int bit, bool val); 464 465 int bt_hci_disconnect(uint16_t handle, uint8_t reason); 466 467 bool bt_le_conn_params_valid(const struct bt_le_conn_param *param); 468 int bt_le_set_data_len(struct bt_conn *conn, uint16_t tx_octets, uint16_t tx_time); 469 int bt_le_set_default_phy(uint8_t all_phys, uint8_t pref_tx_phy, uint8_t pref_rx_phy); 470 int bt_le_set_phy(struct bt_conn *conn, uint8_t all_phys, 471 uint8_t pref_tx_phy, uint8_t pref_rx_phy, uint8_t phy_opts); 472 uint8_t bt_get_phy(uint8_t hci_phy); 473 /** 474 * @brief Convert CTE type value from HCI format to @ref bt_df_cte_type format. 475 * 476 * @param hci_cte_type CTE type in an HCI format. 477 * 478 * @return CTE type (@ref bt_df_cte_type). 479 */ 480 int bt_get_df_cte_type(uint8_t hci_cte_type); 481 482 int bt_le_create_conn(const struct bt_conn *conn); 483 int bt_le_create_conn_cancel(void); 484 int bt_le_create_conn_synced(const struct bt_conn *conn, const struct bt_le_ext_adv *adv, 485 uint8_t subevent); 486 487 const bt_addr_le_t *bt_lookup_id_addr(uint8_t id, const bt_addr_le_t *addr); 488 489 int bt_send(struct net_buf *buf); 490 491 /* Don't require everyone to include keys.h */ 492 struct bt_keys; 493 void bt_id_add(struct bt_keys *keys); 494 void bt_id_del(struct bt_keys *keys); 495 496 struct bt_keys *bt_id_find_conflict(struct bt_keys *candidate); 497 498 int bt_setup_random_id_addr(void); 499 int bt_setup_public_id_addr(void); 500 501 void bt_finalize_init(void); 502 503 void bt_hci_host_num_completed_packets(struct net_buf *buf); 504 505 /* HCI event handlers */ 506 void bt_hci_pin_code_req(struct net_buf *buf); 507 void bt_hci_link_key_notify(struct net_buf *buf); 508 void bt_hci_link_key_req(struct net_buf *buf); 509 void bt_hci_io_capa_resp(struct net_buf *buf); 510 void bt_hci_io_capa_req(struct net_buf *buf); 511 void bt_hci_ssp_complete(struct net_buf *buf); 512 void bt_hci_user_confirm_req(struct net_buf *buf); 513 void bt_hci_user_passkey_notify(struct net_buf *buf); 514 void bt_hci_user_passkey_req(struct net_buf *buf); 515 void bt_hci_auth_complete(struct net_buf *buf); 516 517 /* Common HCI event handlers */ 518 void bt_hci_le_enh_conn_complete(struct bt_hci_evt_le_enh_conn_complete *evt); 519 520 /* Scan HCI event handlers */ 521 void bt_hci_le_adv_report(struct net_buf *buf); 522 void bt_hci_le_scan_timeout(struct net_buf *buf); 523 void bt_hci_le_adv_ext_report(struct net_buf *buf); 524 void bt_hci_le_per_adv_sync_established(struct net_buf *buf); 525 void bt_hci_le_per_adv_sync_established_v2(struct net_buf *buf); 526 void bt_hci_le_per_adv_report(struct net_buf *buf); 527 void bt_hci_le_per_adv_report_v2(struct net_buf *buf); 528 void bt_hci_le_per_adv_sync_lost(struct net_buf *buf); 529 void bt_hci_le_biginfo_adv_report(struct net_buf *buf); 530 void bt_hci_le_df_connectionless_iq_report(struct net_buf *buf); 531 void bt_hci_le_vs_df_connectionless_iq_report(struct net_buf *buf); 532 void bt_hci_le_past_received(struct net_buf *buf); 533 void bt_hci_le_past_received_v2(struct net_buf *buf); 534 535 /* CS HCI event handlers */ 536 void bt_hci_le_cs_read_remote_supported_capabilities_complete(struct net_buf *buf); 537 void bt_hci_le_cs_read_remote_fae_table_complete(struct net_buf *buf); 538 void bt_hci_le_cs_config_complete_event(struct net_buf *buf); 539 void bt_hci_le_cs_security_enable_complete(struct net_buf *buf); 540 void bt_hci_le_cs_procedure_enable_complete(struct net_buf *buf); 541 void bt_hci_le_cs_subevent_result(struct net_buf *buf); 542 void bt_hci_le_cs_subevent_result_continue(struct net_buf *buf); 543 void bt_hci_le_cs_test_end_complete(struct net_buf *buf); 544 545 /* Adv HCI event handlers */ 546 void bt_hci_le_adv_set_terminated(struct net_buf *buf); 547 void bt_hci_le_scan_req_received(struct net_buf *buf); 548 549 /* BR/EDR HCI event handlers */ 550 void bt_hci_conn_req(struct net_buf *buf); 551 void bt_hci_conn_complete(struct net_buf *buf); 552 553 554 void bt_hci_inquiry_complete(struct net_buf *buf); 555 void bt_hci_inquiry_result_with_rssi(struct net_buf *buf); 556 void bt_hci_extended_inquiry_result(struct net_buf *buf); 557 void bt_hci_remote_name_request_complete(struct net_buf *buf); 558 559 void bt_hci_read_remote_features_complete(struct net_buf *buf); 560 void bt_hci_read_remote_ext_features_complete(struct net_buf *buf); 561 void bt_hci_role_change(struct net_buf *buf); 562 void bt_hci_synchronous_conn_complete(struct net_buf *buf); 563 564 void bt_hci_le_df_connection_iq_report(struct net_buf *buf); 565 void bt_hci_le_vs_df_connection_iq_report(struct net_buf *buf); 566 void bt_hci_le_df_cte_req_failed(struct net_buf *buf); 567 568 void bt_hci_le_per_adv_subevent_data_request(struct net_buf *buf); 569 void bt_hci_le_per_adv_response_report(struct net_buf *buf); 570 571 int bt_hci_read_remote_version(struct bt_conn *conn); 572 int bt_hci_le_read_remote_features(struct bt_conn *conn); 573 int bt_hci_le_read_max_data_len(uint16_t *tx_octets, uint16_t *tx_time); 574 575 bool bt_drv_quirk_no_auto_dle(void); 576 577 void bt_tx_irq_raise(void); 578