[pve-devel] [PATCH v2 docs 1/3] Add man-page and notes about custom CPU models

[Stefan Reiter]

Signed-off-by: Stefan Reiter <s.reiter at proxmox.com>
---

Requires qemu-server with patch 2 applied.

v2:
* improved wording from Aaron's review
Other patches are unchanged.

 Makefile                      |  1 +
 cpu-models.conf.adoc          | 82 +++++++++++++++++++++++++++++++++++
 gen-cpu-models.conf.5-opts.pl | 14 ++++++
 qm.adoc                       | 11 +++++
 4 files changed, 108 insertions(+)
 create mode 100644 cpu-models.conf.adoc
 create mode 100755 gen-cpu-models.conf.5-opts.pl

diff --git a/Makefile b/Makefile
index ca56e96..98b6b44 100644
--- a/Makefile
+++ b/Makefile
@@ -53,6 +53,7 @@ GEN_SCRIPTS=					\
 	gen-pct-network-opts.pl			\
 	gen-pct-mountpoint-opts.pl		\
 	gen-qm.conf.5-opts.pl			\
+	gen-cpu-models.conf.5-opts.pl 		\
 	gen-qm-cloud-init-opts.pl		\
 	gen-vzdump.conf.5-opts.pl		\
 	gen-pve-firewall-cluster-opts.pl	\
diff --git a/cpu-models.conf.adoc b/cpu-models.conf.adoc
new file mode 100644
index 0000000..7b48a6e
--- /dev/null
+++ b/cpu-models.conf.adoc
@@ -0,0 +1,82 @@
+ifdef::manvolnum[]
+cpu-models.conf(5)
+==================
+:pve-toplevel:
+
+NAME
+----
+
+cpu-models.conf - Custom CPU model configuration file
+
+
+SYNOPSIS
+--------
+
+'/etc/pve/virtual-guest/cpu-models.conf'
+
+
+DESCRIPTION
+-----------
+endif::manvolnum[]
+
+ifndef::manvolnum[]
+Custom CPU Model Configuration
+==============================
+endif::manvolnum[]
+ifdef::wiki[]
+:pve-toplevel:
+:title: Manual: cpu-models.conf
+endif::wiki[]
+
+The `/etc/pve/virtual-guest/cpu-models.conf` file stores custom CPU
+models, which can be used by VMs to get access to advanced CPU
+features (for example custom CPU flags).
+
+
+File Format
+-----------
+
+CPU models each have their own section in the file, beginning with
+the header:
+
+ cpu-model: <name>
+
+Note that <name> does not include the 'custom-' prefix, which is
+required in VM configs to denote custom CPU models.
+
+For example, if the <name> is 'foobar', the CPU for a VM would need to be
+configured as 'custom-foobar'.
+
+Each section can specify several options. They are indented by either one TAB
+character or multiple spaces. Every option and its value is separated by one
+space, for example:
+
+ reported-model qemu64
+
+See below for all available options.
+
+Blank lines and those starting with a `#` are ignored.
+
+
+Options
+-------
+
+include::cpu-models.conf.5-opts.adoc[]
+
+
+Example File
+------------
+
+----
+cpu-model: avx
+    flags +avx;+avx2
+    phys-bits host
+    hidden 0
+    hv-vendor-id proxmox
+    reported-model kvm64
+----
+
+
+ifdef::manvolnum[]
+include::pve-copyright.adoc[]
+endif::manvolnum[]
diff --git a/gen-cpu-models.conf.5-opts.pl b/gen-cpu-models.conf.5-opts.pl
new file mode 100755
index 0000000..7c35d69
--- /dev/null
+++ b/gen-cpu-models.conf.5-opts.pl
@@ -0,0 +1,14 @@
+#!/usr/bin/perl
+
+use lib '.';
+use strict;
+use warnings;
+use PVE::RESTHandler;
+use PVE::QemuServer::CPUConfig;
+
+my $prop = PVE::QemuServer::CPUConfig::add_cpu_json_properties({});
+
+# cputype is given as section header and explained seperately
+delete $prop->{cputype};
+
+print PVE::RESTHandler::dump_properties($prop);
diff --git a/qm.adoc b/qm.adoc
index cd6641f..45832e9 100644
--- a/qm.adoc
+++ b/qm.adoc
@@ -352,6 +352,17 @@ the kvm64 default. If you don’t care about live migration or have a homogeneou
 cluster where all nodes have the same CPU, set the CPU type to host, as in
 theory this will give your guests maximum performance.
 
+Custom CPU Types
+^^^^^^^^^^^^^^^^
+
+You can specify custom CPU types with a configurable set of features. These are
+maintained in the configuration file `/etc/pve/virtual-guest/cpu-models.conf` by
+an administrator. See `man cpu-models.conf` for format details.
+
+Specified custom types can be selected by any user with the `Sys.Audit`
+privilege on `/nodes`. When configuring a custom CPU type for a VM via the CLI
+or API, the name needs to be prefixed with 'custom-'.
+
 Meltdown / Spectre related CPU flags
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-- 
2.20.1