corr opencode (run debug flash)

AGENTS.md

@@ -18,7 +18,9 @@ This project uses a **dual-project architecture**:
 | **Boot** | `/Boot/` | Bootloader - initializes hardware, loads application from external flash |
 | **Appli** | `/Appli/` | Main application - TouchGFX UI + audio processing |
 
-**Flashing order**: Boot must be flashed first, then Appli. After flashing Appli, press NRST button to start.
+**Flashing order**: Boot must be flashed first (without loader), then Appli (with external loader). After flashing Appli, press NRST button to start.
+
+**Note**: The Appli uses external memory (0x70000000) for TouchGFX assets and requires the external FlashLoader `MX66UW1G45G_STM32H7S78-DK.stldr` to program the external flash.
 
 ## Project Setup
 
@@ -31,19 +33,20 @@ This project uses a **dual-project architecture**:
 ## Key Constraints
 
 1. **Dual-boot flashing sequence**: Flash Boot first, then Appli. Press NRST after Appli flash.
-2. **Never edit `Core/Src/` and `Core/Inc/` directly** - regenerate via STM32CubeMX instead
-3. **High-speed audio acquisition (48kHz)** - uses DMA for ADF1 (microphone) and audio codec
-4. **External memory usage**: Audio buffers (>900KB) stored in external PSRAM (section `AudioLooperBuffer`)
-5. **TouchGFX architecture**: Two-stage debug - debug Boot first, then Appli
-6. **FreeRTOS heap size**: Configured to 50KB in `FreeRTOSConfig.h` (heap_4)
-7. **Interrupt priorities**: Audio interrupts at priority 2 (high priority), touch/SD at 14-15
+2. **External FlashLoader required**: Use `gcc/MX66UW1G45G_STM32H7S78-DK.stldr` for programming external flash (0x70000000)
+3. **Never edit `Core/Src/` and `Core/Inc/` directly** - regenerate via STM32CubeMX instead
+4. **High-speed audio acquisition (48kHz)** - uses DMA for ADF1 (microphone) and audio codec
+5. **External memory usage**: Audio buffers (>900KB) stored in external PSRAM (section `AudioLooperBuffer`)
+6. **TouchGFX architecture**: Two-stage debug - debug Boot first, then Appli
+7. **FreeRTOS heap size**: Configured to 50KB in `FreeRTOSConfig.h` (heap_4)
+8. **Interrupt priorities**: Audio interrupts at priority 2 (high priority), touch/SD at 14-15
 
 ## Build & Flash
 
 ### Prerequisites
 - STM32CubeIDE (for CubeMX GUI, code generation)
 - gcc-arm-embedded (`arm-none-eabi-gcc`)
-- OpenOCD (for flashing)
+- **STM32CubeProgrammer** (for flashing with external loader)
 - TouchGFX 4.26.1 (for GUI generation)
 
 ### Build Commands
@@ -61,11 +64,33 @@ make -f makefile_boot all
 
 # Build only Appli
 make -f makefile_appli all
-
-# Flash Appli (after Boot is already flashed)
-make -f makefile_appli flash
 ```
 
+### Flashing Commands
+
+**Important**: Flashing requires external FlashLoader for external memory access.
+
+**Flash Boot (internal flash only):**
+```bash
+STM32_Programmer_CLI -c port=SWD \
+  -d Boot/TouchGFX/build/bin/target.hex \
+  -hardRst
+```
+
+**Flash Appli (requires external FlashLoader for 0x70000000):**
+```bash
+STM32_Programmer_CLI -c port=SWD \
+  -d Appli/TouchGFX/build/bin/target.hex \
+  -el gcc/MX66UW1G45G_STM32H7S78-DK.stldr \
+  -hardRst
+```
+
+**Or using STM32CubeIDE GUI:**
+1. Open STM32CubeIDE
+2. Connect ST-Link
+3. Right-click on project → **Run As** → **1 STM32CubeProgrammer**
+4. Select the appropriate loader for external memory
+
 ### Debugging
 
 **Two-stage debugging process:**
@@ -179,6 +204,7 @@ Appli/
 ### External Memory
 - **PSRAM**: 8MB (XSPI1) - Audio buffers + framebuffers
 - **Flash**: 128MB (XSPI2) - TouchGFX assets (compressed images/fonts)
+- **External FlashLoader**: `gcc/MX66UW1G45G_STM32H7S78-DK.stldr` (required for programming external flash via STM32CubeProgrammer)
 
 ## Data Logging
 
@@ -190,3 +216,35 @@ Appli/
 
 *Last updated: October 2026*
 *Project: STM32H7S78-DK Audio Effects Processor with TouchGFX*
+
+**Last fixed**: October 18, 2026 (Flashing method updated with external FlashLoader)
+
+## Flashing Troubleshooting
+
+### Common Issues
+
+1. **"Upload size is bigger than flash memory size"**
+   - Cause: Trying to read too much memory (e.g., 1MB from 0x08000000)
+   - Solution: Use smaller read size (64KB max for internal flash)
+
+2. **"Error: The read command you trying to perform (-u) is missing some arguments"**
+   - Cause: Incorrect STM32CubeProgrammer syntax for external loader
+   - Solution: Use `-el <loader.stldr>` flag with correct loader path
+
+3. **External memory (0x70000000) not accessible**
+   - Cause: External FlashLoader not loaded
+   - Solution: Flash Appli with `-el gcc/MX66UW1G45G_STM32H7S78-DK.stldr`
+
+4. **Application runs but display is blank**
+   - Cause: Appli not flashed in external memory correctly
+   - Solution: Re-flash Appli with external loader, verify with `-u 0x70000000` read
+
+### Verification Commands
+
+```bash
+# Verify internal flash (Boot)
+STM32_Programmer_CLI -c port=SWD -u 0x08000000 0x1000 /tmp/read_int.bin
+
+# Verify external flash (Appli)
+STM32_Programmer_CLI -c port=SWD -u 0x70000000 0x1000 /tmp/read_ext.bin
+```