Restored original function documentation

1 files changed, 149 insertions, 184 deletions

diff --git a/embassy-stm32-wpan/src/wba/linklayer_plat.rs b/embassy-stm32-wpan/src/wba/linklayer_plat.rs
index be9c49ab3..99afc78d6 100644
--- a/embassy-stm32-wpan/src/wba/linklayer_plat.rs
+++ b/embassy-stm32-wpan/src/wba/linklayer_plat.rs
@@ -75,10 +75,6 @@
 #![cfg(feature = "wba")]
 #![allow(clippy::missing_safety_doc)]
 
-//! STM32WBA Link Layer platform adaptation layer.
-//!
-//! Based on STMicroelectronics original C source `linklayer_plat.c` (2024).
-
 use core::hint::spin_loop;
 use core::ptr;
 use core::sync::atomic::{AtomicBool, AtomicI32, AtomicPtr, AtomicU32, Ordering};
@@ -278,36 +274,31 @@ pub unsafe fn run_radio_sw_low_isr() {
     }
 }
 
-/// Initialize radio-related clock prerequisites.
-///
-/// Currently this touches the sleep timer to ensure the Link Layer common
-/// interface is initialized. It does not actively reconfigure clocks.
-///
-/// # Safety
-/// Called from the vendor Link Layer. Must run in a context where accessing
-/// the LL common interface is safe.
+// /**
+//   * @brief  Configure the necessary clock sources for the radio.
+//   * @param  None
+//   * @retval None
+//   */
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn LINKLAYER_PLAT_ClockInit() {
     let _ = link_layer::ll_intf_cmn_get_slptmr_value();
 }
 
-/// Busy-wait for the requested duration in microseconds.
-///
-/// Blocks the current context until `delay` microseconds have elapsed.
-///
-/// # Safety
-/// Must be called only in contexts where busy-waiting is acceptable (e.g. no
-/// hard real-time deadlines are violated).
+// /**
+//   * @brief  Link Layer active waiting loop.
+//   * @param  delay: delay in us
+//   * @retval None
+//   */
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn LINKLAYER_PLAT_DelayUs(delay: u32) {
     block_for(Duration::from_micros(u64::from(delay)));
 }
 
