add notes about how to maintain the XOUS_MIN_VER field

This commit is contained in:
bunnie 2022-10-09 14:22:02 +08:00
parent 01b68cbdc9
commit 4aad245b31

View file

@ -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";