{"record":{"id":"49c6f2265600e6ae","repo":"embassy-rs/embassy","slug":"failed-to-configure-pll-usb","errorCode":null,"errorMessage":"Failed to configure PLL_USB: {:?}","messagePattern":"Failed to configure PLL_USB: (.+?)","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"embassy-rp/src/clocks.rs","lineNumber":1117,"sourceCode":"        }\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);\n    CLOCKS.pll_usb.store(pll_usb_freq, Ordering::Relaxed);\n\n    let (ref_src, ref_aux, clk_ref_freq) = {\n        use ClkRefCtrlAuxsrc as Aux;\n        use ClkRefCtrlSrc as Src;\n        let div = config.ref_clk.div as u32;\n        assert!(div >= 1 && div <= 4);","sourceCodeStart":1099,"sourceCodeEnd":1135,"githubUrl":"https://github.com/embassy-rs/embassy/blob/463a07b963419a1bfe61d5d597c44acb810afb8b/embassy-rp/src/clocks.rs#L1099-L1135","documentation":"Same failure path as PLL_SYS but for the USB PLL: `configure_pll(PLL_USB, ...)` returned an error during clock init and the driver panics with the PLL error attached. The USB PLL must produce a 48 MHz clock for USB operation, and invalid divider settings from the crystal reference cause setup failure.","triggerScenarios":"Calling clock init with a `usb_pll: Some(config)` whose frequency plan cannot be derived from `config.hz` (crystal frequency mismatch or invalid VCO/divider combination).","commonSituations":"Board crystal differs from the assumed 12 MHz; board code passing a custom usb_pll value that cannot hit exactly 48 MHz after post-dividers; clone/custom hardware with an unusual oscillator.","solutions":["Confirm `config.hz` equals the actual crystal frequency on the board","Use the default usb_pll config (targets 48 MHz) rather than a hand-computed value","Read the `{:?}` error payload to identify whether VCO or post-divider selection failed","Set `usb_pll: None` only if you do not need USB and have an alternate 48 MHz source"],"exampleFix":"// before\nusb_pll: Some(96_000_000) // cannot post-divide to required USB clock from this ref\n// after\nusb_pll: Some(48_000_000) // standard USB PLL target from the default config\n","handlingStrategy":"validation","validationCode":"fn validate_usb_pll(ref_hz: u32) -> Result<(), &'static str> {\n    // USB PLL must produce exactly 48 MHz after refdiv/fbdiv/postdiv\n    if ref_hz != 12_000_000 && ref_hz != 12_288_000 && ref_hz != 25_000_000 {\n        return Err(\"unsupported crystal for default USB PLL plan\");\n    }\n    Ok(())\n}\n","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Prefer the default USB PLL configuration targeting 48 MHz","Verify crystal frequency against the schematic for custom boards","Only override usb_pll with verified divider math"],"tags":["rust","embedded","rp2040","clock","pll","usb"],"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"}