From 4aad245b31d5e9e0b18f31b890fa3727996f7ab1 Mon Sep 17 00:00:00 2001 From: bunnie Date: Sun, 9 Oct 2022 14:22:02 +0800 Subject: [PATCH] add notes about how to maintain the XOUS_MIN_VER field --- xtask/src/main.rs | 31 +++++++++++++++++++++++++------ 1 file changed, 25 insertions(+), 6 deletions(-) diff --git a/xtask/src/main.rs b/xtask/src/main.rs index 4db88ec28..dde6f16c5 100644 --- a/xtask/src/main.rs +++ b/xtask/src/main.rs @@ -14,12 +14,31 @@ use std::env; /// be manually updated every time the SoC version is bumped. const PRECURSOR_SOC_VERSION: &str = "c809403"; -/// This is the minimum Xous version required to read a PDDB backup generated -/// by the current kernel revision. -/// NOTE: this actually doesn't work. This field needed to find its way into -/// the backup header, but instead it's just attached to the metadata of the -/// kernel file itself. -const MIN_XOUS_VERSION: &str = "v0.9.9-466-gc471ca0f"; +/* + Some notes on kernel versions versus backups. + + At v0.9.8-791, migrations from v1 PDDB were deprecated + At v0.9.9-42, backups were introduced, with a backup header version of v1.0 + At v0.9.9-466, a bug parsing minor versions was fixed; + now the minor version field of the backup header is actually compatible for restore + header version is now v1.1 + + The latest kernel can parse everything down to v0.9.8-791's backup. + However, backups generated by the latest kernel require at least v0.9.9-466 to read it, + due to the minor version masking bug. + + The MIN_XOUS_VERSION field is the oldest backup that a given kernel can parse. + Backups older than this cannot be parsed because the migration code for that backup + was deprecated. The main purpose of this field is to assist the restore script + in selecting a kernel: it will automatically downgrade a kernel as far as it must + to read a very old backup. This tag is *not* useful for enforcing a minimum + version of the kernel to read a very *new* backup. + + Instead, when picking a kernel to restore from, the latest kernel should always be picked, + that is also able to parse the backup. In the case of developing a new breaking change + on backups, the bleeding-edge directory must be added to the list of selectable URLs. +*/ +const MIN_XOUS_VERSION: &str = "v0.9.8-791"; /// target triple for precursor builds const TARGET_TRIPLE: &str = "riscv32imac-unknown-xous-elf";