HAL Design Philosophy

[jessebraham]

In a PR @bjoernQ had mentioned:

Maybe it's also a good occasion to think about the general philosophy of the HAL (i.e. should it be as much "batteries-included" as possible or not). While there are a lot of wild assumptions currently (e.g. regarding the various clock speeds) which we need to address there are also other things more similar to this (e.g. is synchronization something that should be taken care of at the call-site (with some hints in the docs where needed) or not)

This discussion has been created with the intent of trying to solve some of these problems.

[jessebraham]

Going to do a bit of a brain-dump just to get this out in the open, will likely add on to it later. Feel free to discuss these and/or add your own points.

• The esp-hal-common crate should be invisible to the end user
• We should prohibit invalid configuration/states using type states whenever possible
• We should allow the use of any (or no) second-stage bootloader, and not assume that the ESP-IDF bootloader is being used
• Any crates used internally by the HAL which may also need to be used by the end user (eg. embedded-hal) should be re-exported by the HAL

[bjoernQ]

I agree on all of the above - especially the thing about as much compile-time-safety as possible.

For the "not depend on ESP-IDF bootloader" we could try MCU-boot until we have some minimal (direct-boot like) bootloader written in pure Rust to verify that - I guess we will need some specific init code for every bootloader we will support? e.g. NuttX does some different things when ESP-IDF bootloader or MCU boot is used. But I really like the idea of a pure Rust minimal-bootloader

One thing I really don't have a strong opinion on: Concurrency. I looked at different HAL implementations and seems like some don't care at all and some do care. In most situations exclusive ownership of the peripheral should do the trick for us but some peripherals are used in multiple places (for enabling peripherals and interrupt configuration / reset at least) - in those places we just use raw-pointers from the PAC which will cause problems when modified concurrently. One solution could be to move that functionality elsewhere and enforce ownership. That however will be much less convenient - if not problematic in some situations - at the call site. Not even sure if we can do that really for everything

[jessebraham]

They do some multi-core stuff in rp-hal:
https://github.com/rp-rs/rp-hal

Haven't dug into it yet but might be some inspiration at the very least.