host/iso: Add doxygen comments in the header file

Adds missing structures and functions documentation.

nimble/host/include/host/ble_iso.h

@@ -19,29 +19,112 @@
 
 #ifndef H_BLE_ISO_
 #define H_BLE_ISO_
+
+/**
+ * @file ble_iso.h
+ *
+ * @brief Bluetooth ISO
+ * @defgroup bt_iso Bluetooth ISO
+ * @ingroup bt_host
+ * @{
+ */
+
 #include "syscfg/syscfg.h"
 
+/**
+ * @defgroup ble_iso_events ISO Events
+ * @{
+ */
+
 /** ISO event: BIG Create Completed */
 #define BLE_ISO_EVENT_BIG_CREATE_COMPLETE                  0
 
 /** ISO event: BIG Terminate Completed */
 #define BLE_ISO_EVENT_BIG_TERMINATE_COMPLETE               1
 
+/** @} */
+
 #include <inttypes.h>
 
+/** Broadcast Isochronous Group (BIG) descriptor */
 struct ble_iso_big_desc
 {
+    /**
+     * The identifier of the BIG. Assigned by the Host when a new BIG is
+     * created. The value shall be between 0x00 and 0xEF.
+     */
     uint8_t big_handle;
+
+    /**
+     * The maximum time in microseconds for transmission of PDUs of all BISes in
+     * a BIG event. The value of BIG_Sync_Delay shall equal the time from the
+     * anchor point to the BIG Synchronization point and shall be between
+     * 0x0000EA and 0x7FFFFF.
+     */
     uint32_t big_sync_delay;
+
+    /**
+     * The actual transport latency of transmitting payloads of all BISes in the
+     * BIG in microseconds. The value shall be between 0x0000EA and 0x7FFFFF.
+     */
     uint32_t transport_latency_big;
+
+    /**
+     * The PHY used to create the BIG. The value shall be one of the following:
+     *     o BLE_HCI_LE_PHY_1M
+     *     o BLE_HCI_LE_PHY_2M
+     *     o BLE_HCI_LE_PHY_CODED
+     */
     uint8_t phy;
+
+    /**
+     * The number of subevents per BIS in each BIG event. The value shall be
+     * between 1 and 31 and shall be an integer multiple of BN.
+     */
     uint8_t nse;
+
+    /**
+     * The Burst Number (BN) specifies the number of new payloads in each BIS
+     * event. The value of BN shall be between 1 and 7.
+     */
     uint8_t bn;
+
+    /**
+     * The Pre-Transmission Offset (PTO) specifies the offset of groups that
+     * carry data associated with the future BIS events. The value of PTO shall
+     * be between 0 and 15.
+     */
     uint8_t pto;
+
+    /**
+     * The Immediate Repetition Count (IRC) specifies the number of groups that
+     * carry the data associated with the current BIS event. The value of IRC
+     * shall be between 1 and 15.
+     */
     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. The value shall be between 1 and
+     * 251 octets.
+     */
     uint16_t max_pdu;
+
+    /**
+     * The time between two adjacent BIG anchor points in units of 1.25 ms. The
+     * value shall be between 0x0004 and 0x0C80 (i.e. 5 ms to 4 s).
+     */
     uint16_t iso_interval;
+
+    /**
+     * The total number of BISes in the BIG. The value shall be between 1 and 31.
+     */
     uint8_t num_bis;
+
+    /**
+     * The connection handles of all the BIS in the BIG. The value shall be
+     * between 0x0000 and 0x0EFF.
+     */
     uint16_t conn_handle[MYNEWT_VAL(BLE_MAX_BIS)];
 };
 
@@ -83,30 +166,126 @@ struct ble_iso_event {
     };
 };
 
+/** 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 can 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 can 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 can
+     * be one of the following:
+     *     o 0x00 - Unframed
+     *     o 0x01 - Framed
+     */
     uint8_t framing;
+
+    /**
+     * Indicates whether the BIG is encrypted or not. The value can 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 Isochronous Broadcaster Group (BIG).
+ *
+ * @param big_id            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_id);
 
 void
@@ -117,8 +296,27 @@ ble_gap_rx_terminate_big_complete(const struct
                                   ble_hci_ev_le_subev_terminate_big_complete
                                   *ev);
 
+/**
+ * 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
+/**
+ * @}
+ */
+
+#endif /* H_BLE_ISO_ */