From 42828bd4f9abfe917beaeeb11ef6302e09cc6826 Mon Sep 17 00:00:00 2001 From: Adam Dobrowolski Date: Fri, 24 Jun 2022 09:02:02 +0200 Subject: [PATCH] [MOS-561] Minimal documentation on how update works Added minimal documentation on upate: - how it works - what is the arhitecture behind --- doc/README.md | 1 + doc/boot_and_update.md | 127 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 128 insertions(+) diff --git a/doc/README.md b/doc/README.md index 9aea58655aec3b2d60942ee2edf56b8211481ce6..71cd9baa74f89b066c862187152af63c69a4c4b4 100644 --- a/doc/README.md +++ b/doc/README.md @@ -7,6 +7,7 @@ This folder contains the documentation of the MuditaOS. - [Development environment](quickstart.md) - [Build targets supported by MuditaOS](build_targets.md) +- [Booting and updating MuditaOS](boot_and_update.md) - [Setting up integrated development environment](setup_ide.md) - [How to use Mudita Pure simulator](howto_simulator.md) - [Keybindings on Linux](host_keyboard_bindings.md) diff --git a/doc/boot_and_update.md b/doc/boot_and_update.md index fcf1374d1900e987dd2f11791263995cbf90acee..bc6ae24f85c9d4a2f380d74f9189d006da1d3f76 100644 --- a/doc/boot_and_update.md +++ b/doc/boot_and_update.md @@ -1,5 +1,132 @@ # How to boot Mudita Pure and create a storage partition +## General update architecture + +There are two major ways to update the OS: +- via update utility +- via MMC access (only for internal development) + +General applications interaction diagram: + +``` + +------------+ + +_____ [reboot] _______| MuditaOS | + ↓ | (boot.bin) | +------------+ +------------+ +|bootloader | ↑ +|ecoboot.bin |--[load and boot]------→◇ ++------------+ ↓ + ↑ ↓ +--------------+ + | |-----[update flag]---------→| Updater | + |________ [reboot] ____________ | (updater.bin)| + +--------------+ +``` + +Simplified flow: +- Bootloader always starts first + - Then, depending on SNVS flag, it boots either: + - updater + - os +- Updater starts after ecoboot, then executes one of the procedures: + - update + - creates backup + - updates the os + - **synchronises changes on success** + - reboots with clean boot flag + - system recovery + - restores last backup + - **synchronises changes on success** + - reboots with clean boot flag + - factory reset + - removes selected data + - **synchronises changes on success** + - reboots with clean boot flag + - pgm keys programming + - programs signkeys for bootloader and OS + - reboots with clean boot flag + - reboot with clean boot flag + - reboots with clean boot flag +- OS, from update perspective + - accepts tar update package + - reboots the OS with SNVS flag set to update + - **nothing more** + +**Important** +The updater is by design: +- as OS-agnostic as possible +- as simple as possible +- does only one procedure at a time with fail-fast approach +- procedural software with: + - short update trace + - that exits on first error + - with easy to pin point failure in the trace + +### How user update works - overview of the user flow + +``` +[PC] -> new session -> [MuditaOS] +[PC] -> send file update.tar -> [MuditaOS] +[PC] <- OK <-- [MuditaOS] +[PC] -> reboot to update [MuditaOS] +[PC] <- OK <-- [MuditaOS] + --- REBOOT --- + [MuditaOS] -- RAM flag -> [ bootloader ] + [ bootloader ] -- RAM flag --> [updater] + [updater] -> process update -> save file: OK / FAIL +--- REBOOT --- + [MuditaOS] <-- [ bootloader ] +[PC] -> new session -> [MuditaOS] +[PC] -> gimme update trace -> [MuditaOS] +[PC] <- OK <-- [MuditaOS] +[PC] -> if: process update == OK => USER: success + == NOK => USER: failure +``` + +### TL;DR; What updater provides: + +1. update +2. restore: from last update to previous system version +3. factory reset: it only cleans data, does not restore factory OS + +## Why is the updater a separate updater application + +To assert that the process is fully separated from the OS and as abstract from the +hardware as possible and finally as simple the update process was designed as +above. + +# Quick and dirty way of how to debug update issues: +1. download update package +2. run the update + - easiest with `QAMuditaOS` i.e. : `python -m pytest +./scenarios/updater/test_load_update.py -s +--update_package=/home/pholat/Downloads/PurePhone-1.2.1-rc.1-RT1051-Update.tar` +3. see the trace result on either: + - trace file on the disk + - uart console from the phone + Trace file have explicitly: + - in what file & line line issue occured + - which procedure failed + - what was the procedure error + - what was the procedure extended error + i.e. +`t:10,name:"checksum_verify:/os/tmp/updater.bin",err:1,ext_err:88,err_cstr:"Checksu +mInvalid",file:"/home/jenkins/workspace/PureUpdater_release_builder_-_signed/ +PureUpdater/updater/procedure/checksum/checksum.c",line:89,opt:checksum +mismatch: : 94bbac3d04632172584d4cb5fd3c21bb` +4. debug via: + ./run.sh + *OR* + load updater.bin + *OR* + from the example: check why there is no checksum in the first place + - check if file with checksum exists + - check if it has checksum in it + Then: + - it there is no checksum **FIX IT** on the CI/locally (for local builds) + - if there was a checksum, and the updater failed **FIX IT** in the updater +5. status is always in 3:/updater.log +6. There is no crash log, if it was to be added - then it should be added with upmost care to not i.e. depend on non existing filesystem into separate crash dump file. + ## Booting Mudita Pure To follow these steps please make sure that you have the latest `ecoboot` bootloader on the phone. We recommend [version 1.0.4](https://github.com/mudita/ecoboot/releases/tag/1.0.4) which will work even if you manage to break the filesystems in the next steps (it's goot to be prepared).