Cleanups, docs

1 files changed, 70 insertions, 18 deletions

diff --git a/embassy-mcxa/src/clocks/config.rs b/embassy-mcxa/src/clocks/config.rs
index 3f1729d00..4beca5f27 100644
--- a/embassy-mcxa/src/clocks/config.rs
+++ b/embassy-mcxa/src/clocks/config.rs
@@ -136,7 +136,7 @@ pub enum SoscMode {
     ActiveClock,
 }
 
-// SOSC/clk_in configuration
+/// SOSC/clk_in configuration
 #[derive(Copy, Clone)]
 pub struct SoscConfig {
     /// Mode of the external reference clock
@@ -149,22 +149,23 @@ pub struct SoscConfig {
 
 // SPLL
 
-// Fin: 32kHz to 150MHz
-// Fcco: 275MHz to 550MHz
-// Fout: 4.3MHz to 2x Max CPU Frequency
-
+/// PLL1/SPLL configuration
 pub struct SpllConfig {
+    /// Input clock source for the PLL1/SPLL
     pub source: SpllSource,
+    /// Mode of operation for the PLL1/SPLL
     pub mode: SpllMode,
+    /// Power state of the SPLL
     pub power: PoweredClock,
     /// Is the "pll1_clk_div" clock enabled?
     pub pll1_clk_div: Option<Div8>,
 }
 
+/// Input clock source for the PLL1/SPLL
 pub enum SpllSource {
-    /// External Oscillator (8-50M)
+    /// External Oscillator (8-50MHz)
     Sosc,
-    /// Fast Internal Oscillator (45M)
+    /// Fast Internal Oscillator (45MHz)
     // NOTE: Figure 69 says "firc_45mhz"/"clk_45m", not "fro_hf_gated",
     // so this is is always 45MHz.
     Firc,
@@ -173,32 +174,83 @@ pub enum SpllSource {
     // TODO: the reference manual hints that ROSC is possible,
     // however the minimum input frequency is 32K, but ROSC is 16K.
     // Some diagrams show this option, and some diagrams omit it.
+    // SVD shows it as "reserved".
     //
     // /// Realtime Internal Oscillator (16K Osc)
     // Rosc,
 }
 
-/// N: 1..=255
-/// M: 1..=65535
-/// P: 1..=31
+/// Mode of operation for the SPLL/PLL1
+///
+/// NOTE: Currently, only "Mode 1" normal operational modes are implemented,
+/// as described in the Reference Manual.
+#[non_exhaustive]
 pub enum SpllMode {
-    /// Fout = M x Fin
-    Mode1a { m_mult: u16 },
-    /// if !bypass_p2_div: Fout = (M / (2 x P)) x Fin
-    /// if  bypass_p2_div: Fout = (M /    P   ) x Fin
+    /// Mode 1a does not use the Pre/Post dividers.
+    ///
+    /// `Fout = m_mult x SpllSource`
+    ///
+    /// Both of the following constraints must be met:
+    ///
+    /// * Fout: 275MHz to 550MHz
+    /// * Fout: 4.3MHz to 2x Max CPU Frequency
+    Mode1a {
+        /// PLL Multiplier. Must be in the range 1..=65535.
+        m_mult: u16,
+    },
+
+    /// Mode 1b does not use the Pre-divider.
+    ///
+    /// * `if !bypass_p2_div: Fout = (M / (2 x P)) x Fin`
+    /// * `if  bypass_p2_div: Fout = (M /    P   ) x Fin`
+    ///
+    /// Both of the following constraints must be met:
+    ///
+    /// * Fcco: 275MHz to 550MHz
+    ///   * `Fcco = m_mult x SpllSource`
+    /// * Fout: 4.3MHz to 2x Max CPU Frequency
     Mode1b {
+        /// PLL Multiplier. `m_mult` must be in the range 1..=65535.
         m_mult: u16,
+        /// Post Divider. `p_div` must be in the range 1..=31.
         p_div: u8,
+        /// Bonus post divider
         bypass_p2_div: bool,
     },
-    /// Fout = (M / N) x Fin
-    Mode1c { m_mult: u16, n_div: u8 },
-    /// if !bypass_p2_div: Fout = (M / (N x 2 x P)) x Fin
-    /// if  bypass_p2_div: Fout = (M / (  N x P  )) x Fin
+
+    /// Mode 1c does use the Pre-divider, but does not use the Post-divider
+    ///
+    /// `Fout = (M / N) x Fin`
+    ///
+    /// Both of the following constraints must be met:
+    ///
+    /// * Fout: 275MHz to 550MHz
+    /// * Fout: 4.3MHz to 2x Max CPU Frequency
+    Mode1c {
+        /// PLL Multiplier. `m_mult` must be in the range 1..=65535.
+        m_mult: u16,
+        /// Pre Divider. `n_div` must be in the range 1..=255.
+        n_div: u8,
+    },
+
+    /// Mode 1b uses both the Pre and Post dividers.
+    ///
+    /// * `if !bypass_p2_div: Fout = (M / (N x 2 x P)) x Fin`
+    /// * `if  bypass_p2_div: Fout = (M / (  N x P  )) x Fin`
+    ///
+    /// Both of the following constraints must be met:
+    ///
+    /// * Fcco: 275MHz to 550MHz
+    ///   * `Fcco = (m_mult x SpllSource) / (n_div x p_div (x 2))`
+    /// * Fout: 4.3MHz to 2x Max CPU Frequency
     Mode1d {
+        /// PLL Multiplier. `m_mult` must be in the range 1..=65535.
         m_mult: u16,
+        /// Pre Divider. `n_div` must be in the range 1..=255.
         n_div: u8,
+        /// Post Divider. `p_div` must be in the range 1..=31.
         p_div: u8,
+        /// Bonus post divider
         bypass_p2_div: bool,
     },
 }