[RFC PATCH v2 5/5] docs: document Thunderbolt PCIe hotplug layer

[Dmitry R <rdmitry0911@gmail.com>]

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 <rdmitry0911@gmail.com>
---
 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 <rdmitry0911@gmail.com>
+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 <gustavo.romero@linaro.org>
 L: qemu-arm@nongnu.org
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