[PATCH qemu-server/docs/manager v3 0/3] add pvpanic device support

[PATCH qemu-server/docs/manager v3 0/3] add pvpanic device support

[Kaiyang Wu]

This patchset adds pvpanic device support to QEMU virtual machines to
provide extra virtual machine status (guest-panicked) when virtual
machines panic [0].

[0]: https://www.qemu.org/docs/master/specs/pvpanic.html

v1: https://lore.proxmox.com/pve-devel/20260827103529.393388-1-wukaiyang@loongfans.cn/
v2: https://lore.proxmox.com/pve-devel/20260914092015.125780-1-wukaiyang@loongfans.cn/

Changes v1 -> v2:
- Remove the pvpanic ISA device support to simplify the code
- Move the pvpanic setting from Hardware to Options
- Restart a HA-managed VM when it panics to restore the "started" state

Changes v2 -> v3:
- Allow to set panic action. The HA stack automatically restarts a panicked VM
  when the VM exits using the 'exit-failure' panic action


qemu-server:

Kaiyang Wu (1):
  qemuserver: add pvpanic device

 src/PVE/API2/Qemu.pm      |  1 +
 src/PVE/QemuServer.pm     | 42 +++++++++++++++++++++++++++++++++++++++
 src/PVE/QemuServer/PCI.pm |  1 +
 3 files changed, 44 insertions(+)


docs:

Kaiyang Wu (1):
  qm: add document section for the pvpanic device

 qm.adoc | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)


manager:

Kaiyang Wu (1):
  ui: qemu: add pvpanic device support

 www/manager6/Makefile                |  1 +
 www/manager6/Utils.js                | 18 +++++++++
 www/manager6/form/PvpanicSelector.js | 56 ++++++++++++++++++++++++++++
 www/manager6/qemu/Options.js         | 16 ++++++++
 4 files changed, 91 insertions(+)
 create mode 100644 www/manager6/form/PvpanicSelector.js

-- 
2.56.0

[PATCH qemu-server v3 1/3] qemuserver: add pvpanic device

[Kaiyang Wu]

Add pvpanic PCI device to monitor guest system panics. Allow to specify
the action to perform when the guest system panics.

Suggested-by: Dominik Csapak <d.csapak@proxmox.com>
Signed-off-by: Kaiyang Wu <wukaiyang@loongfans.cn>
---
 src/PVE/API2/Qemu.pm      |  1 +
 src/PVE/QemuServer.pm     | 42 +++++++++++++++++++++++++++++++++++++++
 src/PVE/QemuServer/PCI.pm |  1 +
 3 files changed, 44 insertions(+)

