Struct atsamd_hal::clock::v2::dpll::Dpll

pub struct Dpll<D, I>where
    D: DpllId,
    I: DpllSourceId,{ /* private fields */ }

Digital phase-locked loop used to multiply clock frequencies

A DPLL is used to multiply clock frequencies, taking a lower-frequency input clock and producing a higher-frequency output clock.

The type parameter D is a DpllId that determines which of the two instances this Dpll represents (Dpll0 or Dpll1). The type parameter I represents the Id type for the clock Source driving this Dpll. It must be one of the valid DpllSourceIds. See the clock module documentation for more detail on Id types.

On its own, an instance of Dpll does not represent an enabled DPLL. 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 Dpll and returns an EnabledDpll, 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 a Dpll.

Implementations

impl<D, G> Dpll<D, G>where
    D: DpllId,
    G: GclkId,

pub fn from_pclk(token: DpllToken<D>, pclk: Pclk<D, G>) -> Self

Create a Dpll from a Pclk

Creating a Dpll does not modify any of the hardware registers. It only creates a struct to track the DPLL 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 EnabledDpll is returned. The Dpll is not active or useful until that point.

pub fn free_pclk(self) -> (DpllToken<D>, Pclk<D, G>)

Consume the Dpll, release the DpllToken, and return the Pclk

impl<D, X> Dpll<D, X>where
    D: DpllId,
    X: XoscId + DpllSourceId<Reference<D> = Xosc>,

pub fn from_xosc<S>(token: DpllToken<D>, source: S) -> (Self, S::Inc)where
    S: Source<Id = X> + Increment,

Create a Dpll from an Xosc

Note that, when the Dpll is driven by an Xosc, there is an extra clock divider between the Xosc output and the input to the actual phase-locked loop. This allows the Xosc frequency to be above the maximum DPLL input frequency of 3.2 MHz.

The Xosc pre-divider can be set to any even value in the range [2, 4096]. It defaults to the minimum value of 2, but it can be changed with the Dpll::prediv method.

Creating a Dpll does not modify any of the hardware registers. It only creates a struct to track the DPLL configuration and Increments the Source Enabled counter.

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 EnabledDpll is returned. The Dpll is not active or useful until that point.

pub fn free_xosc<S>(self, source: S) -> (DpllToken<D>, S::Dec)where
    S: Source<Id = X> + Decrement,

Consume the Dpll, release the DpllToken, and Decrement the EnabledXosc consumer count

pub fn prediv(self, prediv: u16) -> Self

Set the Xosc pre-division factor

The Xosc output frequency is divided down before it enters the actual phase-locked loop. This function will panic if the pre-division factor is not an even number in the range [2, 4096].

impl<D: DpllId> Dpll<D, Xosc32kId>

pub fn from_xosc32k<S>(token: DpllToken<D>, source: S) -> (Self, S::Inc)where
    S: Source<Id = Xosc32kId> + Increment,

Create a Dpll from an Xosc32k

Creating a Dpll does not modify any of the hardware registers. It only creates a struct to track the DPLL configuration and Increments the Source Enabled counter.

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 EnabledDpll is returned. The Dpll is not active or useful until that point.

pub fn free_xosc32k<S>(self, source: S) -> (DpllToken<D>, S::Dec)where
    S: Source<Id = Xosc32kId> + Decrement,

Consume the Dpll, release the DpllToken, and Decrement the EnabledXosc32k consumer count

d`] consumer count

impl<D, I> Dpll<D, I>where
    D: DpllId,
    I: DpllSourceId,

pub fn loop_div(self, int: u16, frac: u8) -> Self

Set the Dpll loop divider, which is also the frequency multiplication factor

The inputs to this function are the natural integer and fractional parts of the division factor, i.e. the division factor is:

int + frac / 32

This function will confirm that the int and frac values convert to valid LDR and LDRFRAC register fields, panicking otherwise.

pub fn lock_bypass(self, bypass: bool) -> Self

Bypass the Dpll lock

If true, the Dpll will output its clock regardless of whether it is locked.

pub fn wake_up_fast(self, wuf: bool) -> Self

Output the Dpll clock immediately, without waiting for various conditions

See the datasheet for complete details.

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

Set on-demand mode

See the datasheet for complete details.

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

Set run-in-standby mode

See the datasheet for complete details.

pub fn freq(&self) -> Hertz

Return the output frequency of the Dpll

pub fn enable(self) -> EnabledDpll<D, I>

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

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

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

Panics

This function will also check that the input and output clock frequencies fall within the valid ranges specified in the datasheet. Specifically, the input frequency must be between 32 kHz and 3.2 MHz, while the output frequency must be between 96 MHz and 200 MHz. If either frequency is invalid, this call will panic.

pub fn enable_unchecked(self) -> EnabledDpll<D, I>

Enable the Dpll without validating the input & output frequencies

This is equivalent to calling Dpll::enable but without the checks on input and output frequencies. Using frequencies outside the ranges specified in the datasheet may not work and could cause clocking problems.