[PATCH] docs: add zpci information to pci-addresses.rst

[Cornelia Huck]

Add some information on how pci address work on s390x.

Signed-off-by: Cornelia Huck <cohuck at redhat.com>
---
 docs/pci-addresses.rst | 63 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)

diff --git a/docs/pci-addresses.rst b/docs/pci-addresses.rst
index 923783a151b0..9e241a24fcfb 100644
--- a/docs/pci-addresses.rst
+++ b/docs/pci-addresses.rst
@@ -184,3 +184,66 @@ 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
+``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='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
+
+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
+
+::
+
+  <address type='pci' domain='0x0000' bus='0x01' slot='0x07' function='0x3'>
+
+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'>
+        <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::
+
+  0007:00:00.0 Ethernet controller: Red Hat, Inc. Virtio network device
-- 
2.21.1