stm32: RCC refactor tracking issue

Dirbaio commented 5 months ago

The 3 designs

Note RCC in embassy-stm32 is a bit "in flux". Currently we have three API designs for RCC depending on the family, for historical reasons. Some have been ported from stm32-rs, some have been developed for embassy but before we knew what the best design is.

v1: user specifies the target frequencies, RCC tries to solve for the best config (prescalers etc) to achieve that. example
v2: user specifies prescalers/dividers instead of target freqs. Sysclk mux is an enum whose variants contain the config for the picked clock source. example
v3: user specifies prescalers/dividers. There's separate fields for each clock source (HSE, HSI, MSI, PLL..) to enable and configure them. Sysclk mux is an enum without data that just chooses the source (which the user must ensure is enabled, of course) example

Rationale for the v3 design

Directly specifying frequencies (v1 api design) turned out to be quite troublesome. Solving for the best RCC config backwards from the target frequencies is hard, requires a lot of code that the compiler isn't always able to optimize out, and it's often impossible to exactly match the requested freqs, so we have to pick the closest one making it quite unpredictable for the end user.
The v2 design rules out some configurations that the hardware allows. For example you might want to run sysclk from PLL from HSE, but run some peripheral from HSI (with a CCIPR register). The hardware does allow having HSE and HSI on at the same time, but you can't do it if the mux enum forces you to pick. With the v3 design you can enable all of HSI, HSE, PLL just fine, then pick one for sysclk and a different one for a particular peripheral.

The refactor

We should port all RCCs to the v3 design, both for consistency between chips and to get the v3 benefits.

[x] STM32F1: v1 #2564
[x] STM32F2: v3
[x] STM32L1: v3
[x] STM32F4: v3
[x] STM32F0: v1 #2564
[x] STM32F3: v1 #2560
[x] STM32F7: v3
[x] STM32L0: v3
[x] STM32L4: v3
[x] STM32H7: v3
[x] STM32G0: v2 https://github.com/embassy-rs/embassy/pull/2656
[x] STM32L5: v3
[x] STM32G4: v2 https://github.com/embassy-rs/embassy/pull/2579
[x] STM32WB: v3
[x] STM32WL: v3
[x] STM32U5: v2 https://github.com/embassy-rs/embassy/pull/2617
[x] STM32C0: v2 https://github.com/embassy-rs/embassy/pull/2656
[x] STM32H5: v3
[x] STM32WBA: v2 https://github.com/embassy-rs/embassy/pull/2520

While we're at it, it'd be great to unify similar families into a single file. I have already unified a few into l.rs, h.rs, f.rs , but I think the remaining ones are different enough that we might want to keep them separate.

Some candidates to unify are:

F3, F0, F1
G0, C0 (it's a cut-down G0), and also maybe G4
U5, WBA (?)

Help is welcome!

Help on this would be very welcome. If you want to help:

Pick a family from the above list that's not yet.
Comment in this issue announcing you intend to work on it, so we don't duplicate effort.
Copy its public API from the v3 RCCs (l.rs, h.rs, f.rs ) as close as possible. API and naming should be identical between RCC versions as much as possible.
Make it work for the family. You might want to copy from one of the v3 RCCs as a skeleton, and adjust it.
Adjust examples, tests.
Send a PR

barnabywalters commented 5 months ago

I made a start on G4, not quite ready to PR yet but hopefully in the next days.

Dirbaio commented 4 months ago

this is now DONE, finally :partying_face:

embassy-rs / embassy