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 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 #include <sys/atomic.h> 26 #include <bluetooth/buf.h> 27 #include <bluetooth/conn.h> 28 #include <bluetooth/hci.h> 29 30 /** @def BT_ISO_CHAN_SEND_RESERVE 31 * @brief Headroom needed for outgoing buffers 32 */ 33 #define BT_ISO_CHAN_SEND_RESERVE (CONFIG_BT_HCI_RESERVE + \ 34 BT_HCI_ISO_HDR_SIZE + \ 35 BT_HCI_ISO_DATA_HDR_SIZE) 36 37 /** Value to set the ISO data path over HCi. */ 38 #define BT_ISO_DATA_PATH_HCI 0x00 39 40 /** Minimum interval value in microseconds */ 41 #define BT_ISO_INTERVAL_MIN 0x0000FF 42 /** Maximum interval value in microseconds */ 43 #define BT_ISO_INTERVAL_MAX 0x0FFFFF 44 /** Minimum latency value in milliseconds */ 45 #define BT_ISO_LATENCY_MIN 0x0005 46 /** Maximum latency value in milliseconds */ 47 #define BT_ISO_LATENCY_MAX 0x0FA0 48 /** Packets will be sent sequentially between the channels in the group */ 49 #define BT_ISO_PACKING_SEQUENTIAL 0x00 50 /** Packets will be sent interleaved between the channels in the group */ 51 #define BT_ISO_PACKING_INTERLEAVED 0x01 52 /** Packets may be framed or unframed */ 53 #define BT_ISO_FRAMING_UNFRAMED 0x00 54 /** Packets are always framed */ 55 #define BT_ISO_FRAMING_FRAMED 0x01 56 /** Maximum number of isochronous channels in a single group */ 57 #define BT_ISO_MAX_GROUP_ISO_COUNT 0x1F 58 /** Maximum SDU size */ 59 #define BT_ISO_MAX_SDU 0x0FFF 60 /** Minimum BIG sync timeout value (N * 10 ms) */ 61 #define BT_ISO_SYNC_TIMEOUT_MIN 0x000A 62 /** Maximum BIG sync timeout value (N * 10 ms) */ 63 #define BT_ISO_SYNC_TIMEOUT_MAX 0x4000 64 /** Controller controlled maximum subevent count value */ 65 #define BT_ISO_SYNC_MSE_ANY 0x00 66 /** Minimum BIG sync maximum subevent count value */ 67 #define BT_ISO_SYNC_MSE_MIN 0x01 68 /** Maximum BIG sync maximum subevent count value */ 69 #define BT_ISO_SYNC_MSE_MAX 0x1F 70 /** Maximum connected ISO retransmission value */ 71 #define BT_ISO_CONNECTED_RTN_MAX 0xFF 72 /** Maximum broadcast ISO retransmission value */ 73 #define BT_ISO_BROADCAST_RTN_MAX 0x1E 74 /** Broadcast code size */ 75 #define BT_ISO_BROADCAST_CODE_SIZE 16 76 77 /** @brief Life-span states of ISO channel. Used only by internal APIs 78 * dealing with setting channel to proper state depending on operational 79 * context. 80 */ 81 enum { 82 /** Channel disconnected */ 83 BT_ISO_DISCONNECTED, 84 /** Channel in connecting state */ 85 BT_ISO_CONNECT, 86 /** Channel ready for upper layer traffic on it */ 87 BT_ISO_CONNECTED, 88 /** Channel in disconnecting state */ 89 BT_ISO_DISCONNECT, 90 }; 91 92 /** @brief ISO Channel structure. */ 93 struct bt_iso_chan { 94 /** Channel connection reference */ 95 struct bt_conn *iso; 96 /** Channel operations reference */ 97 struct bt_iso_chan_ops *ops; 98 /** Channel QoS reference */ 99 struct bt_iso_chan_qos *qos; 100 uint8_t state; 101 bt_security_t required_sec_level; 102 }; 103 104 /** @brief ISO Channel IO QoS structure. */ 105 struct bt_iso_chan_io_qos { 106 /** Channel SDU. Maximum value is BT_ISO_MAX_SDU */ 107 uint16_t sdu; 108 /** Channel PHY - See BT_GAP_LE_PHY for values. 109 * Setting BT_GAP_LE_PHY_NONE is invalid. 110 */ 111 uint8_t phy; 112 /** Channel Retransmission Number. */ 113 uint8_t rtn; 114 /** @brief Channel data path reference 115 * 116 * Setting to NULL default to HCI data path (same as setting path.pid 117 * to BT_ISO_DATA_PATH_HCI). 118 */ 119 struct bt_iso_chan_path *path; 120 }; 121 122 /** @brief ISO Channel QoS structure. */ 123 struct bt_iso_chan_qos { 124 /** @brief Channel Receiving QoS. 125 * 126 * Setting NULL disables data path BT_HCI_DATAPATH_DIR_CTLR_TO_HOST. 127 * 128 * Can only be set for a connected isochronous channel, or a broadcast 129 * isochronous receiver. 130 */ 131 struct bt_iso_chan_io_qos *rx; 132 /** @brief Channel Transmission QoS 133 * 134 * Setting NULL disables data path BT_HCI_DATAPATH_DIR_HOST_TO_CTRL. 135 * 136 * Can only be set for a connected isochronous channel, or a broadcast 137 * isochronous transmitter. 138 */ 139 struct bt_iso_chan_io_qos *tx; 140 }; 141 142 /** @brief ISO Channel Data Path structure. */ 143 struct bt_iso_chan_path { 144 /** Default path ID */ 145 uint8_t pid; 146 /** Coding Format */ 147 uint8_t format; 148 /** Company ID */ 149 uint16_t cid; 150 /** Vendor-defined Codec ID */ 151 uint16_t vid; 152 /** Controller Delay */ 153 uint32_t delay; 154 /** Codec Configuration length*/ 155 uint8_t cc_len; 156 /** Codec Configuration */ 157 uint8_t cc[0]; 158 }; 159 160 /** ISO packet status flags */ 161 enum { 162 /** The ISO packet is valid. */ 163 BT_ISO_FLAGS_VALID, 164 /** @brief The ISO packet may possibly contain errors. 165 * 166 * May be caused by a failed CRC check or if missing a part of the SDU. 167 */ 168 BT_ISO_FLAGS_ERROR, 169 /** The ISO packet was lost. */ 170 BT_ISO_FLAGS_LOST 171 }; 172 173 /** @brief ISO Meta Data structure for received ISO packets. */ 174 struct bt_iso_recv_info { 175 /** ISO timestamp - valid only if the Bluetooth controller includes it 176 * If time stamp is not pressent this value will be 0 on all iso packets 177 */ 178 uint32_t ts; 179 180 /** ISO packet sequence number of the first fragment in the SDU */ 181 uint16_t sn; 182 183 /** ISO packet flags (BT_ISO_FLAGS_*) */ 184 uint8_t flags; 185 }; 186 187 188 /** Opaque type representing an Connected Isochronous Group (CIG). */ 189 struct bt_iso_cig; 190 191 struct bt_iso_cig_create_param { 192 /** @brief Array of pointers to CIS channels 193 * 194 * This array shall remain valid for the duration of the CIG. 195 */ 196 struct bt_iso_chan **cis_channels; 197 198 /** @brief Number channels in @p cis_channels 199 * 200 * Maximum number of channels in a single group is 201 * BT_ISO_MAX_GROUP_ISO_COUNT 202 */ 203 uint8_t num_cis; 204 205 /** @brief Channel interval in us. 206 * 207 * Value range BT_ISO_INTERVAL_MIN - BT_ISO_INTERVAL_MAX. 208 */ 209 uint32_t interval; 210 211 /** @brief Channel Latency in ms. 212 * 213 * Value range BT_ISO_LATENCY_MIN - BT_ISO_LATENCY_MAX. 214 */ 215 uint16_t latency; 216 217 /** @brief Channel peripherals sleep clock accuracy Only for CIS 218 * 219 * Shall be worst case sleep clock accuracy of all the peripherals. 220 * For possible values see the BT_GAP_SCA_* values. 221 * If unknown for the peripherals, this should be set to 222 * BT_GAP_SCA_UNKNOWN. 223 */ 224 uint8_t sca; 225 226 /** @brief Channel packing mode. 227 * 228 * BT_ISO_PACKING_SEQUENTIAL or BT_ISO_PACKING_INTERLEAVED 229 */ 230 uint8_t packing; 231 232 /** @brief Channel framing mode. 233 * 234 * BT_ISO_FRAMING_UNFRAMED for unframed and 235 * BT_ISO_FRAMING_FRAMED for framed. 236 */ 237 uint8_t framing; 238 }; 239 240 struct bt_iso_connect_param { 241 /* The ISO channel to connect */ 242 struct bt_iso_chan *iso_chan; 243 244 /* The ACL connection */ 245 struct bt_conn *acl; 246 }; 247 248 /** Opaque type representing an Broadcast Isochronous Group (BIG). */ 249 struct bt_iso_big; 250 251 struct bt_iso_big_create_param { 252 /** Array of pointers to BIS channels 253 * 254 * This array shall remain valid for the duration of the BIG. 255 */ 256 struct bt_iso_chan **bis_channels; 257 258 /** @brief Number channels in @p bis_channels 259 * 260 * Maximum number of channels in a single group is 261 * BT_ISO_MAX_GROUP_ISO_COUNT 262 */ 263 uint8_t num_bis; 264 265 /** @brief Channel interval in us. 266 * 267 * Value range BT_ISO_INTERVAL_MIN - BT_ISO_INTERVAL_MAX. 268 */ 269 uint32_t interval; 270 271 /** @brief Channel Latency in ms. 272 * 273 * Value range BT_ISO_LATENCY_MIN - BT_ISO_LATENCY_MAX. 274 */ 275 uint16_t latency; 276 277 /** @brief Channel packing mode. 278 * 279 * BT_ISO_PACKING_SEQUENTIAL or BT_ISO_PACKING_INTERLEAVED 280 */ 281 uint8_t packing; 282 283 /** @brief Channel framing mode. 284 * 285 * BT_ISO_FRAMING_UNFRAMED for unframed and 286 * BT_ISO_FRAMING_FRAMED for framed. 287 */ 288 uint8_t framing; 289 290 /** Whether or not to encrypt the streams. */ 291 bool encryption; 292 293 /** @brief Broadcast code 294 * 295 * The code used to derive the session key that is used to encrypt and 296 * decrypt BIS payloads. 297 */ 298 uint8_t bcode[BT_ISO_BROADCAST_CODE_SIZE]; 299 }; 300 301 struct bt_iso_big_sync_param { 302 /** Array of pointers to BIS channels */ 303 struct bt_iso_chan **bis_channels; 304 305 /** @brief Number channels in @p bis_channels 306 * 307 * Maximum number of channels in a single group is 308 * BT_ISO_MAX_GROUP_ISO_COUNT 309 */ 310 uint8_t num_bis; 311 312 /** Bitfield of the BISes to sync to 313 * 314 * The BIS indexes start from 0x01, so the lowest allowed bit is 315 * BIT(1) that represents index 0x01. To synchronize to e.g. BIS 316 * indexes 0x01 and 0x02, the bitfield value should be BIT(1) | BIT(2). 317 */ 318 uint32_t bis_bitfield; 319 320 /** @brief Maximum subevents 321 * 322 * The MSE (Maximum Subevents) parameter is the maximum number of 323 * subevents that a Controller should use to receive data payloads 324 * in each interval for a BIS. 325 * 326 * Value range is BT_ISO_SYNC_MSE_MIN to BT_ISO_SYNC_MSE_MAX, or 327 * BT_ISO_SYNC_MSE_ANY to let the controller choose. 328 */ 329 uint32_t mse; 330 331 /** @brief Synchronization timeout for the BIG (N * 10 MS) 332 * 333 * Value range is BT_ISO_SYNC_TIMEOUT_MIN to BT_ISO_SYNC_TIMEOUT_MAX. 334 */ 335 uint16_t sync_timeout; 336 337 /** Whether or not the streams of the BIG are encrypted */ 338 bool encryption; 339 340 /** @brief Broadcast code 341 * 342 * The code used to derive the session key that is used to encrypt and 343 * decrypt BIS payloads. 344 */ 345 uint8_t bcode[BT_ISO_BROADCAST_CODE_SIZE]; 346 }; 347 348 struct bt_iso_biginfo { 349 /** Address of the advertiser */ 350 const bt_addr_le_t *addr; 351 352 /** Advertiser SID */ 353 uint8_t sid; 354 355 /** Number of BISes in the BIG */ 356 uint8_t num_bis; 357 358 /** Maximum number of subevents in each isochronous event */ 359 uint8_t sub_evt_count; 360 361 /** Interval between two BIG anchor point (N * 1.25 ms) */ 362 uint16_t iso_interval; 363 364 /** The number of new payloads in each BIS event */ 365 uint8_t burst_number; 366 367 /** Offset used for pre-transmissions */ 368 uint8_t offset; 369 370 /** The number of times a payload is transmitted in a BIS event */ 371 uint8_t rep_count; 372 373 /** Maximum size, in octets, of the payload */ 374 uint16_t max_pdu; 375 376 /** The interval, in microseconds, of periodic SDUs. */ 377 uint32_t sdu_interval; 378 379 /** Maximum size of an SDU, in octets. */ 380 uint16_t max_sdu; 381 382 /** Channel PHY */ 383 uint8_t phy; 384 385 /** Channel framing mode */ 386 uint8_t framing; 387 388 /** Whether or not the BIG is encrypted */ 389 bool encryption; 390 }; 391 392 /** @brief ISO Channel operations structure. */ 393 struct bt_iso_chan_ops { 394 /** @brief Channel connected callback 395 * 396 * If this callback is provided it will be called whenever the 397 * connection completes. 398 * 399 * @param chan The channel that has been connected 400 */ 401 void (*connected)(struct bt_iso_chan *chan); 402 403 /** @brief Channel disconnected callback 404 * 405 * If this callback is provided it will be called whenever the 406 * channel is disconnected, including when a connection gets 407 * rejected. 408 * 409 * @param chan The channel that has been Disconnected 410 * @param reason HCI reason for the disconnection. 411 */ 412 void (*disconnected)(struct bt_iso_chan *chan, uint8_t reason); 413 414 /** @brief Channel alloc_buf callback 415 * 416 * If this callback is provided the channel will use it to allocate 417 * buffers to store incoming data. 418 * 419 * @param chan The channel requesting a buffer. 420 * 421 * @return Allocated buffer. 422 */ 423 struct net_buf *(*alloc_buf)(struct bt_iso_chan *chan); 424 425 /** @brief Channel recv callback 426 * 427 * @param chan The channel receiving data. 428 * @param buf Buffer containing incoming data. 429 * @param info Pointer to the metadata for the buffer. The lifetime of the 430 * pointer is linked to the lifetime of the net_buf. 431 * Metadata such as sequence number and timestamp can be 432 * provided by the bluetooth controller. 433 */ 434 void (*recv)(struct bt_iso_chan *chan, const struct bt_iso_recv_info *info, 435 struct net_buf *buf); 436 437 /** @brief Channel sent callback 438 * 439 * If this callback is provided it will be called whenever a SDU has 440 * been completely sent. 441 * 442 * @param chan The channel which has sent data. 443 */ 444 void (*sent)(struct bt_iso_chan *chan); 445 }; 446 447 /** @brief ISO Server structure. */ 448 struct bt_iso_server { 449 /** Required minimim security level */ 450 bt_security_t sec_level; 451 452 /** @brief Server accept callback 453 * 454 * This callback is called whenever a new incoming connection requires 455 * authorization. 456 * 457 * @param acl The ACL connection that is requesting authorization 458 * @param chan Pointer to receive the allocated channel 459 * 460 * @return 0 in case of success or negative value in case of error. 461 */ 462 int (*accept)(struct bt_conn *acl, struct bt_iso_chan **chan); 463 }; 464 465 /** @brief Register ISO server. 466 * 467 * Register ISO server, each new connection is authorized using the accept() 468 * callback which in case of success shall allocate the channel structure 469 * to be used by the new connection. 470 * 471 * @param server Server structure. 472 * 473 * @return 0 in case of success or negative value in case of error. 474 */ 475 int bt_iso_server_register(struct bt_iso_server *server); 476 477 /** @brief Creates a CIG as a central 478 * 479 * This can called at any time, even before connecting to a remote device. 480 * This must be called before any connected isochronous stream (CIS) channel 481 * can be connected. 482 * 483 * Once a CIG is created, the channels supplied in the @p param can be 484 * connected using bt_iso_chan_connect. 485 * 486 * @param[in] param The parameters used to create and enable the CIG. 487 * @param[out] out_cig Connected Isochronous Group object on success. 488 * 489 * @return 0 in case of success or negative value in case of error. 490 */ 491 int bt_iso_cig_create(const struct bt_iso_cig_create_param *param, 492 struct bt_iso_cig **out_cig); 493 494 /** @brief Terminates a CIG as a central 495 * 496 * All the CIS in the CIG shall be disconnected first. 497 * 498 * @param cig Pointer to the CIG structure. 499 * 500 * @return 0 in case of success or negative value in case of error. 501 */ 502 int bt_iso_cig_terminate(struct bt_iso_cig *cig); 503 504 /** @brief Connect ISO channels on ACL connections 505 * 506 * Connect ISO channels. The ISO channels must have been initialized in a CIG 507 * first by calling bt_iso_cig_create. 508 * 509 * Once the connection is completed the channels' connected() callback will be 510 * called. If the connection is rejected disconnected() callback is called 511 * instead. 512 * 513 * This function will also setup the ISO data path based on the @p path 514 * parameter of the bt_iso_chan_io_qos for each channel. 515 * 516 * @param param Pointer to a connect parameter array with the ISO and ACL pointers. 517 * @param count Number of connect parameters. 518 * 519 * @return 0 in case of success or negative value in case of error. 520 */ 521 int bt_iso_chan_connect(const struct bt_iso_connect_param *param, size_t count); 522 523 /** @brief Disconnect ISO channel 524 * 525 * Disconnect ISO channel, if the connection is pending it will be 526 * canceled and as a result the channel disconnected() callback is called. 527 * Regarding to input parameter, to get details see reference description 528 * to bt_iso_chan_connect() API above. 529 * 530 * @param chan Channel object. 531 * 532 * @return 0 in case of success or negative value in case of error. 533 */ 534 int bt_iso_chan_disconnect(struct bt_iso_chan *chan); 535 536 /** @brief Send data to ISO channel 537 * 538 * Send data from buffer to the channel. If credits are not available, buf will 539 * be queued and sent as and when credits are received from peer. 540 * Regarding to first input parameter, to get details see reference description 541 * to bt_iso_chan_connect() API above. 542 * 543 * @note Buffer ownership is transferred to the stack in case of success, in 544 * case of an error the caller retains the ownership of the buffer. 545 * 546 * @param chan Channel object. 547 * @param buf Buffer containing data to be sent. 548 * 549 * @return Bytes sent in case of success or negative value in case of error. 550 */ 551 int bt_iso_chan_send(struct bt_iso_chan *chan, struct net_buf *buf); 552 553 /** @brief Creates a BIG as a broadcaster 554 * 555 * @param[in] padv Pointer to the periodic advertising object the BIGInfo shall be sent on. 556 * @param[in] param The parameters used to create and enable the BIG. The QOS parameters are 557 * determined by the QOS field of the first BIS in the BIS list of this 558 * parameter. 559 * @param[out] out_big Broadcast Isochronous Group object on success. 560 * 561 * @return 0 in case of success or negative value in case of error. 562 */ 563 int bt_iso_big_create(struct bt_le_ext_adv *padv, struct bt_iso_big_create_param *param, 564 struct bt_iso_big **out_big); 565 566 /** @brief Terminates a BIG as a broadcaster or receiver 567 * 568 * @param big Pointer to the BIG structure. 569 * 570 * @return 0 in case of success or negative value in case of error. 571 */ 572 int bt_iso_big_terminate(struct bt_iso_big *big); 573 574 /** @brief Creates a BIG as a receiver 575 * 576 * @param[in] sync Pointer to the periodic advertising sync object the BIGInfo was received on. 577 * @param[in] param The parameters used to create and enable the BIG sync. 578 * @param[out] out_big Broadcast Isochronous Group object on success. 579 * 580 * @return 0 in case of success or negative value in case of error. 581 */ 582 int bt_iso_big_sync(struct bt_le_per_adv_sync *sync, struct bt_iso_big_sync_param *param, 583 struct bt_iso_big **out_big); 584 585 #ifdef __cplusplus 586 } 587 #endif 588 589 /** 590 * @} 591 */ 592 593 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_ISO_H_ */ 594
