Stable driver tracking issue

[MabezDev]

Of the four drivers we're choosing to stabilize initially, we need to analyse them and determine a number of things.

• Does the driver meet all expectations in the API-GUIDELINES document?
  • This is not just limited to the driver itself, but any substructs, configs, helpers - everything
• Does the driver encapsulate the hardware it's designed to drive?
  • Does it offer an API that utilizes all hardware features?
  • If it doesn't, will the current API prevent us from adding that additional support in the future?
    • We should analyse the TRMs and find extra modes / alternate operation features
    • This is really important to think about, once we commit it will be a long time before we can change anything.
    • We don't need to support everything in 1.0, but we must design a driver that it extensible beyond 1.0 (without breaking changes)
• Can the driver as a whole be stabilized?
  • Perhaps some parts/modes are not a polished and stable as other parts of the driver
  • Could we partially stabilize some of this
  • We should be conservative at first, and we can relax some unstable flags as the beta phase progresses before 1.0

Please note that this is analysis work that needs to be done, here we will analyse what's wrong. Once the analysis is complete, we can do the following:

• Depending on the result of some parts, fix the code (light refactors, like naming etc)
• Mark part of the driver as unstable
  • Remember this is not 1.0 yet, we can relax some of these prior to 1.0

• Stable driver: GPIO #2492
• Stable driver: UART #2495
• Stable driver: I2C master #2493
• Stable driver: SPI master #2494

[Dominaezzz]

Will this include trait implementations?

For example, Spi implements e-hal 0.2 traits. Will these impls be considered stable too?

e-hal aside what about other trait libraries that are not themselves stable?

[bugadani]

For example, Spi implements e-hal 0.2 traits. Will these impls be considered stable too?

We can't depend on any <1.0 crates that are visible in our public API.

[bjoernQ]

For example, Spi implements e-hal 0.2 traits. Will these impls be considered stable too?

We can't depend on any <1.0 crates that are visible in our public API.

In theory we could mark those impls as unstable forever - but ideally, we could get rid of those

[bugadani]

We should probably do a review of the common bits as well. For example Peripheral/PeripheralRef are in violation of C-SMART-PTR - if they count as smart pointers. Also some Rust API guidelines are crate-wide rules.

[bugadani]

Types should be UpperCamelCase, but peripheral instances are UPPERCASE (SCREAMING_SNAKE_CASE?). We should probably mention these as exceptions.

[bugadani]

Issues not specific to drivers:

• Make set_interrupt panic free #2760
• Builders should annotate the setters with #[must_use] #2745
• [RFC] MSRV policy going forward #2736
• Document using peripheral drivers in generic contexts #2706
• Stabilizing CpuClock #2663
• Evaluate the Peripheral and Peripheral ref module #2661
• Resolve C-METADATA violations #2627
• Resolve C-EXAMPLE violations #2623
• Create non-trivial example applications which encapsulate all required dependencies and configuration #2596
• Explore how private dependencies with links = affect esp-hal #2589
• Auto generate chip support status for docs #2584
• [RFC] The value of new_typed vs always type erasing drivers #2572
• Ensure the PAC crates are never exposed publicly #2525
• [RFC] Should config options affect the public API? #2509
• Add linker scripts (and any additional required code) to support mcuboot #2479
• re-building esp-riscv-rt on top of riscv-rt 0.13.0 #2390
• ESP32: RTC domain must be initialized on boot #2105
• [RFC] Explore and decide on a bootloader option  #1973
• RFC: Provide consistent APIs for configuring clock sources for peripheral drivers #1668
• Private details should not leak into the public API #2766
• C-GOOD_ERR - implementing the Error trait #2780