Struct atsamd_hal::clock::v2::gclk::Gclk

pub struct Gclk<G, I>where
    G: GclkId,
    I: GclkSourceId,{ /* private fields */ }

Generic clock generator used to distribute clocks to various peripherals

A generic clock generator acts as a branch in the clock tree. It can connect a root or branch clock to other branch or leaf clocks. In particular, all peripheral Pclks must be derived from a Gclk.

The type parameter G is a GclkId that determines which of the 12 generators this Gclk represents (Gclk0 - Gclk11). The type parameter I represents the Id type for the clock Source driving this Gclk. It must be one of the valid GclkSourceIds. Alternatively, if the Gclk is driven by a GPIO Pin, then I is a PinId implementing GclkIo. See the clock module documentation for more detail on Id types.

On its own, an instance of Gclk does not represent an enabled clock generator. 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 Gclk and returns an EnabledGclk, 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 Gclk.

Implementations

impl<G, I> Gclk<G, I>where
    G: GclkId,
    I: GclkIo<GclkId = G>,

pub fn from_pin<P>(token: GclkToken<G>, pin: P, freq: impl Into<Hertz>) -> Selfwhere
    P: AnyPin<Id = I>,

Create a new Gclk from a GPIO Pin

Creating a Gclk does not modify any of the hardware registers. It only serves to consume the Pin and create a struct to track the GCLK 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 EnabledGclk is returned. The Gclk is not active or useful until that point.

pub fn free_pin(self) -> (GclkToken<G>, Pin<I, AlternateM>)

Consume the Gclk and free its corresponding resources

Freeing a Gclk returns the corresponding GclkToken and GPIO Pin.

impl<G, I> Gclk<G, I>where
    G: GclkId,
    I: NotGclkIo,

pub fn from_source<S>(token: GclkToken<G>, source: S) -> (Gclk<G, I>, S::Inc)where
    S: Source<Id = I> + Increment,

Create a new Gclk from a clock Source

Creating a Gclk does not modify any of the hardware registers. It only serves to Increment the Source’s Enabled counter and create a struct to track the GCLK 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 EnabledGclk is returned. The Gclk is not active or useful until that point.

pub fn free_source<S>(self, source: S) -> (GclkToken<G>, S::Dec)where
    S: Source<Id = I> + Decrement,

Consume the Gclk and free its corresponding resources

Freeing a Gclk returns the corresponding GclkToken and Decrements the Source’s Enabled counter.

impl<G, I> Gclk<G, I>where
    G: GclkId,
    I: GclkSourceId,

pub fn div(self, div: G::Divider) -> Self

Set the GclkDivider value

Set the clock division factor from input to output. This takes either a GclkDiv8 or GclkDiv16 enum, restricting the possible division factors to only the valid ones for the given Gclk. See the GclkDivider trait for more details.

pub fn improve_duty_cycle(self, flag: bool) -> Self

Output a 50-50 duty cycle clock when using an odd GclkDivider

pub fn freq(&self) -> Hertz

Return the Gclk ouput frequency

This is the input frequency divided by the GclkDivider.

pub fn output_off_value(self, high: bool) -> Self

Set the state of GclkOut pins when GclkIo output is disabled

The output off value (OOV) determines the logic level of a GPIO Pin (configured as a GclkIo output) when the Gclk is disabled OR the GclkOut is disabled.

As mentioned in the Gclk documentation, configuration options are not usually applied until the call to Gclk::enable. However, because the OOV is relevant when the Gclk is disabled, we make an exception. When calling this function, the new OOV will take effect immediately.

However, remember that the Pin is not controlled by the Gclk unless the Pin is configured in AlternateM mode. Pins are automatically set to AlternateM mode when calling enable_gclk_out, but by that point, the OOV is irrelevant. If you need the Pin to be set to its OOV, you must manually set it to AlternateM mode before constructing the GclkOut.

pub fn enable(self) -> EnabledGclk<G, I>

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

As mentioned in the Gclk documentation, no hardware registers are actually modified until this call. Rather, the desired configuration is stored internally, and the Gclk is initialized and configured here according to the datasheet.

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