Fork fix: the SDIO wedge is FIXED (esp-hosted-mcu #167)
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>
This commit is contained in:
Claude Fable 5
@@ -0,0 +1,133 @@
|
||||
# ESP-Hosted-MCU Slave example
|
||||
|
||||
This document details the **ESP-Hosted MCU Slave Example**, demonstrating the slave firmware that provides Wi-Fi and Bluetooth connectivity to host MCUs via ESP32 series co-processors.
|
||||
|
||||
## Overview
|
||||
|
||||
The slave firmware enables host MCUs to utilize the Wi-Fi and Bluetooth capabilities of ESP32 series chips through **SDIO, SPI, or UART** interfaces. This minimal example focuses on basic connectivity; however, advanced features like Network Split and Host Power Save can be optionally configured for optimized network traffic and power management.
|
||||
|
||||
## Supported Co-processors and Transports
|
||||
|
||||
The following table summarizes the supported co-processors and transport communication buses between the slave and host. This example specifically utilizes **SDIO** as the transport and **ESP32-C6** as the slave co-processor.
|
||||
|
||||
| Transport Supported | SDIO | SPI Full-Duplex | SPI Half-Duplex | UART |
|
||||
|---|:---:|:---:|:---:|:---:|
|
||||
| **Co-Processors Supported** | | | | |
|
||||
| ESP32 | ✓ | ✓ | × | ✓ |
|
||||
| ESP32-C2 | × | ✓ | ✓ | ✓ |
|
||||
| ESP32-C3 | × | ✓ | ✓ | ✓ |
|
||||
| ESP32-C5 | ✓ | ✓ | ✓ | ✓ |
|
||||
| ESP32-C6/C61 | ✓ | ✓ | ✓ | ✓ |
|
||||
| ESP32-S2 | × | ✓ | ✓ | ✓ |
|
||||
| ESP32-S3 | × | ✓ | ✓ | ✓ |
|
||||
|
||||
|
||||
## Example Hardware Connections
|
||||
|
||||
This example uses the SDIO interface. The default SDIO pin connections for the ESP32-C6 slave are as follows:
|
||||
|
||||
### SDIO Interface (Default for ESP32-P4-Function-EV-Board)
|
||||
|
||||
| Signal | GPIO | Notes |
|
||||
|:-------|:-----|:------------|
|
||||
| CLK | 19 | Clock |
|
||||
| CMD | 18 | Command |
|
||||
| D0 | 20 | Data 0 |
|
||||
| D1 | 21 | Data 1 |
|
||||
| D2 | 22 | Data 2 |
|
||||
| D3 | 23 | Data 3 |
|
||||
| Reset | EN | Reset input |
|
||||
|
||||
For detailed SDIO hardware connection requirements, refer to the official documentation at [https://github.com/espressif/esp-hosted-mcu/blob/main/docs/sdio.md\#3-hardware-considerations](https://github.com/espressif/esp-hosted-mcu/blob/main/docs/sdio.md#3-hardware-considerations). The GPIO pins and transport can be configured as explained in later sections.
|
||||
|
||||
|
||||
## Quick Start Guide
|
||||
|
||||
### 1. Obtain the Slave Example
|
||||
|
||||
Execute the following commands to retrieve the slave example:
|
||||
|
||||
```bash
|
||||
idf.py create-project-from-example "espressif/esp_hosted:slave"
|
||||
cd slave
|
||||
```
|
||||
|
||||
### 2. Set Up ESP-IDF
|
||||
|
||||
It is presumed that ESP-IDF has already been set up. If not, please proceed with the setup using one of the following options:
|
||||
|
||||
#### Option 1: Installer Way
|
||||
|
||||
* **Windows**
|
||||
|
||||
* Install and set up ESP-IDF on Windows as documented in the [Standard Setup of Toolchain for Windows](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/windows-setup.html).
|
||||
* Use the ESP-IDF [Powershell Command Prompt](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/windows-setup.html#using-the-command-prompt) for subsequent commands.
|
||||
|
||||
* **Linux or macOS**
|
||||
|
||||
* For bash:
|
||||
```bash
|
||||
bash docs/setup_esp_idf__latest_stable__linux_macos.sh
|
||||
```
|
||||
* For fish:
|
||||
```fish
|
||||
fish docs/setup_esp_idf__latest_stable__linux_macos.fish
|
||||
```
|
||||
|
||||
#### Option 2: Manual Way
|
||||
|
||||
Please follow the [ESP-IDF Get Started Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html) for manual installation.
|
||||
|
||||
### 3. Set Target
|
||||
|
||||
Set the target co-processor using the command below:
|
||||
|
||||
```bash
|
||||
idf.py set-target esp32c6
|
||||
```
|
||||
|
||||
> [!TIP]
|
||||
> You can **customize** the target co-processor by replacing `esp32c6` with your desired ESP32 series chip.
|
||||
|
||||
### 4. Customizing Configuration: Transport and Features
|
||||
|
||||
This is optional step. By default, SDIO transport is pre-configured.
|
||||
|
||||
You can access the configuration menu to choose desired configuration and features using:
|
||||
|
||||
```bash
|
||||
idf.py menuconfig
|
||||
```
|
||||
|
||||
The default configuration tree looks like this:
|
||||
```
|
||||
Example Configuration
|
||||
└── Bus Config in between Host and Co-processor
|
||||
└── Transport layer
|
||||
└── Select transport: SDIO/SPI-Full-Duplex/SPI-Half-Duplex/UART
|
||||
└── <Other optional features>
|
||||
```
|
||||
|
||||
|
||||
> [!TIP]
|
||||
> You can optionally **customize** the transport layer (SDIO, SPI Full-Duplex, SPI Half-Duplex, or UART), their GPIOs in use and other optional features within this menu.
|
||||
|
||||
### 5. Build and Flash
|
||||
|
||||
Build and flash the firmware to your device using the commands below, replacing `<SERIAL_PORT>` with your device's serial port:
|
||||
|
||||
```bash
|
||||
idf.py build
|
||||
idf.py -p <SERIAL_PORT> flash monitor
|
||||
```
|
||||
|
||||
> [!TIP]
|
||||
> You can **customize** the serial port (`<SERIAL_PORT>`) to match your specific hardware connection.
|
||||
|
||||
|
||||
## References
|
||||
|
||||
- [ESP-Hosted MCU Documentation](../../README.md)
|
||||
- [ESP32-P4-Function-EV-Board Setup](../../docs/esp32_p4_function_ev_board.md)
|
||||
- [Transport Layer Documentation](../../docs/)
|
||||
- [Troubleshooting Guide](../../docs/troubleshooting.md)
|
||||
Reference in New Issue
Block a user