Merging stm32-rs HALs into one unified STM32 HAL

[FeldrinH]

I think it would be valuable to have a unified stm32-rs HAL for all STM32 variants, similar to how esp32-rs and Embassy have a single HAL.

An annoyance that I've encountered with the current set of HAL-s is that different HAL-s seem to have slightly different API-s for various peripherals and this leads to friction when working with multiple HAL-s. Also the quality and completeness of HAL-s varies a lot. A unified HAL would help a lot to solve these pain points.

It might also help ease the maintenance burden. I figure having the common parts shared and a common API established would reduce duplicate effort accross HAL-s and help speed up the process of adding support for new STM32 device families.

If there is interest in working towards merging the HALs from the maintainers of individual HALs, then I hope this issue can serve as a common place for working towards a unified HAL. I myself am open to contributing to developing a unified HAL, though unfortunately I don't have time to be a long-term maintainer of the project.

I would love to hear the thoughts of current HAL maintainers on this proposal (@burrbull, @astapleton, @usbalbin, @newAM, @therealprof).

Related discussions: rust-embedded/embedded-hal#61, stm32-rs matrix chat.

[newAM]

I think it's a good idea, but it's a lot of work. Structurally I think a unified HAL would need to be in a single repo, similar to how embassy-stm32 does it. As far as I know the embassy-stm32 HAL can be used without embassy; what would a unified HAL offer that isn't offered by embassy-stm32 currently?

[FeldrinH]

As far as I know the embassy-stm32 HAL can be used without embassy; what would a unified HAL offer that isn't offered by embassy-stm32 currently?

A valid question, but I think this question is equally valid for the current HALs. What do the current stm32-rs HALs offer that embassy-stm32 doesn't?

In my mind the main goal of a unified HAL is reducing ecosystem fragmentation. If embassy-stm32 already fills the role of a unified HAL then a more radical possibility is to just deprecate the stm32-rs HALs and direct maintenance resources to embassy-stm32. I don't know if that is feasible in practice, but it seems like a valid alternative in theory.

[burrbull]

stm32-rs/stm32f4xx-hal#667 (comment)

@eldruin @dotcypress @adamgreig @nisembedded @richardeoin @David-OConnor

[David-OConnor]

I think you would need to secure agreement from all relevant HAL maintainers, and willingness from them to either make the change, or allow someone else to. You would also need to reach an agreementson how to handle each case where the API differs. You might need to grant someone a decision-making authority to prevent things from getting deadlocked and stalling when these happen.

Alternatively, someone could create a new repo in the spirit of one or more of these libs, and copy a mix of code, and API (which might have different code) . It would strive for API and design parity with one or more of them, but would be sort of a fork. This might be the easier path, but it introduces the problem of fragmenting the ecosystem, since one or more original maintainers wouldn't have blessed the new one.

You're explicitly seeking this agreement here, so we will see what the answers are!

[nisembedded]

I don't see any cons about this. It will better for consistency and for support new series of stm32 which have no many maintainers yet. Like stm32c0xx, u5, etc. Also will be better to see option like nightly features and use the night version of stm32 PAL, or even stop using it anymore.

[therealprof]

I'm not opposed to this idea, however it is a boatload of work and is only sustainable if there're enough contributors and maintainers driving it forward. There might be some synergy effects by doing it all in one but then again there're enough variants to make it a lot of work to figure out a common scheme. It's also questionable if there's a benefit of a different approach over embassy-stm32 to make it worthwhile to start over. I have my serious doubts about that and would note that even embassy-stm32 is somewhat incomplete in various areas...

[burrbull]

I think this should be done step by step.

1. Allow to review PRs in all -hal crates for all active maintainers from other hal crates. So we can help to each other.
2. Make a list of APIs from different hals (with link) which we consider good or acceptable. And spread them to other hal.
3. Only after these steps we can decide how to reorganize crates:
   a. One crate to rule all families.
   b. Leave all as it is.
   c. Something in between. Crates that collect several similar families. Like F2+F4+F7, G0+C0, H5+U5, etc.

