tweedegolf / dis-bootloader

A rust bootloader for our internal project using the nRF9160 chip.

nRF9160 Bootloader

This is a 100% Rust bootloader for the nRF9160 microcontroller.

Currently, building this project requires a recent nightly compile because is relies on Embassy for the serial output.

Structure

The project is split in two:

• shared: Exposes all types that both the bootloader and application needs to be able to access.
• bootloader: The binary part of the project

Workings

The bootloader has four special memory regions which are defined in the memory.x file. There are two firmware slots, A & B, as well as a bootloader state area and some scratch space.

The bootloader will jump to the application in firmware slot A.

The application can fill slot B with an updated firmware. Then it needs to set the bootloader goal to either StartSwap or StartTestSwap and reboot. When the bootloader sees that it should swap the two firmware slots it will do that in a way so that any cut in power or reset will not lead to a currupt device.

+--------+          2.         +--------+
| Slot A |<--------------------+ Slot B |
|        |                     |        |
|        +-------+     +------>|        |
+--------+       |     |       +--------+
|        |    1. |     | 3.    |        |
|        |       |     |       |        |
|        |       |     |       |        |
+--------+       |     |       +--------+
|        |       |     |       |        |
|        |       |     |       |        |
|        |       |     |       |        |
+--------+       |     |       +--------+
|        |       |     |       |        |
|        |       |     |       |        |
|        |       |     |       |        |
+--------+       |     |       +--------+
|        |       |     |       |        |
|        |       |     |       |        |
|        |       |     |       |        |
+--------+       |     |       +--------+
|        |       |     |       |        |
|        |       |     |       |        |
|        |       |     |       |        |
+--------+       |     |       +--------+
                 v     |
               +-------+-+
               | Scratch |
               |         |
               +---------+
               |         |
               |         |
               +---------+
               |         |
               |         |
               +---------+

First a page of slot A is written to a scratch page. There are multiple scratch pages because flash will wear out when erased. The second step is to move the B page to the A slot. The third and final step is to move the page in scratch to the B slot.

The state of each page is written in the bootloader state without doing an erase. At every step of the way we know where each page is so that we can resume the swap at any point.

When the bootloader is done with everything it needs to jump to the application.

The address of the application is unknown still so it needs to be searched for. The bootloader will go through the memory of the firmware A slot word by word in search of the vector table.

If a word is 0xFFFF_FFFF or 0x0000_0000 then it is ignored because the assumption is that it is some kind of padding. The first word that is not ignored should be the initial stack pointer and the value is checked to see if it is located somewhere in RAM. If it is not, then the bootloader will panic and restart. The second word (the one after the initial stack pointer) should be the reset vector. It is checked that the reset vector lies somewhere in slot A. If it is not, the bootloader will panic and reboot.

So as long as the application has 'clean' padding, the application can be put anywhere in its slot. After the vector table, the image may have arbitrary data. There is no image header or trailer.

With the knowledge that the initial stack pointer and reset vector are ther, we can be quite sure that we've found a vector table.

All peripherals are reset and then the bootloader performs the bootload operation as part of the cortex-m crate.

dis-bootloader's Issues

Project doesn't build anymore on newer compiler versions

We're getting:

error: opaque type's hidden type cannot be another opaque type from the same scope
  --> bootloader/src/main.rs:34:1
   |
34 | #[embassy::main]
   | ^^^^^^^^^^^^^^^^ one of the two opaque types used here has to be outside its defining scope
   |
note: opaque type whose hidden type is being assigned
  --> bootloader/src/main.rs:34:1
   |
34 | #[embassy::main]
   | ^^^^^^^^^^^^^^^^
note: opaque type being used as hidden type
  --> bootloader/src/main.rs:34:1
   |
34 | #[embassy::main]
   | ^^^^^^^^^^^^^^^^
   = note: this error originates in the attribute macro `::embassy::task` (in Nightly builds, run with -Z macro-backtrace for more info)

