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