Add stack trace analysis and manual exception decoder instructions

Enhanced crash analysis to help diagnose the LoadStorePIFAddrError:

Workflow improvements:
- Extract and display backtrace addresses from crash logs
- Identify crash location (PC register)
- Provide detailed manual decoding instructions
- Added 3 methods to decode: PlatformIO, addr2line, online tool
- Explain EXCCAUSE codes and what they mean
- Show crash analysis guidance for QEMU vs real bugs

Documentation improvements (QEMU-ISSUES.md):
- Complete list of ESP32 exception types with codes
- Detailed explanation of LoadStorePIFAddrError (0x0000000f)
- Why it's common in QEMU (hardware register access)
- Step-by-step decoder usage for all 3 methods
- Example decoded output format
- How to analyze crash location (registers, addresses)
- Common QEMU-specific crash patterns
- Clear guidance on QEMU limitation vs real bug

The LoadStorePIFAddrError at 0x401771aa is likely ethernet MAC
initialization hitting unimplemented QEMU hardware features.

Co-authored-by: softhack007 <[email protected]>

Author: Copilot

.github/workflows/qemu-e2e-test.yml

@@ -176,13 +176,63 @@ jobs:
               echo "ESP32 Exception/Crash detected in QEMU output!"
               echo ""
               echo "=== Exception Context ==="
-              grep -A 20 -B 5 -i "exception\|abort\|backtrace\|panic\|guru meditation" qemu-output.log | head -100
+              grep -A 25 -B 5 -i "exception\|abort\|backtrace\|panic\|guru meditation" qemu-output.log | head -150
+              echo ""
+              echo "=== Stack Trace Analysis ==="
+              # Extract backtrace if present
+              if grep -i "Backtrace:" qemu-output.log > /dev/null; then
+                BACKTRACE=$(grep -i "Backtrace:" qemu-output.log | tail -1)
+                echo "Raw Backtrace: $BACKTRACE"
+                echo ""
+                echo "Analyzing crash location:"
+                # Extract first address (PC/crash location)
+                CRASH_ADDR=$(echo "$BACKTRACE" | grep -oP '0x[0-9a-fA-F]+' | head -1)
+                if [ -n "$CRASH_ADDR" ]; then
+                  echo "  - Crash at address: $CRASH_ADDR"
+                  echo "  - This is likely in firmware code or ROM"
+                fi
+              fi
+              echo ""
+              echo "=== Manual Exception Decoder Instructions ==="
+              echo "To decode this crash manually:"
+              echo ""
+              echo "1. Download the 'esp32-firmware' artifact from this GitHub Actions run"
+              echo "2. Extract the firmware.elf file"
+              echo "3. Install ESP-IDF or use PlatformIO's exception decoder:"
+              echo ""
+              echo "   Method A - Using PlatformIO:"
+              echo "     pio device monitor --filter esp32_exception_decoder"
+              echo "     (Then paste the backtrace and exception info)"
+              echo ""
+              echo "   Method B - Using ESP-IDF addr2line:"
+              echo "     ~/.platformio/packages/toolchain-xtensa-esp32/bin/xtensa-esp32-elf-addr2line \\"
+              echo "       -pfiaC -e .pio/build/esp32_16MB_V4_M_eth_debug/firmware.elf \\"
+              echo "       0x401771aa 0x4015b4c5 0x40134813 ..."
+              echo ""
+              echo "   Method C - Using online decoder:"
+              echo "     https://github.com/me-no-dev/EspExceptionDecoder"
+              echo ""
+              echo "4. The decoded output will show:"
+              echo "   - Function names where the crash occurred"
+              echo "   - Source file locations (file:line)"
+              echo "   - Call stack leading to the crash"
+              echo ""
+              echo "=== Crash Analysis Guidance ==="
+              echo "Common crash causes in QEMU:"
+              echo "  - LoadStorePIFAddrError (0x0000000f): Invalid memory access"
+              echo "    * Often caused by accessing uninitialized pointers"
+              echo "    * Or accessing hardware registers not emulated by QEMU"
+              echo "    * Check if crash is in hardware/peripheral initialization code"
+              echo ""
+              echo "  - If crash is in ethernet/network code: May be QEMU limitation"
+              echo "  - If crash is in WiFi code: Expected - WiFi not emulated"
+              echo "  - If crash is in application code: Likely real firmware bug"
               echo ""
               echo "Note: This could be a QEMU-specific issue or a real firmware bug."
               echo "QEMU ESP32 emulation has limitations:"
               echo "  - Many peripherals are not fully emulated"
               echo "  - Some hardware features may cause crashes in QEMU but work on real hardware"
-              echo "  - Network/WiFi emulation is limited"
+              echo "  - Network/ethernet emulation may have issues"
             else
               echo "No ESP32 exceptions detected in QEMU output"
             fi

docs/QEMU-ISSUES.md

@@ -90,18 +90,130 @@ ESP32 QEMU emulation is not perfect and has several known limitations:
 
 ## Analyzing Crashes
 
