Clock Manager Appendix#

Glossary#

Clock Branch: A specific path in the device's clock distribution tree that supplies clock signals to one or more peripheral modules. Each clock branch can be derived from different oscillator sources and may include dividers or multipliers.

Clock Manager: The Silicon Labs platform service responsible for managing system oscillators, clock trees, and runtime clock operations across different device families.

Clock Source: A hardware oscillator (internal or external) that provides the fundamental timing reference for the system. Examples include HFXO, LFXO, HFRCO, LFRCO.

Clock Tree: The hierarchical system of clock distribution within a microcontroller, including oscillators, PLLs, dividers, and clock branches, that supply different parts of the system.

CTUNE: Crystal tuning capacitance setting that adjusts the load capacitance seen by external crystals to optimize frequency accuracy and stability.

Digital Phase-Locked Loop (DPLL): Used to improve the precision of internal RC oscillators by locking them to more accurate reference sources.

Hardware Abstraction Layer (HAL): A software layer that provides a consistent interface for accessing hardware features across different device families, hiding device-specific implementation details.

High-Frequency RC Oscillator (HFRCO): An internal oscillator that provides high-frequency clock signals without requiring external components.

High-Frequency Crystal Oscillator (HFXO): An external crystal-based oscillator that provides high-precision, high-frequency clock signals for system operation.

Low-Frequency RC Oscillator (LFRCO): An internal oscillator that provides low-frequency clock signals for low-power applications.

System-on-Chip Phase-Locked Loop (SOCPLL): A high-frequency PLL available on Series 3 devices that can generate 145 MHz or 150 MHz clock signals for maximum performance applications.

Low-Frequency Crystal Oscillator (LFXO): An external crystal-based oscillator that provides high-precision, low-frequency clock signals, typically used for real-time clock applications.

Oscillator: A hardware component that generates periodic signals used as timing references. Can be internal (RC-based) or external (crystal-based).

Parts Per Million (PPM): A measure of oscillator frequency accuracy, indicating how much the actual frequency deviates from the nominal frequency. Lower PPM values indicate higher precision.

SL Main/SL System: The Silicon Labs initialization framework that manages the startup sequence and initialization of platform services in a coordinated manner.

Universal Configurator (UC): A graphical configuration tool within Simplicity Studio that allows developers to configure Silicon Labs components and generate corresponding configuration files.

Acronyms#

API: Application Programming Interface
CMU: Clock Management Unit (hardware module)
CTUNE: Crystal Tuning Capacitance
DPLL: Digital Phase-Locked Loop
EM0-EM4: Energy Modes (power states)
FSRCO: Fast Startup RC Oscillator (Series 3)
GPIO: General Purpose Input/Output
HAL: Hardware Abstraction Layer
HF: High Frequency
HFRCO: High-Frequency RC Oscillator
HFXO: High-Frequency Crystal Oscillator
IDE: Integrated Development Environment
LF: Low Frequency
LFRCO: Low-Frequency RC Oscillator
LFXO: Low-Frequency Crystal Oscillator
MCU: Microcontroller Unit
PLL: Phase-Locked Loop
PPM: Parts Per Million
RC: Resistor-Capacitor (oscillator type)
RCO: RC Oscillator
RTC: Real-Time Clock
SLC: Silicon Labs Component (file extension)
UC: Universal Configurator
XTAL: Crystal

Extended API Examples#

Oscillator Frequency Query#

// Query oscillator frequencies.
uint32_t hfxo_freq, lfrco_freq;
sl_clock_manager_get_oscillator_frequency(SL_OSCILLATOR_HFXO, &hfxo_freq);
sl_clock_manager_get_oscillator_frequency(SL_OSCILLATOR_LFRCO, &lfrco_freq);
printf("HFXO: %lu Hz, LFRCO: %lu Hz\n", hfxo_freq, lfrco_freq);

Oscillator Calibration#

