[PATCH 23/32] docs: formatdomain-devices: Split out <watchdog>

Signed-off-by: Peter Krempa <pkrempa(a)redhat.com&gt; --- docs/formatdomain-devices-watchdog.rst | 63 +++++++++++++++++++++++++ docs/formatdomain-devices.rst | 65 +------------------------- docs/meson.build | 1 + 3 files changed, 65 insertions(+), 64 deletions(-) create mode 100644 docs/formatdomain-devices-watchdog.rst diff --git a/docs/formatdomain-devices-watchdog.rst b/docs/formatdomain-devices-watchdog.rst new file mode 100644 index 0000000000..7a7ffaffce --- /dev/null +++ b/docs/formatdomain-devices-watchdog.rst @@ -0,0 +1,63 @@ +:anchor:`<a id="elementsWatchdog"/>` + +Watchdog device +~~~~~~~~~~~~~~~ + +A virtual hardware watchdog device can be added to the guest via the +``watchdog`` element. :since:`Since 0.7.3, QEMU and KVM only` + +The watchdog device requires an additional driver and management daemon in the +guest. Just enabling the watchdog in the libvirt configuration does not do +anything useful on its own. + +Currently libvirt does not support notification when the watchdog fires. This +feature is planned for a future version of libvirt. + +:: + + ... + <devices> + <watchdog model='i6300esb'/> + </devices> + ... + +:: + + ... + <devices> + <watchdog model='i6300esb' action='poweroff'/> + </devices> + </domain> + +``model`` + The required ``model`` attribute specifies what real watchdog device is + emulated. Valid values are specific to the underlying hypervisor. + + QEMU and KVM support: + + - 'i6300esb' - the recommended device, emulating a PCI Intel 6300ESB + - 'ib700' - emulating an ISA iBase IB700 + - 'diag288' - emulating an S390 DIAG288 device :since:`Since 1.2.17` + +``action`` + The optional ``action`` attribute describes what action to take when the + watchdog expires. Valid values are specific to the underlying hypervisor. + + QEMU and KVM support: + + - 'reset' - default, forcefully reset the guest + - 'shutdown' - gracefully shutdown the guest (not recommended) + - 'poweroff' - forcefully power off the guest + - 'pause' - pause the guest + - 'none' - do nothing + - 'dump' - automatically dump the guest :since:`Since 0.8.7` + - 'inject-nmi' - inject a non-maskable interrupt into the guest + :since:`Since 1.2.17` + + Note 1: the 'shutdown' action requires that the guest is responsive to ACPI + signals. In the sort of situations where the watchdog has expired, guests are + usually unable to respond to ACPI signals. Therefore using 'shutdown' is not + recommended. + + Note 2: the directory to save dump files can be configured by + ``auto_dump_path`` in file /etc/libvirt/qemu.conf. diff --git a/docs/formatdomain-devices.rst b/docs/formatdomain-devices.rst index acf08e8d15..819c05e531 100644 --- a/docs/formatdomain-devices.rst +++ b/docs/formatdomain-devices.rst @@ -55,70 +55,7 @@ following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0` .. include:: formatdomain-devices-video.rst .. include:: formatdomain-devices-chardev.rst .. include:: formatdomain-devices-sound.rst - -:anchor:`<a id="elementsWatchdog"/>` - -Watchdog device -~~~~~~~~~~~~~~~ - -A virtual hardware watchdog device can be added to the guest via the -``watchdog`` element. :since:`Since 0.7.3, QEMU and KVM only` - -The watchdog device requires an additional driver and management daemon in the -guest. Just enabling the watchdog in the libvirt configuration does not do -anything useful on its own. - -Currently libvirt does not support notification when the watchdog fires. This -feature is planned for a future version of libvirt. - -:: - - ... - <devices> - <watchdog model='i6300esb'/> - </devices> - ... - -:: - - ... - <devices> - <watchdog model='i6300esb' action='poweroff'/> - </devices> - </domain> - -``model`` - The required ``model`` attribute specifies what real watchdog device is - emulated. Valid values are specific to the underlying hypervisor. - - QEMU and KVM support: - - - 'i6300esb' - the recommended device, emulating a PCI Intel 6300ESB - - 'ib700' - emulating an ISA iBase IB700 - - 'diag288' - emulating an S390 DIAG288 device :since:`Since 1.2.17` - -``action`` - The optional ``action`` attribute describes what action to take when the - watchdog expires. Valid values are specific to the underlying hypervisor. - - QEMU and KVM support: - - - 'reset' - default, forcefully reset the guest - - 'shutdown' - gracefully shutdown the guest (not recommended) - - 'poweroff' - forcefully power off the guest - - 'pause' - pause the guest - - 'none' - do nothing - - 'dump' - automatically dump the guest :since:`Since 0.8.7` - - 'inject-nmi' - inject a non-maskable interrupt into the guest - :since:`Since 1.2.17` - - Note 1: the 'shutdown' action requires that the guest is responsive to ACPI - signals. In the sort of situations where the watchdog has expired, guests are - usually unable to respond to ACPI signals. Therefore using 'shutdown' is not - recommended. - - Note 2: the directory to save dump files can be configured by - ``auto_dump_path`` in file /etc/libvirt/qemu.conf. +.. include:: formatdomain-devices-watchdog.rst :anchor:`<a id="elementsMemBalloon"/>` diff --git a/docs/meson.build b/docs/meson.build index c6efff8b80..21dcd589d7 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -140,6 +140,7 @@ docs_rst_files = [ 'formatdomain-devices-video.rst', 'formatdomain-devices-chardev.rst', 'formatdomain-devices-sound.rst', + 'formatdomain-devices-watchdog.rst', ] }, { 'name': 'hacking' }, -- 2.26.2