diff --git a/src/PVE/API2/Qemu.pm b/src/PVE/API2/Qemu.pm
index 922c6599..fb5c2f05 100644
--- a/src/PVE/API2/Qemu.pm
+++ b/src/PVE/API2/Qemu.pm
@@ -818,6 +818,7 @@ my $hwtypeoptions = {
     'watchdog' => 1,
     'audio0' => 1,
     'rng0' => 1,
+    'pvpanic' => 1,
 };
 
 my $generaloptions = {
diff --git a/src/PVE/QemuServer.pm b/src/PVE/QemuServer.pm
index f199371d..8698fb11 100644
--- a/src/PVE/QemuServer.pm
+++ b/src/PVE/QemuServer.pm
@@ -141,6 +141,23 @@ sub nodename {
     return $nodename_cache;
 }
 
+my $pvpanic_fmt = {
+    enabled => {
+        default_key => 1,
+        type => 'boolean',
+        description => "Create a pvpanic device to monitor guest panics.",
+        default => 0,
+    },
+    action => {
+        type => 'string',
+        enum => [qw(none pause shutdown exit-failure)],
+        description =>
+            "The action to perform if the guest panics.",
+        optional => 1,
+    },
+};
+PVE::JSONSchema::register_format('pve-qm-pvpanic', $pvpanic_fmt);
+
 my $watchdog_fmt = {
     model => {
         default_key => 1,
@@ -739,6 +756,12 @@ EODESCR
         optional => 1,
         default => 1,
     },
+    pvpanic => {
+        optional => 1,
+        type => 'string',
+        format => 'pve-qm-pvpanic',
+        description => "Create a panic monitor device.",
+    },
 };
 
 my $cicustom_fmt = {
@@ -1674,6 +1697,16 @@ sub print_smbios1 {
 
 PVE::JSONSchema::register_format('pve-qm-smbios1', $smbios1_fmt);
 
+sub parse_pvpanic {
+    my ($value) = @_;
+
+    return if !$value;
+
+    my $res = eval { parse_property_string($pvpanic_fmt, $value) };
+    warn $@ if $@;
+    return $res;
+}
+
 sub parse_watchdog {
     my ($value) = @_;
 
@@ -3556,6 +3589,15 @@ sub config_to_command {
         push @$devices, '-device', $ballooncmd;
     }
 
+    if ($conf->{pvpanic}) {
+        my $pvpanicopts = parse_pvpanic($conf->{pvpanic});
+        if ($pvpanicopts->{enabled}) {
+            my $pvpanicpciaddr = print_pci_addr("pvpanic", $arch);
+            push @$devices, '-device', "pvpanic-pci,id=pvpanic$pvpanicpciaddr";
+        }
+        push @$devices, '-action', "panic=$pvpanicopts->{action}" if $pvpanicopts->{action};
+    }
+
     if ($conf->{watchdog}) {
         my $wdopts = parse_watchdog($conf->{watchdog});
         my $pciaddr = print_pci_addr("watchdog", $arch);
diff --git a/src/PVE/QemuServer/PCI.pm b/src/PVE/QemuServer/PCI.pm
index d7dc6121..5b0603a0 100644
--- a/src/PVE/QemuServer/PCI.pm
+++ b/src/PVE/QemuServer/PCI.pm
@@ -220,6 +220,7 @@ sub get_pci_addr_map {
         'pci.4' => { bus => 1, addr => 28 },
         'rng0' => { bus => 1, addr => 29 },
         'pci.2-igd' => { bus => 1, addr => 30 }, # replaces pci.2 in case a legacy IGD device is passed through
+        'pvpanic' => { bus => 1, addr => 31 },
         'virtio6' => { bus => 2, addr => 1 },
         'virtio7' => { bus => 2, addr => 2 },
         'virtio8' => { bus => 2, addr => 3 },
-- 
2.56.0

[PATCH docs v3 2/3] qm: add document section for the pvpanic device

[Kaiyang Wu]

Document the pvpanic device and corresponding driver requirements on
different VMs.

Signed-off-by: Kaiyang Wu <wukaiyang@loongfans.cn>
---
 qm.adoc | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/qm.adoc b/qm.adoc
index 18a4fbe..5972fea 100644
--- a/qm.adoc
+++ b/qm.adoc
@@ -1476,6 +1476,44 @@ tag (name used to mount the device on the guest).
 For more information on available virtiofsd parameters, see the
 https://gitlab.com/virtio-fs/virtiofsd[GitLab virtiofsd project page].
 
+[[qm_pvpanic]]
+Pvpanic
+~~~~~~~
+
+Pvpanic is a device to send system panic events to QEMU. It allows to
+provide extra VM status and execute the specified panic action when the VM
+system crashes.
+
+To add a pvpanic device run the following command:
+
+----
+qm set <vmid> -pvpanic enabled=1[,action=<action>]
+----
+
+A panic action can be specified to perform when the VM system crashes. Available
+panic actions are:
+
+* `none`: Continue VM execution
+* `pause`: Pause the VM
+* `shutdown`: Shutdown the VM and exit, according to the shutdown action
+* `exit-failure`: Shutdown the VM and exit with non-zero status
+
+NOTE: The default panic action is `shutdown`. However, because the shutdown
+action is set to `pause` by default, `shutdown` and `pause` both pause the
+VM unless manually specifying the shutdown action using custom `args`.
+
+NOTE: VMs managed by the HA stack can set `exit-failure` to exit the QEMU
+process completely and let the HA stack start it again.
+
+Linux VMs with kernel >=5.2 support pvpanic PCI device by default
+(https://www.kernelconfig.io/CONFIG_PVPANIC_PCI[pvpanic PCI driver]).
+
+Windows VMs require
+https://github.com/virtio-win/kvm-guest-drivers-windows/[kvm-guest-drivers-windows]
+to use pvpanic.
+
+FreeBSD VMs do not support pvpanic.
+
 [[qm_bootorder]]
 Device Boot Order
 ~~~~~~~~~~~~~~~~~
-- 
2.56.0

[PATCH manager v3 3/3] ui: qemu: add pvpanic device support

[Kaiyang Wu]

Add basic structure for adding a pvpanic PCI device, allowing to monitor
guest system panics through the pvpanic device, and specify panic action
to execute when guest system panics.

Suggested-by: Dominik Csapak <d.csapak@proxmox.com>
Signed-off-by: Kaiyang Wu <wukaiyang@loongfans.cn>
---
 www/manager6/Makefile                |  1 +
 www/manager6/Utils.js                | 18 +++++++++
 www/manager6/form/PvpanicSelector.js | 56 ++++++++++++++++++++++++++++
 www/manager6/qemu/Options.js         | 16 ++++++++
 4 files changed, 91 insertions(+)
 create mode 100644 www/manager6/form/PvpanicSelector.js

diff --git a/www/manager6/Makefile b/www/manager6/Makefile
index d2ea786b..d3c15c29 100644
--- a/www/manager6/Makefile
+++ b/www/manager6/Makefile
@@ -65,6 +65,7 @@ JSSRC= 							\
 	form/PoolSelector.js				\
 	form/PreallocationSelector.js			\
 	form/PrivilegesSelector.js			\
+	form/PvpanicSelector.js			\
 	form/QemuBiosSelector.js			\
 	form/QemuMachineSelector.js			\
 	form/RecordSearchField.js			\
diff --git a/www/manager6/Utils.js b/www/manager6/Utils.js
index 8b99371d..8263eea7 100644
--- a/www/manager6/Utils.js
+++ b/www/manager6/Utils.js
@@ -557,6 +557,24 @@ Ext.define('PVE.Utils', {
             }
         },
 
+        render_pvpanic: function (value) {
+            if (!value) {
+                return Proxmox.Utils.defaultText + ' (' + Proxmox.Utils.disabledText + ')';
+            }
+
+            let pvpanic = PVE.Parser.parsePropertyString(value, 'enabled');
+
+            if (!PVE.Parser.parseBoolean(pvpanic.enabled)) {
+                return Proxmox.Utils.disabledText;
+            }
+
+            if (pvpanic.action) {
+                return Proxmox.Utils.enabledText + `, Panic Action: ${pvpanic.action}`;
+            } else {
+                return Proxmox.Utils.enabledText + ', Panic Action: ' + Proxmox.Utils.defaultText + ' (shutdown)';
+            }
+        },
+
         render_dc_ha_opts: function (value) {
             if (!value) {
                 return Proxmox.Utils.defaultText;
diff --git a/www/manager6/form/PvpanicSelector.js b/www/manager6/form/PvpanicSelector.js
new file mode 100644
index 00000000..eda5795d
--- /dev/null
+++ b/www/manager6/form/PvpanicSelector.js
@@ -0,0 +1,56 @@
+Ext.define('PVE.form.PvpanicSelector', {
+    extend: 'Proxmox.panel.InputPanel',
+    alias: 'widget.pvePvpanicSelector',
+
+    viewModel: {},
+
+    items: [
+        {
+            xtype: 'proxmoxcheckbox',
+            fieldLabel: gettext('Enable'),
+            name: 'enabled',
+            reference: 'enabled',
+            uncheckedValue: 0,
+        },
+        {
+            xtype: 'proxmoxKVComboBox',
+            fieldLabel: gettext('Panic Action'),
+            name: 'action',
+            value: '__default__',
+            comboItems: [
+                ['__default__', Proxmox.Utils.defaultText + ' (shutdown)'],
+                ['none', 'none'],
+                ['pause', 'pause'],
+                ['shutdown', 'shutdown'],
+                ['exit-failure', 'exit-failure'],
+            ],
+            bind: {
+                disabled: '{!enabled.checked}',
+            },
+        },
+    ],
+
+    onGetValues: function (values) {
+        let ret = {};
+
+        if (values.enabled) {
+            ret.enabled = 1;
+        }
+        if (values.action) {
+            ret.enabled = values.enabled;
+            ret.action = values.action;
+        }
+        if (Ext.Object.isEmpty(ret)) {
+            return { delete: 'pvpanic' };
+        }
+        let pvpanic = PVE.Parser.printPropertyString(ret, 'enabled');
+        return { pvpanic: pvpanic };
+    },
+
+    setValues: function (values) {
+        if (values.pvpanic) {
+            let pvpanic = PVE.Parser.parsePropertyString(values.pvpanic, 'enabled');
+            this.callParent([pvpanic]);
+        }
+    },
+});
diff --git a/www/manager6/qemu/Options.js b/www/manager6/qemu/Options.js
index 8a4721a0..75cdebf9 100644
--- a/www/manager6/qemu/Options.js
+++ b/www/manager6/qemu/Options.js
@@ -311,6 +311,22 @@ Ext.define('PVE.qemu.Options', {
                       }
                     : undefined,
             },
+            pvpanic: {
+                header: gettext('Panic Monitor'),
+                defaultValue: false,
+                renderer: PVE.Utils.render_pvpanic,
+                editor: caps.vms['VM.Config.HWType']
+                    ? {
+                          xtype: 'proxmoxWindowEdit',
+                          subject: gettext('Panic Monitor'),
+                          onlineHelp: 'qm_pvpanic',
+                          items: {
+                              xtype: 'pvePvpanicSelector',
+                              name: 'pvpanic',
+                          },
+                      }
+                    : undefined,
+            },
             protection: {
                 header: gettext('Protection'),
                 defaultValue: false,
-- 
2.56.0