Add documentation and usage examples for the Thunderbolt PCIe hotplug layer, including VGA, USB storage, and NVMe hotplug flows.
Add a MAINTAINERS entry for the Thunderbolt PCIe files with Dmitry R as reviewer, while keeping the files under the existing PCI area through their paths. Signed-off-by: Dmitry R <[email protected]> --- MAINTAINERS | 7 ++ README.md | 91 +++++++++++++++++++++++ docs/specs/index.rst | 1 + docs/specs/thunderbolt-pcie-hotplug.rst | 99 +++++++++++++++++++++++++ 4 files changed, 198 insertions(+) create mode 100644 README.md create mode 100644 docs/specs/thunderbolt-pcie-hotplug.rst diff --git a/MAINTAINERS b/MAINTAINERS index 6171cc7494..0be88e77fa 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -2223,6 +2223,13 @@ F: docs/pci* F: docs/specs/*pci* F: docs/system/sriov.rst +Thunderbolt PCIe +R: Dmitry R <[email protected]> +S: Maintained +F: docs/specs/thunderbolt-pcie-hotplug.rst +F: hw/display/thunderbolt-vga.c +F: hw/pci-bridge/thunderbolt*.c + ARM PCI Hotplug M: Gustavo Romero <[email protected]> L: [email protected] diff --git a/README.md b/README.md new file mode 100644 index 0000000000..1115c9db82 --- /dev/null +++ b/README.md @@ -0,0 +1,91 @@ +SPDX-License-Identifier: GPL-2.0-or-later + +# QEMU Thunderbolt PCIe hotplug layer + +This branch adds a Thunderbolt-flavoured PCIe hotplug layer for QEMU +experiments. The implementation keeps normal QEMU PCI devices intact and +adds a new Thunderbolt bus/root-port layer around them. + +The primary goal is to provide hotplug and hot-unplug for real and virtual +devices in guests that do not support those devices being added or removed +directly. macOS is the main validation target for this path: devices can be +tunnelled through a guest-visible Thunderbolt layer even when direct PCIe +hotplug for the same endpoint is not usable. + +The regular QEMU `VGA` device is not changed and is not made hotpluggable. +Thunderbolt display experiments use a separate `thunderbolt-vga` device type. + +## Added device types + +- `thunderbolt-root-port`: a PCIe root port that creates a `thunderbolt-bus`. + Its `connected` QOM property controls guest-visible link presence. +- `thunderbolt-pcie-pci-bridge`: a PCIe-to-PCI bridge for tunnelled PCI + endpoints with Thunderbolt-related ACPI properties. +- `thunderbolt-vga`: a hotpluggable stdvga-compatible endpoint with constrained + default EDID settings for guest hotplug tests. + +## Basic boot example + +Start the guest with its normal boot display and an empty Thunderbolt root +port: + +```sh +qemu-system-x86_64 \ + -machine q35 \ + -device VGA,id=bootvga,bus=pcie.0,addr=0x06,vgamem_mb=4,xres=1280,yres=800,xmax=1280,ymax=800,refresh_rate=60000 \ + -device thunderbolt-root-port,id=tbrp0,bus=pcie.0,chassis=1,slot=1,addr=0x05 \ + ... +``` + +Hotplug and remove a Thunderbolt VGA endpoint through the QEMU monitor: + +```text +(qemu) device_add thunderbolt-vga,id=tbvga0,bus=tbrp0,addr=0x00 +(qemu) device_del tbvga0 +``` + +Disconnect or reconnect the whole Thunderbolt root port: + +```text +(qemu) qom-set /machine/peripheral/tbrp0 connected false +(qemu) qom-set /machine/peripheral/tbrp0 connected true +``` + +## USB storage example + +Attach a USB controller behind the Thunderbolt root port, then attach USB mass +storage to that controller: + +```text +(qemu) device_add qemu-xhci,id=tbxhci0,bus=tbrp0,addr=0x00 +(qemu) drive_add 0 if=none,id=TBUSB,file=TBUSB.raw,format=raw,cache=writeback,aio=threads +(qemu) device_add usb-storage,id=tbusb0,bus=tbxhci0.0,drive=TBUSB,serial=tb-usb-stick0 +``` + +After the guest ejects or unmounts the disk, remove the device and controller: + +```text +(qemu) device_del tbusb0 +(qemu) device_del tbxhci0 +``` + +## NVMe example + +```text +(qemu) drive_add 0 if=none,id=TBNVME,file=TBNVME.qcow2,format=qcow2 +(qemu) device_add nvme,id=tbnvme0,bus=tbrp0,addr=0x00,serial=tb-nvme0,drive=TBNVME +(qemu) device_del tbnvme0 +``` + +## Validation status + +The development validation used macOS guests booted from overlay disk images so +the base images stayed immutable. The tested hotplug flows covered: + +- `thunderbolt-vga` detection and removal while the standard boot VGA remained. +- NVMe controller hotplug and driver instance disappearance after unplug. +- USB controller hotplug, USB storage mount/write/eject, controller removal, + replug, and data persistence verification. + +The qtest coverage checks that regular `VGA` hotplug still fails while +`thunderbolt-vga` can be hotplugged behind `thunderbolt-root-port`. diff --git a/docs/specs/index.rst b/docs/specs/index.rst index b7909a108a..1f0d3e4b4a 100644 --- a/docs/specs/index.rst +++ b/docs/specs/index.rst @@ -31,6 +31,7 @@ guest hardware that is specific to QEMU. pvpanic spdm standard-vga + thunderbolt-pcie-hotplug virt-ctlr vmcoreinfo vmgenid diff --git a/docs/specs/thunderbolt-pcie-hotplug.rst b/docs/specs/thunderbolt-pcie-hotplug.rst new file mode 100644 index 0000000000..f14c64b181 --- /dev/null +++ b/docs/specs/thunderbolt-pcie-hotplug.rst @@ -0,0 +1,99 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Thunderbolt PCIe hotplug layer +============================== + +This series adds a Thunderbolt-flavoured PCIe layer for experiments with +guest-visible PCIe tunnelling. Devices behind the layer remain normal QEMU +PCI devices; the Thunderbolt root port provides the guest-visible connection +state, ACPI properties, and PCIe hotplug notifications. + +The main use case is hotplug and hot-unplug of real and virtual devices in +guests that cannot use direct hotplug for those devices. For example, a macOS +guest can observe the endpoint through a guest-visible Thunderbolt layer when +direct PCIe hotplug for the same endpoint is not supported or not usable. + +The implementation adds three user-visible device types: + +``thunderbolt-root-port`` + PCIe root port that creates a ``thunderbolt-bus`` secondary bus. The + ``connected`` QOM property controls whether devices behind the port are + reported as present to the guest. + +``thunderbolt-pcie-pci-bridge`` + PCIe-to-PCI bridge for tunnelled PCI endpoints. It adds Thunderbolt-related + ACPI properties while leaving downstream PCI devices otherwise normal. + +``thunderbolt-vga`` + Hotpluggable stdvga-compatible device for Thunderbolt experiments. The + regular ``VGA`` device is not made hotpluggable and its defaults are not + changed. + +Basic launch example +-------------------- + +Start the guest with its normal boot display and an empty Thunderbolt root +port: + +:: + + qemu-system-x86_64 \ + -machine q35 \ + -device VGA,id=bootvga,bus=pcie.0,addr=0x06,vgamem_mb=4,xres=1280,yres=800,xmax=1280,ymax=800,refresh_rate=60000 \ + -device thunderbolt-root-port,id=tbrp0,bus=pcie.0,chassis=1,slot=1,addr=0x05 \ + ... + +Hotplug a Thunderbolt VGA endpoint after the guest has booted: + +:: + + (qemu) device_add thunderbolt-vga,id=tbvga0,bus=tbrp0,addr=0x00 + (qemu) device_del tbvga0 + +Temporarily disconnect and reconnect the whole Thunderbolt port: + +:: + + (qemu) qom-set /machine/peripheral/tbrp0 connected false + (qemu) qom-set /machine/peripheral/tbrp0 connected true + +USB storage example +------------------- + +Attach a USB controller to the Thunderbolt root port, then attach USB mass +storage to that controller: + +:: + + (qemu) device_add qemu-xhci,id=tbxhci0,bus=tbrp0,addr=0x00 + (qemu) drive_add 0 if=none,id=TBUSB,file=TBUSB.raw,format=raw,cache=writeback,aio=threads + (qemu) device_add usb-storage,id=tbusb0,bus=tbxhci0.0,drive=TBUSB,serial=tb-usb-stick0 + +After the guest ejects or unmounts the disk, remove the USB device and the +controller: + +:: + + (qemu) device_del tbusb0 + (qemu) device_del tbxhci0 + +NVMe example +------------ + +Attach an NVMe controller behind the Thunderbolt root port: + +:: + + (qemu) drive_add 0 if=none,id=TBNVME,file=TBNVME.qcow2,format=qcow2 + (qemu) device_add nvme,id=tbnvme0,bus=tbrp0,addr=0x00,serial=tb-nvme0,drive=TBNVME + (qemu) device_del tbnvme0 + +Notes for review +---------------- + +The regular QEMU ``VGA`` type is intentionally left non-hotpluggable. Tests +check that hotplugging ``VGA`` behind a Thunderbolt root port still fails, and +that ``thunderbolt-vga`` can be hotplugged with constrained display defaults. + +The macOS validation flow used QCOW2 overlays for all mutable disks so the base +guest images remained unchanged. -- 2.47.3
