ras.h

Go to the documentation of this file.

/*
 * Copyright (c) 2024 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
 */
 
#ifndef BT_RAS_H_
#define BT_RAS_H_
 
#include <stdint.h>
#include <zephyr/kernel.h>
#include <zephyr/bluetooth/conn.h>
#include <zephyr/bluetooth/cs.h>
#include <zephyr/bluetooth/uuid.h>
#include <zephyr/bluetooth/hci_types.h>
#include <bluetooth/gatt_dm.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define BT_UUID_RANGING_SERVICE_VAL (0x185B)
 
#define BT_UUID_RAS_FEATURES_VAL (0x2C14)
 
#define BT_UUID_RAS_REALTIME_RD_VAL (0x2C15)
 
#define BT_UUID_RAS_ONDEMAND_RD_VAL (0x2C16)
 
#define BT_UUID_RAS_CP_VAL (0x2C17)
 
#define BT_UUID_RAS_RD_READY_VAL (0x2C18)
 
#define BT_UUID_RAS_RD_OVERWRITTEN_VAL (0x2C19)
 
#define BT_UUID_RANGING_SERVICE    BT_UUID_DECLARE_16(BT_UUID_RANGING_SERVICE_VAL)
#define BT_UUID_RAS_FEATURES       BT_UUID_DECLARE_16(BT_UUID_RAS_FEATURES_VAL)
#define BT_UUID_RAS_REALTIME_RD    BT_UUID_DECLARE_16(BT_UUID_RAS_REALTIME_RD_VAL)
#define BT_UUID_RAS_ONDEMAND_RD    BT_UUID_DECLARE_16(BT_UUID_RAS_ONDEMAND_RD_VAL)
#define BT_UUID_RAS_CP             BT_UUID_DECLARE_16(BT_UUID_RAS_CP_VAL)
#define BT_UUID_RAS_RD_READY       BT_UUID_DECLARE_16(BT_UUID_RAS_RD_READY_VAL)
#define BT_UUID_RAS_RD_OVERWRITTEN BT_UUID_DECLARE_16(BT_UUID_RAS_RD_OVERWRITTEN_VAL)
 
#define BT_RAS_RANGING_HEADER_LEN  4
#define BT_RAS_SUBEVENT_HEADER_LEN 8
#define BT_RAS_STEP_MODE_LEN       1
 
#define BT_RAS_MAX_SUBEVENTS_PER_PROCEDURE 32
#define BT_RAS_MAX_STEPS_PER_PROCEDURE     256
 
#define BT_RAS_STEP_MODE_2_3_ANT_DEPENDENT_LEN(antenna_paths)                                      \
        ((antenna_paths + 1) * sizeof(struct bt_hci_le_cs_step_data_tone_info))
 
#define BT_RAS_STEP_MODE_0_MAX_LEN                                                                 \
        MAX(sizeof(struct bt_hci_le_cs_step_data_mode_0_initiator),                                \
            sizeof(struct bt_hci_le_cs_step_data_mode_0_reflector))
#define BT_RAS_STEP_MODE_1_MAX_LEN (sizeof(struct bt_hci_le_cs_step_data_mode_1))
#define BT_RAS_STEP_MODE_2_MAX_LEN                                                                 \
        (sizeof(struct bt_hci_le_cs_step_data_mode_2) +                                            \
         BT_RAS_STEP_MODE_2_3_ANT_DEPENDENT_LEN(CONFIG_BT_RAS_MAX_ANTENNA_PATHS))
#define BT_RAS_STEP_MODE_3_MAX_LEN                                                                 \
        (sizeof(struct bt_hci_le_cs_step_data_mode_3) +                                            \
         BT_RAS_STEP_MODE_2_3_ANT_DEPENDENT_LEN(CONFIG_BT_RAS_MAX_ANTENNA_PATHS))
 
