docs: CPU Profile generation

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" "<Your chosen name for the CPU profile>"
+
+```
+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:
+- `<your chosen name in lower case with spaces replaced by underscore (_)>.cpuid.json`
+- `<your chosen name in lower case with spaces replaced by underscore (_)>.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<i>` 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.