[PATCH 6/6] docs: document panic device 'pvpanic-pci'

[Andrea Bolognani]

On Thu, Feb 09, 2023 at 06:32:12PM +0100, Peter Krempa wrote:
> On Thu, Feb 09, 2023 at 08:41:01 -0800, Andrea Bolognani wrote:
> > On Wed, Feb 08, 2023 at 01:09:05PM +0100, Peter Krempa wrote:
> > > On Wed, Feb 08, 2023 at 12:49:05 +0100, Kristina Hanicova wrote:
> > > > +++ b/docs/formatdomain.rst
> > > > @@ -7940,6 +7940,7 @@ Example: usage of panic configuration
> > > >     -  'hyperv' - for Hyper-V crash CPU feature. :since:`Since 1.3.0, QEMU and
> > > >        KVM only`
> > > >     -  's390' - default for S390 guests. :since:`Since 1.3.5`
> > > > +   -  'pvpanic' - for PCI pvpanic devicen :since:`Since 9.1.0, QEMU and KVM only`
> > >
> > > s/devicen/device/
> > >
> > > Also is KVM really required? I'd expect that it will also work with TCG
> > > VMs.
> >
> > I think so as well. But to be honest I'm unclear on what "QEMU and
> > KVM only", as used extensively throughout the document, is intended
> > to mean. Does it mean "only when using the QEMU driver and its KVM
> > domain type", or rather "only when using the QEMU or KVM domain
> > type"? The latter sounds more likely to me, and it would be accurate
> > for the pvpanic-pci device.
>
> Generaly in our docs "QEMU only" means that it works only with the qemu
> driver/hypervisor, thus I don't think the interpretation that <domain
> type='qemu'> or kvm will work here.

A few counterexamples:

  > Watchdog devices
  > A virtual hardware watchdog device can be added to the guest via
  > the watchdog element. Since 0.7.3, QEMU and KVM only

  > Memory balloon device
  > A virtual memory balloon device is added to all Xen and KVM/QEMU
  > guests. It will be seen as memballoon element. It will be
  > automatically added when appropriate, so there is no need to
  > explicitly add this element in the guest XML unless a specific
  > PCI slot needs to be assigned. Since 0.8.3, Xen, QEMU and KVM
  > only

  > Firmware
  > The firmware attribute allows management applications to
  > automatically fill <loader/> and <nvram/> elements and possibly
  > enable some features required by selected firmware. [...] Since
  > 5.2.0 (QEMU and KVM only)

  > ROM
  > The optional file attribute contains an absolute path to a binary
  > file to be presented to the guest as the device's ROM BIOS. This
  > can be useful, for example, to provide a PXE boot ROM for a
  > virtual function of an sr-iov capable ethernet device (which has
  > no boot ROMs for the VFs). Since 0.9.10 (QEMU and KVM only)

All of the above work perfectly fine with TCG, at least as far as I
know.

There are a few instances of "(QEMU/KVM only)" in the document, and
even a couple of "(KVM only)".

tl;dr

We're awfully inconsistent about this. I'm okay with dropping the
"and KVM" part from this patch. I'd also be very much okay with
someone[1] going through the document and changing it to use a
single, unambiguous way to indicate whether a feature works with TCG
or is restricted with KVM.


[1] No, I'm not volunteering to be that someone :)
-- 
Andrea Bolognani / Red Hat / Virtualization