Re: [PATCH] docs: Add some details on XenServer PCI devices

[Frediano Ziglio <frediano.ziglio@xxxxxxxxx>]

On Tue, Mar 4, 2025 at 11:08 AM Roger Pau Monné <roger.pau@xxxxxxxxxx> wrote:
>
> On Tue, Mar 04, 2025 at 10:21:52AM +0000, Alejandro Vallejo wrote:
> > Hi,
> >
> > On Fri Feb 28, 2025 at 3:21 PM GMT, Frediano Ziglio wrote:
> > > Describe the usage of devices 5853:0002 and 5853:C000.
> > >
> > > Signed-off-by: Frediano Ziglio <frediano.ziglio@xxxxxxxxx>
> > > ---
> > >  docs/man/xen-pci-device-reservations.7.pod | 9 +++++++++
> > >  1 file changed, 9 insertions(+)
> > >
> > > diff --git a/docs/man/xen-pci-device-reservations.7.pod 
> > > b/docs/man/xen-pci-device-reservations.7.pod
> > > index 9ddf3a18ad..62f3bd2105 100644
> > > --- a/docs/man/xen-pci-device-reservations.7.pod
> > > +++ b/docs/man/xen-pci-device-reservations.7.pod
> > > @@ -10,6 +10,8 @@ use of this is with device ID 0x0001 to advertise the 
> > > Xen Platform PCI
> > >  device - the presence of this virtual device enables a guest Operating
> > >  System (subject to the availability of suitable drivers) to make use of
> > >  paravirtualisation features such as disk and network devices etc.
> > > +XenServer, for Windows machines, presents Xen Platform device with device
> > > +ID 0x0002 instead of 0x0001.
> >
> > nit: in the interest of future-proofing the doc 's/presents/may present/'?
> >
> > >
> > >  Some Xen vendors wish to provide alternative and/or additional guest 
> > > drivers
> > >  that can bind to virtual devices[1]. This may be done using the Xen PCI
> > > @@ -86,4 +88,11 @@ and unplug protocol.
> > >  libxl provides support for creation of a single additional xen-pvdevice.
> > >  See the vendor_device parameter in xl.cfg(5).
> > >
> > > +=item 2.
> > > +
> > > +XenServer, for Windows machines, presents a device with ID 0xC000.
> > > +This device is a placeholders for Windows update.
> > > +Device 0xC000 is presented with a Xen Platform PCI device, usually with 
> > > ID
> > > +0x0002.
> > > +
> > >  =back
> >
> > Wouldn't this be better covered under "=item 1"? Device 0xc000 is a
> > xen-pvdevice, so it could be simplified to a single line of "XenServer uses
> > device-id=0xc000 for its pvdevice on Windows guests", or something like 
> > that.
>
> I think it's important to note that c000 always appears in conjunction
> with 0001 or 0002, and it's not a replacement for either of those
> devices.
>

Do you have something more precise in mind? Can you suggest what to write?

> Likewise it's important to note that 0001 and 0002 are to my
> understanding mutually exclusive, and only one of those must be
> exposed.

Not exactly sure if this is a must or a should. From my testing,
presenting 2 devices (well, they are mostly the same) works. But, as
they do the same things it seems reasonable to avoid the duplication.
It looks like a good recommendation.

>
> Thanks, Roger.

Frediano