#define BT_RAS_STEP_MODE_0_1_MAX_LEN   MAX(BT_RAS_STEP_MODE_0_MAX_LEN, BT_RAS_STEP_MODE_1_MAX_LEN)
#define BT_RAS_STEP_MODE_0_1_2_MAX_LEN MAX(BT_RAS_STEP_MODE_0_1_MAX_LEN, BT_RAS_STEP_MODE_2_MAX_LEN)
 
#if defined(CONFIG_BT_RAS_MODE_3_SUPPORTED)
#define BT_RAS_MAX_STEP_DATA_LEN MAX(BT_RAS_STEP_MODE_0_1_2_MAX_LEN, BT_RAS_STEP_MODE_3_MAX_LEN)
#else
#define BT_RAS_MAX_STEP_DATA_LEN BT_RAS_STEP_MODE_0_1_2_MAX_LEN
#endif
 
#define BT_RAS_PROCEDURE_MEM                                                                       \
        (BT_RAS_RANGING_HEADER_LEN +                                                               \
         (BT_RAS_MAX_SUBEVENTS_PER_PROCEDURE * BT_RAS_SUBEVENT_HEADER_LEN) +                       \
         (BT_RAS_MAX_STEPS_PER_PROCEDURE * BT_RAS_STEP_MODE_LEN) +                                 \
         (BT_RAS_MAX_STEPS_PER_PROCEDURE * BT_RAS_MAX_STEP_DATA_LEN))
 
enum ras_feat {
        RAS_FEAT_REALTIME_RD          = BIT(0),
        RAS_FEAT_RETRIEVE_LOST_RD_SEG = BIT(1),
        RAS_FEAT_ABORT_OP             = BIT(2),
        RAS_FEAT_FILTER_RD            = BIT(3),
};
 
struct ras_ranging_header {
        uint16_t ranging_counter : 12;
        uint8_t  config_id       : 4;
        int8_t   selected_tx_power;
        uint8_t  antenna_paths_mask;
} __packed;
BUILD_ASSERT(sizeof(struct ras_ranging_header) == BT_RAS_RANGING_HEADER_LEN);
 
struct ras_subevent_header {
        uint16_t start_acl_conn_event;
        uint16_t freq_compensation;
        uint8_t ranging_done_status   : 4;
        uint8_t subevent_done_status  : 4;
        uint8_t ranging_abort_reason  : 4;
        uint8_t subevent_abort_reason : 4;
        int8_t  ref_power_level;
        uint8_t num_steps_reported;
} __packed;
BUILD_ASSERT(sizeof(struct ras_subevent_header) == BT_RAS_SUBEVENT_HEADER_LEN);
 
struct bt_ras_rd_buffer_cb {
        void (*new_ranging_data_received)(struct bt_conn *conn, uint16_t ranging_counter);
 
        void (*ranging_data_overwritten)(struct bt_conn *conn, uint16_t ranging_counter);
 
        sys_snode_t node;
};
 
struct ras_rd_buffer {
        struct bt_conn *conn;
        uint16_t ranging_counter;
        uint16_t subevent_cursor;
        atomic_t refcount;
        bool ready;
        bool busy;
        bool acked;
        union {
                uint8_t buf[BT_RAS_PROCEDURE_MEM];
                struct {
                        struct ras_ranging_header ranging_header;
                        uint8_t subevents[];
                } __packed;
        } procedure;
};
 
int bt_ras_rrsp_alloc(struct bt_conn *conn);
 
void bt_ras_rrsp_free(struct bt_conn *conn);
 
void bt_ras_rd_buffer_cb_register(struct bt_ras_rd_buffer_cb *cb);
 
bool bt_ras_rd_buffer_ready_check(struct bt_conn *conn, uint16_t ranging_counter);
 
struct ras_rd_buffer *bt_ras_rd_buffer_claim(struct bt_conn *conn, uint16_t ranging_counter);
 
int bt_ras_rd_buffer_release(struct ras_rd_buffer *buf);
 
