[PATCH 1/1] OvmfPkg/QemuBootOrderLib: recognize "usb-storage" devices in XHCI ports

[Laszlo Ersek <lersek@redhat.com>]

The feature is primarily useful for modern AARCH64 guests that have no
built-in virtio block / SCSI drivers; as on "qemu-system-aarch64 -M virt",
there are no IDE or AHCI controllers that could be used as fallback. XHCI
is available in "-M virt" however, and because XHCI predates AARCH64 by
several years, said guests are expected to have built-in drivers for it.

Other device models ("usb-uas", "usb-bot") are out of scope for now,
similarly to USB1.x (UHCI) and USB2 (EHCI) host controllers, and similarly
to USB hubs (which are USB1.1 only). In particular, port mapping between
EHCI and companion UHCI controllers is very complex; it even leads to PCI
slot/function differences between the OpenFirmware device paths exported
by QEMU and the the UEFI device paths generated by edk2.

The number of ports on the XHCI controller defaults to 4, but it can be
raised via the "p3" property to 15. In addition, several XHCI controllers
can be grouped into a single-slot, multi-function PCI device. These allow
for a good number of usb-storage devices, while their desired boot order
remains recognizable to this patch.

In the example below, we create two XHCI controllers, grouped into PCI
slot 00:02 as functions 0 and 1. Both controllers are given 15 ports. We
attach a "usb-storage" device to controller 1 at port 3 (ports are 1-based
in QEMU, 0-based in edk2), and attach another "usb-storage" device to
controller 2 at port 9.

QEMU command line options (NB. they apply equally to aarch64/virt and
x86_64/{i440fx,q35}):

  -device qemu-xhci,id=xhci1,p3=15,addr=02.0,multifunction=on \
  -device qemu-xhci,id=xhci2,p3=15,addr=02.1 \
  \
  -drive id=disk1,if=none,format=qcow2,$DISK1_OPTIONS \
  -drive id=disk2,if=none,format=qcow2,$DISK2_OPTIONS \
  \
  -device usb-storage,drive=disk1,bus=xhci1.0,port=3,bootindex=1 \
  -device usb-storage,drive=disk2,bus=xhci2.0,port=9,bootindex=2 \

Libvirt domain XML fragment:

  <controller type='usb' index='1' model='qemu-xhci' ports='15'>
    <address type='pci'
     domain='0x0000' bus='0x00' slot='0x02' function='0x0'
     multifunction='on'/>
  </controller>
  <controller type='usb' index='2' model='qemu-xhci' ports='15'>
    <address type='pci'
     domain='0x0000' bus='0x00' slot='0x02' function='0x1'/>
  </controller>

  <disk type='file' device='disk'>
    <driver name='qemu' type='qcow2'/>
    <source file='...'/>
    <target dev='sda' bus='usb'/>
    <boot order='1'/>
    <address type='usb' bus='1' port='3'/>
  </disk>
  <disk type='file' device='disk'>
    <driver name='qemu' type='qcow2'/>
    <source file='...'/>
    <target dev='sdb' bus='usb'/>
    <boot order='2'/>
    <address type='usb' bus='2' port='9'/>
  </disk>

Cc: Ard Biesheuvel <ard.biesheuvel@linaro.org>
Cc: Gerd Hoffmann <kraxel@redhat.com>
Cc: Jordan Justen <jordan.l.justen@intel.com>
Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Laszlo Ersek <lersek@redhat.com>
---
 OvmfPkg/Library/QemuBootOrderLib/QemuBootOrderLib.c | 44 ++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/OvmfPkg/Library/QemuBootOrderLib/QemuBootOrderLib.c b/OvmfPkg/Library/QemuBootOrderLib/QemuBootOrderLib.c
index 567f6f92f452..7c1f375beb20 100644
--- a/OvmfPkg/Library/QemuBootOrderLib/QemuBootOrderLib.c
+++ b/OvmfPkg/Library/QemuBootOrderLib/QemuBootOrderLib.c
@@ -986,6 +986,50 @@ TranslatePciOfwNodes (
       Eui64[7], Eui64[6], Eui64[5], Eui64[4],
       Eui64[3], Eui64[2], Eui64[1], Eui64[0]
       );
+  } else if (NumNodes >= FirstNonBridge + 2 &&
+             SubstringEq (OfwNode[FirstNonBridge + 0].DriverName, "usb") &&
+             SubstringEq (OfwNode[FirstNonBridge + 1].DriverName, "storage")) {
+    //
+    // OpenFirmware device path (usb-storage device in XHCI port):
+    //
+    //   /pci@i0cf8/usb@3[,1]/storage@2/channel@0/disk@0,0
+    //        ^         ^  ^          ^         ^      ^ ^
+    //        |         |  |          |         fixed  fixed
+    //        |         |  |          XHCI port number, 1-based
+    //        |         |  PCI function corresponding to XHCI (optional)
+    //        |         PCI slot holding XHCI
+    //        PCI root at system bus port, PIO
+    //
+    // UEFI device path prefix:
+    //
+    //   PciRoot(0x0)/Pci(0x3,0x1)/USB(0x1,0x0)
+    //                        ^        ^
+    //                        |        XHCI port number in 0-based notation
+    //                        0x0 if PCI function is 0, or absent from OFW
+    //
+    RETURN_STATUS ParseStatus;
+    UINT64        OneBasedXhciPort;
+
+    NumEntries = 1;
+    ParseStatus = ParseUnitAddressHexList (
+                    OfwNode[FirstNonBridge + 1].UnitAddress,
+                    &OneBasedXhciPort,
+                    &NumEntries
+                    );
+    if (RETURN_ERROR (ParseStatus) || OneBasedXhciPort == 0) {
+      return RETURN_UNSUPPORTED;
+    }
+
+    Written = UnicodeSPrintAsciiFormat (
+                Translated,
+                *TranslatedSize * sizeof (*Translated), // BufferSize in bytes
+                "PciRoot(0x%x)%s/Pci(0x%Lx,0x%Lx)/USB(0x%Lx,0x0)",
+                PciRoot,
+                Bridges,
+                PciDevFun[0],
+                PciDevFun[1],
+                OneBasedXhciPort - 1
+                );
   } else {
     //
     // Generic OpenFirmware device path for PCI devices:
-- 
2.14.1.3.gb7cf6e02401b