From e94ddeac0605ab0f4b45ef62a392c2eed5020330 Mon Sep 17 00:00:00 2001
From: Boris Fiuczynski <fiuczy@linux.ibm.com>
Date: Fri, 17 Apr 2020 14:27:34 +0200
Subject: [PATCH] docs: Improve zPCI section in pci-addresses.rst

Improving the zPCI example by choosing more distinct values and
adding explanation for fid.

Signed-off-by: Boris Fiuczynski <fiuczy@linux.ibm.com>
Reviewed-by: Cornelia Huck <cohuck@redhat.com>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
---
 docs/pci-addresses.rst | 22 ++++++++++++----------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/docs/pci-addresses.rst b/docs/pci-addresses.rst
index 7c8e9edd73..885d50517a 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,23 @@ 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. 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 PCI address for the ``virtio-net`` device with
+Any changes in the PCI address are not 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``).
+will result in the exactly same view in the guest, as the ``fid`` and ``uid``
+values in the ``zpci`` element remain unchanged.
 
 
 Device assignment
-- 
GitLab