From 251fa68fcaede2ffb08c8c965b9601084d7ee035 Mon Sep 17 00:00:00 2001 From: Robin Mueller Date: Thu, 12 Sep 2024 19:25:33 +0200 Subject: [PATCH] docs --- README.md | 7 ++++- bootloader/README.md | 57 ++++++++++++++++++++++++++-------------- flashloader/README.md | 60 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 104 insertions(+), 20 deletions(-) create mode 100644 flashloader/README.md diff --git a/README.md b/README.md index 457514a..1b55377 100644 --- a/README.md +++ b/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 diff --git a/bootloader/README.md b/bootloader/README.md index 1e7f462..387675a 100644 --- a/bootloader/README.md +++ b/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 | | -| -------- | ------------------ | ---------------- -| <0x3FFE> | Bootloader CRC | | -| -------- | ------------------ | ---------------- -| <0x4000> | App image A start | | -| -------- | ------------------ | ---------------- -| <0x21FFC> | App image A CRC check length | | -| -------- | ------------------ | ---------------- -| <0x21FFE> | App image A CRC check value | | -| -------- | ------------------ | ---------------- -| <0x22000> | App image B start | | -| -------- | ------------------ | ---------------- -| <0x3FFFC> | App image B CRC check length | | -| -------- | ------------------ | ---------------- -| <0x3FFFE> | App image B CRC check value | | -| -------- | ------------------ | ---------------- -| <0x40000> | End of NVM | | -| -------- | ------------------ | ---------------- +| Address | Notes | Size | +| ------ | ---- | ---- | +| 0x0 | Bootloader start | code up to 0x3FFC bytes | +| 0x3FFC | Bootloader CRC | word | +| 0x4000 | App image A start | code up to 0x1DFFC (~120K) bytes | +| 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 | +| 0x3FFFC | App image B CRC check length | word | +| 0x3FFFE | App image B CRC check value | word | +| 0x40000 | End of NVM | end | + +## Additional Information 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. diff --git a/flashloader/README.md b/flashloader/README.md new file mode 100644 index 0000000..f3bb928 --- /dev/null +++ b/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.