Struct atsamd_hal::clock::v2::dfll::Dfll

pub struct Dfll<M: Mode = OpenLoop> { /* private fields */ }

Digital frequency-locked loop used to generate a 48 MHz clock

The DFLL generates a 48 MHz clock in two different possible Modes. In OpenLoop Mode, it generates the output clock from an internal oscillator, while in the two closed-loop Modes, it multiplies a low-frequency Reference clock.

On its own, the Dfll type does not represent the enabled DFLL. 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 Dfll and returns an EnabledDfll, 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 the Dfll.

Implementations

impl Dfll

pub fn open_loop(token: DfllToken) -> Self

Create the Dfll in open-loop mode

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

pub fn free(self) -> DfllToken

Consume the Dfll and release the DfllToken

impl Dfll<FromUsb>

pub fn from_usb(token: DfllToken) -> Self

Create the Dfll in USB recovery mode

This creates the Dfll in closed-loop mode referenced to the USB start-of-frame signal. For now, this function does not require any proof of a functioning USB interface. Future versions of this function may take ownership of some resource both to prove USB has been setup correctly and to prevent modification while in use.

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

pub fn free(self) -> DfllToken

Consume the Dfll and release the DfllToken

impl<G: GclkId> Dfll<FromPclk<G>>

pub fn from_pclk(token: DfllToken, pclk: Pclk<DfllId, G>) -> Self

Create the Dfll in closed-loop mode

This creates the Dfll in closed-loop mode referenced to a Gclk through a Pclk. It will also auto-calculate the correct multiplication factor to best yield 48 MHz at the output.

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

Panics

According to the datasheet, the Pclk frequency must be between 732 Hz and 33 kHz. This function will perform a run-time check of the input frequency and panic if it is out of range. To use a Pclk frequency outside this range or to force a particular multiplication factor, use Dfll::from_pclk_unchecked.

pub fn from_pclk_unchecked(
    token: DfllToken,
    pclk: Pclk<DfllId, G>,
    mult_factor: u16
) -> Self

Create the Dfll in closed-loop mode

This constructor behaves identically to Dfll::from_pclk, but it skips the run-time check of the Pclk frequency and does not auto-calculate the multiplication factor.

pub fn free(self) -> (DfllToken, Pclk<DfllId, G>)

Consume the Dfll, release the DfllToken, and return the Pclk

pub fn set_chill_cycle(&mut self, value: bool)

Enable or disable the Dfll chill cycle

See the documentation of chill_cycle for more details.

pub fn chill_cycle(self, value: bool) -> Self

Enable or disable the Dfll chill cycle

When operating in closed-loop mode with small multiplication factors, the DFLL can sometimes have trouble locking. To avoid this, the hardware normally implements a chill cycle, during which the output frequency is not measured. The chill cycle is enabled by default, but it can be disabled to reduce the duration before lock. See the datasheet for more details.

pub fn set_quick_lock(&mut self, value: bool)

Enable or disable the Dfll quick lock

See the documentation of quick_lock for more details.

pub fn quick_lock(self, value: bool) -> Self

Enable or disable the Dfll quick lock

By default, the DFLL locking requirements are somewhat loose. Users can tighten these requirements by disabling the quick lock feature, which is enabled by default. See the datasheet for more details.

impl<R: Reference> Dfll<R>

pub fn set_coarse_max_step(&mut self, coarse_max_step: u8)

Set the maximum coarse step size during closed-loop frequency tuning

See the documentation of coarse_max_step for more details.

pub fn coarse_max_step(self, coarse_max_step: u8) -> Self

Set the maximum coarse step size during closed-loop frequency tuning

In closed-loop operation, the DFLL output frequency is continuously regulated against the reference clock by adjusting the coarse and fine tuning parameters. This function sets a maximum step size for the coarse tuning parameter.

In general, a small step size will ensure low overshoot in the output frequency, but it will lengthen the time to lock. A larger step size will produce more overshoot but will be quicker to lock. See the datasheet for more details.

pub fn set_fine_max_step(&mut self, fine_max_step: u8)

Set the maximum fine step size during closed-loop frequency tuning

See the documentation of fine_max_step for more details.

pub fn fine_max_step(self, fine_max_step: u8) -> Self

Set the maximum fine step size during closed-loop frequency tuning

In closed-loop operation, the DFLL output frequency is continuously regulated against the reference clock by adjusting the coarse and fine tuning parameters. This function sets a maximum step size for the fine tuning parameter.

In general, a small step size will ensure low overshoot in the output frequency, but it will lengthen the time to lock. A larger step size will produce more overshoot but will be quicker to lock. See the datasheet for more details.

impl<M: Mode> Dfll<M>

pub fn freq(&self) -> Hertz

Return the Dfll output frequency

The output frequency will always be close to, if not exactly, 48 MHz.

pub fn set_run_standby(&mut self, value: bool)

Control the Dfll behavior during idle or standby sleep modes

See the documentation of run_standby for more details.

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

Control the Dfll behavior during idle or standby sleep modes

When true, the Dfll will run in standby sleep mode, but its behavior can still be modified by the on-demand setting. See the datasheet for more details.

pub fn set_on_demand(&mut self, value: bool)

Control the Dfll on-demand functionality

See the documentation of on_demand for more details.

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

Control the Dfll on-demand functionality

When true, only run the clock when requested by peripheral. If false the clock will be always active. This setting will also modify the behavior in standby sleep modes. See the datasheet for more details.

pub fn enable(self) -> EnabledDfll<M>

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

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

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