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