sdio: initial SDIO HAL implementation

[rmsyn]

Thank you for your contribution!

We appreciate the time and effort you've put into this pull request.
To help us review it efficiently, please ensure you've gone through the following checklist:

Submission Checklist 📝

• I have updated existing examples or added new ones (if applicable).
• I have used cargo xtask fmt-packages command to ensure that all changed code is formatted correctly.
• My changes were added to the CHANGELOG.md in the proper section.
• I have added necessary changes to user code to the Migration Guide.
• My changes are in accordance to the esp-rs developer guidelines

Extra:

• I have read the CONTRIBUTING.md guide and followed its instructions.

Pull Request Details 📖

Description

Provides the initial skeleton for the embedded_hal::mmc::MmcOps implementation for the SDIO peripherals on the ESP32C6 microcontroller.

Testing

Doc tests for now.

Integration tests via examples program is WIP.

[rmsyn]

Running the CI / * checks are failing, partially due to some weird dependency resolution.

As I get closer to a full implementation, I may need to bring in the embedded-hal::mmc::* stuff locally to avoid the git dependency.

What's strange is that running cargo clippy ... directly passes, but the xtask lint-packages can't resolve the embedded_hal::mmc::MmcCommon trait, and fails to build the embassy-hal-async examples.

I'll keep debugging.

[bugadani]

It would be best to not block this PR on embedded-hal, as it'll likely take months to stabilize a new set of traits. You should instead demonstrate new functionality in a new crate, like embedded-sdmmc in the embedded-hal repository, so that it can be released unstably and implemented by esp-hal and one other required implementor.

That way you wouldn't have to patch around the dependency issues with multiple embedded-hal versions in the same project.

[MabezDev]

To expand on @bugadani's comment, we can't merge this with git dependencies, so I would take the suggestion to split this into a separate crate and then work on upstreaming to eh proper. Feel free to iterate here in the mean time, but if you want this merged it won't be with a fork of embedded-hal.

[rmsyn]

It would be best to not block this PR on embedded-hal, as it'll likely take months to stabilize a new set of traits. You should instead demonstrate new functionality in a new crate, like embedded-sdmmc in the embedded-hal repository, so that it can be released unstably and implemented by esp-hal and one other required implementor.

This sounds like a good plan. I'll bring it up in next week's meeting, and see what the rest of the HAL team thinks.

To expand on @bugadani's comment, we can't merge this with git dependencies, so I would take the suggestion to split this into a separate crate and then work on upstreaming to eh proper. Feel free to iterate here in the mean time, but if you want this merged it won't be with a fork of embedded-hal.

Right, I had no intention of trying to get this PR merged with the git dependency. My original thought process was to prove the implementation here and in jh71xx-hal, iterate on the trait in embedded-hal, stabilize in embedded-hal, and take this PR out of Draft status after an embedded-hal release that includes the mmc module + traits.

However, the solution discussed above sounds like a better plan. We could do a embedded-hal-sdmmc v0.1.0-alpha.whatever release, and base the work off that crate until mmc stuff gets merged upstream (if ever).

Without trying to bikeshed too much, we would probably need to call it embedded-hal-sdmmc, since @thejpster already has embedded-sdmmc-rs. embedded-hal-sdmmc also keeps with the naming convention of embedded-hal-[async, io, nb, ...].

[rmsyn]

I added the remaining functions needed for the SDIO init implementation.

Not sure about the best way to approach SOC-specific methods (i.e. the low_level_* methods). The methods do more-or-less the same thing on each SOC, but the register names are different, especially between the ESP32 and ESP32-C6 interrupt naming conventions.

One design I though of was to add a SdioLowLevel trait, and implement the trait on SOC-specific data structures, instead of the Any<Peripheral> types.

@Dominaezzz @MabezDev @bugadani thoughts?

[Dominaezzz]

Regarding the low level stuff, see #1282 . Whilst esp-idf serves as a (mostly reliable) working reference, its design decisions (which were made for a C library) shouldn't be copied directly (into a Rust hal).

Check out what the stable(izing) drivers (SPI, I2C, UART, GPIO) are doing to get an idea of what to do. Also the dev guidelines is another place to check.

imo, for chip-based differences, cfgs are more appropriate than traits. traits are more appropriate for peripheral-based differences on the same chip.

[rmsyn]

Whilst esp-idf serves as a (mostly reliable) working reference, its design decisions (which were made for a C library) shouldn't be copied directly (into a Rust hal).

Agreed, I kept the relative structure of the code the same. It should hopefully make reviewing the code easier, since the mapping from the Rust back to the esp-idf function names is pretty close. I obviously changed the functions to be idiomatic Rust.

imo, for chip-based differences, cfgs are more appropriate than traits. traits are more appropriate for peripheral-based differences on the same chip.

This is the approach I ended up going with, which can hopefully be extended pretty easily as more SDIO-having SOCs are added.

[rmsyn]

Rebased on the latest main (d9815b205) for the 1.0.0 release changes. Hopefully, shouldn't need any further rebases.

Cleaned up the commit history to remove fixup commits, and squashed the first three commits to get rid of the changes that included the embedded-hal fork.

The qa-test integration tests are reliably performing bit transfers again, though I think I need to implement SDIO interrupt handlers to properly follow the ESP SDIO protocol.

Should I use SoftwareInterrupt, or is there a configured hardware interrupt for SDIO? Asking specifically about configuring the handler, since the SDIO interrupt sources are all in registers.

It's also unclear to me if the SDIO device sends the interrupt over the wire, e.g. in SPI mode. The qa-test integration tests are running on separate devices, so they can't access the source interrupt registers directly (obviously). My assumption is that the source interrupt register is set, e.g. device interrupts host, some hardware magic happens, the interrupt is transferred over the wire, some hardware magic happens on the host, the host hardware interrupt handler fires. Does this sound correct?