thomas/CelloEffects
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

new ihm

Browse Source
This commit is contained in:
thomas committed 2026-10-18 23:39:44 +02:00
1 parent 2b9e574ba9
commit b119a6abd7
583 files changed
+224175 -218466
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

AGENTS.md
+91 -84
View File
@@ -4,7 +4,7 @@
- **Board**: STM32H7S78-DK evaluation board
- **MCU**: STM32H7S78 (Cortex-M7 @ 480MHz)
- **Flash**: 2 MB external OSPI Flash (for Boot)
- **Flash**: 64 KB internal flash at 0x08000000 (Boot) + 128 MB external OctoSPI NOR flash at 0x70000000 (Appli code + TouchGFX assets)
- **RAM**: 1 MB internal + external PSRAM (for Audio/Framebuffers)
## Project Architecture
@@ -32,7 +32,7 @@ This project uses a **dual-project architecture**:
## Key Constraints
1. **Dual-boot flashing sequence**: Flash Boot first, then Appli. Press NRST after Appli flash.
1. **Dual-boot flashing sequence**: Flash Boot first, then Appli (`gcc/flash.sh all` does both and hard-resets the board).
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
@@ -40,94 +40,94 @@ This project uses a **dual-project architecture**:
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
9. **Debug probe connection**: always `ap=1 mode=UR` (STM32_Programmer_CLI) / `-m 1 -k` (ST-LINK_gdbserver). Without them the connection fails (`DEV_TARGET_NOT_HALTED`, `Cannot connect to access port 1`)
10. **No OpenOCD**: the installed OpenOCD 0.12 has no STM32H7RS target; debug with ST-LINK_gdbserver (Cortex-Debug in VS Code)
## Build & Flash
### Prerequisites
- STM32CubeIDE (for CubeMX GUI, code generation)
- gcc-arm-embedded (`arm-none-eabi-gcc`)
- **STM32CubeProgrammer** (for flashing with external loader)
- TouchGFX 4.26.1 (for GUI generation)
### Toolchain (macOS, verified)
| Tool | Path |
|------|------|
| `arm-none-eabi-gcc` / `-gdb` 10.3 | `/usr/local/bin` (in PATH) |
| STM32_Programmer_CLI | `/Applications/STMicroelectronics/programmer/STM32CubeProgrammer.app/Contents/MacOs/bin/STM32_Programmer_CLI` (not in PATH; `gcc/flash.sh` finds it, override with `$STM32_PROGRAMMER_CLI`) |
| ST-LINK_gdbserver | `/Applications/STMicroelectronics/STM32CubeIDE.app/Contents/Eclipse/plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.macos64_*/tools/bin/ST-LINK_gdbserver` |
| SVD | `/Applications/STMicroelectronics/programmer/STM32CubeProgrammer.app/Contents/MacOs/SVD/STM32H7S.svd` |
| Probe | on-board STLINK-V3 (USB) |
TouchGFX 4.26.1 + STM32CubeMX are only needed to regenerate code.
### Build Commands
**From `/gcc/` directory:**
Run from the repository root (the makefiles `cd` to the root themselves):
```bash
make # Build both Boot and Appli
make clean # Clean all build artifacts
make -C gcc -j8 # Build Boot + Appli
make -C gcc -j8 -f makefile_boot all # Boot only
make -C gcc -j8 -f makefile_appli all # Appli only
make -C gcc clean # Clean
python3 gcc/gen_compile_commands.py # Regenerate compile_commands.json (IntelliSense/clangd) after adding sources
```
**Individual projects:**
```bash
# Build only Boot
make -f makefile_boot all
Outputs:
- Boot: `Boot/TouchGFX/build/bin/target.elf|.hex` (internal flash 0x08000000)
- Appli: `Appli/TouchGFX/build/bin/target.elf|.hex` (external flash 0x70000000)
# Build only Appli
make -f makefile_appli all
```
The "old Ruby version (2.6.10)" TouchGFX warning during the build is harmless.
### Flashing Commands
**Important**: Flashing requires external FlashLoader for external memory access.
**Flash Boot (internal flash only):**
Use `gcc/flash.sh` (wraps STM32_Programmer_CLI with `ap=1 mode=UR` and the external loader):
```bash
STM32_Programmer_CLI -c port=SWD \
-d Boot/TouchGFX/build/bin/target.hex \
-hardRst
gcc/flash.sh boot # Boot -> internal flash (with verify)
gcc/flash.sh appli # Appli -> external flash via gcc/MX66UW1G45G_STM32H7S78-DK.stldr (~20 s)
gcc/flash.sh all # Boot then Appli (required order), then hard reset
gcc/flash.sh probe # Check the ST-Link/board connection (no write)
gcc/flash.sh reset # Hardware reset
gcc/flash.sh verify # Dump 4 KB of 0x08000000 / 0x70000000 to /tmp/read_int.bin, /tmp/read_ext.bin
make -C gcc flash # Build + flash both (calls gcc/flash.sh on macOS/Linux)
```
**Flash Appli (requires external FlashLoader for 0x70000000):**
Equivalent raw commands:
```bash
STM32_Programmer_CLI -c port=SWD \
-d Appli/TouchGFX/build/bin/target.hex \
-el gcc/MX66UW1G45G_STM32H7S78-DK.stldr \
-hardRst
STM32_Programmer_CLI -c port=SWD ap=1 mode=UR -d Boot/TouchGFX/build/bin/target.hex -v -hardRst
STM32_Programmer_CLI -c port=SWD ap=1 mode=UR -el gcc/MX66UW1G45G_STM32H7S78-DK.stldr \
-d Appli/TouchGFX/build/bin/target.hex -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
Only one tool can hold the ST-Link at a time: stop any debug session before flashing.
### VS Code (`.vscode/`)
- `tasks.json`: Build All (default, Cmd+Shift+B), Build Boot/Appli, Clean, Flash Boot/Appli/All, Build + Flash Boot/Appli/All, Board: Probe/Reset/Verify, Generate compile_commands.json. All tasks call the commands above.
- `launch.json` (Cortex-Debug, `servertype: stlink`): Debug Boot, Debug Appli (builds, flashes via GDB with the external loader, stops at Appli `main()`), Debug Appli (no flash), Attach Appli.
- `settings.json`: Cortex-Debug tool paths, IntelliSense from `compile_commands.json`.
- `c_cpp_properties.json`: uses `compile_commands.json`.
Keep `AGENTS.md`, `.vscode/tasks.json`, `.vscode/launch.json` and `gcc/flash.sh` consistent when changing any build/flash/debug command.
### Debugging
**Two-stage debugging process:**
Boot must already be in internal flash (`gcc/flash.sh boot`): at reset the core runs Boot, which maps the XSPI memories and jumps to Appli `main()` at 0x70000000.
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)
```
VS Code: run "Debug Appli" (F5). No NRST press needed.
2. **Debug Appli project:**
Command line:
```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
GDBSRV=$(ls -d /Applications/STMicroelectronics/STM32CubeIDE.app/Contents/Eclipse/plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.macos64_*/tools/bin | tail -1)/ST-LINK_gdbserver
"$GDBSRV" -p 61234 --swd --halt -m 1 -k \
-cp /Applications/STMicroelectronics/programmer/STM32CubeProgrammer.app/Contents/MacOs/bin \
-el gcc/MX66UW1G45G_STM32H7S78-DK.stldr
# In another terminal
arm-none-eabi-gdb gcc/target.elf
(gdb) target remote :3333
(gdb) load
(gdb) break main
arm-none-eabi-gdb Appli/TouchGFX/build/bin/target.elf
(gdb) target extended-remote :61234
(gdb) load # optional: programs 0x70000000 through the external loader
(gdb) monitor reset
(gdb) break main # hardware breakpoint chosen automatically (0x70000000 is flash in the memory map)
(gdb) continue
```
STM32CubeIDE alternative: debug Boot, terminate (Ctrl+F2), debug Appli, Resume (F8), press NRST.
## Sensors/Peripherals
### Audio (Primary Function)
@@ -138,7 +138,7 @@ arm-none-eabi-gdb gcc/target.elf
### Display
- **LTDC** - LCD-TFT controller
- **GPU2D (NemaGFX)** - 2D acceleration
- **Display**: ST7789 (240x240 RGB)
- **Display**: 800x480 RGB565 (LTDC)
### Storage & Communication
- **XSPI1** - External PSRAM (for audio buffers)
@@ -154,7 +154,7 @@ arm-none-eabi-gdb gcc/target.elf
### Effects Chain (in order)
1. **Octaver** - Dual-grain pitch shifting (-2, -1, +1, +2 octaves)
2. **Equalizer** - 5-band graphic EQ
2. **Equalizer** - 10-band graphic EQ (31 Hz - 16 kHz, -24..+24 dB)
3. **Overdrive** - Distortion effect
4. **Saturation** - Audio saturation
5. **Echo** - Delay-based echo
@@ -188,10 +188,20 @@ Appli/
```
### 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
- **InitScreen** - Splash screen (title + central button) -> Overview
- **Overview** - Home screen: power toggle + master volume, 3x2 grid of effect cards (tap = open the effect screen, switch = enable/bypass), looper (hold to record, plays back x2), Spectrum button
- **Octaver, Equalizer, Overdrive, Saturation, Echo, Reverb** - Effect tuning screens (common header: back, title, on/off; sliders with live value)
- **Oscillo** - Spectrum analyzer (title "SPECTRE")
### UI Conventions (keep when editing the GUI)
- **Never write files in `Appli/TouchGFX/generated/`**: it is regenerated by TouchGFX Designer. Screens, widgets and interactions come from `CelloEffects.touchgfx`.
- **Custom look is done in user code only** (`Appli/TouchGFX/gui/`): each `XxxView::setupScreen()` re-lays out the generated widgets and adds extra ones.
- `gui/include/gui/common/UiTheme.hpp`: palette, per-effect accent color (`ui::accent()`), `ui::Header`, `ui::ValueText` (formatted value: `show("%d %%", v)`, `showDb(v)`), `ui::layoutEffectHeader()`, `ui::layoutParamRow()`
- `gui/include/gui/common/EffectCard.hpp`: home-screen effect card
- The home grid lives in `OverviewView`; the generated `buttonWithLabel1..6` of Overview are hidden on purpose.
- **A new screen must be created in TouchGFX Designer** (so `FrontendHeapBase` and `FrontendApplicationBase` include it). A screen hand-written outside Designer is not in the screen heap and corrupts memory.
- **Texts**: add them to `Appli/TouchGFX/assets/texts/texts.xml` (group `UiRework`); the build regenerates texts and fonts (`T_<ID>`). Typographies: `Default` 20 px, `Medium` 28 px, `Large` 40 px. Wildcard texts: `VALUE_M_LEFT` (Medium), `VALUE_S_CENTER` (Default); a character shown in a wildcard must be listed in the typography's `WidgetWildcardCharacters`.
- **Canvas widgets** (Circle, Graph...) need a per-screen `CanvasWidgetRenderer::setupBuffer()` (see `OverviewView`, `OscilloViewBase`).
## Memory Map
@@ -217,34 +227,31 @@ Appli/
*Last updated: October 2026*
*Project: STM32H7S78-DK Audio Effects Processor with TouchGFX*
**Last fixed**: October 18, 2026 (Flashing method updated with external FlashLoader)
**Last fixed**: October 18, 2026 (VS Code/CLI build-flash-debug verified on board: `gcc/flash.sh`, Cortex-Debug + ST-LINK_gdbserver)
## 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)
1. **`DEV_TARGET_NOT_HALTED` / `Cannot connect to access port 1` / gdbserver `Target unknown error 32`**
- Cause: missing access port or connect-under-reset option
- Solution: `ap=1 mode=UR` (CLI) or `-m 1 -k` (ST-LINK_gdbserver), as used by `gcc/flash.sh` and `.vscode/launch.json`
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
2. **"Upload size is bigger than flash memory size"**
- Cause: reading beyond the 64 KB internal flash (0x08000000-0x08010000)
- Solution: use a smaller read size
3. **External memory (0x70000000) not accessible**
- Cause: External FlashLoader not loaded
- Solution: Flash Appli with `-el gcc/MX66UW1G45G_STM32H7S78-DK.stldr`
- Solution: add `-el gcc/MX66UW1G45G_STM32H7S78-DK.stldr` (CLI and gdbserver)
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
- Cause: Appli not flashed in external memory correctly, or Boot missing
- Solution: `gcc/flash.sh all`, then `gcc/flash.sh verify`
### Verification Commands
5. **ST-Link busy**
- Cause: a debug session or STM32CubeProgrammer GUI holds the probe
- Solution: stop it, then retry
```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
```
6. **`nul` files appear in the repo**
- Cause: Windows `2> nul` redirections in `gcc/include/cube_programmer.mk` (now guarded with `ifeq ($(OS),Windows_NT)`)