[PATCH 2/2] docs: Improve zPCI section in pci-addresses.rst

[Cornelia Huck]

On Thu, 16 Apr 2020 17:56:18 +0200
Boris Fiuczynski <fiuczy at linux.ibm.com> wrote:

> Improving the zPCI example by choosing more distinct values and
> adding explanation for fid.
> 
> Signed-off-by: Boris Fiuczynski <fiuczy at 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