PCI Express devices which use legacy VGA compatibility should be placed
on the Root Complex.  This simplifies ioport access to VGA registers,
which requires use of a special exception bit to work across PCI(e)
bridges.  It is also necessary for ioport access to VESA BIOS Extension
(VBE) registers, which is not forwarded over PCI(e) bridges, even with
the special exception bit for VGA register access.[1]

Update the PCI Express Guidelines to add these to the list of devices
which can be placed directly on the Root Complex.

Note that the only PCI Express display devices currently supported
(bochs-display and virtio-gpu-pci) do not offer VGA compatibility.
Legacy PCI devices (e.g. vga, qxl-vga, virtio-vga) are already
documented as allowed on the Root Complex by the first item in the list.
However, this item documents an additional consideration for placing
devices which was not previously mentioned, and may be relevant for PCIe
devices offering VGA compatibility in the future.

[1]: https://mail.coreboot.org/hyperkitty/list/seabios@seabios.org/thread/XG2RN3HKVRDEDTLA2PRELLIENIIH7II7/#XVP3I2KQVZHSTDA4SNVKOITWGRGSDU3F

Suggested-by: Laszlo Ersek <lersek@redhat.com>
Signed-off-by: Kevin Locke <kevin@kevinlocke.name>
---
Changes since v2:
 * Change Signed-off-by to Suggested-by for Laszlo Ersek, as suggested
   by Laszlo Ersek.

Changes since v1:
 * Replace my overly-broad exception for devices requiring ioport access
   with a list item specifically for PCI Express devices offering VGA
   Compatibility provided by Laszlo Ersek.
 * Rewrite the commit message based on my improved understanding of the
   issue and the improved scope of the change.

 docs/pcie.txt | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/docs/pcie.txt b/docs/pcie.txt
index 89e3502075..59b26817f9 100644
--- a/docs/pcie.txt
+++ b/docs/pcie.txt
@@ -48,13 +48,17 @@ Place only the following kinds of devices directly on the Root Complex:
         strangely when PCI Express devices are integrated
         with the Root Complex.
 
-    (2) PCI Express Root Ports (ioh3420), for starting exclusively PCI Express
+    (2) Assigned PCI Express GPUs that offer legacy VGA compatibility, and
+        that such compatibility is expected of (due to booting with SeaBIOS,
+        or due to UEFI driver bugs or native OS driver bugs).
+
+    (3) PCI Express Root Ports (ioh3420), for starting exclusively PCI Express
         hierarchies.
 
-    (3) PCI Express to PCI Bridge (pcie-pci-bridge), for starting legacy PCI
+    (4) PCI Express to PCI Bridge (pcie-pci-bridge), for starting legacy PCI
         hierarchies.
 
-    (4) Extra Root Complexes (pxb-pcie), if multiple PCI Express Root Buses
+    (5) Extra Root Complexes (pxb-pcie), if multiple PCI Express Root Buses
         are needed.
 
    pcie.0 bus
-- 
2.35.1

Mention devices which support VESA BIOS Extensions (VBE) specifically in
the list item of the Root Bus section discussing devices placed on the
Root Complex.

VESA BIOS Extensions (VBE) present a particular challenge not currently
noted in the recommendations:  ioport access to VBE registers is not
forwarded over PCI(e) bridges, even when using the special exception bit
for VGA register access.[1]  As a result, devices supporting VBE must be
placed on the Root Complex for VBE to be usable.

The new documentation also clarifies that VBE is used on systems with
BIOS firmware, including SeaBIOS, and that it is not generally used on
systems with UEFI firmware, including OVMF, where UEFI GOP is used.  I
say "generally" because VBE may be used on UEFI systems which boot using
a Compatibility Support Module (CSM), such as SeaBIOS.[2]  This
clarification is intended to help users who may not be familiar with VBE
to determine whether it is relevant to their situation.

[1]: https://mail.coreboot.org/hyperkitty/list/seabios@seabios.org/thread/XG2RN3HKVRDEDTLA2PRELLIENIIH7II7/#XVP3I2KQVZHSTDA4SNVKOITWGRGSDU3F
[2]: https://www.mail-archive.com/edk2-devel@lists.sourceforge.net/msg03788.html

Signed-off-by: Kevin Locke <kevin@kevinlocke.name>
---
Changes since v3:
 * Rewrite the doc addition, limiting it to VGA devices with VBE, as
   VBE is the only problematic feature.
 * Rewrite the commit message as a result of the new scope.
 * Mention VBE in relation to BIOS and UEFI to help users determine
   whether they may be using VBE.
 * Make the doc addition a new paragraph of the first list item, rather
   than its own list item, since it raises a consideration for PCI
   graphics devices covered by that list item, rather than a separate
   class of devices.
 * Drop Suggested-by: Laszlo Ersek.  Since I rewrote the text, I can no
   longer blame Laszlo for any issues in it.

Changes since v2:
 * Change Signed-off-by to Suggested-by for Laszlo Ersek, as suggested
   by Laszlo Ersek.

Changes since v1:
 * Replace my overly-broad exception for devices requiring ioport access
   with a list item specifically for PCI Express devices offering VGA
   Compatibility provided by Laszlo Ersek.
 * Rewrite the commit message based on my improved understanding of the
   issue and the improved scope of the change.

 docs/pcie.txt | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/pcie.txt b/docs/pcie.txt
index 89e3502075..21c2624c44 100644
--- a/docs/pcie.txt
+++ b/docs/pcie.txt
@@ -48,6 +48,12 @@ Place only the following kinds of devices directly on the Root Complex:
         strangely when PCI Express devices are integrated
         with the Root Complex.
 
+        VGA compatible devices which support VESA BIOS Extensions (VBE) must
+        be placed on the Root Complex for the VBE registers to be accessible,
+        as the IO port access is not forwarded over bridges or root ports.
+        VBE may be used on systems with BIOS firmware (e.g. SeaBIOS).  It is
+        not generally used on systems with UEFI firmware (e.g. OVMF).
+
     (2) PCI Express Root Ports (ioh3420), for starting exclusively PCI Express
         hierarchies.
 
-- 
2.35.1