// Save/restore HFXO calibration for EM4 wake optimization.
uint32_t saved_calibration;
sl_clock_manager_get_hfxo_calibration(&saved_calibration);  // Save before EM4
sl_clock_manager_set_hfxo_calibration(saved_calibration);   // Restore after wake

// RC oscillator calibration
uint32_t rc_cal;
sl_clock_manager_get_rc_oscillator_calibration(SL_OSCILLATOR_HFRCODPLL, &rc_cal);
sl_clock_manager_set_rc_oscillator_calibration(SL_OSCILLATOR_HFRCODPLL, rc_cal + 10);

Clock Export#

// Export HFXO to GPIO pin for measurement.
sl_clock_manager_set_gpio_clock_output(
  SL_CLOCK_MANAGER_EXPORT_CLOCK_SOURCE_HFXO,    // Clock source
  SL_CLOCK_MANAGER_EXPORT_CLOCK_OUTPUT_0,       // Output channel
  1,                                            // No division
  0, 0                                          // Port A, Pin 0
);

Precision Query#

// Check oscillator precision for wireless protocols.
uint16_t hfxo_precision;
sl_clock_manager_get_oscillator_precision(SL_OSCILLATOR_HFXO, &hfxo_precision);
if (hfxo_precision <= 50) {  // ≤50 PPM for wireless.
  printf("HFXO suitable for wireless protocols\n");
}

// Check SOCPLL precision on Series 3 devices.
uint16_t socpll_precision;
sl_clock_manager_get_oscillator_precision(SL_OSCILLATOR_SOCPLL0, &socpll_precision);
if (socpll_precision <= 50) {  // Precision depends on reference clock.
  printf("SOCPLL suitable for high-precision applications\n");
}

HFXO Sleepy Crystal Notification#

// Callback function for handling consecutive HFXO startup failures.
// This is called when HFXO fails twice in a row during startup.
// Only available when SL_CLOCK_MANAGER_HFXO_SLEEPY_CRYSTAL_SUPPORT is enabled.
void sl_clock_manager_hfxo_notify_consecutive_failed_startups(void)
{
  // Handle sleepy crystal condition - HFXO is running but properties not guaranteed.
  printf("Warning: HFXO consecutive startup failures detected\n");
  
  // Possible recovery actions:
  // - Log the error for diagnostics
  // - Switch to backup clock source if available
  // - Notify application layer of degraded timing precision
  // - Trigger crystal replacement recommendation
  
  // Example: Set flag to indicate degraded timing precision.
  system_timing_degraded = true;
}

External Flash Clock Control (Series 3 Only)#

// Control external flash reference clock on Series 3 devices.
// Available oscillators: SL_OSCILLATOR_FSRCO, SL_OSCILLATOR_FLPLL.
sl_status_t configure_ext_flash_clock(void) {
  sl_status_t status;
  sl_oscillator_t current_clock, initial_clock;
  
  // Get current external flash clock source.
  status = sl_clock_manager_get_ext_flash_clk(&initial_clock);
  if (status != SL_STATUS_OK) {
    printf("External flash clock not supported on this device\n");
    return status;  // Not supported on Series 2 or other devices.
  }
  
  printf("Initial external flash clock: %d\n", initial_clock);
  
  // Switch to FSRCO for lower power operation.
  status = sl_clock_manager_set_ext_flash_clk(SL_OSCILLATOR_FSRCO);
  if (status == SL_STATUS_OK) {
    printf("External flash switched to FSRCO\n");
    
    // Verify the change.
    sl_clock_manager_get_ext_flash_clk(&current_clock);
    printf("Current external flash clock: %d\n", current_clock);
  }
  
  // Switch to FLPLL for higher performance (if HFXO is available as reference).
  status = sl_clock_manager_set_ext_flash_clk(SL_OSCILLATOR_FLPLL);
  if (status == SL_STATUS_OK) {
    printf("External flash switched to FLPLL\n");
  } else if (status == SL_STATUS_INVALID_PARAMETER) {
    printf("FLPLL not available (requires HFXO reference)\n");
  }
  
  // Restore original clock source.
  return sl_clock_manager_set_ext_flash_clk(initial_clock);
}

