[libvirt PATCH 0/4] docs: A few adjustments to pci-addresses.rst
Andrea Bolognani (4): docs: Use consistent style in pci-addresses.rst docs: Move sections around in pci-addresses.rst docs: Remove MAC addresses from pci-addresses.rst docs: Remove one example from pci-addresses.rst docs/pci-addresses.rst | 102 +++++++++++++++++------------------------ 1 file changed, 42 insertions(+), 60 deletions(-) -- 2.25.2
Indent all code snippets by the same number of spaces, and don't embed the :: marker in the line preceding a code block. This commit is best viewed with 'git show -w'. Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- docs/pci-addresses.rst | 60 ++++++++++++++++++++++-------------------- 1 file changed, 32 insertions(+), 28 deletions(-) diff --git a/docs/pci-addresses.rst b/docs/pci-addresses.rst index fbc741e344..0b83bb231f 100644 --- a/docs/pci-addresses.rst +++ b/docs/pci-addresses.rst @@ -196,24 +196,26 @@ In the simplest case, the following XML snippet :: - <controller type='pci' index='0' model='pci-root'/> - <controller type='pci' index='1' model='pci-bridge'> - <model name='pci-bridge'/> - <target chassisNr='1'/> - <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'> - <zpci uid='0x0002' fid='0x00000001'/> - </address> - </controller> - <interface type='bridge'> - <mac address='02:ca:fe:fa:ce:04'/> - <source bridge='virbr0'/> - <model type='virtio'/> - <address type='pci' domain='0x0000' bus='0x01' slot='0x01' function='0x0'> - <zpci uid='0x0001' fid='0x00000000'/> - </address> - </interface> - -will result in the following in a Linux guest:: + <controller type='pci' index='0' model='pci-root'/> + <controller type='pci' index='1' model='pci-bridge'> + <model name='pci-bridge'/> + <target chassisNr='1'/> + <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'> + <zpci uid='0x0002' fid='0x00000001'/> + </address> + </controller> + <interface type='bridge'> + <mac address='02:ca:fe:fa:ce:04'/> + <source bridge='virbr0'/> + <model type='virtio'/> + <address type='pci' domain='0x0000' bus='0x01' slot='0x01' function='0x0'> + <zpci uid='0x0001' fid='0x00000000'/> + </address> + </interface> + +will result in the following in a Linux guest: + +:: 0001:00:00.0 Ethernet controller: Red Hat, Inc. Virtio network device @@ -221,7 +223,7 @@ Note that the PCI bridge is not visible in the guest; s390x always has a flat topology. Neither are any changes in the PCI address visible in the guest; replacing -the PCI address for the virtio-net device with +the PCI address for the ``virtio-net`` device with :: @@ -236,15 +238,17 @@ snippet :: - <interface type='bridge'> - <mac address='02:ca:fe:fa:ce:04'/> - <source bridge='virbr0'/> - <model type='virtio'/> - <address type='pci' domain='0x0000' bus='0x01' slot='0x07' function='0x3'> - <zpci uid='0x0007' fid='0x00000003'/> - </address> - </interface> + <interface type='bridge'> + <mac address='02:ca:fe:fa:ce:04'/> + <source bridge='virbr0'/> + <model type='virtio'/> + <address type='pci' domain='0x0000' bus='0x01' slot='0x07' function='0x3'> + <zpci uid='0x0007' fid='0x00000003'/> + </address> + </interface> -will yield the following result in a Linux guest:: +will yield the following result in a Linux guest: + +:: 0007:00:00.0 Ethernet controller: Red Hat, Inc. Virtio network device -- 2.25.2
On Wed, 15 Apr 2020 19:31:33 +0200 Andrea Bolognani <abologna@redhat.com> wrote:
Indent all code snippets by the same number of spaces, and don't embed the :: marker in the line preceding a code block.
This commit is best viewed with 'git show -w'.
Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- docs/pci-addresses.rst | 60 ++++++++++++++++++++++-------------------- 1 file changed, 32 insertions(+), 28 deletions(-)
Reviewed-by: Cornelia Huck <cohuck@redhat.com>
On a Wednesday in 2020, Andrea Bolognani wrote:
Indent all code snippets by the same number of spaces, and don't embed the :: marker in the line preceding a code block.
But why? It's so ugly. Jano
This commit is best viewed with 'git show -w'.
Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- docs/pci-addresses.rst | 60 ++++++++++++++++++++++-------------------- 1 file changed, 32 insertions(+), 28 deletions(-)
On Thu, Apr 16, 2020 at 12:58:43PM +0200, Ján Tomko wrote:
On a Wednesday in 2020, Andrea Bolognani wrote:
Indent all code snippets by the same number of spaces, and don't embed the :: marker in the line preceding a code block.
But why? It's so ugly.
That aligns with the style we've used in all other rst docs we've done so far. Ideally we wouldn't use a bare "::" anyway - we really ought to be using ".. code-block:: $LANGUAGE" to instruct the renderer how to highlight the code snippets. Our current website generator doesn't use this, but hopefully we will in future 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 :|
On Thu, 2020-04-16 at 12:58 +0200, Ján Tomko wrote:
On a Wednesday in 2020, Andrea Bolognani wrote:
Indent all code snippets by the same number of spaces, and don't embed the :: marker in the line preceding a code block.
But why? It's so ugly.
I disagree, and find it much easier on the eye than the alternative. That's a matter of personal preference, of course, but the fact that all existing reStructuredText files in the repository follow this convention could indicate that I'm not the only one holding this opinion. This change was made for consistency's sake, not to appease my sense of aestethic - althought in this case the two overlap :) More objectively, the fact that the indicator is on its own line makes it stand out more and make it obvious at a glance that what you're looking at is a code block rather than a block quote: this is more important when looking at diffs than when working in the editor, but even with syntax highlighting turned on that small splash of color at the end of a line is easier to miss than when it forms a line of its own. Additionally, the fact that Here's some code:: and Here's some code :: render differently makes this form more error-prone. -- Andrea Bolognani / Red Hat / Virtualization
On Thu, Apr 16, 2020 at 01:35:57PM +0200, Andrea Bolognani wrote:
On Thu, 2020-04-16 at 12:58 +0200, Ján Tomko wrote:
On a Wednesday in 2020, Andrea Bolognani wrote:
Indent all code snippets by the same number of spaces, and don't embed the :: marker in the line preceding a code block.
But why? It's so ugly.
I disagree, and find it much easier on the eye than the alternative.
That's a matter of personal preference, of course, but the fact that all existing reStructuredText files in the repository follow this convention could indicate that I'm not the only one holding this opinion. This change was made for consistency's sake, not to appease my sense of aestethic - althought in this case the two overlap :)
BTW, we could update styleguide.rst to mention this preference. 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 :|
On Thu, 2020-04-16 at 12:38 +0100, Daniel P. Berrangé wrote:
On Thu, Apr 16, 2020 at 01:35:57PM +0200, Andrea Bolognani wrote:
On Thu, 2020-04-16 at 12:58 +0200, Ján Tomko wrote:
On a Wednesday in 2020, Andrea Bolognani wrote:
Indent all code snippets by the same number of spaces, and don't embed the :: marker in the line preceding a code block.
But why? It's so ugly.
I disagree, and find it much easier on the eye than the alternative.
That's a matter of personal preference, of course, but the fact that all existing reStructuredText files in the repository follow this convention could indicate that I'm not the only one holding this opinion. This change was made for consistency's sake, not to appease my sense of aestethic - althought in this case the two overlap :)
BTW, we could update styleguide.rst to mention this preference.
https://www.redhat.com/archives/libvir-list/2020-April/msg00822.html -- Andrea Bolognani / Red Hat / Virtualization
The section about VFIO devices is kept separate from the rest because it's less about domain XML and guest OS disagreeing on the PCI address of a device, and more about which of the two PCI addresses in the domain XML is even relevant to the guest OS. The section on zPCI addresses, on the other hand, falls squarely in the "more complex cases" category, so it should live in the corresponding section. Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- docs/pci-addresses.rst | 57 +++++++++++++++++++++--------------------- 1 file changed, 28 insertions(+), 29 deletions(-) diff --git a/docs/pci-addresses.rst b/docs/pci-addresses.rst index 0b83bb231f..566c81d957 100644 --- a/docs/pci-addresses.rst +++ b/docs/pci-addresses.rst @@ -158,36 +158,8 @@ Once again, while the PCI addresses seen in the domain XML and those seen by the guest OS do not match, the relationships between the various devices are preserved. - -Device assignment -================= - -When using VFIO to assign host devices to a guest, an additional -caveat to keep in mind that the guest OS will base its decisions upon -the *target address* (guest side) rather than the *source address* -(host side). - -For example, the domain XML snippet - -:: - - <hostdev mode='subsystem' type='pci' managed='yes'> - <driver name='vfio'/> - <source> - <address domain='0x0001' bus='0x08' slot='0x00' function='0x0'/> - </source> - <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'/> - </hostdev> - -will result in the device showing up as ``0000:00:01.0`` in the -guest OS rather than as ``0001:08:00.1``, which is the address of the -device on the host. - -Of course, all the rules and behaviors described above still apply. - - zPCI addresses -============== +-------------- For s390x machines, PCI addresses are handled yet differently. No topology information is relayed in the PCI addresses; instead, the @@ -252,3 +224,30 @@ will yield the following result in a Linux guest: :: 0007:00:00.0 Ethernet controller: Red Hat, Inc. Virtio network device + + +Device assignment +================= + +When using VFIO to assign host devices to a guest, an additional +caveat to keep in mind that the guest OS will base its decisions upon +the *target address* (guest side) rather than the *source address* +(host side). + +For example, the domain XML snippet + +:: + + <hostdev mode='subsystem' type='pci' managed='yes'> + <driver name='vfio'/> + <source> + <address domain='0x0001' bus='0x08' slot='0x00' function='0x0'/> + </source> + <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'/> + </hostdev> + +will result in the device showing up as ``0000:00:01.0`` in the +guest OS rather than as ``0001:08:00.1``, which is the address of the +device on the host. + +Of course, all the rules and behaviors described above still apply. -- 2.25.2
On Wed, 15 Apr 2020 19:31:34 +0200 Andrea Bolognani <abologna@redhat.com> wrote:
The section about VFIO devices is kept separate from the rest because it's less about domain XML and guest OS disagreeing on the PCI address of a device, and more about which of the two PCI addresses in the domain XML is even relevant to the guest OS.
The section on zPCI addresses, on the other hand, falls squarely in the "more complex cases" category, so it should live in the corresponding section.
Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- docs/pci-addresses.rst | 57 +++++++++++++++++++++--------------------- 1 file changed, 28 insertions(+), 29 deletions(-)
Not including a 'wonky cases' category is fine with me :) Reviewed-by: Cornelia Huck <cohuck@redhat.com>
Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- docs/pci-addresses.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/pci-addresses.rst b/docs/pci-addresses.rst index 566c81d957..86a41df6ce 100644 --- a/docs/pci-addresses.rst +++ b/docs/pci-addresses.rst @@ -177,7 +177,6 @@ In the simplest case, the following XML snippet </address> </controller> <interface type='bridge'> - <mac address='02:ca:fe:fa:ce:04'/> <source bridge='virbr0'/> <model type='virtio'/> <address type='pci' domain='0x0000' bus='0x01' slot='0x01' function='0x0'> @@ -211,7 +210,6 @@ snippet :: <interface type='bridge'> - <mac address='02:ca:fe:fa:ce:04'/> <source bridge='virbr0'/> <model type='virtio'/> <address type='pci' domain='0x0000' bus='0x01' slot='0x07' function='0x3'> -- 2.25.2
On Wed, 15 Apr 2020 19:31:35 +0200 Andrea Bolognani <abologna@redhat.com> wrote:
Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- docs/pci-addresses.rst | 2 -- 1 file changed, 2 deletions(-)
Yeah, not that useful. Reviewed-by: Cornelia Huck <cohuck@redhat.com>
The idea behind this document is to show, with actual examples, that users should not expect PCI addresses in the domain XML and in the guest OS to match. The first zPCI example already serves this purpose perfectly, so in the interest of keeping the page as brief and easy to digest as possible the second one is removed. Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- docs/pci-addresses.rst | 19 ------------------- 1 file changed, 19 deletions(-) diff --git a/docs/pci-addresses.rst b/docs/pci-addresses.rst index 86a41df6ce..1d2dc8e5fc 100644 --- a/docs/pci-addresses.rst +++ b/docs/pci-addresses.rst @@ -204,25 +204,6 @@ 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``). -Therefore, replacing the virtio-net device definition with the following XML -snippet - -:: - - <interface type='bridge'> - <source bridge='virbr0'/> - <model type='virtio'/> - <address type='pci' domain='0x0000' bus='0x01' slot='0x07' function='0x3'> - <zpci uid='0x0007' fid='0x00000003'/> - </address> - </interface> - -will yield the following result in a Linux guest: - -:: - - 0007:00:00.0 Ethernet controller: Red Hat, Inc. Virtio network device - Device assignment ================= -- 2.25.2
On Wed, 15 Apr 2020 19:31:36 +0200 Andrea Bolognani <abologna@redhat.com> wrote:
The idea behind this document is to show, with actual examples, that users should not expect PCI addresses in the domain XML and in the guest OS to match.
The first zPCI example already serves this purpose perfectly, so in the interest of keeping the page as brief and easy to digest as possible the second one is removed.
Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- docs/pci-addresses.rst | 19 ------------------- 1 file changed, 19 deletions(-)
diff --git a/docs/pci-addresses.rst b/docs/pci-addresses.rst index 86a41df6ce..1d2dc8e5fc 100644 --- a/docs/pci-addresses.rst +++ b/docs/pci-addresses.rst @@ -204,25 +204,6 @@ 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``).
-Therefore, replacing the virtio-net device definition with the following XML -snippet - -:: - - <interface type='bridge'> - <source bridge='virbr0'/> - <model type='virtio'/> - <address type='pci' domain='0x0000' bus='0x01' slot='0x07' function='0x3'> - <zpci uid='0x0007' fid='0x00000003'/> - </address> - </interface> - -will yield the following result in a Linux guest: - -:: - - 0007:00:00.0 Ethernet controller: Red Hat, Inc. Virtio network device -
Device assignment =================
Hm, should that rather go somewhere else? What I wanted to show is "you can have the same PCI address in the XML and still get a different PCI address in the guest, if you change the zpci values", as that might be another source of confusion.
On Wed, 2020-04-15 at 19:47 +0200, Cornelia Huck wrote:
On Wed, 15 Apr 2020 19:31:36 +0200 Andrea Bolognani <abologna@redhat.com> wrote:
-Therefore, replacing the virtio-net device definition with the following XML -snippet - -:: - - <interface type='bridge'> - <source bridge='virbr0'/> - <model type='virtio'/> - <address type='pci' domain='0x0000' bus='0x01' slot='0x07' function='0x3'> - <zpci uid='0x0007' fid='0x00000003'/> - </address> - </interface> - -will yield the following result in a Linux guest: - -:: - - 0007:00:00.0 Ethernet controller: Red Hat, Inc. Virtio network device
Hm, should that rather go somewhere else? What I wanted to show is "you can have the same PCI address in the XML and still get a different PCI address in the guest, if you change the zpci values", as that might be another source of confusion.
I think the previous example, specifically the last bit where you explain how changing the PCI address completely in the domain XML would not change what the guest OS sees because the latter is derived from uid and fid, already drives the point home. It's really two sides of the same coin. Additionally, as I explained elsewhere, this document is not meant to list every possible situation in which PCI addresses in the domain XML and in the guest OS are out of sync, but merely to show that such cases exist. It's valuable to mention the zPCI scenario, but we don't need to show more than one variation of it in my opinion. -- Andrea Bolognani / Red Hat / Virtualization
On Thu, 16 Apr 2020 09:28:58 +0200 Andrea Bolognani <abologna@redhat.com> wrote:
On Wed, 2020-04-15 at 19:47 +0200, Cornelia Huck wrote:
On Wed, 15 Apr 2020 19:31:36 +0200 Andrea Bolognani <abologna@redhat.com> wrote:
-Therefore, replacing the virtio-net device definition with the following XML -snippet - -:: - - <interface type='bridge'> - <source bridge='virbr0'/> - <model type='virtio'/> - <address type='pci' domain='0x0000' bus='0x01' slot='0x07' function='0x3'> - <zpci uid='0x0007' fid='0x00000003'/> - </address> - </interface> - -will yield the following result in a Linux guest: - -:: - - 0007:00:00.0 Ethernet controller: Red Hat, Inc. Virtio network device
Hm, should that rather go somewhere else? What I wanted to show is "you can have the same PCI address in the XML and still get a different PCI address in the guest, if you change the zpci values", as that might be another source of confusion.
I think the previous example, specifically the last bit where you explain how changing the PCI address completely in the domain XML would not change what the guest OS sees because the latter is derived from uid and fid, already drives the point home. It's really two sides of the same coin.
Additionally, as I explained elsewhere, this document is not meant to list every possible situation in which PCI addresses in the domain XML and in the guest OS are out of sync, but merely to show that such cases exist. It's valuable to mention the zPCI scenario, but we don't need to show more than one variation of it in my opinion.
Fair enough. Reviewed-by: Cornelia Huck <cohuck@redhat.com>
On 4/15/20 7:47 PM, Cornelia Huck wrote:
On Wed, 15 Apr 2020 19:31:36 +0200 Andrea Bolognani <abologna@redhat.com> wrote:
The idea behind this document is to show, with actual examples, that users should not expect PCI addresses in the domain XML and in the guest OS to match.
The first zPCI example already serves this purpose perfectly, so in the interest of keeping the page as brief and easy to digest as possible the second one is removed.
Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- docs/pci-addresses.rst | 19 ------------------- 1 file changed, 19 deletions(-)
diff --git a/docs/pci-addresses.rst b/docs/pci-addresses.rst index 86a41df6ce..1d2dc8e5fc 100644 --- a/docs/pci-addresses.rst +++ b/docs/pci-addresses.rst @@ -204,25 +204,6 @@ 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``).
-Therefore, replacing the virtio-net device definition with the following XML -snippet - -:: - - <interface type='bridge'> - <source bridge='virbr0'/> - <model type='virtio'/> - <address type='pci' domain='0x0000' bus='0x01' slot='0x07' function='0x3'> - <zpci uid='0x0007' fid='0x00000003'/> - </address> - </interface> - -will yield the following result in a Linux guest: - -:: - - 0007:00:00.0 Ethernet controller: Red Hat, Inc. Virtio network device - I suggest to use the zpci addressing from the removed example because it outlines more clearly the differences in the parameters. Something like the example below:
For s390x machines, PCI addresses are handled yet differently. No topology information is relayed in the PCI addresses; instead, the fid and uid elements of the zpci device convey information. In the simplest case, the following XML snippet <controller type='pci' index='0' model='pci-root'/> <controller type='pci' index='1' model='pci-bridge'> <model name='pci-bridge'/> <target chassisNr='1'/> <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'> <zpci uid='0x0001' fid='0x00000000'/> </address> </controller> <interface type='bridge'> <mac address='02:ca:fe:fa:ce:04'/> <source bridge='virbr0'/> <model type='virtio'/> <address type='pci' domain='0x0000' bus='0x01' slot='0x01' function='0x0'> <zpci uid='0x0007' fid='0x00000003'/> </address> </interface> will result in the following in a Linux guest: 0007:00:00.0 Ethernet controller: Red Hat, Inc. Virtio network device The slot for the PCI device in the guest OS is defined by the fid (function id).
Device assignment =================
Hm, should that rather go somewhere else? What I wanted to show is "you can have the same PCI address in the XML and still get a different PCI address in the guest, if you change the zpci values", as that might be another source of confusion.
-- 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 Thu, 2020-04-16 at 12:29 +0200, Boris Fiuczynski wrote:
I suggest to use the zpci addressing from the removed example because it outlines more clearly the differences in the parameters. Something like the example below:
For s390x machines, PCI addresses are handled yet differently. No topology information is relayed in the PCI addresses; instead, the fid and uid elements of the zpci device convey information. In the simplest case, the following XML snippet
<controller type='pci' index='0' model='pci-root'/> <controller type='pci' index='1' model='pci-bridge'> <model name='pci-bridge'/> <target chassisNr='1'/> <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'> <zpci uid='0x0001' fid='0x00000000'/> </address> </controller> <interface type='bridge'> <mac address='02:ca:fe:fa:ce:04'/> <source bridge='virbr0'/> <model type='virtio'/> <address type='pci' domain='0x0000' bus='0x01' slot='0x01' function='0x0'> <zpci uid='0x0007' fid='0x00000003'/> </address> </interface>
will result in the following in a Linux guest:
0007:00:00.0 Ethernet controller: Red Hat, Inc. Virtio network device
You're right, this example is more illustrative. Care to submit a patch changing it? -- Andrea Bolognani / Red Hat / Virtualization
participants (5)
-
Andrea Bolognani -
Boris Fiuczynski -
Cornelia Huck -
Daniel P. Berrangé -
Ján Tomko