Add hardware initialization module

Implement bootloader/src/init.rs with:

- BootHardware struct to represent initialized system state
- InitError enum and Result type for robust error handling
- init_hardware() entry point to configure clocks, flash,
  and essential peripherals
- Feature-flag stubs for MCU families (e.g. stm32f4, nrf52)
- Helper functions for flash interface, peripherals, and
  system clock frequency
- Basic unit test validating default initialization

Provides a clean, MCU-agnostic starting point for setting up
bootloader hardware and is ready for platform-specific logic.

Author: m-a-h-b-u-b

bootloader/src/init.rs

@@ -1,4 +1,4 @@
-//! M2 Bootloader RUST 
+//! M2 Bootloader RUST
 //! ------------------
 //! License : Dual License
 //!           - Apache 2.0 for open-source / personal use
@@ -7,6 +7,135 @@
 //! URL     : <https://m-a-h-b-u-b.github.io>
 //! GitHub  : <https://github.com/m-a-h-b-u-b/M2-Bootloader-RUST>
 
-pub fn init_hardware() {
-    // Initialize clocks, watchdog, GPIO pins
-}
+//! Hardware initialization module.
+//!
+//! This module provides a high-level abstraction for initializing the
+//! microcontroller hardware required by the bootloader. It prepares the
+//! system clock, flash interface, and any peripherals (UART/USB) used for
+//! firmware updates. The implementation is MCU-agnostic with hooks for
+//! specific hardware families via feature flags.
+
+use core::fmt;
+
+/// Boot error types returned during hardware initialization.
+#[derive(Debug)]
+pub enum InitError {
+    ClockConfig,
+    FlashConfig,
+    PeripheralInit,
+    Other(&'static str),
+}
+
+impl fmt::Display for InitError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            InitError::ClockConfig => write!(f, "Clock configuration failed"),
+            InitError::FlashConfig => write!(f, "Flash interface configuration failed"),
+            InitError::PeripheralInit => write!(f, "Peripheral initialization failed"),
+            InitError::Other(msg) => write!(f, "Other init error: {}", msg),
+        }
+    }
+}
+
+/// Result type for hardware initialization.
+pub type Result<T> = core::result::Result<T, InitError>;
+
+/// Represents the bootloader hardware state.
+/// In a real implementation this may hold MCU-specific peripherals or handles.
+pub struct BootHardware {
+    pub clock_speed_hz: u32,
+    pub flash_ready: bool,
+    pub peripherals_ready: bool,
+}
+
+impl BootHardware {
+    /// Create a new BootHardware instance with default placeholders.
+    pub const fn new() -> Self {
+        BootHardware {
+            clock_speed_hz: 0,
+            flash_ready: false,
+            peripherals_ready: false,
+        }
+    }
+}
+
+/// Initialize all hardware required for the bootloader.
+///
+/// This function should:
+/// - Configure the system clock.
+/// - Enable and configure the flash memory interface.
+/// - Initialize essential peripherals (UART/USB) for communication.
+///
+/// Feature flags can be used to include MCU-specific implementations.
+/// For example:
+/// ```toml
+/// [features]
+/// stm32f4 = []
+/// nrf52 = []
+/// ```
+///
+/// # Safety
+/// Must be called once at system start before other hardware access.
+pub fn init_hardware() -> Result<BootHardware> {
+    // System clock configuration placeholder.
+    #[cfg(feature = "stm32f4")]
+    stm32f4_clock_setup()?;
+    #[cfg(feature = "nrf52")]
+    nrf52_clock_setup()?;
+
+    // Flash interface setup placeholder.
+    flash_interface_setup()?;
+
+    // Peripheral setup placeholder (UART/USB, etc.).
+    peripherals_setup()?;
+
+    Ok(BootHardware {
+        clock_speed_hz: system_clock_hz(),
+        flash_ready: true,
+        peripherals_ready: true,
+    })
+}
+
+// Below are dummy stubs for platform-specific implementations.
+// Replace with actual HAL or register-level code.
+#[cfg(feature = "stm32f4")]
+fn stm32f4_clock_setup() -> Result<()> {
+    // TODO: configure PLL, flash wait states, bus prescalers, etc.
+    Ok(())
+}
+
+#[cfg(feature = "nrf52")]
+fn nrf52_clock_setup() -> Result<()> {
+    // TODO: enable HFCLK and set correct source.
+    Ok(())
+}
+
+fn flash_interface_setup() -> Result<()> {
+    // TODO: configure flash wait states, caches, or unlock sequences.
+    Ok(())
+}
+
+fn peripherals_setup() -> Result<()> {
+    // TODO: initialize UART/USB or other communication peripherals.
+    Ok(())
+}
+
+/// Query the configured system clock frequency (in Hz).
+/// Replace with MCU-specific readback.
+fn system_clock_hz() -> u32 {
+    // Example placeholder: 48 MHz.
+    48_000_000
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_init_hardware_success() {
+        let hw = init_hardware().unwrap();
+        assert!(hw.flash_ready);
+        assert!(hw.peripherals_ready);
+        assert_eq!(hw.clock_speed_hz, 48_000_000);
+    }
+}