Rewrite ec-slimloader to use persistent state journal and ROM authentication

.github/workflows/check.yml

@@ -21,7 +21,6 @@ concurrency:
   cancel-in-progress: true
 name: check
 jobs:
-
   fmt:
     runs-on: ubuntu-latest
     name: nightly / fmt
@@ -39,8 +38,12 @@ jobs:
         uses: dtolnay/rust-toolchain@nightly
         with:
           components: rustfmt
-      - name: cargo fmt --check
+      - name: cargo fmt --check (libs)
+        run: cargo fmt --check
+        working-directory: "./libs"
+      - name: cargo fmt --check (examples)
         run: cargo fmt --check
+        working-directory: "./examples/rt685s"
 
   clippy:
     runs-on: ubuntu-latest
@@ -65,12 +68,20 @@ jobs:
           components: clippy
       - name: rustup target add ${{ matrix.target }}
         run: rustup target add ${{ matrix.target }}
-      - name: cargo clippy
+      - name: cargo clippy (libs)
+        uses: giraffate/clippy-action@v1
+        with:
+          reporter: "github-pr-check"
+          clippy_flags: -- -F clippy::suspicious -D clippy::correctness -F clippy::perf -F clippy::style
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          workdir: "./libs"
+      - name: cargo clippy (examples)
         uses: giraffate/clippy-action@v1
         with:
-          reporter: 'github-pr-check'
-          clippy_flags: -- -F clippy::suspicious -F clippy::correctness -F clippy::perf -F clippy::style
+          reporter: "github-pr-check"
+          clippy_flags: -- -F clippy::suspicious -D clippy::correctness -F clippy::perf -F clippy::style
           github_token: ${{ secrets.GITHUB_TOKEN }}
+          workdir: "./examples/rt685s"
 
   # Enable once we have a released crate
   # semver:
@@ -107,8 +118,14 @@ jobs:
         uses: dtolnay/rust-toolchain@nightly
       - name: rustup target add ${{ matrix.target }}
         run: rustup target add ${{ matrix.target }}
-      - name: cargo doc
+      - name: cargo doc (libs)
+        run: cargo doc --no-deps --features mimxrt685s
+        working-directory: "./libs"
+        env:
+          RUSTDOCFLAGS: --cfg docsrs
+      - name: cargo doc (examples)
         run: cargo doc --no-deps
+        working-directory: "./examples/rt685s"
         env:
           RUSTDOCFLAGS: --cfg docsrs
 
@@ -125,15 +142,23 @@ jobs:
       - uses: actions/checkout@v4
         with:
           submodules: true
+
       - name: Install stable
         uses: dtolnay/rust-toolchain@stable
-      - name: rustup target add ${{ matrix.target }}
-        run: rustup target add ${{ matrix.target }}
-      - name: cargo install cargo-hack
-        uses: taiki-e/install-action@cargo-hack
-      # intentionally no target specifier; see https://github.com/jonhoo/rust-ci-conf/pull/4
-      - name: cargo hack
-        run: cargo hack --each-feature --exclude-all-features check
+
+      - name: rustup target add thumbv8m.main-none-eabihf
+        run: rustup target add thumbv8m.main-none-eabihf
+
+      - name: cargo install cargo-batch
+        run: cargo install --git https://github.com/embassy-rs/cargo-batch cargo --bin cargo-batch --locked
+
+      - name: cargo manual hack (libs)
+        run: ./ci.sh
+        working-directory: "./libs"
+
+      - name: cargo manual hack (examples/rt685s)
+        run: ./ci.sh
+        working-directory: "./examples/rt685s"
 
   deny:
     # cargo-deny checks licenses, advisories, sources, and bans for
@@ -152,11 +177,17 @@ jobs:
         uses: dtolnay/rust-toolchain@stable
       - name: rustup target add ${{ matrix.target }}
         run: rustup target add ${{ matrix.target }}
-      - name: cargo install cargo-deny
+      - name: Cargo deny (libs)
+        uses: EmbarkStudios/cargo-deny-action@v2
+        with:
+          log-level: warn
+          manifest-path: ./libs/Cargo.toml
+          command: check
+      - name: Cargo deny (examples)
         uses: EmbarkStudios/cargo-deny-action@v2
         with:
           log-level: warn
-          manifest-path: ./Cargo.toml
+          manifest-path: ./examples/rt685s/Cargo.toml
           command: check
 
   msrv:
@@ -167,28 +198,22 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        msrv: ["1.79"] # We're relying on namespaced-features, which
-                       # was released in 1.60
-                       #
-                       # We also depend on `fixed' which requires rust
-                       # 1.71
-                       #
-                       # Additionally, we depend on embedded-hal-async
-                       # which requires 1.75
-                       #
-                       # embassy-time requires 1.79 due to
-                       # collapse_debuginfo
+        msrv: ["1.90"] # We are depending on embassy-imxrt.
         target: [thumbv8m.main-none-eabihf]
-    name: ubuntu / ${{ matrix.msrv }}
+    name: ubuntu / MSRV ${{ matrix.msrv }}
     steps:
       - uses: actions/checkout@v4
         with:
           submodules: true
       - name: Install ${{ matrix.msrv }}
         uses: dtolnay/rust-toolchain@master
         with:
-          toolchain: ${{ matrix.msrv }}  
+          toolchain: ${{ matrix.msrv }}
       - name: rustup target add ${{ matrix.target }}
         run: rustup target add ${{ matrix.target }}
