LXR qemu/docs/pcie_pci

   1Generic PCI Express to PCI Bridge
   2================================
   3
   4Description
   5===========
   6PCIE-to-PCI bridge is a new method for legacy PCI
   7hierarchies creation on Q35 machines.
   8
   9Previously Intel DMI-to-PCI bridge was used for this purpose.
  10But due to its strict limitations - no support of hot-plug,
  11no cross-platform and cross-architecture support - a new generic
  12PCIE-to-PCI bridge should now be used for any legacy PCI device usage
  13with PCI Express machine.
  14
  15This generic PCIE-PCI bridge is a cross-platform device,
  16can be hot-plugged into appropriate root port (requires additional actions,
  17see 'PCIE-PCI bridge hot-plug' section),
  18and supports devices hot-plug into the bridge itself
  19(with some limitations, see below).
  20
  21Hot-plug of legacy PCI devices into the bridge
  22is provided by bridge's built-in Standard hot-plug Controller.
  23Though it still has some limitations, see below.
  24
  25PCIE-PCI bridge hot-plug
  26=======================
  27Guest OSes require extra efforts to enable PCIE-PCI bridge hot-plug.
  28Motivation - now on init any PCI Express root port which doesn't have
  29any device plugged in, has no free buses reserved to provide any of them
  30to a hot-plugged devices in future.
  31
  32To solve this problem we reserve additional buses on a firmware level.
  33Currently only SeaBIOS is supported.
  34The way of bus number to reserve delivery is special
  35Red Hat vendor-specific PCI capability, added to the root port
  36that is planned to have PCIE-PCI bridge hot-plugged in.
  37
  38Capability 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
  59If any reservation field is -1 then this kind of reservation is not
  60needed and must be ignored by firmware.
  61
  62At the moment this capability is used only in QEMU generic PCIe root port
  63(-device pcie-root-port). Capability construction function takes all reservation
  64fields values from corresponding device properties. By default all of them are
  65set to -1 to leave root port's default behavior unchanged.
  66
  67Usage
  68=====
  69A 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
  80Then in monitor it's OK to execute next commands:
  81device_add pcie-pci-bridge,id=br3,bus=rp3 \
  82device_add e1000,bus=br2,addr=1 \
  83device_add e1000,bus=br3,addr=1
  84
  85Here 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
  96Limitations
  97===========
  98The PCIE-PCI bridge can be hot-plugged only into pcie-root-port that
  99has proper 'bus-reserve' property value to provide secondary bus for the
 100hot-plugged bridge.
 101
 102Windows 7 and older versions don't support hot-plug devices into the PCIE-PCI bridge.
 103To enable device hot-plug into the bridge on Linux there're 3 ways:
 1041) Build shpchp module with this patch http://www.spinics.net/lists/linux-pci/msg63052.html
 1052) Use kernel 4.14+ where the patch mentioned above is already merged.
 1063) 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
 110Implementation
 111==============
 112The PCIE-PCI bridge is based on PCI-PCI bridge, but also accumulates PCI Express
 113features as a PCI Express device.
 114
 115