docs/pcie_pci_bridge.txt

   1 Generic PCI Express to PCI Bridge
   2 ================================
   3
   4 Description
   5 ===========
   6 PCIE-to-PCI bridge is a new method for legacy PCI
   7 hierarchies creation on Q35 machines.
   8
   9 Previously Intel DMI-to-PCI bridge was used for this purpose.
  10 But due to its strict limitations - no support of hot-plug,
  11 no cross-platform and cross-architecture support - a new generic
  12 PCIE-to-PCI bridge should now be used for any legacy PCI device usage
  13 with PCI Express machine.
  14
  15 This generic PCIE-PCI bridge is a cross-platform device,
  16 can be hot-plugged into appropriate root port (requires additional actions,
  17 see 'PCIE-PCI bridge hot-plug' section),
  18 and supports devices hot-plug into the bridge itself
  19 (with some limitations, see below).
  20
  21 Hot-plug of legacy PCI devices into the bridge
  22 is provided by bridge's built-in Standard hot-plug Controller.
  23 Though it still has some limitations, see below.
  24
  25 PCIE-PCI bridge hot-plug
  26 =======================
  27 Guest OSes require extra efforts to enable PCIE-PCI bridge hot-plug.
  28 Motivation - now on init any PCI Express root port which doesn't have
  29 any device plugged in, has no free buses reserved to provide any of them
  30 to a hot-plugged devices in future.
  31
  32 To solve this problem we reserve additional buses on a firmware level.
  33 Currently only SeaBIOS is supported.
  34 The way of bus number to reserve delivery is special
  35 Red Hat vendor-specific PCI capability, added to the root port
  36 that is planned to have PCIE-PCI bridge hot-plugged in.
  37
  38 Capability layout (defined in include/hw/pci/pci_bridge.h):
  39
  40     uint8_t id;     Standard PCI capability header field
  41     uint8_t next;   Standard PCI capability header field
  42     uint8_t len;    Standard PCI vendor-specific capability header field
  43
  44     uint8_t type;   Red Hat vendor-specific capability type
  45                     List of currently existing types:
  46                         RESOURCE_RESERVE = 1
  47
  48
  49     uint32_t bus_res;   Minimum number of buses to reserve
  50
  51     uint64_t io;           IO space to reserve
  52     uint32_t mem           Non-prefetchable memory to reserve
  53
  54     At most one of the following two fields may be set to a value
  55     different from -1:
  56     uint32_t mem_pref_32;  Prefetchable memory to reserve (32-bit MMIO)
  57     uint64_t mem_pref_64;  Prefetchable memory to reserve (64-bit MMIO)
  58
  59 If any reservation field is -1 then this kind of reservation is not
  60 needed and must be ignored by firmware.
  61
  62 At the moment this capability is used only in QEMU generic PCIe root port
  63 (-device pcie-root-port). Capability construction function takes all reservation
  64 fields values from corresponding device properties. By default all of them are
  65 set to -1 to leave root port's default behavior unchanged.
  66
  67 Usage
  68 =====
  69 A detailed command line would be:
  70
  71 [qemu-bin + storage options] \
  72 -m 2G \
  73 -device pcie-root-port,bus=pcie.0,id=rp1,slot=1 \
  74 -device pcie-root-port,bus=pcie.0,id=rp2,slot=2 \
  75 -device pcie-root-port,bus=pcie.0,id=rp3,slot=3,bus-reserve=1 \
  76 -device pcie-pci-bridge,id=br1,bus=rp1 \
  77 -device pcie-pci-bridge,id=br2,bus=rp2 \
  78 -device e1000,bus=br1,addr=8
  79
  80 Then in monitor it's OK to execute next commands:
  81 device_add pcie-pci-bridge,id=br3,bus=rp3 \
  82 device_add e1000,bus=br2,addr=1 \
  83 device_add e1000,bus=br3,addr=1
  84
  85 Here you have:
  86  (1) Cold-plugged:
  87     - Root ports: 1 QEMU generic root port with the capability mentioned above,
  88                   2 QEMU generic root ports without this capability;
  89     - 2 PCIE-PCI bridges plugged into 2 different root ports;
  90     - e1000 plugged into the first bridge.
  91  (2) Hot-plugged:
  92     - PCIE-PCI bridge, plugged into QEMU generic root port;
  93     - 2 e1000 cards, one plugged into the cold-plugged PCIE-PCI bridge,
  94                      another plugged into the hot-plugged bridge.
  95
  96 Limitations
  97 ===========
  98 The PCIE-PCI bridge can be hot-plugged only into pcie-root-port that
  99 has proper 'bus-reserve' property value to provide secondary bus for the
 100 hot-plugged bridge.
 101
 102 Windows 7 and older versions don't support hot-plug devices into the PCIE-PCI bridge.
 103 To enable device hot-plug into the bridge on Linux there're 3 ways:
 104 1) Build shpchp module with this patch http://www.spinics.net/lists/linux-pci/msg63052.html
 105 2) Use kernel 4.14+ where the patch mentioned above is already merged.
 106 3) Set 'msi' property to off - this forces the bridge to use legacy INTx,
 107     which allows the bridge to notify the OS about hot-plug event without having
 108     BUSMASTER set.
 109
 110 Implementation
 111 ==============
 112 The PCIE-PCI bridge is based on PCI-PCI bridge, but also accumulates PCI Express
 113 features as a PCI Express device.
 114