espressif/esp-nimble
1
0
Fork 0
mirror of https://github.com/espressif/esp-nimble.git synced 2026-08-21 01:09:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

host/iso: Add doxygen comments in the header file

Browse Source 
Adds missing structures and functions documentation.
This commit is contained in:
Wojciech Pietraszewski
2024-02-28 16:04:52 +01:00
committed by Szymon Janc
parent a3cef58817
commit ebe1e7804d
1 changed files with 179 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
nimble/host/include/host/ble_iso.h
+179 -5
View File
@@ -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 @@ enum ble_iso_rx_data_status {
/** @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 @@ struct ble_iso_rx_data_info {
/** 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 @@ 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 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 @@ struct ble_iso_data_path_setup_params {
* 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 @@ struct ble_iso_data_path_remove_params {
* 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_ */