From 13b5aa06f146263b6ed1eb985ce54ed8d9599d62 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gabriel=20G=C3=B3rski?= Date: Thu, 9 Sep 2021 18:31:16 +0200 Subject: [PATCH] Xosc32k: Add documentation; (Osculp32k: typo) --- hal/src/thumbv7em/clock/v2/osculp32k.rs | 2 +- hal/src/thumbv7em/clock/v2/xosc32k.rs | 60 +++++++++++++++---------- 2 files changed, 38 insertions(+), 24 deletions(-) diff --git a/hal/src/thumbv7em/clock/v2/osculp32k.rs b/hal/src/thumbv7em/clock/v2/osculp32k.rs index 5c82d2910d85..2405cd99b2e5 100644 --- a/hal/src/thumbv7em/clock/v2/osculp32k.rs +++ b/hal/src/thumbv7em/clock/v2/osculp32k.rs @@ -48,7 +48,7 @@ pub struct OscUlp32kToken { } impl OscUlp32kToken { - /// Create a new instance of [`Xosc32kToken`] + /// Create a new instance of [`OscUlp32kToken`] #[inline] pub(crate) unsafe fn new() -> Self { Self { __: () } diff --git a/hal/src/thumbv7em/clock/v2/xosc32k.rs b/hal/src/thumbv7em/clock/v2/xosc32k.rs index b7b9c9dc2fa9..51f4192ff9b9 100644 --- a/hal/src/thumbv7em/clock/v2/xosc32k.rs +++ b/hal/src/thumbv7em/clock/v2/xosc32k.rs @@ -1,5 +1,5 @@ -//! # Xosc32k - External Oscillator 32 kHz -//! TODO +#![deny(missing_docs)] +//! # Xosc32k - External 32 kHz oscillator //! //! Provides 32 kHz outputs for [`gclk`][super::gclk]s, [`rtc`][super::rtc] //! and [`dpll`][super::dpll]. @@ -35,13 +35,17 @@ use crate::typelevel::Sealed; // Xosc32kToken //============================================================================== -pub struct Xosc32kToken; +/// Token struct that is essential in order to construct an instance of an +/// [`Xosc32k`]. +pub struct Xosc32kToken { + __: (), +} impl Xosc32kToken { /// Create a new instance of [`Xosc32kToken`] #[inline] pub(super) unsafe fn new() -> Self { - Self + Self { __: () } } #[inline] @@ -142,12 +146,20 @@ pub type XOut32 = Pin; // Mode structure for Xosc32k //============================================================================== +/// Trait that defines a mode [`Xosc32k`] is operating in pub trait Mode: Sealed {} +/// Struct representing a clock mode for [`Xosc32k`] +/// +/// In that mode [`Xosc32k`] requires a single clocking signal pub struct ClockMode {} impl Mode for ClockMode {} impl Sealed for ClockMode {} +/// Struct representing a crystal mode for [`Xosc32k`] +/// +/// In that mode [`Xosc32k`] requires two signals coming from an external +/// crystal pub struct CrystalMode { xout32: XOut32, /// Control external crystal tuning @@ -160,6 +172,12 @@ impl Sealed for CrystalMode {} // Xosc32k //============================================================================== +/// Struct representing a disabled external oscillator +/// +/// It is generic over: +/// - a mode (crystal or clock mode) +/// - An output state of a 32 kHz signal (active/inactive) +/// - An output state of a 1 kHz signal (active/inactive) pub struct Xosc32k where M: Mode, @@ -189,14 +207,14 @@ where self } - /// Controls how Xosc32k behaves when a peripheral clock request is detected + /// Controls how [`Xosc32k`] behaves when a peripheral clock request is detected #[inline] pub fn set_on_demand(mut self, on_demand: bool) -> Self { self.on_demand_mode = on_demand; self } - /// Controls how Xosc32k should behave during standby + /// Controls how [`Xosc32k`] should behave during standby #[inline] pub fn set_run_standby(mut self, run_standby: bool) -> Self { self.run_standby = run_standby; @@ -210,7 +228,7 @@ where } impl Xosc32k { - /// Construct a Xosc32k from a single pin oscillator clock signal + /// Construct a [`Xosc32k`] from a single pin oscillator clock signal #[inline] pub fn from_clock(token: Xosc32kToken, xin32: impl AnyPin) -> Self { // Configure input pin @@ -227,11 +245,10 @@ impl Xosc32k { } } - /// Enable the Xosc32k, allowing it to be used by other peripherals + /// Enable the [`Xosc32k`], allowing it to be used by other peripherals /// /// To output a 32 kHz clock signal the output must be activated with /// the method: [`Enabled::activate_32k`] - /// #[inline] pub fn enable(mut self) -> Enabled { self.token.from_clock(); @@ -248,7 +265,7 @@ where X: Output32k, Y: Output1k, { - /// Deconstruct the Xosc32k into a Xosc32kToken and the associated GPIO pin + /// Deconstruct the [`Xosc32k`] into a Xosc32kToken and the associated GPIO pin #[inline] pub fn free(self) -> (Xosc32kToken, XIn32) { (self.token, self.xin32) @@ -256,7 +273,7 @@ where } impl Xosc32k { - /// Construct a Xosc32k from a two pin crystal oscillator signal + /// Construct a [`Xosc32k`] from a two pin crystal oscillator signal #[inline] pub fn from_crystal( token: Xosc32kToken, @@ -292,7 +309,7 @@ impl Xosc32k { self } - /// Enable the Xosc32k, allowing it to be used by other peripherals + /// Enable the [`Xosc32k`], allowing it to be used by other peripherals /// /// To output a 32 kHz clock signal the output must be activated with /// the method: [`Enabled::activate_32k`] @@ -315,7 +332,8 @@ where X: Output32k, Y: Output1k, { - /// Deconstruct the Xosc32k into a Xosc32kToken and the two associated GPIO pins + /// Deconstruct the [`Xosc32k`] into a Xosc32kToken and the two associated GPIO + /// pins #[inline] pub fn free(self) -> (Xosc32kToken, XIn32, XOut32) { (self.token, self.xin32, self.mode.xout32) @@ -327,7 +345,7 @@ where M: Mode, Y: Output1k, { - /// Enable the output of 32 kHz clock + /// Activate the 32 kHz signal output #[inline] pub fn activate_32k(mut self) -> Enabled, U0> { self.0.token.activate_32k(true); @@ -350,7 +368,7 @@ where M: Mode, Y: Output1k, { - /// Disable the output of 32 kHz clock + /// Deactivate the 32 kHz signal output #[inline] pub fn deactivate_32k(mut self) -> Enabled, U0> { self.0.token.activate_32k(false); @@ -373,7 +391,7 @@ where M: Mode, X: Output32k, { - /// Enable the output of 1 kHz (1024 Hz) clock + /// Activate the 1 kHz signal output /// /// Used by RTC only #[inline] @@ -398,7 +416,7 @@ where M: Mode, X: Output32k, { - /// Disable the output of 1 kHz (1024 Hz) clock + /// Deactivate the 1 kHz signal output /// /// Used by RTC only #[inline] @@ -424,12 +442,7 @@ where X: Output32k, Y: Output1k, { - /// Disable the enabled Xosc32k - /// - /// Only possible with no users - /// - /// This allows changing the configuration or retrieving the Xosc32kToken - /// and GPIO pin + /// Disable the enabled [`Xosc32k`] #[inline] pub fn disable(mut self) -> Xosc32k { self.0.token.activate_32k(false); @@ -443,6 +456,7 @@ where // GclkSource //============================================================================== +/// A marker type. More information at [`SourceMarker`] documentation entry pub enum Osc32k {} impl Sealed for Osc32k {}