Struct Xosc

pub struct Xosc<X, M>
where
    X: XoscId,
    M: Mode,
{ /* private fields */ }

An external multipurpose crystal oscillator controller

An Xosc interfaces with either an external clock or external crystal oscillator and delivers the resulting clock to the rest of the clock system.

The type parameter X is a XoscId that determines which of the two instances this Xosc represents (Xosc0 or Xosc1). The type parameter M represents the operating Mode, either ClockMode or CrystalMode.

On its own, an instance of Xosc does not represent an enabled XOSC. Instead, it must first be wrapped with Enabled, which implements compile-time safety of the clock tree.

Because the terminal call to enable consumes the Xosc and returns an EnabledXosc, the remaining API uses the builder pattern, where each method takes and returns self by value, allowing them to be easily chained.

See the module-level documentation for an example of creating, configuring and using an Xosc.

Implementations

impl<X: XoscId> Xosc<X, ClockMode>

pub fn from_clock( token: XoscToken<X>, xin: impl Into<XIn<X>>, freq: impl Into<Hertz>, ) -> Self

Create an Xosc from an external clock, taking ownership of the XIn Pin

Creating a Xosc does not modify any of the hardware registers. It only creates a struct to track the configuration. The configuration data is stored until the user calls enable. At that point, all of the registers are written according to the initialization procedures specified in the datasheet, and an EnabledXosc is returned. The Xosc is not active or useful until that point.

pub fn free(self) -> (XoscToken<X>, XIn<X>)

Consume the Xosc and release the XoscToken and XIn Pin

impl<X: XoscId> Xosc<X, CrystalMode>

pub fn from_crystal( token: XoscToken<X>, xin: impl Into<XIn<X>>, xout: impl Into<XOut<X>>, freq: impl Into<Hertz>, ) -> Self

Create an Xosc from an external crystal oscillator, taking ownership of the XIn and XOut Pins.

Creating a Xosc does not modify any of the hardware registers. It only creates a struct to track the configuration. The configuration data is stored until the user calls enable. At that point, all of the registers are written according to the initialization procedures specified in the datasheet, and an EnabledXosc is returned. The Xosc is not active or useful until that point.

pub fn free(self) -> (XoscToken<X>, XIn<X>, XOut<X>)

Consume the Xosc and release the XoscToken, XIn and XOut Pins

pub fn current(self, current: CrystalCurrent) -> Self

Set the CrystalCurrent drive strength

pub fn loop_control(self, loop_control: bool) -> Self

Toggle automatic loop control

If enabled, the hardware will automatically adjust the oscillator amplitude. In most cases, this will lower power consumption.

pub fn low_buf_gain(self, low_buf_gain: bool) -> Self

Modify the oscillator amplitude when automatic loop control is enabled

The datasheet name for this setting is very misleading. When automatic loop control is enabled, setting the LOWBUFGAIN field to 1 will increase the oscillator amplitude by a factor of appoximately 2. This can help solve stability issues.

impl<X, M> Xosc<X, M>

where X: XoscId, M: Mode,

pub fn freq(&self) -> Hertz

Return the clock or crystal frequency

pub fn start_up_delay(self, delay: StartUpDelay) -> Self

Set the start up delay before the Xosc is unmasked and continuously monitored

During the start up period, the Xosc is masked to prevent clock instability from propagating to the digital logic. During this time, clock failure detection is disabled.

pub fn on_demand(self, on_demand: bool) -> Self

Control the Xosc on-demand behavior

When the on-demand is enabled, the Xosc will only run in Idle or Standby sleep modes if it is requested by a peripheral. Otherwise, its behavior is dependent on the run-standby setting.

pub fn run_standby(self, run_standby: bool) -> Self

Control the Xosc behavior in Standby sleep mode

When RUNSTDBY is disabled, the Xosc will never run in Standby sleep mode unless ONDEMAND is enabled and the Xosc is requested by a peripheral. When RUNSTDBY is enabled, the Xosc will run in Standby sleep mode, but it can still be disabled if ONDEMAND is enabled and the Xosc is not requested.

pub fn enable(self) -> EnabledXosc<X, M>

Enable the Xosc, so that it can be used as a clock Source

As mentioned when creating a new Xosc, no hardware registers are actually modified until this call. Rather, the desired configuration is stored internally, and the Xosc is initialized and configured here according to the datasheet.

The returned value is an EnabledXosc that can be used as a clock Source for other clocks.