Runtime SYSCLK Source Switching (Advanced)#

// Advanced: Change SYSCLK source at runtime.
// WARNING: This affects all modules connected to SYSCLK branch.
sl_status_t switch_to_low_power_clock(void) {
  sl_status_t status;
  sl_oscillator_t original_source;
  
  // Save current SYSCLK source.
  status = sl_clock_manager_get_sysclk_source(&original_source);
  if (status != SL_STATUS_OK) {
    return status;
  }
  
  printf("Current SYSCLK source: %d\n", original_source);
  
  // Switch to FSRCO for ultra-low-power mode.
  status = slx_clock_manager_set_sysclk_source(SL_OSCILLATOR_FSRCO);
  if (status == SL_STATUS_OK) {
    printf("SYSCLK switched to FSRCO for low power\n");
    
    // In low-power mode, reduced performance but lower consumption.
    // Peripheral timing will be affected, adjust accordingly.
    
    // Later, restore high-performance clock.
    status = slx_clock_manager_set_sysclk_source(SL_OSCILLATOR_HFXO);
    if (status == SL_STATUS_OK) {
      printf("SYSCLK restored to HFXO\n");
    }
  } else {
    printf("SYSCLK switching not supported or oscillator not available\n");
  }
  
  return status;
}

Oscillator Calibration Override (NVM3-Based)#

// Use NVM3 to store and retrieve oscillator calibration overrides.
#include "sl_clock_manager_oscillator_calibration_override.h"

sl_status_t manage_hfxo_calibration_override(void) {
  sl_status_t status;
  uint32_t ctune_override;
  
  // Initialize calibration override system.
  status = sl_clock_manager_init_oscillator_calibration_override();
  if (status != SL_STATUS_OK) {
    printf("Calibration override initialization failed\n");
    return status;
  }
  
  // Try to read existing override from NVM3.
  status = sl_clock_manager_read_hfxo_calibration_override(&ctune_override);
  if (status == SL_STATUS_OK) {
    printf("Found HFXO calibration override in NVM3: %lu\n", ctune_override);
    
    // Override is automatically applied during initialization.
    // No need to manually set it here.
  } else {
    printf("No HFXO calibration override found in NVM3\n");
    
    // Example: Store a new override value.
    uint32_t new_ctune = 140;  // Board-specific optimized value.
    status = sl_clock_manager_write_hfxo_calibration_override(new_ctune);
    if (status == SL_STATUS_OK) {
      printf("Stored new HFXO calibration override: %lu\n", new_ctune);
      
      // Override will take effect on next initialization.
      // For immediate effect, also set the calibration directly.
      slx_clock_manager_hfxo_set_ctune(new_ctune);
    }
  }
  
  // Example: Remove override to return to default calibration.
  // status = sl_clock_manager_delete_hfxo_calibration_override();
  
  return status;
}

Clock Export#

// Example: Export HFXO to GPIO pin for external monitoring
sl_status_t configure_clock_export_for_debugging(void) {
  sl_status_t status;
  
  // Export HFXO signal to Port C, Pin 0
  status = sl_clock_manager_set_gpio_clock_output(
    SL_CLOCK_MANAGER_EXPORT_CLOCK_SOURCE_HFXO,      // Clock source
    SL_CLOCK_MANAGER_EXPORT_CLOCK_OUTPUT_SELECT_0,  // Output select  
    1,                                              // No division
    2,                                              // Port C (GPIO port 2)
    0                                               // Pin 0
  );
  
  if (status == SL_STATUS_OK) {
    printf("HFXO exported to PC0 for external monitoring\n");
    // Configure PC0 as output pin in your GPIO setup
  }
  
  return status;
}

Clock Export Design Considerations:

Loading Effects: Exported clocks add capacitive load to the source oscillator
Signal Integrity: GPIO drive strength affects signal quality and EMI
Power Impact: Clock export increases overall power consumption
Pin Availability: Check device data sheet for clock-capable GPIO pins

