From d79ff7fedae2f9cb1215868b824a5cc5baa70f6f Mon Sep 17 00:00:00 2001 From: Oliver Anderson Date: Mon, 23 Mar 2026 18:40:03 +0100 Subject: [PATCH] docs: CPU Profile generation We add developer documentation on how to use the CPU profile generation tool. We also include a short outlook section with ideas for what we want to improve in the near future. Signed-off-by: Oliver Anderson On-behalf-of: SAP oliver.anderson@sap.com --- docs/cpu_profile_generation.md | 54 ++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 docs/cpu_profile_generation.md diff --git a/docs/cpu_profile_generation.md b/docs/cpu_profile_generation.md new file mode 100644 index 0000000000..e39132e3ee --- /dev/null +++ b/docs/cpu_profile_generation.md @@ -0,0 +1,54 @@ +# CPU Profile Generation + +## Generating a CPU profile for a new target + +To generate a new CPU profile you start by executing the following command + +```shell +$ cargo run --release -p arch --bin generate-cpu-profile --features="cpu_profile_generation" "" + +``` +on the machine you want to create a CPU profile for. This creates four new files in the `arch/src/x86_64/cpu_profiles` directory: +- `.cpuid.json` +- `.msr.json` +- one license file for each of the two files listed above + +check them in to git and then extend the `arch::x86_64::CpuProfile` enum with a new variant for your freshly generated profile. + +The final step is then to adapt `arch::x86_64::CpuProfile::cpuid_data` and `arch::x86_64::CpuProfile::msr_data` mutatis mutandis +to load the cpuid and msr JSON files we created above. + +## Can existing CPU profiles be updated? + +More recent KVM versions may introduce more support for already existing hardware features. When this happens it is of course +tempting to run the CPU profile generation tool again with the new KVM version as we then get a profile supporting more CPU +functionality. Doing this without giving the CPU profile a new name is however a breaking change and thus not permitted. +Such PRs will **not be accepted**. Instead we encourage you add a `V2` (or higher number if `V` already exists) suffix +when generating the profile. + +## Outlook + +We intend to improve both CPU profile support in Cloud hypervisor as well as the CPU profile generation tool. Here is a +list of ideas that we want to consider. + +### Buildscript: Full automation and (de-) compression + +We will include a build script that automatically extends the `CpuProfile` enum and updates the `cpuid_data` and `msr_data` +methods accordingly. + +While we are at it we can also make the build script compress the JSON files and place those bytes into the binary instead +of the full JSON files as we currently do. + +### CPU Profile upload endpoint + +It would not be much effort to adapt CHV to permit end users to specify their own JSON files instead of those associated +with a profile name. + +This way users can run the CPU profile generation tool on their own hardware and use the resulting CPU profile without +involving upstream. + +Advanced users also get a lot of control to adjust CPU profiles to satisfy their needs as they can now manipulate several +CPUID and/or MSR-based features themselves. + +Before we go ahead with this however, we need to clearly document which changes Cloud hypervisor makes itself regardless +of the selected CPU profile.