This is an automated email from the ASF dual-hosted git repository.
janc pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/mynewt-nimble.git
The following commit(s) were added to refs/heads/master by this push:
new f65f61ac nimble/ble: Add doxygen comments to the header file
f65f61ac is described below
commit f65f61acdbc427d11b5c7fb1b8213cedc1410766
Author: Wojciech Pietraszewski <[email protected]>
AuthorDate: Tue Jun 4 14:10:10 2024 +0200
nimble/ble: Add doxygen comments to the header file
Adds missing macros and structures documentation.
---
nimble/include/nimble/ble.h | 120 ++++++++++++++++++++++++++++++++++++++++++--
1 file changed, 115 insertions(+), 5 deletions(-)
diff --git a/nimble/include/nimble/ble.h b/nimble/include/nimble/ble.h
index 6979e945..c42d5c5b 100644
--- a/nimble/include/nimble/ble.h
+++ b/nimble/include/nimble/ble.h
@@ -20,6 +20,11 @@
#ifndef H_BLE_
#define H_BLE_
+/**
+ * @defgroup bt_low_energy Bluetooth Low Energy
+ * @{
+ */
+
#include <inttypes.h>
#include <string.h>
#include "syscfg/syscfg.h"
@@ -29,15 +34,18 @@
extern "C" {
#endif
-/* The number of advertising instances */
+/** The number of advertising instances */
#define BLE_ADV_INSTANCES (MYNEWT_VAL(BLE_MULTI_ADV_INSTANCES) + 1)
-/* BLE encryption block definitions */
+/** BLE encryption block definitions */
#define BLE_ENC_BLOCK_SIZE (16)
-/* 4 byte header + 251 byte payload. */
+/** 4 byte header + 251 byte payload. */
#define BLE_ACL_MAX_PKT_SIZE 255
+/**
+ * @cond INTERNAL_DOCS
+ */
struct ble_encryption_block
{
uint8_t key[BLE_ENC_BLOCK_SIZE];
@@ -122,17 +130,34 @@ struct ble_mbuf_hdr_txiso {
uint16_t packet_seq_num;
};
+/**
+ * @endcond
+ */
+
+/** Structure representing a BLE mbuf header. */
struct ble_mbuf_hdr
{
union {
+ /** RX info for received packets. */
struct ble_mbuf_hdr_rxinfo rxinfo;
+
+ /** TX info for transmitted packets. */
struct ble_mbuf_hdr_txinfo txinfo;
+
+ /** TX ISO info for transmitted isochronous packets. */
struct ble_mbuf_hdr_txiso txiso;
};
+
+ /** CPU time when the packet processing began. */
uint32_t beg_cputime;
+
+ /** Remaining microseconds for packet processing. */
uint32_t rem_usecs;
};
+/**
+ * @cond INTERNAL_DOCS
+ */
#define BLE_MBUF_HDR_IGNORED(hdr) \
(!!((hdr)->rxinfo.flags & BLE_MBUF_HDR_F_IGNORED))
@@ -186,7 +211,16 @@ struct ble_mbuf_hdr
/* Length of host user header. Only contains the peer's connection handle. */
#define BLE_MBUF_HS_HDR_LEN (2)
+/**
+ * @endcond
+ */
+
+/** Length of a Bluetooth Device Address. */
#define BLE_DEV_ADDR_LEN (6)
+
+/**
+ * @cond INTERNAL_DOCS
+ */
extern uint8_t g_dev_addr[BLE_DEV_ADDR_LEN];
extern uint8_t g_random_addr[BLE_DEV_ADDR_LEN];
@@ -271,29 +305,103 @@ enum ble_error_codes
#define BLE_HW_ERR_DO_NOT_USE (0) /* XXX: reserve this one for now */
#define BLE_HW_ERR_HCI_SYNC_LOSS (1)
-/* Own Bluetooth Device address type */
+/**
+ * @endcond
+ */
+
+/**
+ * @defgroup ble_own_address_types Bluetooth Device Own Address Types
+ * @{
+ */
+
+/** Bluetooth Device Own Address Type: Public. */
#define BLE_OWN_ADDR_PUBLIC (0x00)
+
+/** Bluetooth Device Own Address Type: Random. */
#define BLE_OWN_ADDR_RANDOM (0x01)
+
+/**
+ * Bluetooth Device Own Address Type: Resolvable Private Address (RPA)
+ * with Public fallback.
+ */
#define BLE_OWN_ADDR_RPA_PUBLIC_DEFAULT (0x02)
+
+/**
+ * Bluetooth Device Own Address Type: Resolvable Private Address (RPA)
+ * with Random fallback.
+ */
#define BLE_OWN_ADDR_RPA_RANDOM_DEFAULT (0x03)
-/* Bluetooth Device address type */
+/** @} */
+
+/**
+ * @defgroup ble_address_types Bluetooth Device Address Types
+ * @{
+ */
+
+/** Bluetooth Device Address Type: Public. */
#define BLE_ADDR_PUBLIC (0x00)
+
+/** Bluetooth Device Address Type: Random. */
#define BLE_ADDR_RANDOM (0x01)
+
+/**
+ * Bluetooth Device Address Type: Public Identity Address
+ * (Corresponds to Resolved Private Address).
+ */
#define BLE_ADDR_PUBLIC_ID (0x02)
+
+/**
+ * Bluetooth Device Address Type: Random (Static) Identity Address
+ * (Corresponds to Resolved Private Address).
+ */
#define BLE_ADDR_RANDOM_ID (0x03)
+/** @} */
+
+/**
+ * @brief A macro representing any BLE address.
+ *
+ * This macro initializes a `ble_addr_t` structure to all zeros.
+ */
#define BLE_ADDR_ANY (&(ble_addr_t) { 0, {0, 0, 0, 0, 0, 0} })
+/**
+ * Checks if the given address is a Resolvable Private Address (RPA).
+ *
+ * @param addr Pointer to the `ble_addr_t` structure.
+ * @return Non-zero if the address is an RPA,
+ * zero otherwise.
+ */
#define BLE_ADDR_IS_RPA(addr) (((addr)->type == BLE_ADDR_RANDOM) && \
((addr)->val[5] & 0xc0) == 0x40)
+
+/**
+ * Checks if the given address is a Non-Resolvable Private Address (NRPA).
+ *
+ * @param addr Pointer to the `ble_addr_t` structure.
+ * @return Non-zero if the address is an NRPA,
+ * zero otherwise.
+ */
#define BLE_ADDR_IS_NRPA(addr) (((addr)->type == BLE_ADDR_RANDOM) && \
((addr)->val[5] & 0xc0) == 0x00)
+
+/**
+ * @brief Checks if the given address is a Static Random Address.
+ *
+ * @param addr Pointer to the `ble_addr_t` structure.
+ * @return Non-zero if the address is a Static Random Address,
+ * zero otherwise.
+ */
#define BLE_ADDR_IS_STATIC(addr) (((addr)->type == BLE_ADDR_RANDOM) && \
((addr)->val[5] & 0xc0) == 0xc0)
+/** Structure representing a BLE address. */
typedef struct {
+ /** The type of the address. */
uint8_t type;
+
+ /** The value of the address as an array of 6 bytes. */
uint8_t val[6];
} ble_addr_t;
@@ -314,4 +422,6 @@ static inline int ble_addr_cmp(const ble_addr_t *a, const
ble_addr_t *b)
}
#endif
+/** @} **/
+
#endif /* H_BLE_ */
