init

2026-10-18 14:06:40 +02:00
commit 2c2202e60d
@@ -0,0 +1,192 @@
+# AGENTS.md
+
+## Hardware
+
+- **Board**: STM32H7S78-DK evaluation board
+- **MCU**: STM32H7S78 (Cortex-M7 @ 480MHz)
+- **Flash**: 2 MB external OSPI Flash (for Boot)
+- **RAM**: 1 MB internal + external PSRAM (for Audio/Framebuffers)
+
+## Project Architecture
+
+### Dual-Boot Structure
+
+This project uses a **dual-project architecture**:
+
+| Project | Directory | Purpose |
+|---------|-----------|---------|
+| **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.
+
+## Project Setup
+
+- **IDE**: STM32CubeIDE with STM32CubeMX plugin
+- **RTOS**: FreeRTOS V10.5.1 (CMSIS-RTOS V2)
+- **GUI**: TouchGFX 4.26.1 with NemaGFX GPU acceleration
+- **Language**: C/C++
+- **Build System**: GCC Makefile (not CMake)
+
+## 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
+
+## Build & Flash
+
+### Prerequisites
+- STM32CubeIDE (for CubeMX GUI, code generation)
+- gcc-arm-embedded (`arm-none-eabi-gcc`)
+- OpenOCD (for flashing)
+- TouchGFX 4.26.1 (for GUI generation)
+
+### Build Commands
+
+**From `/gcc/` directory:**
+```bash
+make          # Build both Boot and Appli
+make clean    # Clean all build artifacts
+```
+
+**Individual projects:**
+```bash
+# Build only Boot
+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
+```
+
+### Debugging
+
+**Two-stage debugging process:**
+
+1. **Debug Boot project first:**
+```bash
+# In STM32CubeIDE:
+# 1. Open Boot project
+# 2. Launch debug session
+# 3. Wait for compilation/flash complete
+# 4. Terminate session (Ctrl+F2)
+```
+
+2. **Debug Appli project:**
+```bash
+# In STM32CubeIDE:
+# 1. Open Appli project
+# 2. Launch debug session
+# 3. Wait for compilation/flash complete
+# 4. Click Resume (F8)
+# 5. Press the black NRST button on the board
+# 6. Application breaks at first line of main() in Appli
+```
+
+**Command line (if needed):**
+```bash
+# Start GDB server
+openocd -f interface/jlink.cfg -f target/sth7rs.cfg
+
+# In another terminal
+arm-none-eabi-gdb gcc/target.elf
+(gdb) target remote :3333
+(gdb) load
+(gdb) break main
+(gdb) continue
+```
+
+## Sensors/Peripherals
+
+### Audio (Primary Function)
+- **ADF1** - Digital microphone (PDM interface, 48kHz sample rate)
+- **I2C1** - Audio codec (STM32 Audio BSP)
+- **DMA2D/GPDMA1/HPDMA1** - Audio DMA channels
+
+### Display
+- **LTDC** - LCD-TFT controller
+- **GPU2D (NemaGFX)** - 2D acceleration
+- **Display**: ST7789 (240x240 RGB)
+
+### Storage & Communication
+- **XSPI1** - External PSRAM (for audio buffers)
+- **XSPI2** - External Flash (for TouchGFX assets)
+- **I2C1** - Touch controller (FT5336), sensors
+
+### Touch Control
+- **FT5336** - Capacitive touch controller
+- **SPI** - Touch interface
+- **GPIO** - Touch interrupt (TP_IRQ)
+
+## Audio Processing
+
+### Effects Chain (in order)
+1. **Octaver** - Dual-grain pitch shifting (-2, -1, +1, +2 octaves)
+2. **Equalizer** - 5-band graphic EQ
+3. **Overdrive** - Distortion effect
+4. **Saturation** - Audio saturation
+5. **Echo** - Delay-based echo
+6. **Reverb** - Room reverb
+
+### Analysis
+- **FFT**: 2048-point real FFT (CMSIS-DSP)
+- **Sample rate**: 48kHz
+- **Bins**: 1024 (0-24kHz spectrum)
+- **Peak detection**: Frequency with maximum magnitude
+
+### Looping
+- **Duration**: Up to 5 seconds at 48kHz
+- **Playback**: 2x speed (raises pitch by octave)
+- **Storage**: External PSRAM (937.5KB buffer)
+
+## TouchGFX Architecture
+
+### Project Structure
+```
+Appli/
+├── TouchGFX/
+│   ├── App/                    # Application code (user created)
+│   ├── assets/                 # Images, fonts, videos
+│   ├── build/                  # Generated build files
+│   ├── config/                 # Build configuration
+│   ├── generated/              # Auto-generated code (DO NOT EDIT)
+│   ├── gui/                    # Custom GUI code (views, presenters)
+│   ├── simulator/              # Simulator files
+│   └── target/                 # Target-specific code
+```
+
+### GUI Screens
+- **InitScreen** - Initial splash screen
+- **Overview** - Main screen with audio on/off, volume, looper button
+- **Oscillo** - Spectrum analyzer display
+- **Octaver, Equalizer, Overdrive, Saturation, Echo, Reverb** - Effect tuning screens
+
+## Memory Map
+
+### Key Sections
+- **AudioLooperBuffer** - External PSRAM (audio loop recording)
+- **TouchGFX framebuffers** - External PSRAM (LCD display)
+- **Heap** - Internal RAM (50KB FreeRTOS heap)
+- **Stack** - Internal RAM (task stacks)
+
+### External Memory
+- **PSRAM**: 8MB (XSPI1) - Audio buffers + framebuffers
+- **Flash**: 128MB (XSPI2) - TouchGFX assets (compressed images/fonts)
+
+## Data Logging
+
+- **Format**: CSV (to be implemented)
+- **Storage**: SD card via SPI (not currently implemented in main code)
+- **FATFS**: File system (available via Middlewares/ST)
+
+---
+
+*Last updated: October 2026*
+*Project: STM32H7S78-DK Audio Effects Processor with TouchGFX*