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