STM32 HRTIM Refactor

[hatimthayyil]

• Refactors the HRTIM module
• Separate out the bridge implementations
• Add a Master Timer Trait Instance (WIP for synchronised bridges)
• Add a Fullbridge Implementation

[xoviat]

If you can discuss with @usbalbin and decide on a way forward for hrtim, I can merge once an agreement has been reached. The stm32-hrtim code should be merged into embassy-stm32 eventually, but I am not sure whether it's the right time for that now or not.

[usbalbin]

In my mind stm32-hrtim should be a type safe (as far as possible) interface over the hardware that allows you to, ideally, do everything the hardware supports but with some guard rails. There are a lot of weird edge cases like "timers can only trigger neighbors if they have the same prescaler" or some things that needs to be set up in a very specific order, which are enforced by that crate. But I do not think it that crate should do much higher level things than that.

In my mind specific topologies are a level higher than that and therefore should probably live somewhere else(embassy?). In my experience, especially for the HRTIM which is so customizable, if you make an abstraction that is too high then chances are you will limit the practical usablility. Lets say you want to make a half bridge, but you want cycle by cycle current limit. Then you realize you need slope compensation so you need dac trigger. Perhaps the adc measurements are noisy so you need adc trigger and perhaps external fault input etc etc. Adding all these things on all the high level types will probably scale badly. So a lot of times I think you end up having to do your own higher level abstraction almost on a case by case basis. However, I very much hope I am wrong, please convince me :). I still think it is great to have some topologies as a showcase and a starting point for users though.

This is the reason I think it is very important to have a powerful low level API (which stm32-hrtim tries to be) that does not get in your way but still offers plenty of protection from all potholes when you build things on top of it. Ideally you should never need to access registers directly and stm32-hrtim should be used instead. If the need ever arises, maybe it should have some very explicit escape hatch if there is something important that can not be done in a safely checked manner.

Currently the stm32-hrtim API is a bit limited for what can be done after init. I have been quite conservative with that since there are a lot of edge cases for those type of things. For some of the settings, such as dead time, we even set the lock bits on init. In my projects, that has not really turned out to be an issue but that could probably be expanded upon a quite a bit if there is a need for it.

Other than that, there are also a lot of weird trait bounds etc that might be simplified and cleaned up. There is no way to automatically set a frequency without having to manually calculate the period and prescaler, which I suppose could be nice etc. Overall the API does not yet cover everything.

---

As for this PR, I think your high level APIs are best suited for embassy and should preferably be built on top of the types etc from stm32-hrtim as is done now with the half bridge and resonant converter. If you find any limitations in the process of doing that then PRs/issues are very much welcome for stm32-hrtim.

Anyways this is just my personal view and others might not agree. I am happy to discuss either way :)

[hatimthayyil]

I agree with your points on needing a flexibile low-level API. And that examples might be the appropriate location to showcase topologies using the low-level API.

The full bridge topology was something that I needed for a project. It was straightforward to use your library to setup what I needed (#5450). I can help clean up your API, please let me know if you need.

[Dirbaio]

We need to have the hrtim driver in-tree and make it consistent with the design of the rest of the HAL.

• The design of the stm32-hrtim API is the opposite of the Embassy HAL design: it's very typestate and generic-heavy, it uses extension traits.
• It uses the svd2rust-based PACs which build very slowly and are inconsistent with stm32-metapac.
• Docs quality suffers. You have to jump between crates. Docs for a trait doesn't show up implementors in downstream crates. e.g. if you look at Output1Pin you have no idea what types from embassy-stm32 impl it. It doesn't show up in the docs for embassy-stm32 either. The only way to know is to look at the source.
• We already tried external drivers with bxcan and fdcan, and the conclusion was it's a mistake for the reasons above. see Port fdcan HAL module to use PAC directly instead of fdcan crate. #2571 Use stm32-metapac for BXCAN. #2650