gossamer 0.0.1
a very lightweight app framework for SAMD and SAML chips
Loading...
Searching...
No Matches
System Internals

Functions for configuring the system and putting it in standby mode. More...

Functions

void sys_init (void)
 Initializes the system clocks and performs any required system-wide setup.
 
uint32_t get_cpu_frequency (void)
 Gets the CPU frequency.
 
bool set_cpu_frequency (uint32_t freq)
 Sets the CPU frequency.
 
void _enable_48mhz_gclk1 (void)
 Enables the 48 MHz clock on GCLK1 for USB operation.
 
void set_light_sleep_enabled (bool enabled)
 Enables or disables light sleep mode.
 
bool get_light_sleep_enabled (void)
 Gets whether light sleep mode is enabled.
 
void _enter_standby_mode (void)
 Enters the configured sleep mode. Does not return until an interrupt fires.
 

Detailed Description

Functions for configuring the system and putting it in standby mode.

Function Documentation

◆ _enable_48mhz_gclk1()

void _enable_48mhz_gclk1 ( void )

Enables the 48 MHz clock on GCLK1 for USB operation.

This function is called by the USB stack when it is initialized.

Warning
On the SAM D11, D21, L21 and L22, the 48 MHz clock is hard-coded to use USB Clock Recovery Mode, and as such will only be available if your device is plugged into a USB host. It is possible to derive the 48 MHz DFLL from an external 32kHz crystal, but this is not currently implemented in Gossamer. On the SAM D51, GCLK1 carries the open-loop DFLL at 48 MHz from startup (set up by sys_init), so the clock is available regardless of USB. This function switches the DFLL to closed-loop USB Clock Recovery Mode, which disciplines the frequency against the USB start-of-frame signal. The clock keeps running whether or not a USB host is connected; however, its frequency is only actively corrected when a host is present and sending SOF packets.

◆ _enter_standby_mode()

void _enter_standby_mode ( void )

Enters the configured sleep mode. Does not return until an interrupt fires.

You should not generally need to call this function; at the end of every app_loop invocation, the main run loop enters sleep mode if your app indicated that it was appropriate. The sleep mode used depends on whether light sleep is enabled via set_light_sleep_enabled.

◆ get_cpu_frequency()

uint32_t get_cpu_frequency ( void )

Gets the CPU frequency.

Returns
8000000 by default, or another value if set by set_cpu_frequency

◆ get_light_sleep_enabled()

bool get_light_sleep_enabled ( void )

Gets whether light sleep mode is enabled.

Returns
true if the lighter IDLE sleep mode is enabled; false if using default STANDBY.

◆ set_cpu_frequency()

bool set_cpu_frequency ( uint32_t freq)

Sets the CPU frequency.

Parameters
freqone of 1000000, 2000000, 4000000, 8000000, 12000000, 16000000, 48000000, 96000000 or 120000000 (last three are SAM D51 only).

Supported CPU frequencies vary from chip to chip:

  • On the SAM D11 and D21, you can choose 8, 4, 2 or 1 MHz.
  • On the SAM L21 and L22, you can choose 16, 12, 8 or 4 MHz.
  • On the SAM D51, you can choose 48, 96 or 120 MHz. On the D11, D21, L21 and L22, Gossamer only supports the internal oscillator at one of its standard frequencies. On the SAM D51, 96 and 120 MHz are produced by DPLL0 using a 1 MHz reference on GCLK5. The function waits for the PLL to lock and report its clock as ready before returning, which may take a brief moment.
    Note
    On most chips, peripherals like SERCOMs and TC/TCCs read the CPU frequency when they are configured, to set critical timing-related parameters like baud rate or period. If you change the CPU frequency after setting up these peripherals, they will very likely behave in unexpected ways. You should de-init any peripherals that depend on GCLK0 before calling set_cpu_frequency, and then re-init them after. On the SAM D51, SERCOMs and the ADC are clocked from the fixed 48 MHz GCLK1 and are unaffected by CPU frequency changes. Only peripherals that the application explicitly clocks from GCLK0 — such as TC and TCC timers — need to be de-inited and re-inited when the CPU frequency changes. Note that at 120 MHz, GCLK0 exceeds the TC/TCC maximum peripheral clock of 100 MHz: above 96 MHz, clock your timers from GCLK1 or GCLK2 instead.

◆ set_light_sleep_enabled()

void set_light_sleep_enabled ( bool enabled)

Enables or disables light sleep mode.

Parameters
enabledtrue to use a lighter IDLE sleep mode when app_loop returns true; false to use the default deep STANDBY mode.

By default, returning true from app_loop enters STANDBY mode, the deepest sleep available. Light sleep uses a lighter idle mode instead, which is useful when your application needs DMA to continue running during sleep, or when fast interrupt response time is critical.

On SAM D11 and D21 light sleep uses IDLE0, which keeps the AHB and APB peripheral buses running. This is required to allow DMA transfers to continue.

On SAM L21 and L22, light sleep uses IDLE2 mode, which stops all buses but provides faster wakeup than STANDBY. IDLE0 is not available on L21 and L22; for DMA on those chips, consult the DMAC's per-channel RUNSTDBY bits.

◆ sys_init()

void sys_init ( void )

Initializes the system clocks and performs any required system-wide setup.

Gossamer aims for consistency at system startup, no matter which chip you are working with. On the SAM D11, D21, L21 and L22:

  • GCLK0, the main system clock, is set to 8 MHz.
  • GCLK2 is the low-power 32768 Hz clock, OSCULP32K.
  • GCLK3 is a 1024 Hz clock, derived from the most accurate source available. GCLK0 is set to ONDEMAND with RUNSTDBY off, so the main clock remains off when in standby mode. GCLK2 and GCLK3 are also ONDEMAND, but RUNSTDBY is on. This ensures that if a peripheral requests it, the clock will remain on in standby, but if no peripheral requests it, it will not run at all. On these chips, GCLK1 is not turned on at startup; if you intend to use USB, the usb_init function will claim GCLK1 for the 48 MHz DFLL clock.

On the SAM D51, the clock layout is different. The DFLL is the CPU clock source at reset, so GCLK0 boots at 48 MHz from the DFLL. sys_init sets up the following generators:

  • GCLK1 is a standing 48 MHz reference (DFLL), used by SERCOMs, the ADC and USB. It is available from startup, independent of CPU speed.
  • GCLK2 is the low-power 32768 Hz clock, OSCULP32K.
  • GCLK3 is a 1024 Hz clock, derived from the most accurate source available. Two additional generators may be claimed by other subsystems:
  • GCLK4 is reserved by dac_init as a 12 MHz clock (DFLL divided by 4), required because the D51 DAC's input clock may not exceed 12 MHz.
  • GCLK5 is reserved by set_cpu_frequency as a 1 MHz PLL reference (DFLL divided by 48), used when switching GCLK0 to DPLL0. The D51 also enables the CMCC cache controller, which becomes important once the CPU frequency exceeds the flash access speed.