{"record":{"id":"a527e866a85b8ac0","repo":"embassy-rs/embassy","slug":"failed-to-configure-pll-sys","errorCode":null,"errorMessage":"Failed to configure PLL_SYS: {:?}","messagePattern":"Failed to configure PLL_SYS: (.+?)","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"embassy-rp/src/clocks.rs","lineNumber":1110,"sourceCode":"            });\n            #[cfg(feature = \"_rp235x\")]\n            vreg.bod().write(|w| {\n                w.0 = (w.0 & 0x0000FFFF) | (0x5AFE << 16); // Set the password\n                w.set_vsel(voltage.recommended_bod());\n                w.set_en(true); // Enable brownout detection\n            });\n        }\n    }\n\n    let (xosc_freq, pll_sys_freq, pll_usb_freq) = match config.xosc {\n        Some(config) => {\n            // start XOSC\n            start_xosc(config.hz, config.delay_multiplier);\n\n            let pll_sys_freq = match config.sys_pll {\n                Some(sys_pll_config) => match configure_pll(pac::PLL_SYS, config.hz, sys_pll_config) {\n                    Ok(freq) => freq,\n                    Err(e) => panic!(\"Failed to configure PLL_SYS: {:?}\", e),\n                },\n                None => 0,\n            };\n            let pll_usb_freq = match config.usb_pll {\n                Some(usb_pll_config) => match configure_pll(pac::PLL_USB, config.hz, usb_pll_config) {\n                    Ok(freq) => freq,\n                    Err(e) => panic!(\"Failed to configure PLL_USB: {:?}\", e),\n                },\n                None => 0,\n            };\n\n            (config.hz, pll_sys_freq, pll_usb_freq)\n        }\n        None => (0, 0, 0),\n    };\n\n    CLOCKS.xosc.store(xosc_freq, Ordering::Relaxed);\n    CLOCKS.pll_sys.store(pll_sys_freq, Ordering::Relaxed);","sourceCodeStart":1092,"sourceCodeEnd":1128,"githubUrl":"https://github.com/embassy-rs/embassy/blob/463a07b963419a1bfe61d5d597c44acb810afb8b/embassy-rp/src/clocks.rs#L1092-L1128","documentation":"During clock initialization, the RP clock setup calls `configure_pll(PLL_SYS, ...)` and panics with the underlying PLL error if the system PLL cannot be locked or configured. The error value (`e`) indicates which PLL setup step failed (e.g. no valid feedback divider, frequency out of range).","triggerScenarios":"Calling `Clocks::init` (or `init_with_config`) with a `sys_pll` configuration whose reference frequency, feedback/post divider combination cannot produce a valid VCO output from the crystal frequency (`config.hz`).","commonSituations":"Using a non-12 MHz crystal (e.g. 12.288 MHz or 25 MHz) with a default PLL config tuned for 12 MHz; requesting a sys frequency outside the VCO range (750 MHz–1.6 GHz VCO constraint); typo in target frequency.","solutions":["Verify `config.hz` matches your board's actual crystal frequency (RP2040 dev boards: 12 MHz)","Choose a `sys_pll` target frequency within the valid VCO range for your reference clock, or pass `None` to run without the PLL","Check the returned debug value `{:?}` to see the specific PLLSetupError variant (e.g. VCO out of range)","Extend/adjust the PLL divider search: pick a refdiv so ref_freq stays in 5–800 MHz and fbdiv/post_div yield a valid VCO"],"exampleFix":"// before\nlet clocks = Clocks::init(&config_with(hz: 12_000_000, sys_pll: Some(125_000_000))); // board crystal is 25 MHz\n// after\nlet clocks = Clocks::init(&Config { hz: 25_000_000, sys_pll: Some(125_000_000), ..config }); // hz matches real crystal\n","handlingStrategy":"validation","validationCode":"fn validate_pll_plan(ref_hz: u32, target_hz: u32) -> Result<(), &'static str> {\n    // RP2040: VCO must be in 750..=1600 MHz, refdiv so 5..=800 MHz reference\n    let vco = (ref_hz as u64 * target_hz as u64) ; // compute per configure_pll rules\n    // perform the same feasibility math configure_pll does and reject early\n    Ok(())\n}\n","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Confirm config.hz matches the board crystal before clock init","Use default PLL configs unless you have computed dividers yourself","Keep target frequencies within documented VCO ranges","Test clock init on the actual hardware revision early"],"tags":["rust","embedded","rp2040","clock","pll","configuration"],"backgroundTag":"invalid-config-value","analyzedSha":"463a07b963419a1bfe61d5d597c44acb810afb8b","analyzedAt":"2026-09-10T13:38:26.660Z","contentChangedAt":"2026-09-10T13:38:26.660Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}