Expand description

Generic Clock Controllers

Overview

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).

Structs

Generic clock generator used to distribute clocks to various peripherals
A GPIO Pin configured as a Gclk output
Singleton token that can be exchanged for a Gclk
Set of GclkTokens representing the disabled Gclks at power-on reset

Enums

Value-level enum identifying one of 12 possible Gclks
Value-level enum of possible clock sources for a Gclk
Type-level variant of GclkId representing the identity of GCLK0
Type-level variant of GclkId representing the identity of GCLK1
Type-level variant of GclkId representing the identity of GCLK2
Type-level variant of GclkId representing the identity of GCLK3
Type-level variant of GclkId representing the identity of GCLK4
Type-level variant of GclkId representing the identity of GCLK5
Type-level variant of GclkId representing the identity of GCLK6
Type-level variant of GclkId representing the identity of GCLK7
Type-level variant of GclkId representing the identity of GCLK8
Type-level variant of GclkId representing the identity of GCLK9
Type-level variant of GclkId representing the identity of GCLK10
Type-level variant of GclkId representing the identity of GCLK11
Enum for the clock division factor of all Gclks other than Gclk1
Enum for the clock division factor of Gclk1 only

Traits

Set of PinIds whose implementations of GclkIo map to Gclk0Id
Trait unifying the two Gclk divider types, GclkDiv8 and GclkDiv16
Type-level enum identifying one of 12 possible Gclks
Trait mapping each PinId to its corresponding GclkId when used as a Gclk input or output
Type-level enum of possible clock Sources for a Gclk
Type-level enum of GclkSourceId types that are not a GclkIo

Type Definitions

Type alias for the corresponding EnabledGclk
Type alias for the corresponding EnabledGclk
Type alias for the corresponding EnabledGclk
Type alias for the corresponding EnabledGclk
Type alias for the corresponding EnabledGclk
Type alias for the corresponding EnabledGclk
Type alias for the corresponding EnabledGclk
Type alias for the corresponding EnabledGclk
Type alias for the corresponding EnabledGclk
Type alias for the corresponding EnabledGclk
Type alias for the corresponding EnabledGclk
Type alias for the corresponding EnabledGclk
Type alias for the corresponding Gclk
Type alias for the corresponding Gclk
Type alias for the corresponding Gclk
Type alias for the corresponding Gclk
Type alias for the corresponding Gclk
Type alias for the corresponding Gclk
Type alias for the corresponding Gclk
Type alias for the corresponding Gclk
Type alias for the corresponding Gclk
Type alias for the corresponding Gclk
Type alias for the corresponding Gclk
Type alias for the corresponding Gclk