iso.h

Go to the documentation of this file.

 
/*
 * Copyright (c) 2020 Intel Corporation
 * Copyright (c) 2021-2025 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: Apache-2.0
 */
#ifndef ZEPHYR_INCLUDE_BLUETOOTH_ISO_H_
#define ZEPHYR_INCLUDE_BLUETOOTH_ISO_H_

 
#include <stdint.h>
#include <stddef.h>
 
#include <zephyr/bluetooth/addr.h>
#include <zephyr/bluetooth/bluetooth.h>
#include <zephyr/bluetooth/buf.h>
#include <zephyr/bluetooth/conn.h>
#include <zephyr/bluetooth/hci.h>
#include <zephyr/net_buf.h>
#include <zephyr/sys/atomic.h>
#include <zephyr/sys/slist.h>
#include <zephyr/sys/util_macro.h>
 
#ifdef __cplusplus
extern "C" {
#endif

#define BT_ISO_CHAN_SEND_RESERVE BT_BUF_ISO_SIZE(0)

#define BT_ISO_SDU_BUF_SIZE(mtu) BT_BUF_ISO_SIZE(mtu)

#define BT_ISO_BIS_INDEX_BIT(x) (BIT((x) - 1))

#define BT_ISO_DATA_PATH_HCI        0x00

#define BT_ISO_SDU_INTERVAL_UNKNOWN 0x000000U
#define BT_ISO_DATA_PATH_VS_ID_MIN  0x01
#define BT_ISO_DATA_PATH_VS_ID_MAX  0xFE
#define BT_ISO_CONTROLLER_DELAY_MIN 0x000000
#define BT_ISO_CONTROLLER_DELAY_MAX 0x3D0900
#define BT_ISO_SDU_INTERVAL_MIN     0x0000FFU
#define BT_ISO_SDU_INTERVAL_MAX     0x0FFFFFU
#define BT_ISO_ISO_INTERVAL_MIN     0x0004U
#define BT_ISO_ISO_INTERVAL_MAX     0x0C80U
#define BT_ISO_LATENCY_MIN          0x0005
#define BT_ISO_LATENCY_MAX          0x0FA0
#define BT_ISO_PACKING_SEQUENTIAL   0x00
#define BT_ISO_PACKING_INTERLEAVED  0x01
#define BT_ISO_FRAMING_UNFRAMED     0x00
#define BT_ISO_FRAMING_FRAMED       0x01
#define BT_ISO_MAX_GROUP_ISO_COUNT  0x1F
#define BT_ISO_MIN_SDU              0x0001
#define BT_ISO_MAX_SDU              0x0FFF
#define BT_ISO_CONNECTED_PDU_MIN    0x0000U
#define BT_ISO_BROADCAST_PDU_MIN    0x0001U
#define BT_ISO_PDU_MAX              0x00FBU
#define BT_ISO_BN_MIN               0x01U
#define BT_ISO_BN_MAX               0x0FU
#define BT_ISO_FT_MIN               0x01U
#define BT_ISO_FT_MAX               0xFFU
#define BT_ISO_NSE_MIN              0x01U
#define BT_ISO_NSE_MAX              0x1FU
#define BT_ISO_SYNC_TIMEOUT_MIN     0x000A
#define BT_ISO_SYNC_TIMEOUT_MAX     0x4000
#define BT_ISO_SYNC_MSE_ANY         0x00
#define BT_ISO_SYNC_MSE_MIN         0x01
#define BT_ISO_SYNC_MSE_MAX         0x1F
#define BT_ISO_CONNECTED_RTN_MIN    0x00
#define BT_ISO_CONNECTED_RTN_MAX    0xFF
#define BT_ISO_BROADCAST_RTN_MIN    0x00
#define BT_ISO_BROADCAST_RTN_MAX    0x1E
#define BT_ISO_BROADCAST_CODE_SIZE  0x10
#define BT_ISO_BIS_INDEX_MIN        0x01
#define BT_ISO_BIS_INDEX_MAX        0x1F
#define BT_ISO_IRC_MIN              0x01U
#define BT_ISO_IRC_MAX              0x0FU
#define BT_ISO_PTO_MIN              0x00U
#define BT_ISO_PTO_MAX              0x0FU
#define BT_ISO_SUBINTERVAL_NONE     0x00000000U
#define BT_ISO_SUBINTERVAL_UNKNOWN  0xFFFFFFFFU
#define BT_ISO_SUBINTERVAL_MIN      0x00000190U
#define BT_ISO_SUBINTERVAL_MAX      0x00009C3FU

#define BT_ISO_VALID_BIS_BITFIELD(_bis_bitfield)                                                   \
        ((_bis_bitfield) != 0U && (_bis_bitfield) <= BIT_MASK(BT_ISO_BIS_INDEX_MAX))

enum bt_iso_state {
        BT_ISO_STATE_DISCONNECTED,
        BT_ISO_STATE_ENCRYPT_PENDING,
        BT_ISO_STATE_CONNECTING,
        BT_ISO_STATE_CONNECTED,
        BT_ISO_STATE_DISCONNECTING,
};
 

enum bt_iso_chan_type {
        BT_ISO_CHAN_TYPE_NONE,          
        BT_ISO_CHAN_TYPE_CENTRAL,       
        BT_ISO_CHAN_TYPE_PERIPHERAL,    
        BT_ISO_CHAN_TYPE_BROADCASTER,   
        BT_ISO_CHAN_TYPE_SYNC_RECEIVER  
};

struct bt_iso_chan {
        struct bt_conn                  *iso;
        struct bt_iso_chan_ops          *ops;
        struct bt_iso_chan_qos          *qos;
        enum bt_iso_state               state;
#if (defined(CONFIG_BT_SMP) && defined(CONFIG_BT_ISO_UNICAST)) || defined(__DOXYGEN__)
        bt_security_t                   required_sec_level;
#endif /* CONFIG_BT_SMP && CONFIG_BT_ISO_UNICAST */
        sys_snode_t node;
};

struct bt_iso_chan_io_qos {
        uint16_t                        sdu;
        uint8_t                         phy;
        uint8_t                         rtn;
 
#if defined(CONFIG_BT_ISO_TEST_PARAMS) || defined(__DOXYGEN__)
        uint16_t max_pdu;

        uint8_t burst_number;
#endif /* CONFIG_BT_ISO_TEST_PARAMS */
};

struct bt_iso_chan_qos {
        struct bt_iso_chan_io_qos       *rx;
        struct bt_iso_chan_io_qos       *tx;
 
#if defined(CONFIG_BT_ISO_TEST_PARAMS) || defined(__DOXYGEN__)
        uint8_t num_subevents;
#endif /* CONFIG_BT_ISO_TEST_PARAMS */
};

struct bt_iso_chan_path {
        uint8_t pid;
        uint8_t format;
        uint16_t cid;
        uint16_t vid;
        uint32_t delay;
        uint8_t cc_len;
        uint8_t *cc;
};

enum {
        BT_ISO_FLAGS_VALID = BIT(0),

        BT_ISO_FLAGS_ERROR = BIT(1),

        BT_ISO_FLAGS_LOST = BIT(2),

        BT_ISO_FLAGS_TS = BIT(3)
};

struct bt_iso_recv_info {
        uint32_t ts;

        uint16_t seq_num;

        uint8_t flags;
};

struct bt_iso_tx_info {
        uint32_t ts;

        uint32_t offset;

        uint16_t seq_num;
};
 

struct bt_iso_cig;

struct bt_iso_cig_param {
        struct bt_iso_chan **cis_channels;

        uint8_t num_cis;

        uint32_t c_to_p_interval;

        uint32_t p_to_c_interval;

        uint16_t c_to_p_latency;

        uint16_t p_to_c_latency;

        uint8_t sca;

        uint8_t packing;

        uint8_t framing;
 
#if defined(CONFIG_BT_ISO_TEST_PARAMS) || defined(__DOXYGEN__)
        uint8_t c_to_p_ft;

        uint8_t p_to_c_ft;

        uint16_t iso_interval;
#endif /* CONFIG_BT_ISO_TEST_PARAMS */
};

struct bt_iso_connect_param {
        struct bt_iso_chan *iso_chan;

        struct bt_conn *acl;
};

struct bt_iso_big;

struct bt_iso_big_create_param {
        struct bt_iso_chan **bis_channels;

        uint8_t num_bis;

        uint32_t interval;

        uint16_t latency;

        uint8_t packing;

        uint8_t framing;

        bool encryption;

        uint8_t bcode[BT_ISO_BROADCAST_CODE_SIZE];
 
#if defined(CONFIG_BT_ISO_TEST_PARAMS) || defined(__DOXYGEN__)
        uint8_t irc;

        uint8_t pto;

        uint16_t iso_interval;
#endif /* CONFIG_BT_ISO_TEST_PARAMS */
};

struct bt_iso_big_sync_param {
        struct bt_iso_chan **bis_channels;

        uint8_t num_bis;

        uint32_t bis_bitfield;

        uint32_t mse;

        uint16_t sync_timeout;

        bool  encryption;

        uint8_t bcode[BT_ISO_BROADCAST_CODE_SIZE];
};

struct bt_iso_biginfo {
        const bt_addr_le_t *addr;

        uint8_t sid;

        uint8_t  num_bis;

        uint8_t  sub_evt_count;

        uint16_t iso_interval;

        uint8_t  burst_number;

        uint8_t  offset;

        uint8_t  rep_count;

        uint16_t max_pdu;

        uint32_t sdu_interval;

        uint16_t max_sdu;

        uint8_t  phy;

        uint8_t  framing;

        bool  encryption;
};

struct bt_iso_chan_ops {
        void (*connected)(struct bt_iso_chan *chan);

        void (*disconnected)(struct bt_iso_chan *chan, uint8_t reason);

        struct net_buf *(*alloc_buf)(struct bt_iso_chan *chan);

        void (*recv)(struct bt_iso_chan *chan, const struct bt_iso_recv_info *info,
                     struct net_buf *buf);

        void (*sent)(struct bt_iso_chan *chan);
};

struct bt_iso_accept_info {
        struct bt_conn *acl;

        uint8_t cig_id;

        uint8_t cis_id;
};

struct bt_iso_server {
#if defined(CONFIG_BT_SMP) || defined(__DOXYGEN__)
        bt_security_t           sec_level;
#endif /* CONFIG_BT_SMP */

        int (*accept)(const struct bt_iso_accept_info *info, struct bt_iso_chan **chan);
};

int bt_iso_server_register(struct bt_iso_server *server);

int bt_iso_server_unregister(struct bt_iso_server *server);

int bt_iso_cig_create(const struct bt_iso_cig_param *param, struct bt_iso_cig **out_cig);

int bt_iso_cig_reconfigure(struct bt_iso_cig *cig, const struct bt_iso_cig_param *param);

int bt_iso_cig_terminate(struct bt_iso_cig *cig);

int bt_iso_chan_connect(const struct bt_iso_connect_param *param, size_t count);

int bt_iso_chan_disconnect(struct bt_iso_chan *chan);

int bt_iso_chan_send(struct bt_iso_chan *chan, struct net_buf *buf, uint16_t seq_num);

int bt_iso_chan_send_ts(struct bt_iso_chan *chan, struct net_buf *buf, uint16_t seq_num,
                        uint32_t ts);

int bt_iso_setup_data_path(const struct bt_iso_chan *chan, uint8_t dir,
                           const struct bt_iso_chan_path *path);

int bt_iso_remove_data_path(const struct bt_iso_chan *chan, uint8_t dir);

struct bt_iso_unicast_tx_info {
        uint32_t latency;

        uint32_t flush_timeout;

        uint16_t max_pdu;

        uint8_t  phy;

        uint8_t  bn;

        uint16_t max_sdu;

        uint32_t sdu_interval;
};

struct bt_iso_unicast_info {
        uint8_t cig_id;

        uint8_t cis_id;

        uint32_t cig_sync_delay;

        uint32_t cis_sync_delay;

        uint32_t subinterval;

        struct bt_iso_unicast_tx_info central;

        struct bt_iso_unicast_tx_info peripheral;
};

struct bt_iso_broadcaster_info {
        uint8_t big_handle;

        uint8_t bis_number;

        uint32_t sync_delay;

        uint32_t latency;

        uint32_t  pto;

        uint16_t max_pdu;

        uint8_t  phy;

        uint8_t  bn;

        uint8_t  irc;
};

struct bt_iso_sync_receiver_info {
        uint8_t big_handle;

        uint8_t bis_number;

        uint32_t latency;

        uint32_t  pto;

        uint16_t max_pdu;

        uint8_t  bn;

        uint8_t  irc;
};

struct bt_iso_info {
        enum bt_iso_chan_type type;

        uint16_t iso_interval;

        uint8_t  max_subevent;

        bool can_send;

        bool can_recv;

        union {
#if defined(CONFIG_BT_ISO_UNICAST) || defined(__DOXYGEN__)
                struct bt_iso_unicast_info unicast;
#endif /* CONFIG_BT_ISO_UNICAST */
#if defined(CONFIG_BT_ISO_BROADCASTER) || defined(__DOXYGEN__)
                struct bt_iso_broadcaster_info broadcaster;
#endif /* CONFIG_BT_ISO_BROADCASTER */
#if defined(CONFIG_BT_ISO_SYNC_RECEIVER) || defined(__DOXYGEN__)
                struct bt_iso_sync_receiver_info sync_receiver;
#endif /* CONFIG_BT_ISO_SYNC_RECEIVER */
        };
};

int bt_iso_chan_get_info(const struct bt_iso_chan *chan, struct bt_iso_info *info);

int bt_iso_chan_get_tx_sync(const struct bt_iso_chan *chan, struct bt_iso_tx_info *info);

struct bt_iso_big_cb {
        void (*started)(struct bt_iso_big *big);

        void (*stopped)(struct bt_iso_big *big, uint8_t reason);

        sys_snode_t _node;
};

int bt_iso_big_register_cb(struct bt_iso_big_cb *cb);

int bt_iso_big_create(struct bt_le_ext_adv *padv, struct bt_iso_big_create_param *param,
                      struct bt_iso_big **out_big);

int bt_iso_big_terminate(struct bt_iso_big *big);

int bt_iso_big_sync(struct bt_le_per_adv_sync *sync, struct bt_iso_big_sync_param *param,
                    struct bt_iso_big **out_big);
 
#ifdef __cplusplus
}
#endif

 
#endif /* ZEPHYR_INCLUDE_BLUETOOTH_ISO_H_ */