Extended Configuration Examples#

Example 1: HFXO Crystal Sharing Configuration#

The HFXO Crystal Sharing feature allows multiple EFR devices to share a single crystal oscillator, reducing BOM cost and board space. This feature requires special board design and configuration.

Crystal Sharing Architecture:

Leader Device: Outputs a sinusoidal clock signal via the HFCLKOUT pin
Follower Device: Receives the clock signal from the leader device
Request Signal: GPIO-based communication between leader and follower
Power Optimization: Leader only outputs clock when requested by follower

Hardware Requirements:

Dedicated HFCLKOUT pin on leader device for clock output
GPIO connection between devices for request signaling
Proper signal routing and impedance matching on PCB
Only leader device requires physical HFXO crystal

Leader Device Configuration:

// Enable crystal sharing feature (required for both leader and follower)
#define SL_CLOCK_MANAGER_HFXO_CRYSTAL_SHARING_EN                1

// Leader configuration - device that outputs the clock
#define SL_CLOCK_MANAGER_HFXO_CRYSTAL_SHARING_LEADER_EN         1
#define SL_CLOCK_MANAGER_HFXO_CRYSTAL_SHARING_FOLLOWER_EN       0

// GPIO configuration for request signal (leader receives requests)
#define SL_CLOCK_MANAGER_HFXO_CRYSTAL_SHARING_GPIO_PORT         0   // Port A
#define SL_CLOCK_MANAGER_HFXO_CRYSTAL_SHARING_GPIO_PIN          10  // Pin 10

// Optional: Minimum startup delay to prevent power waste
#define SL_CLOCK_MANAGER_HFXO_CRYSTAL_SHARING_LEADER_MIN_STARTUP_DELAY_EN    1
#define SL_CLOCK_MANAGER_HFXO_CRYSTAL_SHARING_LEADER_TIMEOUT_STARTUP         HFXO_BUFOUTCTRL_TIMEOUTSTARTUP_T208US

Follower Device Configuration:

// Follower configuration - device that receives the clock
#define SL_CLOCK_MANAGER_HFXO_CRYSTAL_SHARING_LEADER_EN         0
#define SL_CLOCK_MANAGER_HFXO_CRYSTAL_SHARING_FOLLOWER_EN       1

// GPIO configuration for request signal (follower sends requests)
#define SL_CLOCK_MANAGER_HFXO_CRYSTAL_SHARING_GPIO_PORT         0   // Port A
#define SL_CLOCK_MANAGER_HFXO_CRYSTAL_SHARING_GPIO_PIN          10  // Pin 10

// HFXO mode must be set to external clock for follower
#define SL_CLOCK_MANAGER_HFXO_MODE                              HFXO_CFG_MODE_EXTCLK

Crystal Sharing Design Guidelines:

Signal Integrity: Ensure proper PCB layout for high-frequency clock signals
Power Management: Leader device controls clock output based on follower requests
Startup Timing: Consider startup delays and coordination between devices
Pin Configuration: Refer to device data sheet for HFCLKOUT and GPIO pin assignments
Frequency Matching: Both devices must be configured for the same HFXO frequency

Example 2: Advanced DPLL Configuration for High Performance#

// High-performance configuration using DPLL with HFXO reference.
// Target: 78 MHz system clock from 39 MHz HFXO.
#define SL_CLOCK_MANAGER_HFXO_EN                    1
#define SL_CLOCK_MANAGER_HFXO_FREQ                  39000000

// DPLL configuration: f_out = f_ref × (N + 1) / (M + 1)
// 78 MHz = 39 MHz × (3839 + 1) / (1919 + 1) = 78 MHz
#define SL_CLOCK_MANAGER_DPLL_EN                    1
#define SL_CLOCK_MANAGER_DPLL_FREQ                  78000000
#define SL_CLOCK_MANAGER_DPLL_N                     3839
#define SL_CLOCK_MANAGER_DPLL_M                     1919
#define SL_CLOCK_MANAGER_DPLL_REFCLK                CMU_DPLLREFCLKCTRL_CLKSEL_HFXO
#define SL_CLOCK_MANAGER_DPLL_EDGE                  cmuDPLLEdgeSel_Fall

