How a firmware works

The two processors, the platform, settings, storage, and what happens at power-on.

The big picture, before the details. Read this first if the pedal’s insides are new to you.

Two processors

The GP-5 has two processors, and a firmware has a part for each.

the DSPthe control processor
chipArm Cortex-M4F, 192 MHzAndes NDS32 (BP1048), 288 or 320 MHz
doesthe audio: guitar in, two outputsthe screen, knobs, foot switch, LEDs, USB, storage
your codedsp/firmware.hnds32/*.c
runsfw_process() every 1.45 ms, for 64 samplesa main loop that calls your callbacks; fw_tick() every 10 ms
memory (the firmware’s, promised for 1.x)19,712 bytes for variables, 122,880 for big buffers258,016 bytes of RAM for the firmware’s data (code runs from flash)

The DSP is where sound happens. The control processor is the “brain” around it, and it can do sound work too (below).

The platform

OpenGP5 is the code both processors share: start-up, drivers, USB, the screen, the link between the processors, storage. You never edit it. Your firmware is a few callbacks and calls into it:

flowchart TB
    io(["Knobs, foot switch, screen, USB"]) <--> ctl
    ctl["`**Control processor**

    _The platform:_ drivers, USB, screen, storage, parameters, presets, log

    _Your code:_ fw_para_turn, fw_foot_down, fw_draw, on_block (optional)`"]
    ctl <== "the link: parameters, and audio (optional)" ==> dsp
    dsp["`**DSP**

    _Your code:_ fw_process, fw_param

    _The platform:_ audio in and out`"]
    dsp <--> audio(["Guitar in, out L / R"])

Your callbacks run when the platform calls them, and must return quickly. Nothing in a firmware waits. Even the screen is drawn a strip at a time (fw_draw returns “more to do”), so the controls and USB stay responsive.

Settings: parameters

A firmware’s settings are parameters, declared once in params.h. The platform takes care of the rest:

  • it sends each change to the DSP (fw_param());
  • it keeps them across power-off, and keeps presets;
  • it lets a computer list, read and change them.

Launchpad’s Live page edits them, with no code of its own for your firmware. See parameters.

The two processors exchange a block of words after every audio block: the audio link. A firmware can send the guitar to the control processor, process it there, and play the result on the DSP, 3 blocks (about 4.4 ms) later. NAM Loader and Dreamcatcher do this: some sound code is faster on the control processor, and it has more memory. See the audio link.

Storage

The pedal’s storage (about 300 KB) belongs to the firmware that is installed. The firmware’s id (in firmware.json) says whose it is:

  • an update to the same firmware keeps it;
  • installing another firmware starts empty;
  • going back to Valeton’s firmware gives Valeton’s presets back.

Parameters are stored there automatically. For anything else there are store records (up to 1 KB each) and files (bigger things that a computer writes, such as captures). See storage.

What happens at power-on

  1. The control processor starts the platform, checks who owns the storage, loads saved parameters, and calls your fw_init().
  2. It starts the DSP. The DSP starts the platform there and calls its fw_init(). The DSP has your params.h defaults until the control processor sends the saved values, a moment later.
  3. From then on: the DSP runs fw_process() for every block. The control processor runs its main loop: your callbacks, parameter changes to the DSP, saving, USB, and the screen (fw_draw).

From code to pedal

flowchart TB
    src["Your firmware: firmware.json, params.h, dsp/firmware.h, nds32/*.c"]
    src -- "platform/build_firmware.sh" --> bin["build/GP-5_&lt;id&gt;.bin: both parts, and a description of itself (name, version, author)"]
    bin -- "Launchpad, the web flasher, or gp5tool.py flash" --> pedal(["The pedal"])

Before you build, tools/simulate.py runs the whole firmware on the computer: both processors, the screen and the sound (The simulator). If something goes wrong on the pedal, holding the foot switch and pressing PARA in at power-on brings back update mode (Recovery).

Next: your first effect, or the firmware template for a repository of your own.