Add an example using the Daisy bootloader

Signed-off-by: Petr Horacek <petr@zlosynth.com>

Author: phoracek

CHANGELOG.md

@@ -6,13 +6,15 @@ backwards compatibility.
 
 ## Unreleased
 
+* Add a feature flag for longer audio block length.
+* Document how to use Daisy bootloader.
+
 ## 0.10.0
 
 * Bump STM32H7 HAL to version 0.16.
 * Introduce `probe-rs` to the project.
 * Illustrate use of `defmt` in examples.
 * Introduce support for Daisy Seed 1.2.
-* Add a feature flag for longer audio block length.
 
 ## 0.9.0
 

README.md

@@ -33,6 +33,12 @@ additional logs and panic messages:
 make flash WHAT=blinky BOARD=seed_1_1
 ```
 
+# Using Daisy bootloader
+
+It is possible to use the [Daisy Bootloader](https://electro-smith.github.io/libDaisy/md_doc_2md_2__a7___getting-_started-_daisy-_bootloader.html)
+to extend the maximum firmware capacity. You can find a guide with an example under
+[examples/bootloader](examples/bootloader/).
+
 # API stability
 
 I am still trying to figure out a good API for the project. Expect it to change.

examples/bootloader/.cargo/config.toml

@@ -0,0 +1,9 @@
+[target.thumbv7em-none-eabihf]
+runner = 'probe-rs run --chip STM32H750VBTx'
+rustflags = [
+  "-C",
+  "link-arg=-Tdefmt.x",
+]
+
+[build]
+target = "thumbv7em-none-eabihf" # Cortex-M4F and Cortex-M7F (with FPU)

examples/bootloader/.gitignore

@@ -0,0 +1,6 @@
+# Generated by Cargo
+0;95;0c# will have compiled files and executables
+/target/
+
+# These are backup files generated by rustfmt
+**/*.rs.bk

examples/bootloader/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "example_bootloader"
+version = "0.10.0" # hack/release.sh
+edition = "2024"
+
+[dependencies]
+cortex-m = "0.7"
+cortex-m-rt = { version = "0.7", features = [ "device", "set-vtor" ] }
+daisy = { path = "../../", features = ["patch_sm", "defmt"]}
+defmt = { version = "0.3.8" }
+defmt-rtt = { version = "0.4.1" }
+panic-probe = { version = "0.3.2", features = ["print-defmt"] }

examples/bootloader/Embed.toml

@@ -0,0 +1,8 @@
+[default.general]
+chip = "STM32H750VBTx"
+
+[default.rtt]
+enabled = true
+
+[default.flashing]
+enabled = false

examples/bootloader/README.md

@@ -0,0 +1,109 @@
+# Uploading firmware through Daisy Bootloader
+
+The chip on board has quite limited flash capacity of 128 kB. To fit larger
+firmware on Daisy, [the Daisy Bootloader exists](https://electro-smith.github.io/libDaisy/md_doc_2md_2__a7___getting-_started-_daisy-_bootloader.html).
+Check the documentation to learn about the different bootloader modes and the
+methods for uploading firmware through it.
+
+In this directory, you'll find an example project that uses the bootloader.
+The program is copied via DFU to the onboard 8 MB flash storage. When the board
+starts, the bootloader will then copy the program to SDRAM for faster execution.
+
+This example is made for Daisy Patch SM and assumes you're already familiar with
+this crate. If you want to flash a different board, update the `Cargo.toml`
+accordingly.
+
+## Flashing the example
+
+First, install the bootloader on the board. You can use <https://flash.daisy.audio/>,
+go to the "Bootloader" tab, select version "v6.2", and flash it.
+Alternatively, you can use the libDaisy project and its Makefile.
+
+First, install the bootloader on the board. You can use <https://flash.daisy.audio/>,
+go to the "Bootloader" tab, select version "v6.2", and flash it. Alternatively
+you can use the [libDaisy](https://github.com/electro-smith/libDaisy/tree/master)
+project and its `Makefile`.
+
+Once the bootloader is installed, restart the module and press the BOOT button
+within the first 2 seconds after startup. The onboard LED should start pulsing,
+indicating the bootloader is active and waiting.
+
+Now build the example firmware:
+
+```sh
+cargo objcopy --release -- -O binary target/program.bin
+```
+
+After building, use `dfu-util` to upload the program. Note the `-s` parameter,
+which now points to the beginning of the writable onboard flash, not the
+internal flash:
+
+After that, it is just a matter of using `dfu-util` to upload the program.
+Note the `-s` parameter which now points at the beginning of writeable
+on-board flash, instead of the internal flash:
+
+```sh
+dfu-util -a 0 -s 0x90040000:leave -D target/program.bin -d ,0483:df11
+```
+
+The program should now be uploaded, and the onboard LED should be blinking.
+
+## Attaching to logs
+
+The bootloader doesn't allow flashing the program using
+[`probe-rs`](https://probe.rs/), but you can still attach to logs using
+[cargo-embed](https://probe.rs/docs/tools/cargo-embed/).
+
+Build the program including INFO-level logs, flash it, and attach to
+it using an ST-Link programmer:
+
+```sh
+DEFMT_LOG=info cargo objcopy --release -- -O binary target/program.bin
+dfu-util -a 0 -s 0x90040000:leave -D target/program.bin -d ,0483:df11
+DEFMT_LOG=info cargo-embed --release
+```
+
+You should now see the log output.
+
+## What makes this work
+
+### `Cargo.toml`
+
+The `Cargo.toml` config is standard, except for the `set-vtor` feature flag
+that must be enabled on `cortex-m-rt`.
+
+### `memory.x`
+
+This file is different from the standard `memory.x`. The main difference is the
+region alias replacing `FLASH` of the default link file with `SRAM`.
+The rest of the layout is also slightly adjusted to meet the bootloader’s
+requirements.
+
+### `Embed.toml`
+
+This file is optional. It makes `cargo-embed` only read logs without trying to
+flash the firmware.
+
+## Caveats
+
+### SRAM
+
+Since the program is uploaded to SRAM and runs from there, your program can't
+use that memory. Other memory regions are still available, but keep in mind
+they are either smaller or slower.
+
+### Reserved flash
+
+Part of the onboard flash is used to store the firmware. It’s still possible
+for the firmware to use this flash, but care must be taken when writing to it.  
+The first four 64 kB blocks are reserved, followed by the firmware itself.
+When using the bootloader in SRAM mode (as in this example), the firmware can
+take up to 480 kB, so the first 736 kB, or 184 sectors, are occupied and should
+not be written to.
+
+## Credits
+
+Kudos to `eulerdisk` for [explaining](https://github.com/rust-embedded/cortex-m/issues/599#issuecomment-2956003568)
+how to adjust the linker to work with the bootloader. Thanks to `Corvus Prudens`
+and `mito3705` from [Daisy Discord](https://discord.com/channels/1037767234803740694/1039305128886403072)
+who shared valuable input on using the Daisy Bootloader with Rust.

examples/bootloader/build.rs.backup

@@ -0,0 +1,39 @@
+//! This build script copies the `memory.x` file from the crate root into
+//! a directory where the linker can always find it at build time.
+//! For many projects this is optional, as the linker always searches the
+//! project root directory -- wherever `Cargo.toml` is. However, if you
+//! are using a workspace or have a more complicated build setup, this
+//! build script becomes required. Additionally, by requesting that
+//! Cargo re-run the build script whenever `memory.x` is changed,
+//! updating `memory.x` ensures a rebuild of the application with the
+//! new memory settings.
+
+use std::env;
+use std::fs::File;
+use std::io::Write;
+use std::path::PathBuf;
+
+fn main() {
+    // Put `memory.x` and `link_ram.x` in our output directory and ensure it's
+    // on the linker search path.
+    let out = &PathBuf::from(env::var_os("OUT_DIR").unwrap());
+    File::create(out.join("memory.x"))
+        .unwrap()
+        .write_all(include_bytes!("memory.x"))
+        .unwrap();
+    File::create(out.join("link_ram.x"))
+        .unwrap()
+        .write_all(include_bytes!("link_ram.x"))
+        .unwrap();
+    println!("cargo:rustc-link-search={}", out.display());
+
+    // By default, Cargo will re-run a build script whenever
+    // any file in the project changes. By specifying `memory.x`
+    // here, we ensure the build script is only re-run when
+    // `memory.x` is changed.
+    println!("cargo:rerun-if-changed=memory.x");
+    // Ditto for `link_ram.x`.
+    println!("cargo:rerun-if-changed=link_ram.x");
+
+    // println!("cargo:rustc-link-arg=-Tdefmt.x");
+}

examples/bootloader/memory.x

@@ -0,0 +1,17 @@
+/* See: https://github.com/electro-smith/libDaisy/blob/master/core/STM32H750IB_sram.lds */
+
+MEMORY
+{
+	DTCMRAM     (RWX) : ORIGIN = 0x20000000, LENGTH = 128K
+	SRAM        (RWX) : ORIGIN = 0x24000000, LENGTH = 512K - 32K
+	RAM_D2_DMA  (RWX) : ORIGIN = 0x30000000, LENGTH = 32K
+	RAM_D2      (RWX) : ORIGIN = 0x30008000, LENGTH = 256K
+	RAM_D3      (RWX) : ORIGIN = 0x38000000, LENGTH = 64K
+	BACKUP_SRAM (RWX) : ORIGIN = 0x38800000, LENGTH = 4K
+	ITCMRAM     (RWX) : ORIGIN = 0x00000000, LENGTH = 64K
+	SDRAM       (RWX) : ORIGIN = 0xc0000000, LENGTH = 64M
+	QSPIFLASH   (RX)  : ORIGIN = 0x90040000, LENGTH = 7936K
+}
+
+REGION_ALIAS(RAM, DTCMRAM);
+REGION_ALIAS("FLASH", SRAM);

examples/bootloader/src/main.rs

@@ -0,0 +1,28 @@
+//! Example of basic interaction with the board.
+
+#![no_main]
+#![no_std]
+
+use cortex_m_rt::entry;
+
+use {defmt_rtt as _, panic_probe as _};
+
+#[entry]
+fn main() -> ! {
+    // Get device peripherals and the board abstraction.
+    let dp = daisy::pac::Peripherals::take().unwrap();
+    let board = daisy::Board::take().unwrap();
+
+    // Configure board's peripherals.
+    let ccdr = daisy::board_freeze_clocks!(board, dp);
+    let pins = daisy::board_split_gpios!(board, ccdr, dp);
+    let mut led_user = daisy::board_split_leds!(pins).USER;
+
+    // Blink every second.
+    let one_second = ccdr.clocks.sys_ck().to_Hz();
+    loop {
+        led_user.toggle();
+        cortex_m::asm::delay(one_second);
+        defmt::info!("Tick");
+    }
+}