Probably need to update to a newer version of Embassy

application using embassy_time not working

An application using embassy_time and "time-driver-rtc1" from embassy-nrf crashes.

(HOST) INFO  flashing program (8.71 KiB)
(HOST) INFO  success!
────────────────────────────────────────────────────────────────────────────────
────────────────────────────────────────────────────────────────────────────────
stack backtrace:
   0: HardFaultTrampoline
      <exception entry>
   1: _ZN4core3ptr13read_volatile17hd3f8821b78d6920fE
        at /rustc/8b705839cd656d202e920efa8769cbe43a5ee269/library/core/src/ptr/mod.rs:1474:9
   2: _ZN5vcell21VolatileCell$LT$T$GT$3get17h846ed7bb76a64525E
        at /Users/martin/.cargo/registry/src/github.com-1ecc6299db9ec823/vcell-0.1.3/src/lib.rs:33:18
   3: _ZN11nrf9160_pac7generic14Reg$LT$REG$GT$4read17h781ecf172b477ff2E
        at /Users/martin/.cargo/registry/src/github.com-1ecc6299db9ec823/nrf9160-pac-0.11.0/src/generic.rs:65:19
   4: _ZN84_$LT$embassy_nrf..time_driver..RtcDriver$u20$as$u20$embassy_time..driver..Driver$GT$3now17h4e33ced8e698ee26E
        at /Users/martin/.cargo/git/checkouts/embassy-9312dcb0ed774b29/d49d1b6/embassy-nrf/src/time_driver.rs:218:23
   5: _embassy_time_now
        at /Users/martin/.cargo/git/checkouts/embassy-9312dcb0ed774b29/d49d1b6/embassy-time/src/driver.rs:156:13
   6: _ZN12embassy_time6driver3now17hf91ab4d33d5c6c11E
        at /Users/martin/.cargo/git/checkouts/embassy-9312dcb0ed774b29/d49d1b6/embassy-time/src/driver.rs:126:14
   7: _ZN12embassy_time7instant7Instant3now17h0483671508ea8743E
        at /Users/martin/.cargo/git/checkouts/embassy-9312dcb0ed774b29/d49d1b6/embassy-time/src/instant.rs:21:26
   8: _ZN16embassy_executor3raw8Executor4poll17h42b4164cf3414afbE
        at /Users/martin/.cargo/git/checkouts/embassy-9312dcb0ed774b29/d49d1b6/embassy-executor/src/raw/mod.rs:358:42
   9: _ZN16embassy_executor4arch8Executor3run17hb54781054eaf4739E
        at /Users/martin/.cargo/git/checkouts/embassy-9312dcb0ed774b29/d49d1b6/embassy-executor/src/arch/cortex_m.rs:54:17
  10: _ZN7bateman18__cortex_m_rt_main17hf74310984f680484E
        at src/main.rs:12:1
  11: main
        at src/main.rs:12:1
  12: Reset
(HOST) ERROR the program panicked

If I run it without any time features it works.

Vector table is not changed

We use the cortex m bootload function:

dis-bootloader/bootloader/src/main.rs

Line 371 in 4741e29

unsafe { cortex_m::asm::bootload(application_address as *const u32) }

But that doesn't change the vector table. We should do that.

Update the page swapping so no scratch space is required

Suggestion by Dirbaio:

There's one trick to swap without needing scratch space, just needs slot B to be 1 page bigger.

[ABC] [abc.]
[ABC] [abcC]
[ABc] [abcC]
[ABc] [abBC]
[Abc] [abBC]
[Abc] [aABC]
[abc] [aABC]
[abc] [.ABC]

Needs "moving" each page just once, and each page gets written just once (so if your flash can do 10k erases you can do 10k swaps, with scratch you can do less because you're "concentrating" many erases into the scratch pages).
After swap slot B is "shifted" by 1, so you need to do the "unswap" in the reverse order to account for that.