[PATCH] qapi: better document NVMe blockdev @device parameter

[PATCH] qapi: better document NVMe blockdev @device parameter

[Daniel P. Berrangé]

Mention that this is a PCI device address & give the format it is
expected it. Also mention that it must be first unbound from any
host kernel driver.

Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
---
 qapi/block-core.json | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/qapi/block-core.json b/qapi/block-core.json
index 0cf68fea14..fcb52ec24f 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -2963,9 +2963,13 @@
 #
 # Driver specific block device options for the NVMe backend.
 #
-# @device:    controller address of the NVMe device.
+# @device:    PCI controller address of the NVMe device in
+#             format hhhh:bb:ss.f (host:bus:slot.function)
 # @namespace: namespace number of the device, starting from 1.
 #
+# Note that the PCI @device must have been unbound from any host
+# kernel driver before instructing QEMU to add the blockdev.
+#
 # Since: 2.12
 ##
 { 'struct': 'BlockdevOptionsNVMe',
-- 
2.23.0

Re: [PATCH] qapi: better document NVMe blockdev @device parameter

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 440 bytes --]

On Fri, Dec 06, 2019 at 02:38:11PM +0000, Daniel P. Berrangé wrote:
> Mention that this is a PCI device address & give the format it is
> expected it. Also mention that it must be first unbound from any
> host kernel driver.
> 
> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
> ---
>  qapi/block-core.json | 6 +++++-
>  1 file changed, 5 insertions(+), 1 deletion(-)

Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [PATCH] qapi: better document NVMe blockdev @device parameter

[Eric Blake]

On 12/6/19 8:38 AM, Daniel P. Berrangé wrote:
> Mention that this is a PCI device address & give the format it is
> expected it. Also mention that it must be first unbound from any

maybe s/expected it/expecting/

> host kernel driver.
> 
> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
> ---
>   qapi/block-core.json | 6 +++++-
>   1 file changed, 5 insertions(+), 1 deletion(-)
> 
> diff --git a/qapi/block-core.json b/qapi/block-core.json
> index 0cf68fea14..fcb52ec24f 100644
> --- a/qapi/block-core.json
> +++ b/qapi/block-core.json
> @@ -2963,9 +2963,13 @@
>   #
>   # Driver specific block device options for the NVMe backend.
>   #
> -# @device:    controller address of the NVMe device.
> +# @device:    PCI controller address of the NVMe device in
> +#             format hhhh:bb:ss.f (host:bus:slot.function)
>   # @namespace: namespace number of the device, starting from 1.
>   #
> +# Note that the PCI @device must have been unbound from any host
> +# kernel driver before instructing QEMU to add the blockdev.
> +#

Reviewed-by: Eric Blake <eblake@redhat.com>

Doesn't affect code, but similarly no reason to hurry this into 4.2. 
5.0 and qemu-stable (cc'd) is good enough.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org

Re: [PATCH] qapi: better document NVMe blockdev @device parameter

[Daniel P. Berrangé]

On Fri, Dec 06, 2019 at 08:51:15AM -0600, Eric Blake wrote:
> On 12/6/19 8:38 AM, Daniel P. Berrangé wrote:
> > Mention that this is a PCI device address & give the format it is
> > expected it. Also mention that it must be first unbound from any
> 
> maybe s/expected it/expecting/

It was supposed to be "in" rather than "it", but your suggestion
is fine too.

> 
> > host kernel driver.
> > 
> > Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
> > ---
> >   qapi/block-core.json | 6 +++++-
> >   1 file changed, 5 insertions(+), 1 deletion(-)
> > 
> > diff --git a/qapi/block-core.json b/qapi/block-core.json
> > index 0cf68fea14..fcb52ec24f 100644
> > --- a/qapi/block-core.json
> > +++ b/qapi/block-core.json
> > @@ -2963,9 +2963,13 @@
> >   #
> >   # Driver specific block device options for the NVMe backend.
> >   #
> > -# @device:    controller address of the NVMe device.
> > +# @device:    PCI controller address of the NVMe device in
> > +#             format hhhh:bb:ss.f (host:bus:slot.function)
> >   # @namespace: namespace number of the device, starting from 1.
> >   #
> > +# Note that the PCI @device must have been unbound from any host
> > +# kernel driver before instructing QEMU to add the blockdev.
> > +#
> 
> Reviewed-by: Eric Blake <eblake@redhat.com>
> 
> Doesn't affect code, but similarly no reason to hurry this into 4.2. 5.0 and
> qemu-stable (cc'd) is good enough.
> 
> -- 
> Eric Blake, Principal Software Engineer
> Red Hat, Inc.           +1-919-301-3226
> Virtualization:  qemu.org | libvirt.org

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [PATCH] qapi: better document NVMe blockdev @device parameter

[Kevin Wolf]

Am 06.12.2019 um 15:38 hat Daniel P. Berrangé geschrieben:
> Mention that this is a PCI device address & give the format it is
> expected it. Also mention that it must be first unbound from any
> host kernel driver.
> 
> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

Thanks, applied to the block branch.

Kevin