[PATCH 0/2] docs: Further adjustments to pci-addresses.rst
Andrea Bolognani (1): docs: Update introduction in pci-addresses.rst Boris Fiuczynski (2): docs: Improve zPCI section in pci-addresses.rst docs/pci-addresses.rst | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) -- 2.25.1
Changing the introduction to bring the idea of this document better across. Signed-off-by: Andrea Bolognani <abologna@redhat.com> Reviewed-by: Boris Fiuczynski <fiuczy@linux.ibm.com> --- docs/pci-addresses.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/pci-addresses.rst b/docs/pci-addresses.rst index 1d2dc8e5fc..7c8e9edd73 100644 --- a/docs/pci-addresses.rst +++ b/docs/pci-addresses.rst @@ -4,9 +4,12 @@ PCI addresses in domain XML and guest OS .. contents:: -When discussing PCI addresses, it's important to understand the -relationship between the addresses that can be seen in the domain XML -and those that are visible inside the guest OS. +Looking at the configuration for a guest, it would be reasonable +to expect that each PCI device would show up in the guest OS with +a PCI address that matches the one present in the corresponding +``<address>`` element of the domain XML, but that's not guaranteed +to happen and will in fact not be the case in all but the simplest +scenarios. Simple cases -- 2.25.1
On Thu, 16 Apr 2020 17:56:17 +0200 Boris Fiuczynski <fiuczy@linux.ibm.com> wrote:
Changing the introduction to bring the idea of this document better across.
Signed-off-by: Andrea Bolognani <abologna@redhat.com> Reviewed-by: Boris Fiuczynski <fiuczy@linux.ibm.com> --- docs/pci-addresses.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-)
diff --git a/docs/pci-addresses.rst b/docs/pci-addresses.rst index 1d2dc8e5fc..7c8e9edd73 100644 --- a/docs/pci-addresses.rst +++ b/docs/pci-addresses.rst @@ -4,9 +4,12 @@ PCI addresses in domain XML and guest OS
.. contents::
-When discussing PCI addresses, it's important to understand the -relationship between the addresses that can be seen in the domain XML -and those that are visible inside the guest OS. +Looking at the configuration for a guest, it would be reasonable +to expect that each PCI device would show up in the guest OS with +a PCI address that matches the one present in the corresponding +``<address>`` element of the domain XML, but that's not guaranteed +to happen and will in fact not be the case in all but the simplest +scenarios.
Simple cases
Reviewed-by: Cornelia Huck <cohuck@redhat.com> ...although I'm not sure about the s-o-b chain here :)
Improving the zPCI example by choosing more distinct values and adding explanation for fid. Signed-off-by: Boris Fiuczynski <fiuczy@linux.ibm.com> --- docs/pci-addresses.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/pci-addresses.rst b/docs/pci-addresses.rst index 7c8e9edd73..4492389da5 100644 --- a/docs/pci-addresses.rst +++ b/docs/pci-addresses.rst @@ -176,14 +176,14 @@ In the simplest case, the following XML snippet <model name='pci-bridge'/> <target chassisNr='1'/> <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'> - <zpci uid='0x0002' fid='0x00000001'/> + <zpci uid='0x0001' fid='0x00000000'/> </address> </controller> <interface type='bridge'> <source bridge='virbr0'/> <model type='virtio'/> <address type='pci' domain='0x0000' bus='0x01' slot='0x01' function='0x0'> - <zpci uid='0x0001' fid='0x00000000'/> + <zpci uid='0x0007' fid='0x00000003'/> </address> </interface> @@ -191,21 +191,22 @@ will result in the following in a Linux guest: :: - 0001:00:00.0 Ethernet controller: Red Hat, Inc. Virtio network device + 0007:00:00.0 Ethernet controller: Red Hat, Inc. Virtio network device Note that the PCI bridge is not visible in the guest; s390x always has a flat -topology. +topology. Also ``fid`` does not define slot or function of the PCI address. Neither are any changes in the PCI address visible in the guest; replacing the PCI address for the ``virtio-net`` device with :: - <address type='pci' domain='0x0000' bus='0x01' slot='0x07' function='0x3'> + <address type='pci' domain='0x0000' bus='0x01' slot='0x06' function='0x4'> will result in the exactly same view in the guest, as the addresses there -are generated from the information provided via the ``zpci`` element (in -fact, from the ``uid``). +are generated from the information provided via the ``zpci`` element: +the ``uid`` is used as PCI domain, and the ``fid`` is used as the PCI devices +slot in the sysfs. Device assignment -- 2.25.1
On Thu, 16 Apr 2020 17:56:18 +0200 Boris Fiuczynski <fiuczy@linux.ibm.com> wrote:
Improving the zPCI example by choosing more distinct values and adding explanation for fid.
Signed-off-by: Boris Fiuczynski <fiuczy@linux.ibm.com> --- docs/pci-addresses.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-)
diff --git a/docs/pci-addresses.rst b/docs/pci-addresses.rst index 7c8e9edd73..4492389da5 100644 --- a/docs/pci-addresses.rst +++ b/docs/pci-addresses.rst @@ -176,14 +176,14 @@ In the simplest case, the following XML snippet <model name='pci-bridge'/> <target chassisNr='1'/> <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'> - <zpci uid='0x0002' fid='0x00000001'/> + <zpci uid='0x0001' fid='0x00000000'/>
Why this change? The pci-bridge does not show up in the guest anyway.
</address> </controller> <interface type='bridge'> <source bridge='virbr0'/> <model type='virtio'/> <address type='pci' domain='0x0000' bus='0x01' slot='0x01' function='0x0'> - <zpci uid='0x0001' fid='0x00000000'/> + <zpci uid='0x0007' fid='0x00000003'/> </address> </interface>
@@ -191,21 +191,22 @@ will result in the following in a Linux guest:
::
- 0001:00:00.0 Ethernet controller: Red Hat, Inc. Virtio network device + 0007:00:00.0 Ethernet controller: Red Hat, Inc. Virtio network device
Note that the PCI bridge is not visible in the guest; s390x always has a flat -topology. +topology. Also ``fid`` does not define slot or function of the PCI address.
I find the sentence regarding 'fid' confusing. Maybe instead move up the explanation from below regarding uid and fid? "The PCI address in the guest is generated from..."
Neither are any changes in the PCI address visible in the guest; replacing
The 'neither' is now a bit confusing; what about "Any changes in the PCI address are not visible in the guest..." ?
the PCI address for the ``virtio-net`` device with
::
- <address type='pci' domain='0x0000' bus='0x01' slot='0x07' function='0x3'> + <address type='pci' domain='0x0000' bus='0x01' slot='0x06' function='0x4'>
will result in the exactly same view in the guest, as the addresses there
If you move the fid/uid stuff up, make this "as the fid and uid values in the zpci element remain unchanged." ?
-are generated from the information provided via the ``zpci`` element (in -fact, from the ``uid``). +are generated from the information provided via the ``zpci`` element: +the ``uid`` is used as PCI domain, and the ``fid`` is used as the PCI devices
s/devices/device's/
+slot in the sysfs.
s/the sysfs./sysfs (it does not influence the PCI device address.)/ *
Device assignment
On 4/16/20 6:14 PM, Cornelia Huck wrote:
On Thu, 16 Apr 2020 17:56:18 +0200 Boris Fiuczynski <fiuczy@linux.ibm.com> wrote:
Improving the zPCI example by choosing more distinct values and adding explanation for fid.
Signed-off-by: Boris Fiuczynski <fiuczy@linux.ibm.com> --- docs/pci-addresses.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-)
diff --git a/docs/pci-addresses.rst b/docs/pci-addresses.rst index 7c8e9edd73..4492389da5 100644 --- a/docs/pci-addresses.rst +++ b/docs/pci-addresses.rst @@ -176,14 +176,14 @@ In the simplest case, the following XML snippet <model name='pci-bridge'/> <target chassisNr='1'/> <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'> - <zpci uid='0x0002' fid='0x00000001'/> + <zpci uid='0x0001' fid='0x00000000'/>
Why this change? The pci-bridge does not show up in the guest anyway. My assumption was that uid and fid for this would be autogenerated. Since uid 0x0001 and fid 0x00000000 have been freed up due to the change below this would be the autogenerated set.
</address> </controller> <interface type='bridge'> <source bridge='virbr0'/> <model type='virtio'/> <address type='pci' domain='0x0000' bus='0x01' slot='0x01' function='0x0'> - <zpci uid='0x0001' fid='0x00000000'/> + <zpci uid='0x0007' fid='0x00000003'/> </address> </interface>
@@ -191,21 +191,22 @@ will result in the following in a Linux guest:
::
- 0001:00:00.0 Ethernet controller: Red Hat, Inc. Virtio network device + 0007:00:00.0 Ethernet controller: Red Hat, Inc. Virtio network device
Note that the PCI bridge is not visible in the guest; s390x always has a flat -topology. +topology. Also ``fid`` does not define slot or function of the PCI address.
I find the sentence regarding 'fid' confusing. Maybe instead move up the explanation from below regarding uid and fid?
"The PCI address in the guest is generated from..."
Lets join your proposal with Andreas and move his rewrite up to here. Like: ...topology. The PCI address in the guest is generated from the information provided via the ``zpci`` element: more specifically, ``uid`` is used as the PCI domain.``fid`` doesn't appear in the PCI address itself, but it will be used in sysfs (``/sys/bus/pci/slots/$fid/...``).
Neither are any changes in the PCI address visible in the guest; replacing
The 'neither' is now a bit confusing; what about
"Any changes in the PCI address are not visible in the guest..." ? Agreed.
the PCI address for the ``virtio-net`` device with
::
- <address type='pci' domain='0x0000' bus='0x01' slot='0x07' function='0x3'> + <address type='pci' domain='0x0000' bus='0x01' slot='0x06' function='0x4'>
will result in the exactly same view in the guest, as the addresses there
If you move the fid/uid stuff up, make this
"as the fid and uid values in the zpci element remain unchanged." ?
Yes.
-are generated from the information provided via the ``zpci`` element (in -fact, from the ``uid``). +are generated from the information provided via the ``zpci`` element: +the ``uid`` is used as PCI domain, and the ``fid`` is used as the PCI devices
s/devices/device's/
+slot in the sysfs.
s/the sysfs./sysfs (it does not influence the PCI device address.)/ *
Andreas rewrite makes it clear.
Device assignment
-- Mit freundlichen Grüßen/Kind regards Boris Fiuczynski IBM Deutschland Research & Development GmbH Vorsitzender des Aufsichtsrats: Gregor Pillen Geschäftsführung: Dirk Wittkopp Sitz der Gesellschaft: Böblingen Registergericht: Amtsgericht Stuttgart, HRB 243294
On Fri, 17 Apr 2020 10:50:02 +0200 Boris Fiuczynski <fiuczy@linux.ibm.com> wrote:
On 4/16/20 6:14 PM, Cornelia Huck wrote:
On Thu, 16 Apr 2020 17:56:18 +0200 Boris Fiuczynski <fiuczy@linux.ibm.com> wrote:
Improving the zPCI example by choosing more distinct values and adding explanation for fid.
Signed-off-by: Boris Fiuczynski <fiuczy@linux.ibm.com> --- docs/pci-addresses.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-)
diff --git a/docs/pci-addresses.rst b/docs/pci-addresses.rst index 7c8e9edd73..4492389da5 100644 --- a/docs/pci-addresses.rst +++ b/docs/pci-addresses.rst @@ -176,14 +176,14 @@ In the simplest case, the following XML snippet <model name='pci-bridge'/> <target chassisNr='1'/> <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'> - <zpci uid='0x0002' fid='0x00000001'/> + <zpci uid='0x0001' fid='0x00000000'/>
Why this change? The pci-bridge does not show up in the guest anyway. My assumption was that uid and fid for this would be autogenerated. Since uid 0x0001 and fid 0x00000000 have been freed up due to the change below this would be the autogenerated set.
If that makes the XML look saner, no objection.
</address> </controller> <interface type='bridge'> <source bridge='virbr0'/> <model type='virtio'/> <address type='pci' domain='0x0000' bus='0x01' slot='0x01' function='0x0'> - <zpci uid='0x0001' fid='0x00000000'/> + <zpci uid='0x0007' fid='0x00000003'/> </address> </interface>
@@ -191,21 +191,22 @@ will result in the following in a Linux guest:
::
- 0001:00:00.0 Ethernet controller: Red Hat, Inc. Virtio network device + 0007:00:00.0 Ethernet controller: Red Hat, Inc. Virtio network device
Note that the PCI bridge is not visible in the guest; s390x always has a flat -topology. +topology. Also ``fid`` does not define slot or function of the PCI address.
I find the sentence regarding 'fid' confusing. Maybe instead move up the explanation from below regarding uid and fid?
"The PCI address in the guest is generated from..."
Lets join your proposal with Andreas and move his rewrite up to here. Like: ...topology. The PCI address in the guest is generated from the information provided via the ``zpci`` element: more specifically, ``uid`` is used as the PCI domain.``fid`` doesn't appear in the PCI address itself, but it will be used in sysfs (``/sys/bus/pci/slots/$fid/...``).
Sounds good. (Also the rest of the changes.)
On Fri, 2020-04-17 at 11:02 +0200, Cornelia Huck wrote:
On Fri, 17 Apr 2020 10:50:02 +0200 Boris Fiuczynski <fiuczy@linux.ibm.com> wrote:
<model name='pci-bridge'/> <target chassisNr='1'/> <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'> - <zpci uid='0x0002' fid='0x00000001'/> + <zpci uid='0x0001' fid='0x00000000'/>
Why this change? The pci-bridge does not show up in the guest anyway.
My assumption was that uid and fid for this would be autogenerated. Since uid 0x0001 and fid 0x00000000 have been freed up due to the change below this would be the autogenerated set.
If that makes the XML look saner, no objection.
I don't think it makes a lot of difference, but it doesn't make it any more confusing either, so I'm okay with changing it :)
Note that the PCI bridge is not visible in the guest; s390x always has a flat -topology. +topology. Also ``fid`` does not define slot or function of the PCI address.
I find the sentence regarding 'fid' confusing. Maybe instead move up the explanation from below regarding uid and fid?
"The PCI address in the guest is generated from..."
Lets join your proposal with Andreas and move his rewrite up to here. Like: ...topology. The PCI address in the guest is generated from the information provided via the ``zpci`` element: more specifically, ``uid`` is used as the PCI domain.``fid`` doesn't appear in the PCI address itself, but it will be used in sysfs (``/sys/bus/pci/slots/$fid/...``).
Sounds good.
(Also the rest of the changes.)
Cool. Boris, are you going to post a v2 squashing in all proposed changes? -- Andrea Bolognani / Red Hat / Virtualization
On 4/17/20 11:02 AM, Cornelia Huck wrote:
On Fri, 17 Apr 2020 10:50:02 +0200 Boris Fiuczynski <fiuczy@linux.ibm.com> wrote:
On 4/16/20 6:14 PM, Cornelia Huck wrote:
On Thu, 16 Apr 2020 17:56:18 +0200 Boris Fiuczynski <fiuczy@linux.ibm.com> wrote:
Improving the zPCI example by choosing more distinct values and adding explanation for fid.
Signed-off-by: Boris Fiuczynski <fiuczy@linux.ibm.com> --- docs/pci-addresses.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-)
diff --git a/docs/pci-addresses.rst b/docs/pci-addresses.rst index 7c8e9edd73..4492389da5 100644 --- a/docs/pci-addresses.rst +++ b/docs/pci-addresses.rst @@ -176,14 +176,14 @@ In the simplest case, the following XML snippet <model name='pci-bridge'/> <target chassisNr='1'/> <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'> - <zpci uid='0x0002' fid='0x00000001'/> + <zpci uid='0x0001' fid='0x00000000'/>
Why this change? The pci-bridge does not show up in the guest anyway. My assumption was that uid and fid for this would be autogenerated. Since uid 0x0001 and fid 0x00000000 have been freed up due to the change below this would be the autogenerated set.
If that makes the XML look saner, no objection.
</address> </controller> <interface type='bridge'> <source bridge='virbr0'/> <model type='virtio'/> <address type='pci' domain='0x0000' bus='0x01' slot='0x01' function='0x0'> - <zpci uid='0x0001' fid='0x00000000'/> + <zpci uid='0x0007' fid='0x00000003'/> </address> </interface>
@@ -191,21 +191,22 @@ will result in the following in a Linux guest:
::
- 0001:00:00.0 Ethernet controller: Red Hat, Inc. Virtio network device + 0007:00:00.0 Ethernet controller: Red Hat, Inc. Virtio network device
Note that the PCI bridge is not visible in the guest; s390x always has a flat -topology. +topology. Also ``fid`` does not define slot or function of the PCI address.
I find the sentence regarding 'fid' confusing. Maybe instead move up the explanation from below regarding uid and fid?
"The PCI address in the guest is generated from..."
Lets join your proposal with Andreas and move his rewrite up to here. Like: ...topology. The PCI address in the guest is generated from the information provided via the ``zpci`` element: more specifically, ``uid`` is used as the PCI domain.``fid`` doesn't appear in the PCI address itself, but it will be used in sysfs (``/sys/bus/pci/slots/$fid/...``).
Sounds good.
(Also the rest of the changes.)
Before I break the r-b chain as well... Is that your r-b? :) -- Mit freundlichen Grüßen/Kind regards Boris Fiuczynski IBM Deutschland Research & Development GmbH Vorsitzender des Aufsichtsrats: Gregor Pillen Geschäftsführung: Dirk Wittkopp Sitz der Gesellschaft: Böblingen Registergericht: Amtsgericht Stuttgart, HRB 243294
On Fri, 17 Apr 2020 13:29:43 +0200 Boris Fiuczynski <fiuczy@linux.ibm.com> wrote:
On 4/17/20 11:02 AM, Cornelia Huck wrote:
On Fri, 17 Apr 2020 10:50:02 +0200 Boris Fiuczynski <fiuczy@linux.ibm.com> wrote:
On 4/16/20 6:14 PM, Cornelia Huck wrote:
On Thu, 16 Apr 2020 17:56:18 +0200 Boris Fiuczynski <fiuczy@linux.ibm.com> wrote:
Improving the zPCI example by choosing more distinct values and adding explanation for fid.
Signed-off-by: Boris Fiuczynski <fiuczy@linux.ibm.com> --- docs/pci-addresses.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-)
diff --git a/docs/pci-addresses.rst b/docs/pci-addresses.rst index 7c8e9edd73..4492389da5 100644 --- a/docs/pci-addresses.rst +++ b/docs/pci-addresses.rst @@ -176,14 +176,14 @@ In the simplest case, the following XML snippet <model name='pci-bridge'/> <target chassisNr='1'/> <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'> - <zpci uid='0x0002' fid='0x00000001'/> + <zpci uid='0x0001' fid='0x00000000'/>
Why this change? The pci-bridge does not show up in the guest anyway. My assumption was that uid and fid for this would be autogenerated. Since uid 0x0001 and fid 0x00000000 have been freed up due to the change below this would be the autogenerated set.
If that makes the XML look saner, no objection.
</address> </controller> <interface type='bridge'> <source bridge='virbr0'/> <model type='virtio'/> <address type='pci' domain='0x0000' bus='0x01' slot='0x01' function='0x0'> - <zpci uid='0x0001' fid='0x00000000'/> + <zpci uid='0x0007' fid='0x00000003'/> </address> </interface>
@@ -191,21 +191,22 @@ will result in the following in a Linux guest:
::
- 0001:00:00.0 Ethernet controller: Red Hat, Inc. Virtio network device + 0007:00:00.0 Ethernet controller: Red Hat, Inc. Virtio network device
Note that the PCI bridge is not visible in the guest; s390x always has a flat -topology. +topology. Also ``fid`` does not define slot or function of the PCI address.
I find the sentence regarding 'fid' confusing. Maybe instead move up the explanation from below regarding uid and fid?
"The PCI address in the guest is generated from..."
Lets join your proposal with Andreas and move his rewrite up to here. Like: ...topology. The PCI address in the guest is generated from the information provided via the ``zpci`` element: more specifically, ``uid`` is used as the PCI domain.``fid`` doesn't appear in the PCI address itself, but it will be used in sysfs (``/sys/bus/pci/slots/$fid/...``).
Sounds good.
(Also the rest of the changes.)
Before I break the r-b chain as well... Is that your r-b? :)
I'll add my R-b to a final patch :)
On Fri, 2020-04-17 at 13:31 +0200, Cornelia Huck wrote:
On Fri, 17 Apr 2020 13:29:43 +0200 Boris Fiuczynski <fiuczy@linux.ibm.com> wrote:
On 4/17/20 11:02 AM, Cornelia Huck wrote:
Sounds good.
(Also the rest of the changes.)
Before I break the r-b chain as well... Is that your r-b? :)
I'll add my R-b to a final patch :)
Same :) -- Andrea Bolognani / Red Hat / Virtualization
On Thu, 2020-04-16 at 17:56 +0200, Boris Fiuczynski wrote:
Note that the PCI bridge is not visible in the guest; s390x always has a flat -topology. +topology. Also ``fid`` does not define slot or function of the PCI address.
This sentence is unnecessary, since you explain what fid does just a few lines later.
will result in the exactly same view in the guest, as the addresses there -are generated from the information provided via the ``zpci`` element (in -fact, from the ``uid``). +are generated from the information provided via the ``zpci`` element: +the ``uid`` is used as PCI domain, and the ``fid`` is used as the PCI devices +slot in the sysfs.
I think we need to be a bit more verbose to make sure we don't confuse the reader, or better yet avoid mentioning "PCI slot" altogether because the terminology is ambiguous. Something like [...] are generated from the information provided via the ``zpci`` element: more specifically, ``uid`` is used as the PCI domain. ``fid`` doesn't appear in the PCI address itself, but it will be used in sysfs (``/sys/bus/pci/slots/$fid/...``). -- Andrea Bolognani / Red Hat / Virtualization
participants (3)
-
Andrea Bolognani -
Boris Fiuczynski -
Cornelia Huck