Add docs for the BLE bindings

These new docs explain a lot of the current implementation for the BLE
stack, with reference to AN5289 14.1. They also detail the additional
requirements around BLE startup behaviour; specifically, that certain
SYS events must be awaited, and that shci_c2_ble_init should be called.

Since the ble feature is now enabled by default for the docs, the
remaining documentation for the BLE behaviour (as implemented by the
`stm32wb-hci` crate) should be bought in automatically.

1 files changed, 7 insertions, 0 deletions

diff --git a/embassy-stm32-wpan/src/tables.rs b/embassy-stm32-wpan/src/tables.rs
index f2c250527..e730d6d87 100644
--- a/embassy-stm32-wpan/src/tables.rs
+++ b/embassy-stm32-wpan/src/tables.rs
@@ -89,12 +89,19 @@ pub struct DeviceInfoTable {
     pub wireless_fw_info_table: WirelessFwInfoTable,
 }
 
+/// The bluetooth reference table, as defined in figure 67 of STM32WX AN5289.
 #[derive(Debug)]
 #[repr(C)]
 pub struct BleTable {
+    /// A pointer to the buffer that is used for sending BLE commands.
     pub pcmd_buffer: *mut CmdPacket,
+    /// A pointer to the buffer used for storing Command statuses.
     pub pcs_buffer: *const u8,
+    /// A pointer to the event queue, over which IPCC BLE events are sent. This may be accessed via
+    /// [crate::sub::ble::tl_read].
     pub pevt_queue: *const u8,
+    /// A pointer to the buffer that is used for sending HCI (Host-Controller Interface) ACL
+    /// (Asynchronous Connection-oriented Logical transport) commands (unused).
     pub phci_acl_data_buffer: *mut AclDataPacket,
 }