[PATCH] docs: Document reserved PCI addresses for QEMU

[Laine Stump]

On 4/21/20 11:01 AM, Michal Privoznik wrote:
> >From time to time we are asked which PCI addresses are reserved
> in QEMU. Let's document them in one place, it's easier than
> reconstructing the list from the code each time.


Definitely a good idea. I'm pasting in some notes I added when replying 
to the email thread that precipitated this document.


>
> Signed-off-by: Michal Privoznik <mprivozn at redhat.com>
> ---
>   docs/pci-addresses.rst | 40 ++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 40 insertions(+)
>
> diff --git a/docs/pci-addresses.rst b/docs/pci-addresses.rst
> index 885d50517a..6c203fb1ac 100644
> --- a/docs/pci-addresses.rst
> +++ b/docs/pci-addresses.rst
> @@ -235,3 +235,43 @@ 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.
> +
> +
> +Reserved addresses
> +==================
> +
> +Due to some historical reasons hypervisors might expect some PCI
> +devices to appear at certain addresses instead of 'random' ones.
> +For QEMU this is machine type and guest architecture dependant.
> +But to give you at least a gist here is list of reserved PCI
> +addresses:
> +
> +For ``I440FX`` the following addresses are reserved:
> +
> +============  ======================
> +0000:00:01.0  ISA bridge
> +0000:00:01.1  primary IDE controller
> +0000:00:01.2  PIIX3 USB controller
> +0000:00:01.3  PCI bridge

(The device named at 01.3 is misleading - lspci says it is a "Bridge", 
but it's actually (according to the PIIX4 spec) an ACPI (power 
management) and SMBus controller.


All the devices in slot 1 are hard coded into qemu - they are at that 
address, and can't be moved or eliminated. (I think "reserved" is a bit 
vague - they are actually "in use").


> +0000:00:02.0  primary video card
> +============  ======================


As for the primary video card - In the bad old days (early 2010's) slot 
2 was reserved for a video card and the video card had to be at slot 2, 
but that hasn't been the case for a very long time. The way it works now 
is: if slot 2 is empty and there's a video card with no PCI address, 
then we'll put it at slot 2. But it's completely acceptable to put a 
different device at slot 2 and/or to put the video card at a different 
address. As a matter of fact, libvirt itself will auto-assign a 
different type of device to slot 2, and also doesn't complain if you add 
a video device and slot 2 is already taken - it will just put the video 
device in a different slot.


(the reason for reserving slot 2 in the past was that certain *very* old 
versions of qemu (and maybe some current versions of weird unsupported 
qemu platforms) could only specify a video device with the "-vga" qemu 
commandline option, and that option would always put the device at slot 
2 (or, rather, it would put the device at the first free slot, and the 
only way for us to maintain guest ABI stability across runs was to 
enforce that slot 2 was always either assigned to the video device, or 
left unused in case a video device was added later)).


So the short of that - slot 2 isn't "reserved" unless you are running 
qemu from 10 years ago, and you can put whatever you want in slot 2 on 
440fx.


> +
> +For ``Q35`` the following addresses are reserved:
> +
> +============  =======================
> +0000:00:1f.2  primary SATA controller
> +0000:00:1f.0  ISA bridge
> +0000:00:1f.3  SMBus


^^ These three devices are in the Q35 chipset, hardcoded into qemu, and 
can't be moved or deleted - they are always there.


> +0000:00:01.0  primary video card


Again, this isn't reserved, it just usually works out that way. You can 
put anything you like in slot 1, and you can put the primary video 
device anywhere you want.

> +============  =======================
> +
> +and the following are recommended


I think "recommended" is a bit misleading, as it might suggest to some 
people that they should actually use a USB2 controller. In reality, 
nobody should be using USB2 controllers since they are more complicated 
than USB3 and also use more CPU (although admittedly they aren't as bad 
as USB1).


>   (libvirt will try to place
> +corresponding devices there because that's how real ``Q35`` would
> +do it, but won't fail if the address is already taken):
> +
> +============  ===============
> +0000:00:1a.0  USB2 controller
> +0000:00:1b.0  ICH9 sound chip


The ICH9 sound chip actually *is* to be recommended, since it is the 
only emulated audio device that will automatically be assigned to a slot 
on pcie-root, and *all* qemu sound devices are conventional PCI, so all 
the other audio devices will by default pull in a pcie-to-pci-bridge 
device, and we try to avoid that since it's considered to be "legacy".

> +0000:00:1d.0  USB2 controller
> +0000:00:1e.0  dmi-to-pci bridge


Although we'll place a dmi-to-pci-bridge at this address if someone adds 
one to the config, it hasn't been needed for a few years (if you really 
need conventional PCI slots, pcie-to-pci-bridge is a much better choice, 
and what libvirt chooses/adds by default when needed). So again this 
device will never be added by libvirt, shouldn't be added by users, and 
so will almost never take up this address. Even pointing out that we 
would put a dmi-to-pci-bridge in slot 1e *were they to add one* might 
mislead users into thinking that slot is otherwise unavailable, or at 
least that they should avoid using it.


In the end, I think the devices in slot 1 on 440fx, and slot 1F on q35 
should be marked as mandatory/in-use (rather than reserved), while all 
the other addresses (including video) should be in a list labeled as 
"these addresses will be used by default by the listed devices *if not 
otherwise used*, but aren't reserved or mandatory.


Oh, and also slot 0 is reserved/in-use on both pci-root and pcie-root 
(for the PCI bus controller I think?).