[Qemu-devel] [PATCH] docs: pcie: Spell out machine type needs for PCIe features

[Qemu-devel] [PATCH] docs: pcie: Spell out machine type needs for PCIe features

[Kashyap Chamarthy]

PCIe features are available only via the Q35 machine for x86, or the
'virt' machine type for AArch64 architecture.

Mention that explicitly.

Thanks: Daniel Berrangé

Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
---
 docs/pcie.txt | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/docs/pcie.txt b/docs/pcie.txt
index 8d3694970e..3e5bf52e0b 100644
--- a/docs/pcie.txt
+++ b/docs/pcie.txt
@@ -3,8 +3,14 @@ PCI EXPRESS GUIDELINES
 
 1. Introduction
 ================
-The doc proposes best practices on how to use PCI Express/PCI device
-in PCI Express based machines and explains the reasoning behind them.
+The doc proposes best practices on how to use PCI Express (PCIe) / PCI
+device in PCI Express based machines and explains the reasoning behind
+them.
+
+This applies to the Q35 machine type on x86 and the 'virt' machine type
+on AArch64 (in other words, PCIe features are available only when using
+the Q35 and 'virt' machine types for the said architectures). Other
+machine types do not use PCI Express at this time.
 
 The following presentations accompany this document:
  (1) Q35 overview.
-- 
2.13.6

Re: [Qemu-devel] [PATCH] docs: pcie: Spell out machine type needs for PCIe features

[Daniel P. Berrangé]

On Mon, Feb 19, 2018 at 04:43:33PM +0100, Kashyap Chamarthy wrote:
> PCIe features are available only via the Q35 machine for x86, or the
> 'virt' machine type for AArch64 architecture.
> 
> Mention that explicitly.
> 
> Thanks: Daniel Berrangé
> 
> Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
> ---
>  docs/pcie.txt | 10 ++++++++--
>  1 file changed, 8 insertions(+), 2 deletions(-)
> 
> diff --git a/docs/pcie.txt b/docs/pcie.txt
> index 8d3694970e..3e5bf52e0b 100644
> --- a/docs/pcie.txt
> +++ b/docs/pcie.txt
> @@ -3,8 +3,14 @@ PCI EXPRESS GUIDELINES
>  
>  1. Introduction
>  ================
> -The doc proposes best practices on how to use PCI Express/PCI device
> -in PCI Express based machines and explains the reasoning behind them.
> +The doc proposes best practices on how to use PCI Express (PCIe) / PCI
> +device in PCI Express based machines and explains the reasoning behind
> +them.

Pre-existing bug  s/device/devices/

> +This applies to the Q35 machine type on x86 and the 'virt' machine type

For consistency I'd suggest  'q35' rather than Q35.

> +on AArch64 (in other words, PCIe features are available only when using
> +the Q35 and 'virt' machine types for the said architectures). Other

And again, though I feel the stuff in (...) is just repeating what's
said in the stuff either side of the brackets.

> +machine types do not use PCI Express at this time.
>  
>  The following presentations accompany this document:
>   (1) Q35 overview.
> -- 
> 2.13.6
> 

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: [Qemu-devel] [PATCH] docs: pcie: Spell out machine type needs for PCIe features

[Kashyap Chamarthy]

On Mon, Feb 19, 2018 at 03:46:12PM +0000, Daniel P. Berrangé wrote:
> On Mon, Feb 19, 2018 at 04:43:33PM +0100, Kashyap Chamarthy wrote:
> > PCIe features are available only via the Q35 machine for x86, or the

[...]

> >  1. Introduction
> >  ================
> > -The doc proposes best practices on how to use PCI Express/PCI device
> > -in PCI Express based machines and explains the reasoning behind them.
> > +The doc proposes best practices on how to use PCI Express (PCIe) / PCI
> > +device in PCI Express based machines and explains the reasoning behind
> > +them.
> 
> Pre-existing bug  s/device/devices/

Fixed in v2.

> > +This applies to the Q35 machine type on x86 and the 'virt' machine type
> 
> For consistency I'd suggest  'q35' rather than Q35.

Yep, fixed in v2.

(I actually did that first in v1 and removed it — as I saw the
captialized variant used througout the doc.  But I see you're asking to
be consistent in the sentence.)

> > +on AArch64 (in other words, PCIe features are available only when using
> > +the Q35 and 'virt' machine types for the said architectures). Other
> 
> And again, though I feel the stuff in (...) is just repeating what's
> said in the stuff either side of the brackets.

I was also hesitant on the repetition.  But I wanted to put some wording
that is unambiguous about the mandatory requirements.  How about this,
that I currently have in my v2 draft:

    "Note that the PCIe features are available only when using the 'q35'
    machine type on x86 architecture and the 'virt' machine type on
    AArch64. Other machine types do not use PCIe at this time."


Thanks for the quick review!

-- 
/kashyap