2 files changed, 20 insertions, 0 deletions

diff --git a/embassy-stm32-wpan/src/sub/ble.rs b/embassy-stm32-wpan/src/sub/ble.rs
index c5f2334f4..a47c6a699 100644
--- a/embassy-stm32-wpan/src/sub/ble.rs
+++ b/embassy-stm32-wpan/src/sub/ble.rs
@@ -11,11 +11,20 @@ use crate::tables::{BleTable, BLE_CMD_BUFFER, CS_BUFFER, EVT_QUEUE, HCI_ACL_DATA
 use crate::unsafe_linked_list::LinkedListNode;
 use crate::{channels, evt};
 
+/// A guard that, once constructed, may be used to send BLE commands to CPU2.
+///
+/// It is the responsibility of the caller to ensure that they have awaited an event via
+/// [crate::sub::Sys::read] before sending any of these commands, and to call
+/// [crate::sub::Sys::shci_c2_ble_init] and await the HCI_COMMAND_COMPLETE_EVENT before sending any
+/// other commands.
 pub struct Ble {
     _private: (),
 }
 
 impl Ble {
+    /// Constructs a guard that allows for BLE commands to be sent to CPU2.
+    ///
+    /// This takes the place of `TL_BLE_Init`, completing that step as laid out in AN5289, Fig 66.
     pub(crate) fn new() -> Self {
         unsafe {
             LinkedListNode::init_head(EVT_QUEUE.as_mut_ptr());
@@ -30,6 +39,7 @@ impl Ble {
 
         Self { _private: () }
     }
+
     /// `HW_IPCC_BLE_EvtNot`
     pub async fn tl_read(&self) -> EvtBox<Self> {
         Ipcc::receive(channels::cpu2::IPCC_BLE_EVENT_CHANNEL, || unsafe {
diff --git a/embassy-stm32-wpan/src/sub/sys.rs b/embassy-stm32-wpan/src/sub/sys.rs
index bd2ea3f74..fcc2c651e 100644
--- a/embassy-stm32-wpan/src/sub/sys.rs
+++ b/embassy-stm32-wpan/src/sub/sys.rs
@@ -10,6 +10,7 @@ use crate::tables::{SysTable, WirelessFwInfoTable};
 use crate::unsafe_linked_list::LinkedListNode;
 use crate::{channels, Ipcc, SYSTEM_EVT_QUEUE, SYS_CMD_BUF, TL_DEVICE_INFO_TABLE, TL_SYS_TABLE};
 
+/// A guard that, once constructed, allows for sys commands to be sent to CPU2.
 pub struct Sys {
     _private: (),
 }
@@ -86,12 +87,21 @@ impl Sys {
         self.write_and_get_response(ShciOpcode::Mac802_15_4Init, &[]).await
     }
 
+    /// Send a request to CPU2 to initialise the BLE stack.
+    ///
+    /// This must be called before any BLE commands are sent via the BLE channel (according to
+    /// AN5289, Figures 65 and 66). It should only be called after CPU2 sends a system event, via
+    /// `HW_IPCC_SYS_EvtNot`, aka `IoBusCallBackUserEvt` (as detailed in Figure 65), aka [read].
     #[cfg(feature = "ble")]
     pub async fn shci_c2_ble_init(&self, param: ShciBleInitCmdParam) -> Result<SchiCommandStatus, ()> {
         self.write_and_get_response(ShciOpcode::BleInit, param.payload()).await
     }
 
     /// `HW_IPCC_SYS_EvtNot`
+    ///
+    /// This method takes the place of the `HW_IPCC_SYS_EvtNot`/`SysUserEvtRx`/`APPE_SysUserEvtRx`,
+    /// as the embassy implementation avoids the need to call C public bindings, and instead
+    /// handles the event channels directly.
     pub async fn read(&self) -> EvtBox<mm::MemoryManager> {
         Ipcc::receive(channels::cpu2::IPCC_SYSTEM_EVENT_CHANNEL, || unsafe {
             if let Some(node_ptr) = LinkedListNode::remove_head(SYSTEM_EVT_QUEUE.as_mut_ptr()) {