Rewrite documentation and generally improve it

1 files changed, 31 insertions, 22 deletions

diff --git a/examples/stm32h755cm4/src/bin/intercore.rs b/examples/stm32h755cm4/src/bin/intercore.rs
index 3a66a1ecd..715df28d6 100644
--- a/examples/stm32h755cm4/src/bin/intercore.rs
+++ b/examples/stm32h755cm4/src/bin/intercore.rs
@@ -1,18 +1,32 @@
 #![no_std]
 #![no_main]
 
-// IMPORTANT: This must match EXACTLY the definition in CM7!
+//! STM32H7 Secondary Core (CM4) Intercore Communication Example
+//!
+//! This example demonstrates reliable communication between the Cortex-M7 and
+//! Cortex-M4 cores. This secondary core monitors shared memory for LED state
+//! changes and updates the physical LEDs accordingly.
+//!
+//! The CM4 core handles:
+//! - Responding to state changes from CM7
+//! - Controlling the physical green and yellow LEDs
+//! - Providing visual feedback via a heartbeat on the red LED
+//!
+//! Usage:
+//! 1. Flash this CM4 (secondary) core binary first
+//! 2. Then flash the CM7 (primary) core binary
+//! 3. The red LED should blink continuously as a heartbeat
+//! 4. Green and yellow LEDs should toggle according to CM7 core signals
+
+/// Module providing shared memory constructs for intercore communication
 mod shared {
     use core::sync::atomic::{AtomicU32, Ordering};
 
-    /// Shared LED state between CM7 and CM4 cores
+    /// State shared between CM7 and CM4 cores for LED control
     #[repr(C, align(4))]
     pub struct SharedLedState {
-        // Magic number for validation
         pub magic: AtomicU32,
-        // Counter for synchronization testing
         pub counter: AtomicU32,
-        // LED states packed into a single atomic
         pub led_states: AtomicU32,
     }
 
@@ -23,19 +37,17 @@ mod shared {
     impl SharedLedState {
         pub const fn new() -> Self {
             Self {
-                magic: AtomicU32::new(0xDEADBEEF), // Magic number
+                magic: AtomicU32::new(0xDEADBEEF),
                 counter: AtomicU32::new(0),
                 led_states: AtomicU32::new(0),
             }
         }
 
-        /// Set LED state using safe bit operations
+        /// Set LED state by manipulating the appropriate bit in the led_states field
         #[inline(never)]
         #[allow(dead_code)]
         pub fn set_led(&self, is_green: bool, state: bool) {
             let bit = if is_green { GREEN_LED_BIT } else { YELLOW_LED_BIT };
-
-            // Use bit operations to avoid complex atomic operations
             let current = self.led_states.load(Ordering::SeqCst);
 
             let new_value = if state {
@@ -48,7 +60,7 @@ mod shared {
             core::sync::atomic::fence(Ordering::SeqCst);
         }
 
-        /// Get LED state using safe bit operations
+        /// Get current LED state
         #[inline(never)]
         pub fn get_led(&self, is_green: bool) -> bool {
             let bit = if is_green { GREEN_LED_BIT } else { YELLOW_LED_BIT };
@@ -59,7 +71,7 @@ mod shared {
             (value & (1 << bit)) != 0
         }
 
-        /// Increment counter safely
+        /// Increment counter and return new value
         #[inline(never)]
         #[allow(dead_code)]
         pub fn increment_counter(&self) -> u32 {
@@ -70,7 +82,7 @@ mod shared {
             new_value
         }
 
-        /// Get counter without incrementing
+        /// Get current counter value
         #[inline(never)]
         pub fn get_counter(&self) -> u32 {
             let value = self.counter.load(Ordering::SeqCst);
@@ -84,19 +96,18 @@ mod shared {
 }
 
 use core::mem::MaybeUninit;
-
 use defmt::*;
 use embassy_executor::Spawner;
 use embassy_stm32::gpio::{Level, Output, Speed};
 use embassy_stm32::SharedData;
 use embassy_time::Timer;
-// Use our shared state from the module
 use shared::SHARED_LED_STATE;
 use {defmt_rtt as _, panic_probe as _};
 
 #[link_section = ".ram_d3"]
 static SHARED_DATA: MaybeUninit<SharedData> = MaybeUninit::uninit();
 
+/// Task that continuously blinks the red LED as a heartbeat indicator
 #[embassy_executor::task]
 async fn blink_heartbeat(mut led: Output<'static>) {
     loop {
@@ -112,11 +123,11 @@ async fn main(spawner: Spawner) -> ! {
     let p = embassy_stm32::init_secondary(&SHARED_DATA);
     info!("CM4 core initialized!");
 
-    // Read the magic value to ensure shared memory is accessible
+    // Verify shared memory is accessible
     let magic = SHARED_LED_STATE.magic.load(core::sync::atomic::Ordering::SeqCst);
     info!("CM4: Magic value = 0x{:X}", magic);
 
-    // Initialize LEDs
+    // Set up LEDs
     let mut green_led = Output::new(p.PB0, Level::Low, Speed::Low); // LD1
     let mut yellow_led = Output::new(p.PE1, Level::Low, Speed::Low); // LD2
     let red_led = Output::new(p.PB14, Level::Low, Speed::Low); // LD3 (heartbeat)
@@ -124,31 +135,30 @@ async fn main(spawner: Spawner) -> ! {
     // Start heartbeat task
     unwrap!(spawner.spawn(blink_heartbeat(red_led)));
 
-    // Previous values for detecting changes
+    // Track previous values to detect changes
     let mut prev_green = false;
     let mut prev_yellow = false;
     let mut prev_counter = 0;
 
     info!("CM4: Starting main loop");
     loop {
-        // Read values from shared memory
+        // Read current values from shared memory
         let green_state = SHARED_LED_STATE.get_led(true);
         let yellow_state = SHARED_LED_STATE.get_led(false);
         let counter = SHARED_LED_STATE.get_counter();
 
-        // Check for state changes
+        // Detect changes
         let green_changed = green_state != prev_green;
         let yellow_changed = yellow_state != prev_yellow;
         let counter_changed = counter != prev_counter;
 
-        // If any state changed, log it and update LEDs
+        // Update LEDs and logs when values change
         if green_changed || yellow_changed || counter_changed {
             if counter_changed {
                 info!("CM4: Counter = {}", counter);
                 prev_counter = counter;
             }
 
-            // Update LED states
             if green_changed {
                 if green_state {
                     green_led.set_high();
@@ -172,7 +182,6 @@ async fn main(spawner: Spawner) -> ! {
             }
         }
 
-        // Poll at a reasonable rate
         Timer::after_millis(10).await;
     }
 }