From 8d6953ca89230b558ae332f87886e40998254f59 Mon Sep 17 00:00:00 2001 From: Wojciech Pietraszewski Date: Wed, 14 Feb 2024 15:02:09 +0100 Subject: [PATCH] host/iso: Add doxygen comments in the header file Adds missing structures and functions documentation. --- nimble/host/include/host/ble_iso.h | 200 ++++++++++++++++++++++++++++- 1 file changed, 199 insertions(+), 1 deletion(-) diff --git a/nimble/host/include/host/ble_iso.h b/nimble/host/include/host/ble_iso.h index 44877dca68..635b863d24 100644 --- a/nimble/host/include/host/ble_iso.h +++ b/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 +/** 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_ */