Update documentation and information about vf-token

Signed-off-by: Vivek Kashyap <vivek.kashyap@linux.intel.com>
---
 NEWS.rst              | 8 ++++++++
 docs/formatdomain.rst | 4 ++++
 2 files changed, 12 insertions(+)

diff --git a/NEWS.rst b/NEWS.rst
index f12734c2a1..3fb0230e71 100644
--- a/NEWS.rst
+++ b/NEWS.rst
@@ -22,6 +22,14 @@ v9.10.0 (unreleased)
     The QEMU hypervisor driver now allows setting ``pipewire`` backend for
     ``<audio/>`` device.
 
+  * qemu: support VF tokens for vfio-pci
+
+    "vf-token",implemented as a UUID, is a shared secret between userspace
+    vfio-based PF and VF drivers. The token is set by the PF driver and is part
+    of the device matching by the VF driver. The vfio vf-token uuid is
+    included in the VM XML specification for the pci device, and the token is
+    passed in qemu commandline on VM launch.
+
 * **Improvements**
 
 * **Bug fixes**
diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
index 310d2bc427..08d7540de5 100644
--- a/docs/formatdomain.rst
+++ b/docs/formatdomain.rst
@@ -3744,6 +3744,10 @@ control where on the bus the device will be placed:
    between 0x0001 and 0xffff, inclusive), and ``fid`` (a hex value between
    0x00000000 and 0xffffffff, inclusive) used by PCI devices on S390 for
    User-defined Identifiers and Function Identifiers.
+   :since:'Since 8.1.0`, the vf-token element is supported in uuid format. The
+   vf-token is a shared secret between userspace vfio-pci PF driver and VF
+   driver. The token is set by the PF driver, and must be provided for VF
+   access.
    :since:`Since 1.3.5` , some hypervisor drivers may accept an
    ``<address type='pci'/>`` element with no other attributes as an explicit
    request to assign a PCI address for the device rather than some other type of
-- 
2.25.1
_______________________________________________
Devel mailing list -- devel@lists.libvirt.org
To unsubscribe send an email to devel-leave@lists.libvirt.org

On Wed, Nov 29, 2023 at 21:07:27 -0700, Vivek Kashyap wrote:
> Update documentation and information about vf-token
> 
> Signed-off-by: Vivek Kashyap <vivek.kashyap@linux.intel.com>
> ---
>  NEWS.rst              | 8 ++++++++
>  docs/formatdomain.rst | 4 ++++
>  2 files changed, 12 insertions(+)
> 
> diff --git a/NEWS.rst b/NEWS.rst
> index f12734c2a1..3fb0230e71 100644
> --- a/NEWS.rst
> +++ b/NEWS.rst
> @@ -22,6 +22,14 @@ v9.10.0 (unreleased)
>      The QEMU hypervisor driver now allows setting ``pipewire`` backend for
>      ``<audio/>`` device.
>  
> +  * qemu: support VF tokens for vfio-pci
> +
> +    "vf-token",implemented as a UUID, is a shared secret between userspace
> +    vfio-based PF and VF drivers. The token is set by the PF driver and is part
> +    of the device matching by the VF driver. The vfio vf-token uuid is
> +    included in the VM XML specification for the pci device, and the token is
> +    passed in qemu commandline on VM launch.

Note that updates to NEWS.rst must always be a separate patch without
any other changes.


> +
>  * **Improvements**
>  
>  * **Bug fixes**
> diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
> index 310d2bc427..08d7540de5 100644
> --- a/docs/formatdomain.rst
> +++ b/docs/formatdomain.rst
> @@ -3744,6 +3744,10 @@ control where on the bus the device will be placed:
>     between 0x0001 and 0xffff, inclusive), and ``fid`` (a hex value between
>     0x00000000 and 0xffffffff, inclusive) used by PCI devices on S390 for
>     User-defined Identifiers and Function Identifiers.
> +   :since:'Since 8.1.0`, the vf-token element is supported in uuid format. The
> +   vf-token is a shared secret between userspace vfio-pci PF driver and VF

So wait, this is considered a 'secret'? If so note that it's put on
qemu's commandline and thus exposed for ALL users on the sytem.

> +   driver. The token is set by the PF driver, and must be provided for VF
> +   access.

If this is to be a secret it MUST be passed to qemu via a 'secret'
object which will most likely require also qemu changes first.

>     :since:`Since 1.3.5` , some hypervisor drivers may accept an
>     ``<address type='pci'/>`` element with no other attributes as an explicit
>     request to assign a PCI address for the device rather than some other type of
> -- 
> 2.25.1
> _______________________________________________
> Devel mailing list -- devel@lists.libvirt.org
> To unsubscribe send an email to devel-leave@lists.libvirt.org
_______________________________________________
Devel mailing list -- devel@lists.libvirt.org
To unsubscribe send an email to devel-leave@lists.libvirt.org

On Thu, Nov 30, 2023 at 09:45:30 +0100, Peter Krempa wrote:
> On Wed, Nov 29, 2023 at 21:07:27 -0700, Vivek Kashyap wrote:
> > Update documentation and information about vf-token
> > 
> > Signed-off-by: Vivek Kashyap <vivek.kashyap@linux.intel.com>
> > ---
> >  NEWS.rst              | 8 ++++++++
> >  docs/formatdomain.rst | 4 ++++
> >  2 files changed, 12 insertions(+)
> > 
> > diff --git a/NEWS.rst b/NEWS.rst
> > index f12734c2a1..3fb0230e71 100644
> > --- a/NEWS.rst
> > +++ b/NEWS.rst
> > @@ -22,6 +22,14 @@ v9.10.0 (unreleased)
> >      The QEMU hypervisor driver now allows setting ``pipewire`` backend for
> >      ``<audio/>`` device.
> >  
> > +  * qemu: support VF tokens for vfio-pci
> > +
> > +    "vf-token",implemented as a UUID, is a shared secret between userspace
> > +    vfio-based PF and VF drivers. The token is set by the PF driver and is part
> > +    of the device matching by the VF driver. The vfio vf-token uuid is
> > +    included in the VM XML specification for the pci device, and the token is
> > +    passed in qemu commandline on VM launch.
> 
> Note that updates to NEWS.rst must always be a separate patch without
> any other changes.
> 
> 
> > +
> >  * **Improvements**
> >  
> >  * **Bug fixes**
> > diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
> > index 310d2bc427..08d7540de5 100644
> > --- a/docs/formatdomain.rst
> > +++ b/docs/formatdomain.rst
> > @@ -3744,6 +3744,10 @@ control where on the bus the device will be placed:
> >     between 0x0001 and 0xffff, inclusive), and ``fid`` (a hex value between
> >     0x00000000 and 0xffffffff, inclusive) used by PCI devices on S390 for
> >     User-defined Identifiers and Function Identifiers.

One more thing:

> > +   :since:'Since 8.1.0`, the vf-token element is supported in uuid format. The

This is supposed to say the libvirt version when this was introduced
thus 10.0.0 will be the next one you'll be able to make with these
patches.

You can additionally mention the qemu version required but it MUST be
separate and the libvirt version is always required. There are plenty
examples in this file.
_______________________________________________
Devel mailing list -- devel@lists.libvirt.org
To unsubscribe send an email to devel-leave@lists.libvirt.org