Skip to contentSkip to conversation

docs: pcie: Spell out machine type needs for PCIe features

PATCH Superseded Kashyap Chamarthy 2 participants 3 messages Feb 19, 2018

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 docs: pcie: Spell out machine type needs for PCIe features

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é

---
 docs/pcie.txt | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)
docs/pcie.txt +8 -2
index 8d3694970e..3e5bf52e0b 100644
@@ -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.
Signature · 1 line
2.13.6
#1 lore raw
Quoted 17 lines · 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é

---
 docs/pcie.txt | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)
docs/pcie.txt +0 -0
index 8d3694970e..3e5bf52e0b 100644

docs/pcie.txt PCI EXPRESS GUIDELINES · line 8

Quoted 8 lines
docs/pcie.txt +3 -2
@@ -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/

docs/pcie.txt PCI EXPRESS GUIDELINES · line 10

Quoted 1 line
docs/pcie.txt +1 -0
+This applies to the Q35 machine type on x86 and the 'virt' machine type

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

docs/pcie.txt PCI EXPRESS GUIDELINES · line 12

Quoted 2 lines
docs/pcie.txt +2 -0
+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.

Quoted 7 lines
docs/pcie.txt +1 -0
+machine types do not use PCI Express at this time.
 
 The following presentations accompany this document:
  (1) Q35 overview.
Signature · 1 line
2.13.6

Regards,
Daniel

Signature · 3 lines
|: 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 :|
#2 lore raw
Quoted 2 lines · Daniel P. Berrangé
Quoted 1 line · Kashyap Chamarthy

PCIe features are available only via the Q35 machine for x86, or the

[...]

Quoted 9 lines

docs/pcie.txt PCI EXPRESS GUIDELINES · line 8

Quoted 7 lines

1. Introduction
================

docs/pcie.txt +3 -2
-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.

Quoted 3 lines
Quoted 1 line

+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.)

Quoted 5 lines

docs/pcie.txt PCI EXPRESS GUIDELINES · line 12

Quoted 2 lines
docs/pcie.txt +2 -0
+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!

Signature · 1 line
/kashyap