host/iso: Add doxygen comments in the header file
Adds missing structures and functions documentation.
diff --git a/nimble/host/include/host/ble_iso.h b/nimble/host/include/host/ble_iso.h
index 8b0182f..cdd3df8 100644
--- a/nimble/host/include/host/ble_iso.h
+++ b/nimble/host/include/host/ble_iso.h
@@ -19,11 +19,25 @@
#ifndef H_BLE_ISO_
#define H_BLE_ISO_
-#include <inttypes.h>
+/**
+ * @file ble_iso.h
+ *
+ * @brief Bluetooth ISO
+ * @defgroup bt_iso Bluetooth ISO
+ * @ingroup bt_host
+ * @{
+ */
+
+#include <inttypes.h>
#include "nimble/hci_common.h"
#include "syscfg/syscfg.h"
+/**
+ * @defgroup ble_iso_events ISO Events
+ * @{
+ */
+
/** ISO event: BIG Create Completed */
#define BLE_ISO_EVENT_BIG_CREATE_COMPLETE 0
@@ -39,18 +53,62 @@
/** ISO event: ISO Data received */
#define BLE_ISO_EVENT_ISO_RX 4
+/** @} */
+
/** @brief Broadcast Isochronous Group (BIG) description */
struct ble_iso_big_desc {
+ /**
+ * The identifier of the BIG. Assigned by the Host when a new BIG is
+ * created.
+ */
uint8_t big_handle;
+
+ /**
+ * The maximum time in microseconds for transmission of PDUs of all BISes in
+ * a BIG event.
+ */
uint32_t big_sync_delay;
+
+ /**
+ * The actual transport latency of transmitting payloads of all BISes in the
+ * BIG in microseconds.
+ */
uint32_t transport_latency_big;
+
+ /** The number of subevents per BIS in each BIG event. */
uint8_t nse;
+
+ /**
+ * The Burst Number (BN) specifies the number of new payloads in each BIS
+ * event.
+ */
uint8_t bn;
+
+ /**
+ * The Pre-Transmission Offset (PTO) specifies the offset of groups that
+ * carry data associated with the future BIS events.
+ */
uint8_t pto;
+
+ /**
+ * The Immediate Repetition Count (IRC) specifies the number of groups that
+ * carry the data associated with the current BIS event.
+ */
uint8_t irc;
+
+ /**
+ * The maximum number of data octets (excluding the MIC, if any) that can be
+ * carried in each BIS Data PDU in the BIG.
+ */
uint16_t max_pdu;
+
+ /** The time between two adjacent BIG anchor points in units of 1.25 ms. */
uint16_t iso_interval;
+
+ /** The total number of BISes in the BIG. */
uint8_t num_bis;
+
+ /** The connection handles of all the BIS in the BIG. */
uint16_t conn_handle[MYNEWT_VAL(BLE_MAX_BIS)];
};
@@ -68,7 +126,7 @@
/** @brief Received ISO data info structure */
struct ble_iso_rx_data_info {
- /** ISO Data timestamp. Valid if @ref ble_iso_data_info.ts_valid is set */
+ /** ISO Data timestamp. Valid if @ref ble_iso_rx_data_info.ts_valid is set */
uint32_t ts;
/** Packet sequence number */
@@ -77,7 +135,7 @@
/** SDU length */
uint16_t sdu_len : 12;
- /** ISO Data status. See @ref ble_iso_data_status */
+ /** ISO Data status. See @ref ble_iso_rx_data_status */
uint16_t status : 2;
/** Timestamp is valid */
@@ -146,30 +204,127 @@
};
};
+/** Function prototype for isochronous event callback. */
typedef int ble_iso_event_fn(struct ble_iso_event *event, void *arg);
+/** Broadcast Isochronous Group (BIG) parameters */
struct ble_iso_big_params {
+ /**
+ * The time interval of the periodic SDUs in microseconds. The value shall
+ * be between 0x0000FF and 0x0FFFFF.
+ */
uint32_t sdu_interval;
+
+ /**
+ * The maximum size of an SDU in octets. The value shall be between 0x0001
+ * and 0x0FFF.
+ */
uint16_t max_sdu;
+
+ /**
+ * The maximum transport latency in milliseconds. The value shall be between
+ * 0x0005 and 0x0FA0.
+ */
uint16_t max_transport_latency;
+
+ /**
+ * The Retransmission Number (RTN) parameter contains the number of times
+ * every PDU should be retransmitted, irrespective of which BIG events the
+ * retransmissions occur in. The value shall be between 0x00 and 0x1E.
+ */
uint8_t rtn;
+
+ /**
+ * The PHY parameter is a bit field that indicates the PHY used for
+ * transmission of PDUs of BISes in the BIG. The value shall be one of the
+ * following:
+ * o BLE_HCI_LE_PHY_1M_PREF_MASK
+ * o BLE_HCI_LE_PHY_2M_PREF_MASK
+ * o BLE_HCI_LE_PHY_CODED_PREF_MASK
+ */
uint8_t phy;
+
+ /**
+ * Indicates the preferred method of arranging subevents of multiple BISes.
+ * The value shall be one of the following:
+ * o 0x00 - Sequential
+ * o 0x01 - Interleaved
+ */
uint8_t packing;
+
+ /**
+ * Indicates whether the BIG carries framed or unframed data. The value
+ * shall be one of the following:
+ * o 0x00 - Unframed
+ * o 0x01 - Framed
+ */
uint8_t framing;
+
+ /**
+ * Indicates whether the BIG is encrypted or not. The value shall be one of
+ * the following:
+ * o 0x00 - Unencrypted
+ * o 0x01 - Encrypted
+ */
uint8_t encryption;
+
+ /**
+ * The 128-bit code used to derive the session key that is used to encrypt
+ * and decrypt BIS payloads.
+ */
const char *broadcast_code;
};
+/** Create BIG parameters */
struct ble_iso_create_big_params {
+ /** The associated periodic advertising train of the BIG. */
uint8_t adv_handle;
+
+ /** The total number of BISes in the BIG. */
uint8_t bis_cnt;
+
+ /** Callback function for reporting the status of the procedure. */
ble_iso_event_fn *cb;
+
+ /**
+ * An optional user-defined argument to be passed to the callback function.
+ */
void *cb_arg;
};
+/**
+ * Initiates the creation of Broadcast Isochronous Group (BIG). It configures
+ * the BIG parameters based on the provided input and triggers the corresponding
+ * HCI command.
+ *
+ * @param create_params A pointer to the structure holding the
+ * parameters specific to creating the BIG.
+ * These parameters define the general settings
+ * and include a callback function for handling
+ * creation events.
+ * @param big_params A pointer to the structure holding detailed
+ * parameters specific to the configuration of
+ * the BIG. These parameters include settings
+ * such as SDU interval, maximum SDU size,
+ * transport latency, etc.
+ *
+ * @return 0 on success;
+ * an error code on failure.
+ *
+ * @note The actual BIG creation result will be reported through the callback
+ * function specified in @p create_params.
+ */
int ble_iso_create_big(const struct ble_iso_create_big_params *create_params,
const struct ble_iso_big_params *big_params);
+/**
+ * Terminates an existing Broadcast Isochronous Group (BIG).
+ *
+ * @param big_handle The identifier of the BIG to be terminated.
+ *
+ * @return 0 on success;
+ * an error code on failure.
+ */
int ble_iso_terminate_big(uint8_t big_handle);
/** @brief BIS parameters for @ref ble_iso_big_sync_create */
@@ -295,7 +450,7 @@
* between the Host and the Controller for a CIS, CIS configuration, or BIS
* identified by the @p param->conn_handle parameter.
*
- * @param[in] params BIG synchronization parameters
+ * @param[in] param BIG synchronization parameters
*
* @return 0 on success;
* A non-zero value on failure.
@@ -318,15 +473,34 @@
* associated with a CIS, CIS configuration, or BIS identified by the
* @p param->conn_handle parameter.
*
- * @param[in] params BIG synchronization parameters
+ * @param[in] param BIG synchronization parameters
*
* @return 0 on success;
* A non-zero value on failure.
*/
int ble_iso_data_path_remove(const struct ble_iso_data_path_remove_params *param);
+/**
+ * Initiates the transmission of isochronous data.
+ *
+ * @param conn_handle The connection over which to execute the procedure.
+ * @param data A pointer to the data to be transmitted.
+ * @param data_len Number of the data octets to be transmitted.
+ *
+ * @return 0 on success;
+ * an error code on failure.
+ */
int ble_iso_tx(uint16_t conn_handle, void *data, uint16_t data_len);
+/**
+ * Initializes memory for ISO.
+ *
+ * @return 0 on success
+ */
int ble_iso_init(void);
+/**
+ * @}
+ */
+
#endif /* H_BLE_ISO_ */