-### Check Exception Type
-Common ESP32 exceptions:
-- `LoadProhibited`: Reading from invalid memory address
-- `StoreProhibited`: Writing to invalid memory address  
-- `IllegalInstruction`: Executing invalid code
+### Common Exception Types
+ESP32 exceptions with EXCCAUSE codes:
+- `0x00000000` (IllegalInstruction): Executing invalid code
+- `0x00000001` (Syscall): Syscall instruction
+- `0x00000002` (InstructionFetchError): Cannot fetch instruction
+- `0x00000003` (LoadStoreError): Load/store alignment error
+- `0x00000005` (LoadStoreAlignmentCause): Load/store alignment error
+- `0x00000006` (InstructionDataError): Data error during instruction fetch
+- `0x00000007` (LoadStoreDataError): Data error during load/store
+- `0x00000009` (LoadStorePrivilegeViolation): Privilege violation
+- `0x0000000f` (LoadStorePIFAddrError): Invalid PIF address (common in QEMU)
+- `0x0000001c` (InstructionAddrError): Address error during instruction fetch
+- `0x0000001d` (LoadStoreAddrError): Address error during load/store
+- `0x0000001e` (InstructionBusError): Bus error during instruction fetch
+- `0x0000001f` (LoadStoreBusError): Bus error during load/store
+
+### LoadStorePIFAddrError (0x0000000f)
+This is **very common in QEMU** and usually indicates:
+- Accessing hardware registers not emulated by QEMU
+- Accessing invalid memory-mapped peripheral addresses
+- Often occurs during peripheral initialization (I2C, SPI, ADC, etc.)
+- **May work fine on real hardware** - QEMU limitation
+
+### Decoding Crash Backtraces
+
+When you see a crash like:
+```
+Guru Meditation Error: Core 1 panic'ed (LoadStorePIFAddrError)
+Backtrace: 0x401771aa:0x3ffb2090 0x4015b4c5:0x3ffb20c0 ...
+```
+
+#### Method 1: Using PlatformIO Exception Decoder
+```bash
+# In the WLED-MM directory
+pio device monitor --filter esp32_exception_decoder
+
+# Then paste the exception output (registers + backtrace)
+# The decoder will show function names and file locations
+```
+
+#### Method 2: Using ESP-IDF addr2line
+```bash
+# Install toolchain (if not already from PlatformIO)
+~/.platformio/packages/toolchain-xtensa-esp32/bin/xtensa-esp32-elf-addr2line \
+  -pfiaC -e .pio/build/esp32_16MB_V4_M_eth_debug/firmware.elf \
+  0x401771aa 0x4015b4c5 0x40134813 0x40103cd0 0x40135d33 0x401383c6 0x4016107e
+```
+
+Replace the addresses with those from your backtrace.
+
+#### Method 3: Online Decoder
+1. Get firmware.elf from build artifacts
+2. Use https://github.com/me-no-dev/EspExceptionDecoder
+3. Paste exception info and upload firmware.elf
+4. Get decoded stack trace
+
+### Example Decoded Output
+```
+0x401771aa: emac_hal_init at components/hal/esp32/emac_hal.c:45
+0x4015b4c5: esp_eth_mac_esp32_init at components/esp_eth/src/esp_eth_mac_esp32.c:123
+0x40134813: NetworkClass::begin at wled00/network.cpp:234
+```
+
+This shows the crash occurred in ethernet MAC initialization - likely a QEMU emulation limitation.
+
+### Analyzing the Crash Location
+
+1. **Check the function names**: Are they in hardware/peripheral code?
+   - `emac_`, `i2c_`, `spi_`, `adc_`, etc. → Likely QEMU limitation
+   - Application functions → Likely real bug
+
+2. **Check EXCVADDR**: The address being accessed
+   - `0x3ff69xxx` range → Peripheral registers (QEMU issue)
+   - `0x00000000` or very low → Null pointer (real bug)
+   - Stack addresses → Possible stack overflow
+
+3. **Check PC (Program Counter)**: Where code was executing
+   - ROM addresses (`0x4000xxxx`) → ESP32 ROM functions
+   - Flash addresses (`0x400dxxxx - 0x4017xxxx`) → Your firmware
+   - RAM addresses (`0x4008xxxx`) → RAM-loaded code
+
+### Common QEMU-Specific Crashes
+
+#### Ethernet MAC Initialization
+```
+Backtrace: ... esp_eth_mac_esp32_init ... emac_hal_init ...
+```
+**Cause**: QEMU's ethernet emulation may not fully support all MAC features  
+**Action**: Check if ethernet link comes up; web server may still work
+
+#### I2C/SPI Peripheral Access
+```
+Backtrace: ... i2c_master_cmd_begin ... 
+```
+**Cause**: I2C peripherals not emulated  
+**Action**: Expected in QEMU; disable or mock peripheral access
+
+#### WiFi Functions
+```
+Backtrace: ... esp_wifi_init ... wifi_hw_init ...
+```
+**Cause**: WiFi not emulated  
+**Action**: Use ethernet build (already configured)
 
 ### Expected Behavior in QEMU
 For WLED testing in QEMU, we expect:
 - ✅ Web server to start successfully
 - ✅ HTTP requests to be handled
 - ✅ Web UI pages to load
-- ⚠️ WiFi operations to fail/be limited
+- ✅ Basic ethernet connectivity
+- ⚠️ WiFi operations to fail/be disabled
 - ⚠️ Some LED control features may not work fully
+- ⚠️ Peripheral access (I2C, SPI) may crash
+- ⚠️ Some hardware features cause QEMU-specific crashes
 
-See full QEMU logs in GitHub Actions artifacts.
+### Investigating Crashes
+
+1. **Download QEMU logs** from GitHub Actions artifacts
+2. **Find the exception** in qemu-output.log
+3. **Copy the backtrace addresses**
+4. **Decode using one of the methods above**
+5. **Analyze the decoded output**:
+   - Hardware access? → Probably QEMU limitation
+   - Application logic? → Likely real bug to fix
+   - Initialization code? → May need QEMU workaround
+
+See full QEMU logs in GitHub Actions artifacts (`qemu-logs`).