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]

Apologies for stalling on this, I was waiting on 10kOhm resistors to arrive, and they did last week. I added them to the bench circuit, but they didn't help. The device still returns garbage to the host using SDIO in SPI-mode.

I'm honestly at a loss for what else to even try. The communication at this phase of the SDIO protocol is all happening in hardware in the SPI and SDIO DMA engines, so it feels like even hooking something like probe-rs into the loop won't do much good. If anyone has other ideas on how to continue debugging this issue, I'm willing to try whatever approach looks most promising.

Edit: there does appear to be a GPIO IRQ firing on the SDIO device side, so maybe I need to setup a handler? From our discussions before, I thought that the low-level SDIO protocol was handled in hardware because any software would be too slow (including an IRQ handler). Am I missing something?