docs

README.md

@@ -19,7 +19,12 @@ This workspace contains the following crates:
 
 It also contains the following helper crates:
 
-- The `examples` crates contains various example applications for the HAL and the PAC.
+- The [`bootloader`](https://egit.irs.uni-stuttgart.de/rust/va416xx-rs/src/branch/main/bootloader)
+  crate contains a sample bootloader strongly based on the one provided by Vorago.
+- The [`flashloader`](https://egit.irs.uni-stuttgart.de/rust/va416xx-rs/src/branch/main/flashloader)
+  crate contains a sample flashloader which is able to update the redundant images in the NVM which
+  is compatible to the provided bootloader as well.
+- The `examples` folder contains various example applications crates for the HAL and the PAC.
 
 ## Using the `.cargo/config.toml` file
 

bootloader/README.md

@@ -3,26 +3,45 @@ VA416xx Bootloader Application
 
 This is the Rust version of the bootloader supplied by Vorago.
 
+## Memory Map
+
 The bootloader uses the following memory map:
 
-| <0x0> | Bootloader start | <code up to 0x3FFE bytes> |
+| Address | Notes | Size |
-| -------- | ------------------ | ---------------- 
+| ------ | ---- |  ---- |
-| <0x3FFE> | Bootloader CRC | <word> |
+| 0x0 | Bootloader start | code up to 0x3FFC bytes |
-| -------- | ------------------ | ---------------- 
+| 0x3FFC | Bootloader CRC | word |
-| <0x4000> | App image A start | <code up to 0x1DFFC (~120K) bytes> |
+| 0x4000 | App image A start | code up to 0x1DFFC (~120K) bytes |
-| -------- | ------------------ | ---------------- 
+| 0x21FFC | App image A CRC check length | word |
-| <0x21FFC> | App image A CRC check length | <word> |
+| 0x21FFE | App image A CRC check value | word |
-| -------- | ------------------ | ---------------- 
+| 0x22000 | App image B start | code up to 0x1DFFC (~120K) bytes |
-| <0x21FFE> | App image A CRC check value | <word> | 
+| 0x3FFFC | App image B CRC check length | word |
-| -------- | ------------------ | ---------------- 
+| 0x3FFFE | App image B CRC check value | word |
-| <0x22000> | App image B start | <code up to 0x1DFFC (~120K) bytes> |
+| 0x40000 | End of NVM | end  |
-| -------- | ------------------ | ---------------- 
+
-| <0x3FFFC> | App image B CRC check length | <word> |
+## Additional Information
-| -------- | ------------------ | ---------------- 
-| <0x3FFFE> | App image B CRC check value | <word> |
-| -------- | ------------------ | ---------------- 
-| <0x40000> | End of NVM | <end>  |
-| -------- | ------------------ | ---------------- 
 
 As opposed to the Vorago example code, this bootloader assumes a 40 MHz external clock
-but does not scale that clock up.
+but does not scale that clock up. It also uses a word (4 bytes) instead of a half-word for the CRC
+and uses the ISO 3309 CRC32 standard checksum.
+
+This bootloader does not provide tools to flash the NVM memories by itself. Instead, you can use
+the [flashloader](https://egit.irs.uni-stuttgart.de/rust/va416xx-rs/src/branch/main/flashloader)
+application to perform this task using a CCSDS interface via a UART.
+
+The bootloader performs the following steps:
+
+1. The application will calculate the checksum of itself if the bootloader CRC is blank (all zeroes
+   or all ones). If the CRC is not blank and the checksum check fails, it will immediately boot
+   application image A. Otherwise, it proceeds to the next step.
+2. Check the checksum of App A. If that checksum is valid, it will boot App A. If not, it will
+   proceed to the next step.
+3. Check the checksum of App B. If that checksum is valid, it will boot App B. If not, it will
+   boot App A as the fallback image.
+
+You could adapt and combine this bootloader with a non-volatile memory to select a prefered app
+image, which would be a first step towards an updatable flight software.
+
+Please note that you *MUST* compile the application at slot A and slot B with an appropriate
+`memory.x` file where the base address of the `FLASH` was adapted according to the base address
+shown in the memory map above. The memory files to do this were provided in the `scripts` folder.

flashloader/README.md

@@ -0,0 +1,60 @@
+VA416xx Flashloader Application
+========
+
+This flashloader shows a minimal example for a self-updatable Rust software which exposes
+a simple PUS (CCSDS) interface to update the software. It also provides a Python application
+called the `image-loader.py` which can be used to upload compiled images to the flashloader
+application to write them to the NVM.
+
+The software can quickly be adapted to interface with a real primary on-board software instead of
+the Python script provided here to upload images because it uses a low-level CCSDS based packet
+interface.
+
+## Using the Python image loader
+
+It is recommended to run the script in a dedicated virtual environment. For example, on UNIX
+systems you can use `python3 -m venv venv` and then `source venv/bin/activate` to create
+and activate a virtual environment.
+
+After that, you can use
+
+```sh
+pip install -r requirements.txt
+```
+
+to install all required dependencies.
+
+After that, it is recommended to use `./image-load.py -h` to get an overview of some options.
+The flash loader uses the UART0 interface of the VA416xx board to perform CCSDS based
+communication. The Python image loader application will search for a file named `loader.toml` and
+use the `serial_port` key to determine the serial port to use for serial communication.
+
+### Examples
+
+You can use
+
+```sh
+./image-loader.py -p
+```
+
+to send a ping an verify the connection.
+
+You can use
+
+```sh
+cd flashloader/slot-a-blinky
+cargo build --release
+cd ../..
+./image-loader.py -t a ./slot-a-blinky/target/thumbv7em-none-eabihf/release/slot-a-blinky
+```
+
+to build the slot A sample application and upload it to a running flash loader application
+to write it to slot A.
+
+You can use
+
+```sh
+./image-loader.py -c -t a
+```
+
+to corrupt the image A and test that it switches to image B after a failed CRC check instead.