The separate question is should we collect all repos in one from start?
Advantage is we can skip first step and partially third.
Disadvantage: this big work somebody should do and also see "15 competing standards" meme.

[usbalbin]

Maybe we should summarize what makes this different from embassy's hal?

[David-OConnor]

Note: As of PAC 0.16, many of the cases of PAC syntax differences for equivalent registers among variants have gone away.

I made heavy use of the cfg_if macro, and feature gates in general. Sometimes for whole families, sometimes for specific variants. If you embark up on this quest, I will borrow any good ideas you come up with that makes the code easier to read and maintain. Of special interest is timer handling. That will likely be the biggest challenge.

For example, I recently found the cfg_aliases lib. It lets you set up combined feature gates. Wish I knew of that earlier!

[astapleton]

As others have said, this is a big task that someone needs to own and have the motivation to finish. I think it's going to require quite a bit of design work up front to figure out how to elegantly abstract across the differences in families without sprinkling conditional compilation directives everywhere (good source of bugs in my experience).

I think an alternative approach to going straight for a monolithic HAL crate, and that could be expanded as one goes, is to break out a single peripheral for which to make a universal driver that can then be integrated into the various HALs and replace the implementations therein. It's likely that that would surface a lot of the difficulties while allowing for a smaller up front cost in time. Each of the maintainers in the various HALs could then find where it comes up short. Once that is settled, tackle another peripheral until most are using the shared peripherals. From there we would have a good idea of the remaining effort and whether it's worth integrating all the families into a single crate, or stick with shared driver crates.

In terms of choices, I would vote for one of the peripheral drivers covered by embedded-hal, given that they are the most widely used, it seems. Or perhaps it should be something particularly tricky, like the timers.

[therealprof]

@astapleton That has been suggested before and indeed seems to be one of the most promising approaches, however there's one major caveat: The owned PAC singleton which makes it really hard to have separate HALs sharing driver implementations for individual peripherals via dedicated crates.

[newAM]

If embassy-stm32 already fills the role of a unified HAL then a more radical possibility is to just deprecate the stm32-rs HALs and direct maintenance resources to embassy-stm32.

I am willing to do this for the stm32wlxx-hal, I have already been directing people who ask me questions about the HAL on matrix to use embassy instead because it is more complete than stm32wlxx-hal. I am not sure if this holds true for all HALs, but I think it would be easier to add missing features to embassy than starting from scratch.

[astapleton]

@astapleton That has been suggested before and indeed seems to be one of the most promising approaches, however there's one major caveat: The owned PAC singleton which makes it really hard to have separate HALs sharing driver implementations for individual peripherals via dedicated crates.

Maybe I'm missing something, but why is that an issue? If the driver crate is integrated into the individual PAC and provides it's own extension trait to take ownership of the SPI peripheral, like most stm32 HAL drivers do, what would be the difference?

[FeldrinH]

I think an alternative approach to going straight for a monolithic HAL crate, and that could be expanded as one goes, is to break out a single peripheral for which to make a universal driver that can then be integrated into the various HALs and replace the implementations therein. It's likely that that would surface a lot of the difficulties while allowing for a smaller up front cost in time. Each of the maintainers in the various HALs could then find where it comes up short. Once that is settled, tackle another peripheral until most are using the shared peripherals. From there we would have a good idea of the remaining effort and whether it's worth integrating all the families into a single crate, or stick with shared driver crates.

I think it's better to have a clean break with no dependency between the unified HAL and existing HALs. A clean break would allow the unified HAL a lot more freedom to change the API in ways that are not compatible with the existing HALs.

Also, I suspect breaking out individual peripherals will end up being more work alltogether, even though the individual chunks are smaller.

[astapleton]

In terms of why not use embassy, I'm not super enthusiastic about the HAL for the processor family being owned by an organization that has its own potentially incompatible interests. While I don't have any problems with the embassy organization (and plan to use embassy myself!), I feel like putting the destiny in their hands invites potential conflicts of interest down the line (e.g. maybe they don't want to allow support for a competing runtime). I would much rather it belong to a community that is simply focused on providing a HAL for the processor family.