Clock API Debugging and Error Handling (Silicon Labs SiWG917 SoC)#

This section describes best practices for debugging and error handling when you use the SiWG917 Clock Manager application programming interface (API).

It explains how to identify clock synchronization issues, interpret status codes, and implement recovery mechanisms to help ensure stable system operation.

Common Debugging Tips#

When you debug clock-related issues, verify core system configurations before analyzing error codes.

For a comprehensive troubleshooting approach, see the official WiSeConnect Debugging Guide.

When Clock Synchronization Issues Occur#

  • Verify timer configuration. Ensure that the system timer is properly initialized and synchronized with the selected clock source.

  • Confirm clock source selection. Validate that the correct clock input (RC, XTAL, or PLL) is configured and stable.

  • Monitor status registers. Use sl_si91x_clock_manager_get_core_clk_src_freq() to confirm expected frequency values.

  • Check dependencies. Ensure that required services, such as the Power Manager, are initialized before clock operations.

Tip: Many synchronization issues occur when the Power Manager or PLL is configured after peripheral initialization.
Always initialize clock and power domains first.

Error Code Handling#

The Clock Manager API uses standard Silicon Labs status codes (sl_status_t) to report the result of function calls.

These status codes allow applications to detect failures, identify their cause, and perform appropriate recovery or fallback actions.

How Error Codes Work#

Each Clock API function returns an sl_status_t value indicating success or a specific failure condition.

Return values are categorized by operation outcome, such as success, initialization error, or parameter validation failure.

Recommended practices:

  • Check function return values immediately after each API call.

  • Implement retry or fallback logic for recoverable errors.

  • Log error codes and conditions during debugging to identify trends or recurring issues.

Common Clock Manager Error Codes#

The following table lists commonly encountered status codes when using the Clock Manager API.

Error Code

Value

Category

Description

Clock Manager Context

Recommended Recovery Action

SL_STATUS_OK

0x0000

Success

Operation completed successfully.

API executed normally; clock configuration or frequency update succeeded.

Continue normal operation.

SL_STATUS_FAIL

0x0001

General

Unspecified system failure.

Hardware timer or oscillator instability; clock source not ready.

Verify system hardware configuration and retry after a short delay.

SL_STATUS_NOT_INITIALIZED

0x0011

Initialization

Service or driver not initialized.

Clock Manager or Power Manager APIs used before initialization.

Initialize all dependent services (e.g., sl_si91x_power_manager_init(), sl_si91x_clock_manager_init()) before use.

SL_STATUS_INVALID_COUNT

0x0027

Parameter

Invalid counter or divider value.

Out-of-range count parameter or invalid divider configuration.

Verify all counter and divider settings against supported limits.

SL_STATUS_INVALID_RANGE

0x0028

Parameter

Parameter value outside valid range.

PLL frequency or divider exceeds supported range.

Adjust inputs to remain within the valid range and reapply configuration.

Reference:
For a complete list of Silicon Labs status codes, see the Status Codes Documentation.

Best Practices for Error Handling#

To build robust, fault-tolerant applications, apply the following best practices when using the Clock Manager API:

  1. Always validate return values

    • Use if (status != SL_STATUS_OK) checks after every API call.

    • Include detailed logging for any failures to support post-mortem debugging.

  2. Implement fallback mechanisms

    • When a clock source fails, switch to a known-stable source (such as the internal RC oscillator).

    • Design recovery paths that maintain minimum functionality.

  3. Use timeout protection

    • Set timeout counters for long-running operations such as PLL locking.

    • Prevent indefinite blocking if a hardware event does not complete.

  4. Log diagnostic information

    • Record timestamped error events to trace configuration issues.

    • Use serial output or a debug console for quick validation.

  5. Validate configuration sequences

    • Follow the initialization order: Power Manager, Clock Manager, then peripherals.

    • Improper sequencing is a common source of synchronization issues.