// System clock configuration.
#define SL_CLOCK_MANAGER_SYSCLK_SOURCE              CMU_SYSCLKCTRL_CLKSEL_HFRCODPLL
#define SL_CLOCK_MANAGER_HCLK_DIVIDER               1  //78 MHz

Example 3: Power-Optimized Configuration for Battery Applications#

// Low-power configuration using internal oscillators only.
// No crystals required, optimized for energy efficiency.

// High-frequency: Use HFRCO at lowest viable frequency.
#define SL_CLOCK_MANAGER_HFXO_EN                    0  // Disable crystal
#define SL_CLOCK_MANAGER_HFRCO_EN                   1
#define SL_CLOCK_MANAGER_HFRCO_FREQ                 19000000  // 19 MHz

// Low-frequency: Use LFRCO (no LFXO crystal needed).
#define SL_CLOCK_MANAGER_LFXO_EN                    0  // Disable crystal
#define SL_CLOCK_MANAGER_LFRCO_EN                   1

// System clock: Direct HFRCO at moderate frequency for power efficiency.
#define SL_CLOCK_MANAGER_SYSCLK_SOURCE              SL_CLOCK_MANAGER_DEFAULT_HF_CLOCK_SOURCE_HFRCODPLL
#define SL_CLOCK_MANAGER_HCLK_DIVIDER               1  // Full HFRCO frequency (19 MHz)

// Note: For battery applications, running SYSCLK at higher frequency and completing
// tasks quickly to return to sleep is often more power-efficient than slow execution.

// Disable unused oscillators for maximum power savings.
#define SL_CLOCK_MANAGER_DPLL_EN                    0

Example 4: Series 3 Advanced SOCPLL Configuration#

// Advanced SOCPLL configuration with manual settings for Series 3 devices.
// Target: 145 MHz system clock with HFXO reference and optimized settings

// HFXO as reference for SOCPLL precision
#define SL_CLOCK_MANAGER_HFXO_EN                    1
#define SL_CLOCK_MANAGER_HFXO_FREQ                  39000000

// SOCPLL configuration for optimal performance
#define SL_CLOCK_MANAGER_SOCPLL_EN                  1
#define SL_CLOCK_MANAGER_SOCPLL_FREQ                145000000                        // 145 MHz target frequency.
#define SL_CLOCK_MANAGER_SOCPLL_REFCLK              CMU_SOCPLLREFCLKCTRL_CLKSEL_HFXO // HFXO reference.

// System clock configuration
#define SL_CLOCK_MANAGER_SYSCLK_SOURCE              CMU_SYSCLKCTRL_CLKSEL_SOCPLL0    // Use SOCPLL for SYSCLK.
#define SL_CLOCK_MANAGER_HCLK_DIVIDER               1                                // Full SOCPLL frequency.

// Benefits of this configuration:
// - Maximum performance on Series 3 devices (145-150 MHz)
// - High precision from crystal-referenced PLL
// - Power Manager execution modes can dynamically switch to SOCPLL
// - Suitable for compute-intensive applications and wireless protocols

Example 5: Precision RTC Configuration with External Crystal#

// High-precision configuration for RTC applications.
// Uses external crystals for maximum accuracy.

// High-frequency: Standard HFXO configuration.
#define SL_CLOCK_MANAGER_HFXO_EN                    1
#define SL_CLOCK_MANAGER_HFXO_FREQ                  39000000

// Low-frequency: External 32.768 kHz crystal for RTC precision.
#define SL_CLOCK_MANAGER_LFXO_EN                    1
#define SL_CLOCK_MANAGER_LFXO_MODE                  LFXO_CFG_MODE_XTAL
#define SL_CLOCK_MANAGER_LFXO_CTUNE                 79  // Board-specific tuning
#define SL_CLOCK_MANAGER_LFXO_PRECISION             500  // 500 PPM typical

