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