-      - name: cargo +${{ matrix.msrv }} check
+      - name: cargo +${{ matrix.msrv }} check (libs)
+        run: cargo check --features mimxrt685s
+        working-directory: "./libs"
+      - name: cargo +${{ matrix.msrv }} check (examples)
         run: cargo check
+        working-directory: "./examples/rt685s"

.vscode/launch.json

@@ -13,7 +13,7 @@
             },
             "coreConfigs": [
                 {
-                    "programBinary": "target/thumbv8m.main-none-eabihf/debug/ec-slimloader",
+                    "programBinary": "examples/rt685s/target/thumbv8m.main-none-eabihf/release/example-bootloader",
                     "svdFile": ".vscode/MIMXRT685S_cm33.svd",
                     "rttEnabled": true,
                 }

README.md

@@ -1,3 +1,92 @@
-# ec-slimloader
+# ec-slimloader **OUTDATED**
 
-A light-weight stage-one bootloader for loading an app image as configured by ec-slimloader-descriptors
+A light-weight stage-two bootloader written in Rust for loading an app image as configured by ec-slimloader-descriptors. Also contains a tool for signing images, flashing them to the device, setting fuses (or shadow registers) containing crypto keys, and an example application to showcase the bootloaders A/B state functionality.
+
+Currently this bootloader can only be used on the IMXRT600 series of chipsets from NXP.
+
+## Organisation
+
+This repository is split up into four parts:
+* ec-slimloader: the binary project which forms the second stage bootloader
+* ec-slimloader-descriptors: the library crate containing a descriptor of where each image slot exists, as well as a persistent fail-safe state journal for recording the A/B bootloading state.
+* bootloader-tool: a command-line utility using the NXP SPSDK tooling to generate keys, sign images, and flash them to the target device. Also integrates probe-rs and allows for attaching to the RTT buffer for displaying `defmt` output.
+* example: an example application image that uses the state-journal to select alternative images to execute.
+
+## Memory layout
+This repository has default configuration files detailing the used memory layout. This layout will probably will need to be adapted for your specific usecase.
+
+## Quick guide
+This guide details how to use this repository on the NXP MIMXRT685S-EVK. First step is compiling the bootloader and application:
+
+```bash
+pushd ec-slimloader
+cargo build --release --features defmt
+popd
+pushd examples/rt685s-application
+cargo build --release
+popd
+```
+
+In general, the bootloader-tool is a `clap` supported CLI application with for each subcommand a full `--help`:
+```
+cargo run -- --help
+    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.10s
+     Running `target/debug/bootloader-tool --help`
+Usage: bootloader-tool [OPTIONS] [COMMAND]
+
+Commands:
+  generate  Generate keys and certificates
+  sign      Sign binaries for flashing or OTA
+  download  Download binaries to the device
+  run       Run binaries, setting the shadow registers, by going through the bootloader chain for testing purposes
+  fuse      Burn fuse registers with key material and settings
+  help      Print this message or the help of the given subcommand(s)
+
+Options:
+  -c, --config <FILE>  Configuration file path [default: ./config.toml]
+  -h, --help           Print help
+  -V, --version        Print version
+```
+
+For now we need to prepare our testing setup by generating the key material:
+```bash
+cd bootloader-tool
+cargo run -- generate certificates
+cargo run -- generate otp
+```
+
+This key material is only used for testing right now, and everything is put in the `./artifacts` directory. This can be configured in the `./config.toml` file.
+We are working on a setup to also support external HSM integration.
+
+Now we have everything ready to start flashing.
+We can use run `run` command to immediately flash and `attach` in the same way you are familiar with from `probe-rs`. However, we need the bootloader to start up the application, and we need the FCB (we call everything in 0x0 to 0x1000 the 'prelude') to start the bootloader. We can extract the FCB from the `ec-slimloader` as it is built with the appropriate feature flags to include a FCB in the ELF file. Extraction happens as a side-product of signing:
+
+```bash
+cargo run -- sign bootloader -i ../target/thumbv8m.main-none-eabihf/release/ec-slimloader
+```
+
+We can now flash the FCB:
+
+```bash
+cargo run -- download prelude --prelude-path ../target/thumbv8m.main-none-eabihf/release/ec-slimloader.prelude.elf
+```
+
+And we can flash the application into *both slots*:
+```bash
+cargo run -- download application -i ../examples/rt685s-application/target/thumbv8m.main-none-eabihf/release/example-application --slot 0
+cargo run -- download application -i ../examples/rt685s-application/target/thumbv8m.main-none-eabihf/release/example-application --slot 1
+```
+
+To flash & attach to the bootloader now run, whilst setting the OTP shadow registers:
+```bash
+cargo run -- download bootloader -i ../target/thumbv8m.main-none-eabihf/release/ec-slimloader
+```
+
+To flash & attach to the application (TODO it now is not resetting the state journal so take care), assuming you have a and FCB bootloader already flashed:
+```bash
+cargo run -- run application -i ../examples/rt685s-application/target/thumbv8m.main-none-eabihf/release/example-application
+```
+
+You can use the `USER_1` button to change the state journal to either `confirmed` or try the other slot in state `initial` if the current image is already `confirmed`.
+
+You can use the `USER_2` button the reboot into the bootloader, which will set an image to `failed` if it does not verify or if it was in `attempting` without putting the state in `confirmed`.

bootloader-tool/.cargo/config.toml

@@ -0,0 +1,2 @@
+[env]
+RUST_LOG = "none,bootloader_tool=debug"

bootloader-tool/.gitignore

@@ -0,0 +1,8 @@
+/target
+
+# Software package
+/elftosb*
+
+/binaries.tar.xz
+/gpio-blinky
+/*.bin