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