-/// Assert a condition and panic if it is false.
-///
-/// # Safety
-/// None beyond general panic considerations; will abort/panic the program if
-/// `condition == 0`.
+// /**
+//   * @brief  Link Layer assertion API
+//   * @param  condition: conditional statement to be checked.
+//   * @retval None
+//   */
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn LINKLAYER_PLAT_Assert(condition: u8) {
     if condition == 0 {
@@ -315,13 +306,11 @@ pub unsafe extern "C" fn LINKLAYER_PLAT_Assert(condition: u8) {
     }
 }
 
-/// Wait for the AHB5 clock domain to be ready after low-power entry.
-///
-/// If the platform flagged AHB5 as switched off before WFI, this waits until
-/// the sleep timer ticks, indicating the bus has resumed.
-///
-/// # Safety
-/// Spins while waiting; must be safe to busy-wait in the calling context.
+// /**
+//   * @brief  Enable/disable the Link Layer active clock (baseband clock).
+//   * @param  enable: boolean value to enable (1) or disable (0) the clock.
+//   * @retval None
+//   */
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn LINKLAYER_PLAT_WaitHclkRdy() {
     if AHB5_SWITCHED_OFF.swap(false, Ordering::AcqRel) {
@@ -332,23 +321,24 @@ pub unsafe extern "C" fn LINKLAYER_PLAT_WaitHclkRdy() {
     }
 }
 
-/// Notify that the system is entering WFI and AHB5 may be turned off depending
-/// on radio state.
-///
-/// # Safety
-/// None; this only updates internal state used to resynchronize after WFI.
+// /**
+//   * @brief  Notify the Link Layer platform layer the system will enter in WFI
+//   *         and AHB5 clock may be turned of regarding the 2.4Ghz radio state.
+//   * @param  None
+//   * @retval None
+//   */
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn LINKLAYER_PLAT_NotifyWFIEnter() {
     AHB5_SWITCHED_OFF.store(true, Ordering::Release);
 }
 
-/// Notify that the system exited WFI and capture a reference sleep timer value.
-///
-/// If AHB5 was flagged as switched off on entry, records the current sleep
-/// timer value for later synchronization in [`LINKLAYER_PLAT_WaitHclkRdy`].
-///
-/// # Safety
-/// None; reads a monotonic timer from the LL common interface.
+// /**
+//   * @brief  Notify the Link Layer platform layer the system exited WFI and AHB5
+//   *         clock may be resynchronized as is may have been turned of during
+//   *         low power mode entry.
+//   * @param  None
+//   * @retval None
+//   */
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn LINKLAYER_PLAT_NotifyWFIExit() {
     if AHB5_SWITCHED_OFF.load(Ordering::Acquire) {
@@ -357,24 +347,20 @@ pub unsafe extern "C" fn LINKLAYER_PLAT_NotifyWFIExit() {
     }
 }
 
-/// Control the active clock (placeholder).
-///
-/// Currently a no-op. Present for API compatibility with vendor code.
-///
-/// # Safety
-/// None; function does nothing.
+// /**
+//   * @brief  Active wait on bus clock readiness.
+//   * @param  None
+//   * @retval None
+//   */
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn LINKLAYER_PLAT_AclkCtrl(_enable: u8) {}
 
-/// Fill a buffer with pseudo-random bytes.
-///
-/// This uses a xorshift32 PRNG seeded from the sleep timer and core clock.
-/// It is not cryptographically secure and is intended only for non-security
-/// purposes.
-///
-/// # Safety
-/// - `ptr_rnd` must be valid for writes of `len` bytes.
-/// - The memory region must not alias mutable references elsewhere.
+// /**
+//   * @brief  Link Layer RNG request.
+//   * @param  ptr_rnd: pointer to the variable that hosts the number.
+//   * @param  len: number of byte of anthropy to get.
+//   * @retval None
+//   */
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn LINKLAYER_PLAT_GetRNG(ptr_rnd: *mut u8, len: u32) {
     if ptr_rnd.is_null() || len == 0 {
@@ -387,14 +373,11 @@ pub unsafe extern "C" fn LINKLAYER_PLAT_GetRNG(ptr_rnd: *mut u8, len: u32) {
     }
 }
 
-/// Configure the radio high-priority interrupt callback and NVIC state.
-///
-/// When `intr_cb` is `Some`, sets the NVIC priority to
-/// `RADIO_INTR_PRIO_HIGH` and unmasks the interrupt. Passing `None` disables
-/// the interrupt.
-///
-/// # Safety
-/// `intr_cb` must be an ISR-safe function. Alters NVIC state globally.
+// /**
+//   * @brief  Initialize Link Layer radio high priority interrupt.
+//   * @param  intr_cb: function pointer to assign for the radio high priority ISR routine.
+//   * @retval None
+//   */
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn LINKLAYER_PLAT_SetupRadioIT(intr_cb: Option<Callback>) {
     store_callback(&RADIO_CALLBACK, intr_cb);
@@ -407,14 +390,11 @@ pub unsafe extern "C" fn LINKLAYER_PLAT_SetupRadioIT(intr_cb: Option<Callback>)
     }
 }
 
-/// Configure the software low-priority radio interrupt callback and NVIC state.
-///
-/// When `intr_cb` is `Some`, sets the NVIC priority to
-/// `RADIO_SW_LOW_INTR_PRIO` and unmasks the interrupt. Passing `None`
-/// disables the interrupt.
-///
-/// # Safety
-/// `intr_cb` must be ISR-safe. Alters NVIC state globally.
+// /**
+//   * @brief  Initialize Link Layer SW low priority interrupt.
+//   * @param  intr_cb: function pointer to assign for the SW low priority ISR routine.
+//   * @retval None
+//   */
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn LINKLAYER_PLAT_SetupSwLowIT(intr_cb: Option<Callback>) {
     store_callback(&LOW_ISR_CALLBACK, intr_cb);
@@ -427,13 +407,11 @@ pub unsafe extern "C" fn LINKLAYER_PLAT_SetupSwLowIT(intr_cb: Option<Callback>)
     }
 }
 
-/// Trigger the software low-priority radio interrupt.
-///
-/// If `priority` is non-zero, elevates the interrupt to the low radio priority
-/// for this trigger or the next run when already active.
-///
-/// # Safety
-/// Alters NVIC pending and priority state; must be safe for the system.
+// /**
+//   * @brief  Trigger the link layer SW low interrupt.
+//   * @param  None
+//   * @retval None
+//   */
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn LINKLAYER_PLAT_TriggerSwLowIT(priority: u8) {
     let active = nvic_get_active(RADIO_SW_LOW_INTR_NUM);
@@ -452,13 +430,11 @@ pub unsafe extern "C" fn LINKLAYER_PLAT_TriggerSwLowIT(priority: u8) {
     nvic_set_pending(RADIO_SW_LOW_INTR_NUM);
 }
 
-/// Enable interrupts using a reference-counted scheme.
-///
-/// When the internal counter reaches zero, restores the previous PRIMASK
-/// snapshot and enables or keeps interrupts disabled accordingly.
-///
-/// # Safety
-/// Must be paired with prior calls to [`LINKLAYER_PLAT_DisableIRQ`].
+// /**
+//   * @brief  Enable interrupts.
+//   * @param  None
+//   * @retval None
+//   */
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn LINKLAYER_PLAT_EnableIRQ() {
     if counter_release(&IRQ_COUNTER) {
@@ -471,13 +447,11 @@ pub unsafe extern "C" fn LINKLAYER_PLAT_EnableIRQ() {
     }
 }
 
-/// Disable interrupts using a reference-counted scheme.
-///
-/// Captures the current PRIMASK state on the first disable and then disables
-/// interrupts. Must be balanced with [`LINKLAYER_PLAT_EnableIRQ`].
-///
-/// # Safety
-/// Affects global interrupt state; may impact system timing and ISRs.
+// /**
+//   * @brief  Disable interrupts.
+//   * @param  None
+//   * @retval None
+//   */
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn LINKLAYER_PLAT_DisableIRQ() {
     if counter_acquire(&IRQ_COUNTER) {
@@ -487,16 +461,16 @@ pub unsafe extern "C" fn LINKLAYER_PLAT_DisableIRQ() {
     cortex_m::interrupt::disable();
 }
 
-/// Enable specific Link Layer interrupt groups.
-///
-/// - `LL_HIGH_ISR_ONLY`: Unmask high-priority radio ISR.
-/// - `LL_LOW_ISR_ONLY`: Unmask software low-priority radio ISR.
-/// - `SYS_LOW_ISR`: Lower BASEPRI mask to re-enable lower-priority system ISRs.
-///
-/// Uses internal reference counters so multiple disables/enables can be nested.
-///
-/// # Safety
-/// Alters NVIC and BASEPRI state globally.
+// /**
+//   * @brief  Enable specific interrupt group.
+//   * @param  isr_type: mask for interrupt group to enable.
+//   *         This parameter can be one of the following:
+//   *         @arg LL_HIGH_ISR_ONLY: enable link layer high priority ISR.
+//   *         @arg LL_LOW_ISR_ONLY: enable link layer SW low priority ISR.
+//   *         @arg SYS_LOW_ISR: mask interrupts for all the other system ISR with
+//   *              lower priority that link layer SW low interrupt.
+//   * @retval None
+//   */
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn LINKLAYER_PLAT_EnableSpecificIRQ(isr_type: u8) {
     if (isr_type & link_layer::LL_HIGH_ISR_ONLY as u8) != 0 {
@@ -519,16 +493,16 @@ pub unsafe extern "C" fn LINKLAYER_PLAT_EnableSpecificIRQ(isr_type: u8) {
     }
 }
 
-/// Disable specific Link Layer interrupt groups.
-///
-/// - `LL_HIGH_ISR_ONLY`: Mask high-priority radio ISR.
-/// - `LL_LOW_ISR_ONLY`: Mask software low-priority radio ISR.
-/// - `SYS_LOW_ISR`: Raise BASEPRI to mask system ISRs lower than SW low-priority.
-///
-/// Uses internal reference counters so multiple disables/enables can be nested.
-///
-/// # Safety
-/// Alters NVIC and BASEPRI state globally.
+// /**
+//   * @brief  Disable specific interrupt group.
+//   * @param  isr_type: mask for interrupt group to disable.
+//   *         This parameter can be one of the following:
+//   *         @arg LL_HIGH_ISR_ONLY: disable link layer high priority ISR.
+//   *         @arg LL_LOW_ISR_ONLY: disable link layer SW low priority ISR.
+//   *         @arg SYS_LOW_ISR: unmask interrupts for all the other system ISR with
+//   *              lower priority that link layer SW low interrupt.
+//   * @retval None
+//   */
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn LINKLAYER_PLAT_DisableSpecificIRQ(isr_type: u8) {
     if (isr_type & link_layer::LL_HIGH_ISR_ONLY as u8) != 0 {
@@ -552,107 +526,100 @@ pub unsafe extern "C" fn LINKLAYER_PLAT_DisableSpecificIRQ(isr_type: u8) {
     }
 }
 
-/// Unmask the radio high-priority interrupt.
-///
-/// # Safety
-/// Alters NVIC state globally.
+// /**
+//   * @brief  Enable link layer high priority ISR only.
+//   * @param  None
+//   * @retval None
+//   */
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn LINKLAYER_PLAT_EnableRadioIT() {
     nvic_enable(mac::RADIO_INTR_NUM);
 }
 
-/// Mask the radio high-priority interrupt.
-///
-/// # Safety
-/// Alters NVIC state globally.
+// /**
+//   * @brief  Disable link layer high priority ISR only.
+//   * @param  None
+//   * @retval None
+//   */
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn LINKLAYER_PLAT_DisableRadioIT() {
     nvic_disable(mac::RADIO_INTR_NUM);
 }
 
-/// Notify that a radio activity is starting.
-///
-/// Sets the radio interrupt priority to high and unmasks it.
-///
-/// # Safety
-/// Alters NVIC state globally.
+// /**
+//   * @brief  Link Layer notification for radio activity start.
+//   * @param  None
+//   * @retval None
+//   */
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn LINKLAYER_PLAT_StartRadioEvt() {
     nvic_set_priority(mac::RADIO_INTR_NUM, pack_priority(mac::RADIO_INTR_PRIO_HIGH));
     nvic_enable(mac::RADIO_INTR_NUM);
 }
 
-/// Notify that a radio activity ended.
-///
-/// Lowers the radio interrupt priority to its low setting.
-///
-/// # Safety
-/// Alters NVIC state globally.
+// /**
+//   * @brief  Link Layer notification for radio activity end.
+//   * @param  None
+//   * @retval None
+//   */
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn LINKLAYER_PLAT_StopRadioEvt() {
     nvic_set_priority(mac::RADIO_INTR_NUM, pack_priority(mac::RADIO_INTR_PRIO_LOW));
 }
 
-/// Notify that RCO calibration is starting (placeholder).
-///
-/// Currently a no-op.
-///
-/// # Safety
-/// None.
+// /**
+//   * @brief  Link Layer notification for RCO calibration start.
+//   * @param  None
+//   * @retval None
+//   */
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn LINKLAYER_PLAT_RCOStartClbr() {}
 
-/// Notify that RCO calibration ended (placeholder).
-///
-/// Currently a no-op.
-///
-/// # Safety
-/// None.
+// /**
+//   * @brief  Link Layer notification for RCO calibration end.
+//   * @param  None
+//   * @retval None
+//   */
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn LINKLAYER_PLAT_RCOStopClbr() {}
 
-/// Request a temperature measurement for radio calibration (placeholder).
-///
-/// Currently a no-op.
-///
-/// # Safety
-/// None.
+// /**
+//   * @brief  Link Layer requests temperature.
+//   * @param  None
+//   * @retval None
+//   */
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn LINKLAYER_PLAT_RequestTemperature() {}
 
-/// Notify that PHY calibration is starting (placeholder).
-///
-/// Currently a no-op.
-///
-/// # Safety
-/// None.
+// /**
+//   * @brief  PHY Start calibration.
+//   * @param  None
+//   * @retval None
+//   */
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn LINKLAYER_PLAT_PhyStartClbr() {}
 
-/// Notify that PHY calibration ended (placeholder).
-///
-/// Currently a no-op.
-///
-/// # Safety
-/// None.
+// /**
+//   * @brief  PHY Stop calibration.
+//   * @param  None
+//   * @retval None
+//   */
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn LINKLAYER_PLAT_PhyStopClbr() {}
 
-/// Notify that new Link Layer scheduler timings have been applied (placeholder).
-///
-/// Currently a no-op.
-///
-/// # Safety
-/// None.
+// /**
+//  * @brief Notify the upper layer that new Link Layer timings have been applied.
+//  * @param evnt_timing[in]: Evnt_timing_t pointer to structure contains drift time , execution time and scheduling time
+//  * @retval None.
+//  */
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn LINKLAYER_PLAT_SCHLDR_TIMING_UPDATE_NOT(_timings: *const link_layer::Evnt_timing_t) {}
 
-/// Return the STMicroelectronics Bluetooth SIG Company Identifier.
-///
-/// Value: `0x0030`.
-///
-/// # Safety
-/// None.
+// /**
+//   * @brief  Get the ST company ID.
+//   * @param  None
+//   * @retval Company ID
+//   */
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn LINKLAYER_PLAT_GetSTCompanyID() -> u32 {
     // STMicroelectronics Bluetooth SIG Company Identifier
@@ -660,13 +627,11 @@ pub unsafe extern "C" fn LINKLAYER_PLAT_GetSTCompanyID() -> u32 {
     0x0030
 }
 
-/// Return the lower 32 bits of the STM32 unique 96-bit device identifier.
-///
-/// Note: This may differ from the ST-defined UDN encoding found in some device
-/// registers/documents; it returns the first word of the unique ID.
-///
-/// # Safety
-/// None.
+// /**
+//   * @brief  Get the Unique Device Number (UDN).
+//   * @param  None
+//   * @retval UDN
+//   */
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn LINKLAYER_PLAT_GetUDN() -> u32 {
     // Read the first 32 bits of the STM32 unique 96-bit ID