1 /** 2 * @file 3 * @brief Bluetooth ISO handling 4 */ 5 6 /* 7 * Copyright (c) 2020 Intel Corporation 8 * Copyright (c) 2021-2024 Nordic Semiconductor ASA 9 * 10 * SPDX-License-Identifier: Apache-2.0 11 */ 12 #ifndef ZEPHYR_INCLUDE_BLUETOOTH_ISO_H_ 13 #define ZEPHYR_INCLUDE_BLUETOOTH_ISO_H_ 14 15 /** 16 * @brief Isochronous channels (ISO) 17 * @defgroup bt_iso Isochronous channels (ISO) 18 * 19 * @since 2.3 20 * @version 0.8.0 21 * 22 * @ingroup bluetooth 23 * @{ 24 */ 25 26 #include <stdint.h> 27 28 #include <zephyr/bluetooth/addr.h> 29 #include <zephyr/bluetooth/bluetooth.h> 30 #include <zephyr/bluetooth/buf.h> 31 #include <zephyr/bluetooth/conn.h> 32 #include <zephyr/bluetooth/hci.h> 33 #include <zephyr/net_buf.h> 34 #include <zephyr/sys/atomic.h> 35 #include <zephyr/sys/slist.h> 36 #include <zephyr/sys/util_macro.h> 37 #include <zephyr/sys/slist.h> 38 39 #ifdef __cplusplus 40 extern "C" { 41 #endif 42 43 /** 44 * @brief Headroom needed for outgoing ISO SDUs 45 */ 46 #define BT_ISO_CHAN_SEND_RESERVE BT_BUF_ISO_SIZE(0) 47 48 /** 49 * @brief Helper to calculate needed buffer size for ISO SDUs. 50 * Useful for creating buffer pools. 51 * 52 * @param mtu Required ISO SDU size 53 * 54 * @return Needed buffer size to match the requested ISO SDU MTU. 55 */ 56 #define BT_ISO_SDU_BUF_SIZE(mtu) BT_BUF_ISO_SIZE(mtu) 57 58 /** 59 * Convert BIS index to bit 60 * 61 * The BIS indexes start from 0x01, so the lowest allowed bit is 62 * BIT(0) that represents index 0x01. To synchronize to e.g. BIS 63 * indexes 0x01 and 0x02, the bitfield value should be BIT(0) | BIT(1). 64 * As a general notation, to sync to BIS index N use BIT(N - 1). 65 */ 66 #define BT_ISO_BIS_INDEX_BIT(x) (BIT((x) - 1)) 67 68 /** Value to set the ISO data path over HCi. */ 69 #define BT_ISO_DATA_PATH_HCI 0x00 70 71 /** Unknown SDU interval */ 72 #define BT_ISO_SDU_INTERVAL_UNKNOWN 0x000000U 73 /** Minimum interval value in microseconds */ 74 #define BT_ISO_SDU_INTERVAL_MIN 0x0000FFU 75 /** Maximum interval value in microseconds */ 76 #define BT_ISO_SDU_INTERVAL_MAX 0x0FFFFFU 77 /** Minimum ISO interval (N * 1.25 ms) */ 78 #define BT_ISO_ISO_INTERVAL_MIN 0x0004U 79 /** Maximum ISO interval (N * 1.25 ms) */ 80 #define BT_ISO_ISO_INTERVAL_MAX 0x0C80U 81 /** Minimum latency value in milliseconds */ 82 #define BT_ISO_LATENCY_MIN 0x0005 83 /** Maximum latency value in milliseconds */ 84 #define BT_ISO_LATENCY_MAX 0x0FA0 85 /** Packets will be sent sequentially between the channels in the group */ 86 #define BT_ISO_PACKING_SEQUENTIAL 0x00 87 /** Packets will be sent interleaved between the channels in the group */ 88 #define BT_ISO_PACKING_INTERLEAVED 0x01 89 /** Packets may be framed or unframed */ 90 #define BT_ISO_FRAMING_UNFRAMED 0x00 91 /** Packets are always framed */ 92 #define BT_ISO_FRAMING_FRAMED 0x01 93 /** Maximum number of isochronous channels in a single group */ 94 #define BT_ISO_MAX_GROUP_ISO_COUNT 0x1F 95 /** Minimum SDU size */ 96 #define BT_ISO_MIN_SDU 0x0001 97 /** Maximum SDU size */ 98 #define BT_ISO_MAX_SDU 0x0FFF 99 /** Minimum PDU size */ 100 #define BT_ISO_CONNECTED_PDU_MIN 0x0000U 101 /** Minimum PDU size */ 102 #define BT_ISO_BROADCAST_PDU_MIN 0x0001U 103 /** Maximum PDU size */ 104 #define BT_ISO_PDU_MAX 0x00FBU 105 /** Minimum burst number */ 106 #define BT_ISO_BN_MIN 0x01U 107 /** Maximum burst number */ 108 #define BT_ISO_BN_MAX 0x0FU 109 /** Minimum flush timeout */ 110 #define BT_ISO_FT_MIN 0x01U 111 /** Maximum flush timeout */ 112 #define BT_ISO_FT_MAX 0xFFU 113 /** Minimum number of subevents */ 114 #define BT_ISO_NSE_MIN 0x01U 115 /** Maximum number of subevents */ 116 #define BT_ISO_NSE_MAX 0x1FU 117 /** Minimum BIG sync timeout value (N * 10 ms) */ 118 #define BT_ISO_SYNC_TIMEOUT_MIN 0x000A 119 /** Maximum BIG sync timeout value (N * 10 ms) */ 120 #define BT_ISO_SYNC_TIMEOUT_MAX 0x4000 121 /** Controller controlled maximum subevent count value */ 122 #define BT_ISO_SYNC_MSE_ANY 0x00 123 /** Minimum BIG sync maximum subevent count value */ 124 #define BT_ISO_SYNC_MSE_MIN 0x01 125 /** Maximum BIG sync maximum subevent count value */ 126 #define BT_ISO_SYNC_MSE_MAX 0x1F 127 /** Maximum connected ISO retransmission value */ 128 #define BT_ISO_CONNECTED_RTN_MAX 0xFF 129 /** Maximum broadcast ISO retransmission value */ 130 #define BT_ISO_BROADCAST_RTN_MAX 0x1E 131 /** Broadcast code size */ 132 #define BT_ISO_BROADCAST_CODE_SIZE 16 133 /** Lowest BIS index */ 134 #define BT_ISO_BIS_INDEX_MIN 0x01 135 /** Highest BIS index */ 136 #define BT_ISO_BIS_INDEX_MAX 0x1F 137 /** Minimum Immediate Repetition Count */ 138 #define BT_ISO_IRC_MIN 0x01U 139 /** Maximum Immediate Repetition Count */ 140 #define BT_ISO_IRC_MAX 0x0FU 141 /** Minimum pre-transmission offset */ 142 #define BT_ISO_PTO_MIN 0x00U 143 /** Maximum pre-transmission offset */ 144 #define BT_ISO_PTO_MAX 0x0FU 145 /** No subinterval */ 146 #define BT_ISO_SUBINTERVAL_NONE 0x00000000U 147 /** Unknown subinterval */ 148 #define BT_ISO_SUBINTERVAL_UNKNOWN 0xFFFFFFFFU 149 150 /** 151 * @brief Check if ISO BIS bitfield is valid (BT_ISO_BIS_INDEX_BIT(1)|..|BT_ISO_BIS_INDEX_BIT(31)) 152 * 153 * @param _bis_bitfield BIS index bitfield (uint32) 154 */ 155 #define BT_ISO_VALID_BIS_BITFIELD(_bis_bitfield) \ 156 ((_bis_bitfield) != 0U && (_bis_bitfield) <= BIT_MASK(BT_ISO_BIS_INDEX_MAX)) 157 158 /** 159 * @brief Life-span states of ISO channel. Used only by internal APIs dealing with setting channel 160 * to proper state depending on operational context. 161 */ 162 enum bt_iso_state { 163 /** Channel disconnected */ 164 BT_ISO_STATE_DISCONNECTED, 165 /** Channel is pending ACL encryption before connecting */ 166 BT_ISO_STATE_ENCRYPT_PENDING, 167 /** Channel in connecting state */ 168 BT_ISO_STATE_CONNECTING, 169 /** Channel ready for upper layer traffic on it */ 170 BT_ISO_STATE_CONNECTED, 171 /** Channel in disconnecting state */ 172 BT_ISO_STATE_DISCONNECTING, 173 }; 174 175 176 /** 177 * @brief ISO Channel Type. 178 */ 179 enum bt_iso_chan_type { 180 BT_ISO_CHAN_TYPE_NONE, /**< No channel type */ 181 BT_ISO_CHAN_TYPE_CONNECTED, /**< Connected */ 182 BT_ISO_CHAN_TYPE_BROADCASTER, /**< Isochronous broadcaster */ 183 BT_ISO_CHAN_TYPE_SYNC_RECEIVER /**< Synchronized receiver */ 184 }; 185 186 /** @brief ISO Channel structure. */ 187 struct bt_iso_chan { 188 /** Channel connection reference */ 189 struct bt_conn *iso; 190 /** Channel operations reference */ 191 struct bt_iso_chan_ops *ops; 192 /** Channel QoS reference */ 193 struct bt_iso_chan_qos *qos; 194 /** Channel state */ 195 enum bt_iso_state state; 196 #if (defined(CONFIG_BT_SMP) && defined(CONFIG_BT_ISO_UNICAST)) || defined(__DOXYGEN__) 197 /** 198 * @brief The required security level of the channel 199 * 200 * This value can be set as the central before connecting a CIS 201 * with bt_iso_chan_connect(). 202 * The value is overwritten to @ref bt_iso_server::sec_level for the 203 * peripheral once a channel has been accepted. 204 * 205 * Only available when @kconfig{CONFIG_BT_SMP} is enabled. 206 */ 207 bt_security_t required_sec_level; 208 #endif /* CONFIG_BT_SMP && CONFIG_BT_ISO_UNICAST */ 209 /** @internal Node used internally by the stack */ 210 sys_snode_t node; 211 }; 212 213 /** @brief ISO Channel IO QoS structure. */ 214 struct bt_iso_chan_io_qos { 215 /** 216 * @brief Channel SDU. 217 * 218 * Value range is @ref BT_ISO_MIN_SDU to @ref BT_ISO_MAX_SDU. 219 */ 220 uint16_t sdu; 221 /** 222 * @brief Channel PHY - See the BT_GAP_LE_PHY_* values. 223 * 224 * Setting @ref BT_GAP_LE_PHY_NONE is invalid. 225 */ 226 uint8_t phy; 227 /** 228 * @brief Channel Retransmission Number. 229 * 230 * This value is ignored if any advanced ISO parameters are set. 231 */ 232 uint8_t rtn; 233 /** 234 * @brief Channel data path reference 235 * 236 * Setting to NULL default to HCI data path (same as setting path.pid 237 * to @ref BT_ISO_DATA_PATH_HCI). 238 */ 239 struct bt_iso_chan_path *path; 240 241 #if defined(CONFIG_BT_ISO_TEST_PARAMS) || defined(__DOXYGEN__) 242 /** 243 * @brief Maximum PDU size 244 * 245 * Maximum size, in octets, of the payload from link layer to link layer. 246 * 247 * Value range @ref BT_ISO_CONNECTED_PDU_MIN to @ref BT_ISO_PDU_MAX for connected ISO. 248 * 249 * Value range @ref BT_ISO_BROADCAST_PDU_MIN to @ref BT_ISO_PDU_MAX for broadcast ISO. 250 */ 251 uint16_t max_pdu; 252 253 /** 254 * @brief Burst number 255 * 256 * Value range @ref BT_ISO_BN_MIN to @ref BT_ISO_BN_MAX. 257 */ 258 uint8_t burst_number; 259 #endif /* CONFIG_BT_ISO_TEST_PARAMS */ 260 }; 261 262 /** @brief ISO Channel QoS structure. */ 263 struct bt_iso_chan_qos { 264 /** 265 * @brief Channel Receiving QoS. 266 * 267 * Setting NULL disables data path @ref BT_HCI_DATAPATH_DIR_CTLR_TO_HOST. 268 * 269 * Can only be set for a connected isochronous channel, or a broadcast isochronous receiver. 270 */ 271 struct bt_iso_chan_io_qos *rx; 272 /** 273 * @brief Channel Transmission QoS 274 * 275 * Setting NULL disables data path @ref BT_HCI_DATAPATH_DIR_HOST_TO_CTLR. 276 * 277 * Can only be set for a connected isochronous channel, or a broadcast 278 * isochronous transmitter. 279 */ 280 struct bt_iso_chan_io_qos *tx; 281 282 #if defined(CONFIG_BT_ISO_TEST_PARAMS) || defined(__DOXYGEN__) 283 /** 284 * @brief Number of subevents 285 * 286 * Maximum number of subevents in each CIS or BIS event. 287 * 288 * Value range @ref BT_ISO_NSE_MIN to @ref BT_ISO_NSE_MAX. 289 */ 290 uint8_t num_subevents; 291 #endif /* CONFIG_BT_ISO_TEST_PARAMS */ 292 }; 293 294 /** @brief ISO Channel Data Path structure. */ 295 struct bt_iso_chan_path { 296 /** Default path ID */ 297 uint8_t pid; 298 /** Coding Format */ 299 uint8_t format; 300 /** Company ID */ 301 uint16_t cid; 302 /** Vendor-defined Codec ID */ 303 uint16_t vid; 304 /** Controller Delay */ 305 uint32_t delay; 306 /** Codec Configuration length*/ 307 uint8_t cc_len; 308 /** Pointer to an array containing the Codec Configuration */ 309 uint8_t *cc; 310 }; 311 312 /** ISO packet status flag bits */ 313 enum { 314 /** The ISO packet is valid. */ 315 BT_ISO_FLAGS_VALID = BIT(0), 316 317 /** 318 * @brief The ISO packet may possibly contain errors. 319 * 320 * May be caused by a failed CRC check or if missing a part of the SDU. 321 */ 322 BT_ISO_FLAGS_ERROR = BIT(1), 323 324 /** The ISO packet was lost. */ 325 BT_ISO_FLAGS_LOST = BIT(2), 326 327 /** 328 * @brief Timestamp is valid 329 * 330 * If not set, then the bt_iso_recv_info.ts value is not valid, and 331 * should not be used. 332 */ 333 BT_ISO_FLAGS_TS = BIT(3) 334 }; 335 336 /** @brief ISO Meta Data structure for received ISO packets. */ 337 struct bt_iso_recv_info { 338 /** 339 * @brief ISO timestamp 340 * 341 * Only valid if @p flags has the @ref BT_ISO_FLAGS_TS bit set. 342 */ 343 uint32_t ts; 344 345 /** ISO packet sequence number of the first fragment in the SDU */ 346 uint16_t seq_num; 347 348 /** ISO packet flags bitfield (BT_ISO_FLAGS_*) */ 349 uint8_t flags; 350 }; 351 352 /** @brief ISO Meta Data structure for transmitted ISO packets. */ 353 struct bt_iso_tx_info { 354 /** CIG reference point or BIG anchor point of a transmitted SDU, in microseconds. */ 355 uint32_t ts; 356 357 /** Time offset, in microseconds */ 358 uint32_t offset; 359 360 /** Packet sequence number */ 361 uint16_t seq_num; 362 }; 363 364 365 /** Opaque type representing an Connected Isochronous Group (CIG). */ 366 struct bt_iso_cig; 367 368 /** @brief Connected Isochronous Group (CIG) parameters */ 369 struct bt_iso_cig_param { 370 /** @brief Array of pointers to CIS channels */ 371 struct bt_iso_chan **cis_channels; 372 373 /** 374 * @brief Number of channels in @p cis_channels 375 * 376 * Maximum number of channels in a single group is @ref BT_ISO_MAX_GROUP_ISO_COUNT 377 */ 378 uint8_t num_cis; 379 380 /** 381 * @brief Channel interval in us for SDUs sent from Central to Peripheral. 382 * 383 * Value range @ref BT_ISO_SDU_INTERVAL_MIN to @ref BT_ISO_SDU_INTERVAL_MAX. 384 */ 385 uint32_t c_to_p_interval; 386 387 /** 388 * @brief Channel interval in us for SDUs sent from Peripheral to Central. 389 * 390 * Value range @ref BT_ISO_SDU_INTERVAL_MIN to @ref BT_ISO_SDU_INTERVAL_MAX. 391 */ 392 uint32_t p_to_c_interval; 393 394 /** 395 * @brief Channel Latency in ms for SDUs sent from Central to Peripheral 396 * 397 * Value range @ref BT_ISO_LATENCY_MIN to @ref BT_ISO_LATENCY_MAX. 398 * 399 * This value is ignored if any advanced ISO parameters are set. 400 */ 401 uint16_t c_to_p_latency; 402 403 /** 404 * @brief Channel Latency in ms for SDUs sent from Peripheral to Central 405 * 406 * Value range @ref BT_ISO_LATENCY_MIN to @ref BT_ISO_LATENCY_MAX. 407 * 408 * This value is ignored if any advanced ISO parameters are set. 409 */ 410 uint16_t p_to_c_latency; 411 412 /** 413 * @brief Channel peripherals sleep clock accuracy Only for CIS 414 * 415 * Shall be worst case sleep clock accuracy of all the peripherals. 416 * For possible values see the BT_GAP_SCA_* values. 417 * If unknown for the peripherals, this should be set to @ref BT_GAP_SCA_UNKNOWN. 418 */ 419 uint8_t sca; 420 421 /** 422 * @brief Channel packing mode. 423 * 424 * @ref BT_ISO_PACKING_SEQUENTIAL or @ref BT_ISO_PACKING_INTERLEAVED 425 */ 426 uint8_t packing; 427 428 /** 429 * @brief Channel framing mode. 430 * 431 * @ref BT_ISO_FRAMING_UNFRAMED for unframed and @ref BT_ISO_FRAMING_FRAMED for framed. 432 */ 433 uint8_t framing; 434 435 #if defined(CONFIG_BT_ISO_TEST_PARAMS) || defined(__DOXYGEN__) 436 /** 437 * @brief Central to Peripheral flush timeout 438 * 439 * The flush timeout in multiples of ISO_Interval for each payload sent 440 * from the Central to Peripheral. 441 * 442 * Value range from @ref BT_ISO_FT_MIN to @ref BT_ISO_FT_MAX 443 */ 444 uint8_t c_to_p_ft; 445 446 /** 447 * @brief Peripheral to Central flush timeout 448 * 449 * The flush timeout in multiples of ISO_Interval for each payload sent 450 * from the Peripheral to Central. 451 * 452 * Value range from @ref BT_ISO_FT_MIN to @ref BT_ISO_FT_MAX. 453 */ 454 uint8_t p_to_c_ft; 455 456 /** 457 * @brief ISO interval 458 * 459 * Time between consecutive CIS anchor points. 460 * 461 * Value range from @ref BT_ISO_ISO_INTERVAL_MIN to @ref BT_ISO_ISO_INTERVAL_MAX. 462 */ 463 uint16_t iso_interval; 464 #endif /* CONFIG_BT_ISO_TEST_PARAMS */ 465 }; 466 467 /** ISO connection parameters structure */ 468 struct bt_iso_connect_param { 469 /** The ISO channel to connect */ 470 struct bt_iso_chan *iso_chan; 471 472 /** The ACL connection */ 473 struct bt_conn *acl; 474 }; 475 476 /** Opaque type representing a Broadcast Isochronous Group (BIG). */ 477 struct bt_iso_big; 478 479 /** @brief Broadcast Isochronous Group (BIG) creation parameters */ 480 struct bt_iso_big_create_param { 481 /** Array of pointers to BIS channels */ 482 struct bt_iso_chan **bis_channels; 483 484 /** 485 * @brief Number of channels in @p bis_channels 486 * 487 * Maximum number of channels in a single group is @ref BT_ISO_MAX_GROUP_ISO_COUNT 488 */ 489 uint8_t num_bis; 490 491 /** 492 * @brief Channel interval in us. 493 * 494 * Value range @ref BT_ISO_SDU_INTERVAL_MIN to @ref BT_ISO_SDU_INTERVAL_MAX. 495 */ 496 uint32_t interval; 497 498 /** 499 * @brief Channel Latency in ms. 500 * 501 * Value range @ref BT_ISO_LATENCY_MIN to @ref BT_ISO_LATENCY_MAX. 502 * 503 * This value is ignored if any advanced ISO parameters are set. 504 */ 505 uint16_t latency; 506 507 /** 508 * @brief Channel packing mode. 509 * 510 * @ref BT_ISO_PACKING_SEQUENTIAL or @ref BT_ISO_PACKING_INTERLEAVED 511 */ 512 uint8_t packing; 513 514 /** 515 * @brief Channel framing mode. 516 * 517 * @ref BT_ISO_FRAMING_UNFRAMED for unframed and @ref BT_ISO_FRAMING_FRAMED for framed. 518 */ 519 uint8_t framing; 520 521 /** Whether or not to encrypt the streams. */ 522 bool encryption; 523 524 /** 525 * @brief Broadcast code 526 * 527 * The code used to derive the session key that is used to encrypt and decrypt BIS payloads. 528 * 529 * If the value is a string or the value is less than 16 octets, 530 * the remaining octets shall be 0. 531 * 532 * Example: 533 * The string "Broadcast Code" shall be 534 * [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00] 535 */ 536 uint8_t bcode[BT_ISO_BROADCAST_CODE_SIZE]; 537 538 #if defined(CONFIG_BT_ISO_TEST_PARAMS) || defined(__DOXYGEN__) 539 /** 540 * @brief Immediate Repetition Count 541 * 542 * The number of times the scheduled payloads are transmitted in a given event. 543 * 544 * Value range from @ref BT_ISO_IRC_MIN to @ref BT_ISO_IRC_MAX. 545 */ 546 uint8_t irc; 547 548 /** 549 * @brief Pre-transmission offset 550 * 551 * Offset used for pre-transmissions. 552 * 553 * Value range from @ref BT_ISO_PTO_MIN to @ref BT_ISO_PTO_MAX. 554 */ 555 uint8_t pto; 556 557 /** 558 * @brief ISO interval 559 * 560 * Time between consecutive BIS anchor points. 561 * 562 * Value range from @ref BT_ISO_ISO_INTERVAL_MIN to @ref BT_ISO_ISO_INTERVAL_MAX. 563 */ 564 uint16_t iso_interval; 565 #endif /* CONFIG_BT_ISO_TEST_PARAMS */ 566 }; 567 568 /** @brief Broadcast Isochronous Group (BIG) Sync Parameters */ 569 struct bt_iso_big_sync_param { 570 /** Array of pointers to BIS channels */ 571 struct bt_iso_chan **bis_channels; 572 573 /** 574 * @brief Number channels in @p bis_channels 575 * 576 * Maximum number of channels in a single group is @ref BT_ISO_MAX_GROUP_ISO_COUNT 577 */ 578 uint8_t num_bis; 579 580 /** 581 * @brief Bitfield of the BISes to sync to 582 * 583 * Use @ref BT_ISO_BIS_INDEX_BIT to convert BIS indexes to a bitfield. 584 * 585 * To synchronize to e.g. BIS indexes 0x01 and 0x02, this can be set to 586 * BT_ISO_BIS_INDEX_BIT(0x01) | BT_ISO_BIS_INDEX_BIT(0x02). 587 */ 588 uint32_t bis_bitfield; 589 590 /** 591 * @brief Maximum subevents 592 * 593 * The MSE (Maximum Subevents) parameter is the maximum number of 594 * subevents that a Controller should use to receive data payloads 595 * in each interval for a BIS. 596 * 597 * Value range is @ref BT_ISO_SYNC_MSE_MIN to @ref BT_ISO_SYNC_MSE_MAX, or 598 * @ref BT_ISO_SYNC_MSE_ANY to let the controller choose. 599 */ 600 uint32_t mse; 601 602 /** 603 * @brief Synchronization timeout for the BIG (N * 10 MS) 604 * 605 * Value range is @ref BT_ISO_SYNC_TIMEOUT_MIN to @ref BT_ISO_SYNC_TIMEOUT_MAX. 606 */ 607 uint16_t sync_timeout; 608 609 /** Whether or not the streams of the BIG are encrypted */ 610 bool encryption; 611 612 /** 613 * @brief Broadcast code 614 * 615 * The code used to derive the session key that is used to encrypt and decrypt BIS payloads. 616 * 617 * If the value is a string or a the value is less than 16 octets, 618 * the remaining octets shall be 0. 619 * 620 * Example: 621 * The string "Broadcast Code" shall be 622 * [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00] 623 */ 624 uint8_t bcode[BT_ISO_BROADCAST_CODE_SIZE]; 625 }; 626 627 /** @brief Broadcast Isochronous Group (BIG) information */ 628 struct bt_iso_biginfo { 629 /** Address of the advertiser */ 630 const bt_addr_le_t *addr; 631 632 /** Advertiser SID */ 633 uint8_t sid; 634 635 /** Number of BISes in the BIG */ 636 uint8_t num_bis; 637 638 /** Maximum number of subevents in each isochronous event */ 639 uint8_t sub_evt_count; 640 641 /** Interval between two BIG anchor point (N * 1.25 ms) */ 642 uint16_t iso_interval; 643 644 /** The number of new payloads in each BIS event */ 645 uint8_t burst_number; 646 647 /** Offset used for pre-transmissions */ 648 uint8_t offset; 649 650 /** The number of times a payload is transmitted in a BIS event */ 651 uint8_t rep_count; 652 653 /** Maximum size, in octets, of the payload */ 654 uint16_t max_pdu; 655 656 /** The interval, in microseconds, of periodic SDUs. */ 657 uint32_t sdu_interval; 658 659 /** Maximum size of an SDU, in octets. */ 660 uint16_t max_sdu; 661 662 /** Channel PHY */ 663 uint8_t phy; 664 665 /** Channel framing mode */ 666 uint8_t framing; 667 668 /** Whether or not the BIG is encrypted */ 669 bool encryption; 670 }; 671 672 /** @brief ISO Channel operations structure. */ 673 struct bt_iso_chan_ops { 674 /** 675 * @brief Channel connected callback 676 * 677 * If this callback is provided it will be called whenever the connection completes. 678 * 679 * For a peripheral, the QoS values (see @ref bt_iso_chan_io_qos) 680 * are set when this is called. The peripheral does not have any 681 * information about the RTN though. 682 * 683 * @param chan The channel that has been connected 684 */ 685 void (*connected)(struct bt_iso_chan *chan); 686 687 /** 688 * @brief Channel disconnected callback 689 * 690 * If this callback is provided it will be called whenever the 691 * channel is disconnected, including when a connection gets 692 * rejected or when setting security fails. 693 * 694 * @param chan The channel that has been Disconnected 695 * @param reason BT_HCI_ERR_* reason for the disconnection. 696 */ 697 void (*disconnected)(struct bt_iso_chan *chan, uint8_t reason); 698 699 /** 700 * @brief Channel alloc_buf callback 701 * 702 * If this callback is provided the channel will use it to allocate 703 * buffers to store incoming data. 704 * 705 * @param chan The channel requesting a buffer. 706 * 707 * @return Allocated buffer. 708 */ 709 struct net_buf *(*alloc_buf)(struct bt_iso_chan *chan); 710 711 /** 712 * @brief Channel recv callback 713 * 714 * @param chan The channel receiving data. 715 * @param buf Buffer containing incoming data. 716 * @param info Pointer to the metadata for the buffer. The lifetime of the 717 * pointer is linked to the lifetime of the net_buf. 718 * Metadata such as sequence number and timestamp can be 719 * provided by the bluetooth controller. 720 */ 721 void (*recv)(struct bt_iso_chan *chan, const struct bt_iso_recv_info *info, 722 struct net_buf *buf); 723 724 /** 725 * @brief Channel sent callback 726 * 727 * This callback will be called once the controller marks the SDU 728 * as completed. When the controller does so is implementation 729 * dependent. It could be after the SDU is enqueued for transmission, 730 * or after it is sent on air or flushed. 731 * 732 * @param chan The channel which has sent data. 733 */ 734 void (*sent)(struct bt_iso_chan *chan); 735 }; 736 737 /** @brief ISO Accept Info Structure */ 738 struct bt_iso_accept_info { 739 /** The ACL connection that is requesting authorization */ 740 struct bt_conn *acl; 741 742 /** 743 * @brief The ID of the connected isochronous group (CIG) on the central 744 * 745 * The ID is unique per ACL 746 */ 747 uint8_t cig_id; 748 749 /** 750 * @brief The ID of the connected isochronous stream (CIS) on the central 751 * 752 * This ID is unique within a CIG 753 */ 754 uint8_t cis_id; 755 }; 756 757 /** @brief ISO Server structure. */ 758 struct bt_iso_server { 759 #if defined(CONFIG_BT_SMP) || defined(__DOXYGEN__) 760 /** 761 * @brief Required minimum security level. 762 * 763 * Only available when @kconfig{CONFIG_BT_SMP} is enabled. 764 */ 765 bt_security_t sec_level; 766 #endif /* CONFIG_BT_SMP */ 767 768 /** 769 * @brief Server accept callback 770 * 771 * This callback is called whenever a new incoming connection requires authorization. 772 * 773 * @param info The ISO accept information structure 774 * @param chan Pointer to receive the allocated channel 775 * 776 * @return 0 in case of success or negative value in case of error. 777 */ 778 int (*accept)(const struct bt_iso_accept_info *info, struct bt_iso_chan **chan); 779 }; 780 781 /** 782 * @brief Register ISO server. 783 * 784 * Register ISO server, each new connection is authorized using the accept() 785 * callback which in case of success shall allocate the channel structure 786 * to be used by the new connection. 787 * 788 * @param server Server structure. 789 * 790 * @return 0 in case of success or negative value in case of error. 791 */ 792 int bt_iso_server_register(struct bt_iso_server *server); 793 794 /** 795 * @brief Unregister ISO server. 796 * 797 * Unregister previously registered ISO server. 798 * 799 * @param server Server structure. 800 * 801 * @return 0 in case of success or negative value in case of error. 802 */ 803 int bt_iso_server_unregister(struct bt_iso_server *server); 804 805 /** 806 * @brief Creates a CIG as a central 807 * 808 * This can called at any time, even before connecting to a remote device. 809 * This must be called before any connected isochronous stream (CIS) channel can be connected. 810 * 811 * Once a CIG is created, the channels supplied in the @p param can be 812 * connected using bt_iso_chan_connect(). 813 * 814 * @param[in] param The parameters used to create and enable the CIG. 815 * @param[out] out_cig Connected Isochronous Group object on success. 816 * 817 * @return 0 in case of success or negative value in case of error. 818 */ 819 int bt_iso_cig_create(const struct bt_iso_cig_param *param, struct bt_iso_cig **out_cig); 820 821 /** 822 * @brief Reconfigure a CIG as a central 823 * 824 * This function can be used to update a CIG. It will update the group specific 825 * parameters, and, if supplied, change the QoS parameters of the individual 826 * CIS. If the cis_channels in @p param contains CIS that was not originally 827 * in the call to bt_iso_cig_create(), these will be added to the group. 828 * It is not possible to remove any CIS from the group after creation. 829 * 830 * This can be called at any time before connecting an ISO to a remote device. 831 * Once any CIS in the group has connected, the group cannot be changed. 832 * 833 * Once a CIG is created, the channels supplied in the @p param can be 834 * connected using bt_iso_chan_connect(). 835 * 836 * @param cig Connected Isochronous Group object. 837 * @param param The parameters used to reconfigure the CIG. 838 * 839 * @return 0 in case of success or negative value in case of error. 840 */ 841 int bt_iso_cig_reconfigure(struct bt_iso_cig *cig, const struct bt_iso_cig_param *param); 842 843 /** 844 * @brief Terminates a CIG as a central 845 * 846 * All the CIS in the CIG shall be disconnected first. 847 * 848 * @param cig Pointer to the CIG structure. 849 * 850 * @return 0 in case of success or negative value in case of error. 851 */ 852 int bt_iso_cig_terminate(struct bt_iso_cig *cig); 853 854 /** 855 * @brief Connect ISO channels on ACL connections 856 * 857 * Connect ISO channels. The ISO channels must have been initialized in a CIG 858 * first by calling bt_iso_cig_create(). 859 * 860 * Once the connection is completed the channels' connected() callback will be 861 * called. If the connection is rejected disconnected() callback is called 862 * instead. 863 * 864 * This function will also setup the ISO data path based on the @p path 865 * parameter of the @ref bt_iso_chan_io_qos for each channel. 866 * 867 * @param param Pointer to a connect parameter array with the ISO and ACL pointers. 868 * @param count Number of connect parameters. 869 * 870 * @retval 0 Successfully started the connecting procedure. 871 * 872 * @retval -EINVAL Invalid parameters were supplied. 873 * 874 * @retval -EBUSY Some ISO channels are already being connected. 875 * It is not possible to have multiple outstanding connection requests. 876 * May also be returned if @kconfig{CONFIG_BT_SMP} is enabled and a 877 * pairing procedure is already in progress. 878 * 879 * @retval -ENOBUFS Not buffers available to send request to controller or if 880 * @kconfig{CONFIG_BT_SMP} is enabled and no more keys could be stored. 881 * 882 * @retval -ENOMEM If @kconfig{CONFIG_BT_SMP} is enabled and no more keys 883 * could be stored. 884 * 885 * @retval -EIO Controller rejected the request or if @kconfig{CONFIG_BT_SMP} 886 * is enabled and pairing has timed out. 887 * 888 * @retval -ENOTCONN If @kconfig{CONFIG_BT_SMP} is enabled the ACL is not 889 * connected. 890 */ 891 int bt_iso_chan_connect(const struct bt_iso_connect_param *param, size_t count); 892 893 /** 894 * @brief Disconnect connected ISO channel 895 * 896 * Disconnect connected ISO channel. 897 * 898 * If the device is a central and the connection is pending it will be 899 * canceled and as a result the channel bt_iso_chan_ops.disconnected() callback is called. 900 * 901 * If the device is a peripheral and the connection is pending it will be rejected, as a peripheral 902 * shall wait for a CIS Established event (which may trigger a bt_iso_chan_ops.disconnected() 903 * callback in case of an error). 904 * 905 * Regarding to input parameter, to get details see reference description 906 * to bt_iso_chan_connect() API. 907 * 908 * @param chan Channel object. 909 * 910 * @return 0 in case of success or negative value in case of error. 911 */ 912 int bt_iso_chan_disconnect(struct bt_iso_chan *chan); 913 914 /** 915 * @brief Send data to ISO channel without timestamp 916 * 917 * Send data from buffer to the channel. If credits are not available, buf will 918 * be queued and sent as and when credits are received from peer. 919 * Regarding to first input parameter, to get details see reference description 920 * to bt_iso_chan_connect() API. 921 * 922 * @note Buffer ownership is transferred to the stack in case of success, in 923 * case of an error the caller retains the ownership of the buffer. 924 * 925 * @param chan Channel object. 926 * @param buf Buffer containing data to be sent. 927 * @param seq_num Packet Sequence number. This value shall be incremented for 928 * each call to this function and at least once per SDU 929 * interval for a specific channel. 930 * 931 * @return Number of octets sent in case of success or negative value in case of error. 932 */ 933 int bt_iso_chan_send(struct bt_iso_chan *chan, struct net_buf *buf, uint16_t seq_num); 934 935 /** 936 * @brief Send data to ISO channel with timestamp 937 * 938 * Send data from buffer to the channel. If credits are not available, buf will 939 * be queued and sent as and when credits are received from peer. 940 * Regarding to first input parameter, to get details see reference description 941 * to bt_iso_chan_connect() API. 942 * 943 * @note Buffer ownership is transferred to the stack in case of success, in 944 * case of an error the caller retains the ownership of the buffer. 945 * 946 * @param chan Channel object. 947 * @param buf Buffer containing data to be sent. 948 * @param seq_num Packet Sequence number. This value shall be incremented for 949 * each call to this function and at least once per SDU 950 * interval for a specific channel. 951 * @param ts Timestamp of the SDU in microseconds (us). 952 * This value can be used to transmit multiple 953 * SDUs in the same SDU interval in a CIG or BIG. 954 * 955 * @return Number of octets sent in case of success or negative value in case of error. 956 */ 957 int bt_iso_chan_send_ts(struct bt_iso_chan *chan, struct net_buf *buf, uint16_t seq_num, 958 uint32_t ts); 959 960 /** @brief ISO Unicast TX Info Structure */ 961 struct bt_iso_unicast_tx_info { 962 /** The transport latency in us */ 963 uint32_t latency; 964 965 /** The flush timeout (N * 1.25 ms) */ 966 uint32_t flush_timeout; 967 968 /** The maximum PDU size in octets */ 969 uint16_t max_pdu; 970 971 /** The transport PHY */ 972 uint8_t phy; 973 974 /** The burst number */ 975 uint8_t bn; 976 977 /** The maximum SDU size in octets 978 * 979 * May be set to @ref bt_iso_unicast_tx_info.max_pdu for peripherals if unknown 980 */ 981 uint16_t max_sdu; 982 983 /** The SDU interval in microseconds 984 * 985 * May be set to @ref BT_ISO_SDU_INTERVAL_UNKNOWN for if unknown. 986 */ 987 uint32_t sdu_interval; 988 }; 989 990 /** @brief ISO Unicast Info Structure */ 991 struct bt_iso_unicast_info { 992 /** The maximum time in us for all PDUs of all CIS in a CIG event */ 993 uint32_t cig_sync_delay; 994 995 /** The maximum time in us for all PDUs of this CIS in a CIG event */ 996 uint32_t cis_sync_delay; 997 998 /** 999 * @brief The subinterval in microseconds 1000 * 1001 * Will be @ref BT_ISO_SUBINTERVAL_NONE if there is no subinterval (NSE = 1). 1002 * Will be @ref BT_ISO_SUBINTERVAL_UNKNOWN if unknown. 1003 */ 1004 uint32_t subinterval; 1005 1006 /** @brief TX information for the central to peripheral data path */ 1007 struct bt_iso_unicast_tx_info central; 1008 1009 /** TX information for the peripheral to central data */ 1010 struct bt_iso_unicast_tx_info peripheral; 1011 }; 1012 1013 /** @brief ISO Broadcaster Info Structure */ 1014 struct bt_iso_broadcaster_info { 1015 /** The maximum time in us for all PDUs of all BIS in a BIG event */ 1016 uint32_t sync_delay; 1017 1018 /** The transport latency in us */ 1019 uint32_t latency; 1020 1021 /** Pre-transmission offset (N * 1.25 ms) */ 1022 uint32_t pto; 1023 1024 /** The maximum PDU size in octets */ 1025 uint16_t max_pdu; 1026 1027 /** The transport PHY */ 1028 uint8_t phy; 1029 1030 /** The burst number */ 1031 uint8_t bn; 1032 1033 /** Number of times a payload is transmitted in a BIS event */ 1034 uint8_t irc; 1035 }; 1036 1037 /** @brief ISO Synchronized Receiver Info Structure */ 1038 struct bt_iso_sync_receiver_info { 1039 /** The transport latency in us */ 1040 uint32_t latency; 1041 1042 /** Pre-transmission offset (N * 1.25 ms) */ 1043 uint32_t pto; 1044 1045 /** The maximum PDU size in octets */ 1046 uint16_t max_pdu; 1047 1048 /** The burst number */ 1049 uint8_t bn; 1050 1051 /** Number of times a payload is transmitted in a BIS event */ 1052 uint8_t irc; 1053 }; 1054 1055 /** ISO channel Info Structure */ 1056 struct bt_iso_info { 1057 /** Channel Type. */ 1058 enum bt_iso_chan_type type; 1059 1060 /** The ISO interval (N * 1.25 ms) */ 1061 uint16_t iso_interval; 1062 1063 /** The maximum number of subevents in each ISO event */ 1064 uint8_t max_subevent; 1065 1066 /** 1067 * @brief True if the channel is able to send data 1068 * 1069 * This is always true when @p type is @ref BT_ISO_CHAN_TYPE_BROADCASTER, 1070 * and never true when @p type is @ref BT_ISO_CHAN_TYPE_SYNC_RECEIVER. 1071 */ 1072 bool can_send; 1073 1074 /** 1075 * @brief True if the channel is able to recv data 1076 * 1077 * This is always true when @p type is @ref BT_ISO_CHAN_TYPE_SYNC_RECEIVER, 1078 * and never true when @p type is @ref BT_ISO_CHAN_TYPE_BROADCASTER. 1079 */ 1080 bool can_recv; 1081 1082 /** Connection Type specific Info.*/ 1083 union { 1084 #if defined(CONFIG_BT_ISO_UNICAST) || defined(__DOXYGEN__) 1085 /** Unicast specific Info. 1086 * Only available when @kconfig{CONFIG_BT_ISO_UNICAST} is enabled. 1087 */ 1088 struct bt_iso_unicast_info unicast; 1089 #endif /* CONFIG_BT_ISO_UNICAST */ 1090 #if defined(CONFIG_BT_ISO_BROADCASTER) || defined(__DOXYGEN__) 1091 /** Broadcaster specific Info. 1092 * Only available when @kconfig{CONFIG_BT_ISO_BROADCASTER} is enabled. 1093 */ 1094 struct bt_iso_broadcaster_info broadcaster; 1095 #endif /* CONFIG_BT_ISO_BROADCASTER */ 1096 #if defined(CONFIG_BT_ISO_SYNC_RECEIVER) || defined(__DOXYGEN__) 1097 /** Sync receiver specific Info. 1098 * Only available when @kconfig{CONFIG_BT_ISO_SYNC_RECEIVER} is enabled. 1099 */ 1100 struct bt_iso_sync_receiver_info sync_receiver; 1101 #endif /* CONFIG_BT_ISO_SYNC_RECEIVER */ 1102 }; 1103 }; 1104 1105 /** 1106 * @brief Get ISO channel info 1107 * 1108 * @param chan Channel object. 1109 * @param info Channel info object. 1110 * 1111 * @return Zero on success or (negative) error code on failure. 1112 */ 1113 int bt_iso_chan_get_info(const struct bt_iso_chan *chan, struct bt_iso_info *info); 1114 1115 /** 1116 * @brief Get ISO transmission timing info 1117 * 1118 * @details Reads timing information for transmitted ISO packet on an ISO channel. 1119 * The HCI_LE_Read_ISO_TX_Sync HCI command is used to retrieve this information 1120 * from the controller. 1121 * 1122 * @note An SDU must have already been successfully transmitted on the ISO channel 1123 * for this function to return successfully. 1124 * 1125 * @param[in] chan Channel object. 1126 * @param[out] info Transmit info object. 1127 * 1128 * @return Zero on success or (negative) error code on failure. 1129 */ 1130 int bt_iso_chan_get_tx_sync(const struct bt_iso_chan *chan, struct bt_iso_tx_info *info); 1131 1132 /** 1133 * @brief Struct to hold the Broadcast Isochronous Group callbacks 1134 * 1135 * These can be registered for usage with bt_iso_big_register_cb(). 1136 */ 1137 struct bt_iso_big_cb { 1138 /** 1139 * @brief The BIG has started and all of the streams are ready for data 1140 * 1141 * @param big The started BIG 1142 */ 1143 void (*started)(struct bt_iso_big *big); 1144 1145 /** 1146 * @brief The BIG has stopped and none of the streams are ready for data 1147 * 1148 * @param big The stopped BIG 1149 * @param reason The reason why the BIG stopped (see the BT_HCI_ERR_* values) 1150 */ 1151 void (*stopped)(struct bt_iso_big *big, uint8_t reason); 1152 1153 /** @internal Internally used field for list handling */ 1154 sys_snode_t _node; 1155 }; 1156 1157 /** 1158 * @brief Registers callbacks for Broadcast Sources 1159 * 1160 * @param cb Pointer to the callback structure. 1161 * 1162 * @retval 0 on success 1163 * @retval -EINVAL if @p cb is NULL 1164 * @retval -EEXIST if @p cb is already registered 1165 */ 1166 int bt_iso_big_register_cb(struct bt_iso_big_cb *cb); 1167 1168 /** 1169 * @brief Creates a BIG as a broadcaster 1170 * 1171 * @param[in] padv Pointer to the periodic advertising object the BIGInfo shall be sent on. 1172 * @param[in] param The parameters used to create and enable the BIG. The QOS parameters are 1173 * determined by the QOS field of the first BIS in the BIS list of this 1174 * parameter. 1175 * @param[out] out_big Broadcast Isochronous Group object on success. 1176 * 1177 * @return 0 in case of success or negative value in case of error. 1178 */ 1179 int bt_iso_big_create(struct bt_le_ext_adv *padv, struct bt_iso_big_create_param *param, 1180 struct bt_iso_big **out_big); 1181 1182 /** 1183 * @brief Terminates a BIG as a broadcaster or receiver 1184 * 1185 * @param big Pointer to the BIG structure. 1186 * 1187 * @return 0 in case of success or negative value in case of error. 1188 */ 1189 int bt_iso_big_terminate(struct bt_iso_big *big); 1190 1191 /** 1192 * @brief Creates a BIG as a receiver 1193 * 1194 * @param[in] sync Pointer to the periodic advertising sync object the BIGInfo was received on. 1195 * @param[in] param The parameters used to create and enable the BIG sync. 1196 * @param[out] out_big Broadcast Isochronous Group object on success. 1197 * 1198 * @return 0 in case of success or negative value in case of error. 1199 */ 1200 int bt_iso_big_sync(struct bt_le_per_adv_sync *sync, struct bt_iso_big_sync_param *param, 1201 struct bt_iso_big **out_big); 1202 1203 #ifdef __cplusplus 1204 } 1205 #endif 1206 1207 /** 1208 * @} 1209 */ 1210 1211 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_ISO_H_ */ 1212
