Skip to content

F0012 clk-5

Rule: USB has an exact 48 MHz clock.

Code F0012 (stable, never reused)
Id clk-5
Category clk
Source spirit_level
Fix by hand

Level per tier

Tier Level Reason
small off
small-workspace off
medium off
big off
ai off
embedded deny bedrock error: USB enabled on a part without HSI48 / CRS and no exact 48 MHz source configured
ui off
egui off
units-strict off
units-paranoid off

Why

USB full-speed timing is unforgiving of clock error, so a part that drives USB from anything other than a 48 MHz clock accurate to the USB spec's tolerance (HSI48 trimmed by CRS, or a crystal-derived 48 MHz) will enumerate unreliably or not at all, in ways that look like a host or cable problem rather than a clock one. Some STM32 parts don't have HSI48 or CRS at all, and a generated clock config that leaves "USB clock: TODO" in a comment is a config that was never actually tried with a USB host.

Example

This repo's own firmware template (TPL-13) generates a USB clock TODO instead of a working setup for F411, L476 and F103 — parts without HSI48 / CRS — so a firmware generated for one of those chips with --wire-weaver (USB transport) builds but has never been clocked correctly for USB; the gap is tracked, not silently shipped.

How to fix

On a part without HSI48/CRS, derive the exact 48 MHz USB clock from the crystal through the PLL (most of these parts can), and treat "USB clock: TODO" in generated code as a build that must not reach a board.

How it is checked

Check: src mid — matching the configured USB kernel clock source against the part's actual 48 MHz capability (HSI48 trimmed vs. a PLL output) needs the chip's clock-tree model, not just a string match.

Source

Ported from embedded_bedrock's firmware check catalogue, CLK-5 (book/checks.md, detail in book/checks/clk.md). Found on: embedded_bedrock TPL-13.

Configure

[lints.clk-5]
level = "deny"
reason = "why this project wants it at this level"

Allow one finding in the code with // spirit-level: allow(clk-5) <reason> (waivers); the code works there too, as in [lints.F0012].