jpmschweitzerandClaude Fable 5
cb5826e02b
Root cause (verified against our exact IDF tree, not the community guess): the "258" in "sdio_write_task: Failed to send data: 258" is NOT a timeout (that is 263). 258 = 0x102 = ESP_ERR_INVALID_ARG. On the ESP32-P4, block- mode CMD53 writes require the SOURCE buffer to be 64-byte (cache-line) aligned; the IDF sdmmc driver rejects a misaligned source with INVALID_ARG BEFORE any bus activity. esp_hosts write loop then declares "Unrecoverable host sdio state" and reboots the whole P4. The audio TX payload is not 64-aligned, so streaming mic audio wedged on the very FIRST frame (which is exactly what we saw: listening -> instant Failed to send -> reboot). This also explains why buffer/queue/clock/retry tuning all did nothing: the write never reached the bus. And why our symptom was instant, not after ~100 writes (the community block-mode-desync theory) — it is the first misaligned buffer, every time. Fix: vendored esp_hosted 2.12.11 as an editable local component (overrides the registry copy) and bounce a misaligned TX payload through one aligned DMA scratch buffer in hosted_sdio_write_block (port_esp_hosted_host_sdio.c). TX is serialized by the bus lock so a single static bounce buffer is safe; freed in hosted_sdio_deinit. Host-only change — no C6 reflash. VERIFIED ON HARDWARE (autonomous self-test): 40s of continuous mic-audio upstream streaming — the traffic that previously wedged on the first frame — ran clean, zero timeouts, zero reboots. A guarded SDIO_TX_SELFTEST harness is kept (compiled out) for future SDIO stress testing. Credit: root cause + patch designed via multi-agent investigation; the precise 258=INVALID_ARG decode (correcting the upstream community timeout assumption) came from checking our actual esp_err.h. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
196 lines
8.1 KiB
Markdown
196 lines
8.1 KiB
Markdown
# Design Considerations and Debugging ESP-Hosted
|
|
|
|
**Table of Contents**
|
|
|
|
- [1. Choosing the Correct ESP chip as Slave](#1-choosing-the-correct-esp-chip-as-slave)
|
|
- [1.1. Using ESP chip as Hosted Master](#11-using-esp-chip-as-hosted-master)
|
|
- [2. General Hardware Considerations](#2-general-hardware-considerations)
|
|
- [2.1. GPIOs used for interface](#21-gpios-used-for-interface)
|
|
- [2.2. Quick PoC with Jumper Cables](22-evaluate-with-jumpers-first)
|
|
- [2.3. Whenever possible, Use `IO_MUX` GPIOs.](#23-whenever-possible-use-io_mux-gpios)
|
|
- [2.4. Signal Length and Noise Reduction](#24-signal-length-and-noise-reduction)
|
|
- [3. General Debugging Guidelines](#3-general-debugging-guidelines)
|
|
- [3.1. Add tapping points to your PCB prototype](#31-add-tapping-points-to-your-pcb-prototype)
|
|
- [3.2. Tap out additional GPIO signals as testing points and future expansion](#32-tap-out-additional-gpio-signals-as-testing-points-and-future-expansion)
|
|
- [3.3. Verifying Hosted Interface with Raw Throughput](#33-verifying-hosted-interface-with-raw-throughput)
|
|
- [4. Others](#4-others)
|
|
- [5. References](#5-references)
|
|
|
|
There are several considerations that need to be taken into account
|
|
when implementing ESP-Hosted for your system.
|
|
|
|
## 1 Choosing the Correct ESP chip as Slave
|
|
|
|
For prototyping, any ESP32 chip can be used as the slave, provided it
|
|
has the required interface (SPI, SDIO). But when creating an actual
|
|
product, it is important to select the proper ESP32 chip as a Hosted
|
|
Slave.
|
|
|
|
There are many ESP32 chips, each with difference features and
|
|
performance capabilities. Based on your product requirements
|
|
(interface to use, CPU, memory, power requirements, etc.), choose the
|
|
ESP32 chip(s) that can meet your requirements.
|
|
|
|
Use the ESP Product Selector guide to help you decide which ESP32
|
|
chips and/or modules are suitable for your product.
|
|
|
|
> [!NOTE]
|
|
> See [References](#5-references) for links to the Selector Guide
|
|
> and other links.
|
|
|
|
## 1.1 Using ESP chip as Hosted Master
|
|
|
|
The project defaults to using an ESP chip as the Hosted Master. This
|
|
is to act as a reference platform and make it easier to evaluate and
|
|
test Hosted before porting it to your MCU of choice.
|
|
|
|
## 2 General Hardware Considerations
|
|
|
|
### 2.1 GPIOs used for interface
|
|
|
|
Make sure the correct GPIOs pins on the Hosted Slave and Master are
|
|
connected together. Verify that the correct GPIOs are set-up in
|
|
`Menuconfig` for both the Slave and Master.
|
|
|
|
> [!NOTE]
|
|
> In general most ESP GPIOs can be used for input and output. But on
|
|
> the ESP32, some GPIOs can only be used for input and are not usable
|
|
> under Hosted. Check the ESP datasheet to verify the GPIOs you select
|
|
> can be used as a Hosted interface.
|
|
|
|
### 2.2 Evaluate with jumpers first
|
|
|
|
It is flexible to evaluate with jumper cables or bread board than full-fledged PCB.
|
|
In general, SPI (Standard & Dual SPI) imposes fewer hardware requirements compared to
|
|
SDIO. SPI is easier to prototype, and available on more ESP chips and
|
|
MCUs compared to SDIO.
|
|
Before going to SDIO 4 bit mode PCB, it's better to evaluate SDIO 1-Bit mode.
|
|
|
|
Once you evaluate the solution on jumper cables, you can move to PCB solutions with same or high performance transport.
|
|
|
|
###### Jumper cable considerations
|
|
- Use high quality jumper cables
|
|
- Use jumper cables as small as possible. you can cut and solder the joints if need be.
|
|
- Use equal length jumper cables for all the connections
|
|
- Grounds: Connect as many grounds as possible, this lowers the interference.
|
|
- Jumper cable lengths
|
|
- Standard SPI: At max 10cm, lower the better
|
|
- Dual SPI: At max 10cm, lower the better
|
|
- SDIO 1 Bit: At max 5cm, lower the better
|
|
- Quad SPI : jumpers not supported, only PCB
|
|
- SDIO 4 Bit: Jumpers not supported, only PCB
|
|
|
|
### 2.3 Whenever possible, Use `IO_MUX` GPIOs.
|
|
|
|
In general, ESP peripheral interfaces can be assigned to any available
|
|
GPIO through a multiplexer. But some ESPs have dedicated GPIOs for
|
|
peripherals (`IO_MUX`). These `IO_MUX` GPIOs have better timing
|
|
characteristics and support higher frequencies. They should be use
|
|
when possible to minimise timing and skew issues when using the
|
|
interface for Hosted.
|
|
|
|
> [!NOTE]
|
|
> The SDIO interface on the ESP32 and ESP32-C6 have fixed GPIO
|
|
> assignments and cannot be changed.
|
|
|
|
### 2.4 Signal Length and Noise Reduction
|
|
|
|
For best performance, a PCB with traces should be used to connect the
|
|
Hosted Slave and Master. For prototyping, jumper cables can be used,
|
|
but may only work at a lower `CLK` frequency.
|
|
|
|
In general, keep the cable and PCB traces short and of the same
|
|
length, to minimise propagation delay and clock skew:
|
|
|
|
- for SPI, keep them to 10 cm or less
|
|
- for SDIO, keep them to 5 cm or less
|
|
|
|
Isolate the interface signals, especially the `CLK` signal, from other
|
|
signals. For PCBs, surround the signal switch a ground plane, and keep
|
|
the `CLK` signal clean by not routing it close to other high frequency
|
|
signals.
|
|
|
|
For jumper cables, you can try surrounding the signals, especially the
|
|
`CLK` signal, with grounded wires to shield them from interference.
|
|
|
|
> [!NOTE]
|
|
> For SDIO, external pull-up resistors (recommended value: 51 kOhms)
|
|
> are required. Using jumper cable are **not** recommended for SDIO. You
|
|
> may be able to get SDIO working with jumper cables by using a lower
|
|
> `CLK` frequency and using 1-bit SDIO mode.
|
|
|
|
> [!NOTE]
|
|
> Also check the Hosted documentation for SPI and SDIO for more
|
|
> information and guidelines on the interfaces.
|
|
|
|
## 3 General Debugging Guidelines
|
|
|
|
### 3.1 Add tapping points to your prototype
|
|
|
|
Adding tapping points or headers to the Hosted interface signals on
|
|
your prototype will make it easier to check whether the Hosted
|
|
interface is working as expected.
|
|
|
|
### 3.2 Tap out additional GPIO signals as testing points and future expansion
|
|
|
|
Add tapping points to some unused GPIOs on both the Hosted Slave and
|
|
Host on your prototype PCB. This can later be use for debugging or
|
|
enhancing your own Hosted code.
|
|
|
|
For example, add your own debugging code to the Hosted Slave and
|
|
Master code to set a GPIO value when a condition is met. This GPIO can
|
|
be used to light a LED or trigger a capture on an oscilloscope or
|
|
logic analyzer, for example. This is useful for capturing rare or
|
|
intermittent conditions while testing Hosted.
|
|
|
|
In the future, Hosted may also offer newer transport options or more features, like controlling
|
|
power modes on the Host and Slave. These may require additional GPIOs
|
|
for control, so it would be good to keep some additional GPIOs
|
|
available and accessible for future use.
|
|
|
|
### 3.3 Verifying Hosted Interface with Raw Throughput
|
|
|
|
ESP-Hosted has a Raw Throughput Option to test sending of data between
|
|
the Host and Slave. This can be used to verify the hardware for signal
|
|
errors and to check the achievable throughput of Hosted.
|
|
|
|
> [!IMPORTANT]
|
|
> Use this option to verify that Hosted hardware and software are
|
|
> working as expected before involving other software layers like
|
|
> networking.
|
|
|
|
To enable the Raw Throughput Option on Slave, enter `Menuconfig` and
|
|
enable **Example Configuration** ---> **Hosted Debugging** --->
|
|
**RawTP**.
|
|
|
|
To enable the Raw Throughput Option and set Raw Throughput direction
|
|
on Host, enter `Menuconfig` and enable **Component config** --->
|
|
**ESP-Hosted config** ---> **Debug Settings** ---> **RawTP**. Set
|
|
the data transfer direction: **Host to Slave**, **Slave to Host** or
|
|
**Bidirectional**.
|
|
|
|
## 4 Others
|
|
|
|
Check the References below for links to the Product Selector, and more
|
|
detailed information on the interfaces used in Hosted. If you have
|
|
other issues with Hosted, you can check the Troubleshooting Guide.
|
|
|
|
You can also raise an Issue on the ESP-Hosted Github repository. Check
|
|
that the issue has not already been raised before submitting. The
|
|
solution to your problem may have already been provided.
|
|
|
|
## 5 References
|
|
|
|
**External Links**
|
|
|
|
- ESP Product Selector: https://products.espressif.com/
|
|
- ESP-Hosted Github Issues: https://github.com/espressif/esp-hosted-mcu/issues
|
|
|
|
**ESP-Hosted Documentation Links**
|
|
|
|
- SPI Full Duplex interface documentation: [spi_full_duplex.md](spi_full_duplex.md)
|
|
- SDIO interface documentation: [sdio.md](sdio.md)
|
|
- SPI Half Duplex interface documentation: [spi_half_duplex.md](spi_half_duplex.md)
|
|
- UART documentation: [uart.md](uart.md)
|
|
- Troubleshooting Guide: [troubleshooting.md](troubleshooting.md)
|