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