int bt_ras_rd_buffer_bytes_pull(struct ras_rd_buffer *buf, uint8_t *out_buf, uint16_t max_data_len,
                                uint16_t *read_cursor, bool *empty);
 
typedef void (*bt_ras_rreq_rd_ready_cb_t)(struct bt_conn *conn, uint16_t ranging_counter);
 
typedef void (*bt_ras_rreq_rd_overwritten_cb_t)(struct bt_conn *conn, uint16_t ranging_counter);
 
typedef void (*bt_ras_rreq_ranging_data_received_t)(struct bt_conn *conn, uint16_t ranging_counter,
                                                    int err);
 
typedef void (*bt_ras_rreq_features_read_cb_t)(struct bt_conn *conn, uint32_t feature_bits,
                                               int err);
 
int bt_ras_rreq_alloc_and_assign_handles(struct bt_gatt_dm *dm, struct bt_conn *conn);
 
int bt_ras_rreq_subscription_change_cb_register(struct bt_conn *conn,
                                                bt_gatt_subscribe_func_t subscription_change_cb);
 
int bt_ras_rreq_cp_get_ranging_data(struct bt_conn *conn, struct net_buf_simple *ranging_data_out,
                                    uint16_t ranging_counter,
                                    bt_ras_rreq_ranging_data_received_t data_get_complete_cb);
 
void bt_ras_rreq_free(struct bt_conn *conn);
 
int bt_ras_rreq_cp_subscribe(struct bt_conn *conn);
 
int bt_ras_rreq_cp_unsubscribe(struct bt_conn *conn);
 
int bt_ras_rreq_on_demand_rd_subscribe(struct bt_conn *conn);
 
int bt_ras_rreq_on_demand_rd_unsubscribe(struct bt_conn *conn);
 
int bt_ras_rreq_rd_ready_subscribe(struct bt_conn *conn, bt_ras_rreq_rd_ready_cb_t cb);
 
int bt_ras_rreq_rd_ready_unsubscribe(struct bt_conn *conn);
 
int bt_ras_rreq_rd_overwritten_subscribe(struct bt_conn *conn, bt_ras_rreq_rd_overwritten_cb_t cb);
 
int bt_ras_rreq_rd_overwritten_unsubscribe(struct bt_conn *conn);
 
int bt_ras_rreq_realtime_rd_subscribe(struct bt_conn *conn, struct net_buf_simple *ranging_data_out,
                                      bt_ras_rreq_ranging_data_received_t data_received_cb);
 
int bt_ras_rreq_realtime_rd_unsubscribe(struct bt_conn *conn);
 
int bt_ras_rreq_read_features(struct bt_conn *conn, bt_ras_rreq_features_read_cb_t cb);
 
typedef bool (*bt_ras_rreq_ranging_header_cb_t)(struct ras_ranging_header *ranging_header,
                                                 void *user_data);
 
typedef bool (*bt_ras_rreq_subevent_header_cb_t)(struct ras_subevent_header *subevent_header,
                                                 void *user_data);
 
typedef bool (*bt_ras_rreq_step_data_cb_t)(struct bt_le_cs_subevent_step *local_step,
                                           struct bt_le_cs_subevent_step *peer_step,
                                           void *user_data);
 
void bt_ras_rreq_rd_subevent_data_parse(struct net_buf_simple *peer_ranging_data_buf,
                                        struct net_buf_simple *local_step_data_buf,
                                        enum bt_conn_le_cs_role cs_role,
                                        bt_ras_rreq_ranging_header_cb_t ranging_header_cb,
                                        bt_ras_rreq_subevent_header_cb_t subevent_header_cb,
                                        bt_ras_rreq_step_data_cb_t step_data_cb, void *user_data);
 
static inline uint16_t bt_ras_rreq_get_ranging_counter(uint16_t procedure_counter)
{
        return procedure_counter & 0xFFF;
}
 
#ifdef __cplusplus
}
#endif
 
#endif /* BT_RAS_H_ */