Module atsamd_hal::clock::v2::gclk

Expand description

The generic clock controller is central to the clocking system in ATSAMD chips. It provides 12 generic clock generators to modify and distribute clocks to other peripherals. Within the clock tree, these clock generators act as the branch clocks, connecting internal or external root or branch clocks to other branch or leaf clocks.

Each clock generator takes an input clock, optionally divides it, and produces an output clock. The input clock can be:

A GPIO input (Pin)
An external crystal oscillator (Xosc)
An external 32 kHz oscillator (Xosc32k)
The ultra-low power 32 kHz oscillator (OscUlp32k)
The 48 MHz DFLL (Dfll)
A DPLL (Dpll)
Generic clock generator #1 (Gclk1)

The output clock can be:

A peripheral channel clock (Pclk)
A GPIO pin (GclkOut)

Example

The configuration of a Gclk is best shown with an example. However, the example assumes you are already familiar with the basics of the clock module. See the clock module documentation for an overview.

Suppose we start with the default clock tree after power-on reset.

DFLL (48 MHz)
└── GCLK0 (48 MHz)
    └── Main clock (48 MHz)

We would like to transform it to a clock tree like this:

DFLL (48 MHz)
└── GCLK0 (48 MHz)
    └── Main clock (48 MHz)

GCLK_IN1 (PB14, 24 MHz)
└── GCLK1 (12 MHz)
    ├── SERCOM0
    └── GCLK2 (3 MHz)
        ├── SERCOM1
        └── GCLK_OUT2 (PA16, 3 MHz)

Let’s start by using clock_system_at_reset to access the HAL clocking structs. We will also need access to the gpio Pins.

use atsamd_hal::{
    clock::v2::{
        clock_system_at_reset,
        gclk::{Gclk, GclkDiv8, GclkDiv16},
        pclk::Pclk,
    },
    gpio::Pins,
    pac::Peripherals,
    time::U32Ext,
};
let mut pac = Peripherals::take().unwrap();
let (mut buses, clocks, tokens) = clock_system_at_reset(
    pac.OSCCTRL,
    pac.OSC32KCTRL,
    pac.GCLK,
    pac.MCLK,
    &mut pac.NVMCTRL,
);
let pins = Pins::new(pac.PORT);

Next, we use Gclk::from_pin to create a Gclk from a GclkToken, GPIO Pin and frequency, in Hertz. In this case, we create an instance of Gclk1.

At this point, notice that Gclk<G, I> takes two type parameters. G is a GclkId identifying which of the 12 generators this Gclk represents. Gclk1<I> is simply an alias for Gclk<Gclk1Id, I>. I is an Id type identifying the input clock, which must be a valid GclkSourceId. In this case, I is PB14, which is a GclkSourceId for Gclk1, because it implements GclkIo with GclkIo::GclkId = Gclk1Id.

let gclk1 = Gclk::from_pin(tokens.gclks.gclk1, pins.pb15, 24.mhz());

While we have created a Gclk, we have not yet enabled it. But before doing so, we would like to set the divider to reduce the input frequency of 24 MHz to a 12 MHz output. We call Gclk::div, which uses a builder API, so that it can be chained with the call to Gclk::enable.

let gclk1 = gclk1.div(GclkDiv16::Div(2)).enable();

Note that the divider value supplied to Gclk::div must be wrapped by the GclkDiv16 enum. This is for a few different reasons. First, Gclk1 accepts a wider range of divider values than the other Gclks, which use GclkDiv8 instead. Second, the actual divider value is controlled by two register fields, and the set of valid values is best expressed as a Rust enum. The GclkDiv8 and GclkDiv16 enums are connected by the GclkDivider trait.

Once Gclk1 is enabled, we can use it to enable the Pclk for Sercom0. This follows the usual pattern. We provide a PclkToken and the EnabledGclk1. In return, we get an enabled Pclk and the EnabledGclk1 counter is Incremented.

let (pclk_sercom0, gclk1) = Pclk::enable(tokens.pclks.sercom0, gclk1);

Next, we use Gclk1 as a clock Source to create an instance of Gclk2 with Gclk::from_source. However, keep in mind that this is only true for Gclk1. No other Gclk can act as a Source for another Gclk.

let (gclk2, gclk1) = Gclk::from_source(tokens.gclks.gclk2, gclk1);

The pattern repeats now. We divide Gclk1 by 4 to produce the Gclk2 output. Then we enable it to produce an EnabledGclk2 and use it to yield another Pclk.

let gclk2 = gclk2.div(GclkDiv8::Div(4)).enable();
let (pclk_sercom1, gclk2) = Pclk::enable(tokens.pclks.sercom1, gclk2);

Finally, we output Gclk2 directly to a GPIO pin. We supply the GPIO Pin to the EnabledGclk2 to yield a GclkOut.

let (gclk2, gclk2_out) = gclk2.enable_gclk_out(pins.pa16);

The full example is provided below.

use atsamd_hal::{
    clock::v2::{
        clock_system_at_reset,
        gclk::{Gclk, GclkDiv8, GclkDiv16},
        pclk::Pclk,
    },
    gpio::Pins,
    pac::Peripherals,
    time::U32Ext,
};
let mut pac = Peripherals::take().unwrap();
let (mut buses, clocks, tokens) = clock_system_at_reset(
    pac.OSCCTRL,
    pac.OSC32KCTRL,
    pac.GCLK,
    pac.MCLK,
    &mut pac.NVMCTRL,
);
let pins = Pins::new(pac.PORT);
let gclk1 = Gclk::from_pin(tokens.gclks.gclk1, pins.pb15, 24.mhz());
let gclk1 = gclk1.div(GclkDiv16::Div(2)).enable();
let (pclk_sercom0, gclk1) = Pclk::enable(tokens.pclks.sercom0, gclk1);
let (gclk2, gclk1) = Gclk::from_source(tokens.gclks.gclk2, gclk1);
let gclk2 = gclk2.div(GclkDiv8::Div(4)).enable();
let (pclk_sercom1, gclk2) = Pclk::enable(tokens.pclks.sercom1, gclk2);
let (gclk2, gclk2_out) = gclk2.enable_gclk_out(pins.pa16);

`Gclk0`

Gclk0 is significant and special relative to the other Gclks. It is the clock generator for the processor’s main clock, so it can never be disabled. Consequently, it has a special API not available to the other Gclks. While normal Gclks can only change their clock Source or divider while disabled, Gclk0 can never be disabled, so we provide this functionality on EnabledGclk0 instead.

We model the main clock’s consumption of Gclk0 by setting its Enabled counter to U1 in clock_system_at_reset. This prevents users from ever disabling EnabledGclk0, because there is no way to Decrement its Counter to U0.

Additionally, we provide functions to change the clock Source, divider, etc. on EnabledGclk0, but we restrict them to the case where N = U1. This prevents users from changing its Source or divider if any other, additional clock consumes it (besides the main clock).