// RTC clock source configuration.
#define SL_CLOCK_MANAGER_SYSRTCCLK_SOURCE           SL_CLOCK_MANAGER_DEFAULT_LF_CLOCK_SOURCE_LFXO

Next Steps (Additional References)#

Development Resources#

Simplicity Studio: IDE with integrated Universal Configurator
Silicon Labs Community Forums: Technical support and discussions
Application Notes: Clock optimization for specific use cases
Example Projects: Reference implementations for common scenarios

Advanced Topics#

Custom HAL Implementation: Adding support for new device families
Clock Tree Analysis: Understanding device-specific clock distribution
Power Optimization: Advanced techniques for battery-powered applications
Wireless Integration: Protocol-specific timing coordination
Debugging Tools: Clock signal analysis and validation techniques

FAQ#

Q: Why am I getting SL_STATUS_INVALID_PARAMETER when querying oscillator frequency?

A: This usually indicates either an invalid oscillator enum or that the oscillator is not supported on your device. Check the device family documentation and ensure the oscillator is enabled in your configuration files.

Q: Can I change clock sources at runtime?

A: The Clock Manager is designed for compile-time configuration. While some runtime adjustments are possible (like calibration), major clock source changes should be done through configuration files and the Universal Configurator.

Q: How do I know if HFXO crystal sharing is working properly?

A: After you enable crystal sharing in the configuration, confirm that the HFXO frequency is available and that both the Clock Manager and the wireless stack can access it. The system handles coordination automatically through internal callbacks, so no additional application logic is required.

Q: What's the difference between clock_manager and device_init_clocks components?

A: clock_manager is the newer, unified service that provides HAL abstraction and advanced clock-management features. device_init_clocks is the legacy solution. They are mutually exclusive, and you should use clock_manager for all new projects.

Q: How do I optimize clock configuration for battery life?

A: Use internal RC oscillators (HFRCO/LFRCO) when precision allows, disable unused oscillators, choose lower system frequencies, and coordinate with Power Manager for sleep mode optimization.

Q: Why does HFXO take a long time to start after EM4 wake?

A: HFXO needs time to stabilize after power loss. Save calibration values before EM4 entry and restore them after wake to skip the optimization time.

Q: Can I export internal clock signals for debugging?

A: Yes, use sl_clock_manager_set_gpio_clock_output() to export various internal clocks to GPIO pins for external monitoring and debugging.

Q: How do I handle clock precision requirements for wireless protocols?

A: Always verify HFXO precision using sl_clock_manager_get_oscillator_precision() before wireless stack initialization. Most protocols require ≤50 PPM precision.

Q: When should I use SOCPLL on Series 3 devices?

A: SOCPLL provides maximum performance (145-150 MHz) on Series 3 devices and is ideal for compute-intensive applications. Use SOCPLL when you need high performance, have HFXO available as a reference, or want Power Manager to automatically switch to high-performance mode. SOCPLL precision depends on its reference clock source (HFXO provides the best precision).

Clock Manager Appendix#

Glossary#

Acronyms#

Extended API Examples#

Oscillator Frequency Query#

Oscillator Calibration#

Clock Export#

Precision Query#

HFXO Sleepy Crystal Notification#

External Flash Clock Control (Series 3 Only)#

Runtime SYSCLK Source Switching (Advanced)#

Oscillator Calibration Override (NVM3-Based)#

Clock Export#

Extended Configuration Examples#

Example 1: HFXO Crystal Sharing Configuration#

Example 2: Advanced DPLL Configuration for High Performance#

Example 3: Power-Optimized Configuration for Battery Applications#

Example 4: Series 3 Advanced SOCPLL Configuration#

Example 5: Precision RTC Configuration with External Crystal#

Next Steps (Additional References)#

Related Documentation#

Development Resources#

Advanced Topics#

FAQ#