Documentation/PCI/acpi-info.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ========================================
   4 ACPI considerations for PCI host bridges
   5 ========================================
   6
   7 The general rule is that the ACPI namespace should describe everything the
   8 OS might use unless there's another way for the OS to find it [1, 2].
   9
  10 For example, there's no standard hardware mechanism for enumerating PCI
  11 host bridges, so the ACPI namespace must describe each host bridge, the
  12 method for accessing PCI config space below it, the address space windows
  13 the host bridge forwards to PCI (using _CRS), and the routing of legacy
  14 INTx interrupts (using _PRT).
  15
  16 PCI devices, which are below the host bridge, generally do not need to be
  17 described via ACPI.  The OS can discover them via the standard PCI
  18 enumeration mechanism, using config accesses to discover and identify
  19 devices and read and size their BARs.  However, ACPI may describe PCI
  20 devices if it provides power management or hotplug functionality for them
  21 or if the device has INTx interrupts connected by platform interrupt
  22 controllers and a _PRT is needed to describe those connections.
  23
  24 ACPI resource description is done via _CRS objects of devices in the ACPI
  25 namespace [2].   The _CRS is like a generalized PCI BAR: the OS can read
  26 _CRS and figure out what resource is being consumed even if it doesn't have
  27 a driver for the device [3].  That's important because it means an old OS
  28 can work correctly even on a system with new devices unknown to the OS.
  29 The new devices might not do anything, but the OS can at least make sure no
  30 resources conflict with them.
  31
  32 Static tables like MCFG, HPET, ECDT, etc., are *not* mechanisms for
  33 reserving address space.  The static tables are for things the OS needs to
  34 know early in boot, before it can parse the ACPI namespace.  If a new table
  35 is defined, an old OS needs to operate correctly even though it ignores the
  36 table.  _CRS allows that because it is generic and understood by the old
  37 OS; a static table does not.
  38
  39 If the OS is expected to manage a non-discoverable device described via
  40 ACPI, that device will have a specific _HID/_CID that tells the OS what
  41 driver to bind to it, and the _CRS tells the OS and the driver where the
  42 device's registers are.
  43
  44 PCI host bridges are PNP0A03 or PNP0A08 devices.  Their _CRS should
  45 describe all the address space they consume.  This includes all the windows
  46 they forward down to the PCI bus, as well as registers of the host bridge
  47 itself that are not forwarded to PCI.  The host bridge registers include
  48 things like secondary/subordinate bus registers that determine the bus
  49 range below the bridge, window registers that describe the apertures, etc.
  50 These are all device-specific, non-architected things, so the only way a
  51 PNP0A03/PNP0A08 driver can manage them is via _PRS/_CRS/_SRS, which contain
  52 the device-specific details.  The host bridge registers also include ECAM
  53 space, since it is consumed by the host bridge.
  54
  55 ACPI defines a Consumer/Producer bit to distinguish the bridge registers
  56 ("Consumer") from the bridge apertures ("Producer") [4, 5], but early
  57 BIOSes didn't use that bit correctly.  The result is that the current ACPI
  58 spec defines Consumer/Producer only for the Extended Address Space
  59 descriptors; the bit should be ignored in the older QWord/DWord/Word
  60 Address Space descriptors.  Consequently, OSes have to assume all
  61 QWord/DWord/Word descriptors are windows.
  62
  63 Prior to the addition of Extended Address Space descriptors, the failure of
  64 Consumer/Producer meant there was no way to describe bridge registers in
  65 the PNP0A03/PNP0A08 device itself.  The workaround was to describe the
  66 bridge registers (including ECAM space) in PNP0C02 catch-all devices [6].
  67 With the exception of ECAM, the bridge register space is device-specific
  68 anyway, so the generic PNP0A03/PNP0A08 driver (pci_root.c) has no need to
  69 know about it.
  70
  71 New architectures should be able to use "Consumer" Extended Address Space
  72 descriptors in the PNP0A03 device for bridge registers, including ECAM,
  73 although a strict interpretation of [6] might prohibit this.  Old x86 and
  74 ia64 kernels assume all address space descriptors, including "Consumer"
  75 Extended Address Space ones, are windows, so it would not be safe to
  76 describe bridge registers this way on those architectures.
  77
  78 PNP0C02 "motherboard" devices are basically a catch-all.  There's no
  79 programming model for them other than "don't use these resources for
  80 anything else."  So a PNP0C02 _CRS should claim any address space that is
  81 (1) not claimed by _CRS under any other device object in the ACPI namespace
  82 and (2) should not be assigned by the OS to something else.
  83
  84 The PCIe spec requires the Enhanced Configuration Access Method (ECAM)
  85 unless there's a standard firmware interface for config access, e.g., the
  86 ia64 SAL interface [7].  A host bridge consumes ECAM memory address space
  87 and converts memory accesses into PCI configuration accesses.  The spec
  88 defines the ECAM address space layout and functionality; only the base of
  89 the address space is device-specific.  An ACPI OS learns the base address
  90 from either the static MCFG table or a _CBA method in the PNP0A03 device.
  91
  92 The MCFG table must describe the ECAM space of non-hot pluggable host
  93 bridges [8].  Since MCFG is a static table and can't be updated by hotplug,
  94 a _CBA method in the PNP0A03 device describes the ECAM space of a
  95 hot-pluggable host bridge [9].  Note that for both MCFG and _CBA, the base
  96 address always corresponds to bus 0, even if the bus range below the bridge
  97 (which is reported via _CRS) doesn't start at 0.
  98
  99
 100 [1] ACPI 6.2, sec 6.1:
 101     For any device that is on a non-enumerable type of bus (for example, an
 102     ISA bus), OSPM enumerates the devices' identifier(s) and the ACPI
 103     system firmware must supply an _HID object ... for each device to
 104     enable OSPM to do that.
 105
 106 [2] ACPI 6.2, sec 3.7:
 107     The OS enumerates motherboard devices simply by reading through the
 108     ACPI Namespace looking for devices with hardware IDs.
 109
 110     Each device enumerated by ACPI includes ACPI-defined objects in the
 111     ACPI Namespace that report the hardware resources the device could
 112     occupy [_PRS], an object that reports the resources that are currently
 113     used by the device [_CRS], and objects for configuring those resources
 114     [_SRS].  The information is used by the Plug and Play OS (OSPM) to
 115     configure the devices.
 116
 117 [3] ACPI 6.2, sec 6.2:
 118     OSPM uses device configuration objects to configure hardware resources
 119     for devices enumerated via ACPI.  Device configuration objects provide
 120     information about current and possible resource requirements, the
 121     relationship between shared resources, and methods for configuring
 122     hardware resources.
 123
 124     When OSPM enumerates a device, it calls _PRS to determine the resource
 125     requirements of the device.  It may also call _CRS to find the current
 126     resource settings for the device.  Using this information, the Plug and
 127     Play system determines what resources the device should consume and
 128     sets those resources by calling the device’s _SRS control method.
 129
 130     In ACPI, devices can consume resources (for example, legacy keyboards),
 131     provide resources (for example, a proprietary PCI bridge), or do both.
 132     Unless otherwise specified, resources for a device are assumed to be
 133     taken from the nearest matching resource above the device in the device
 134     hierarchy.
 135
 136 [4] ACPI 6.2, sec 6.4.3.5.1, 2, 3, 4:
 137     QWord/DWord/Word Address Space Descriptor (.1, .2, .3)
 138       General Flags: Bit [0] Ignored
 139
 140     Extended Address Space Descriptor (.4)
 141       General Flags: Bit [0] Consumer/Producer:
 142
 143         * 1 – This device consumes this resource
 144         * 0 – This device produces and consumes this resource
 145
 146 [5] ACPI 6.2, sec 19.6.43:
 147     ResourceUsage specifies whether the Memory range is consumed by
 148     this device (ResourceConsumer) or passed on to child devices
 149     (ResourceProducer).  If nothing is specified, then
 150     ResourceConsumer is assumed.
 151
 152 [6] PCI Firmware 3.2, sec 4.1.2:
 153     If the operating system does not natively comprehend reserving the
 154     MMCFG region, the MMCFG region must be reserved by firmware.  The
 155     address range reported in the MCFG table or by _CBA method (see Section
 156     4.1.3) must be reserved by declaring a motherboard resource.  For most
 157     systems, the motherboard resource would appear at the root of the ACPI
 158     namespace (under \_SB) in a node with a _HID of EISAID (PNP0C02), and
 159     the resources in this case should not be claimed in the root PCI bus’s
 160     _CRS.  The resources can optionally be returned in Int15 E820 or
 161     EFIGetMemoryMap as reserved memory but must always be reported through
 162     ACPI as a motherboard resource.
 163
 164 [7] PCI Express 4.0, sec 7.2.2:
 165     For systems that are PC-compatible, or that do not implement a
 166     processor-architecture-specific firmware interface standard that allows
 167     access to the Configuration Space, the ECAM is required as defined in
 168     this section.
 169
 170 [8] PCI Firmware 3.2, sec 4.1.2:
 171     The MCFG table is an ACPI table that is used to communicate the base
 172     addresses corresponding to the non-hot removable PCI Segment Groups
 173     range within a PCI Segment Group available to the operating system at
 174     boot. This is required for the PC-compatible systems.
 175
 176     The MCFG table is only used to communicate the base addresses
 177     corresponding to the PCI Segment Groups available to the system at
 178     boot.
 179
 180 [9] PCI Firmware 3.2, sec 4.1.3:
 181     The _CBA (Memory mapped Configuration Base Address) control method is
 182     an optional ACPI object that returns the 64-bit memory mapped
 183     configuration base address for the hot plug capable host bridge. The
 184     base address returned by _CBA is processor-relative address. The _CBA
 185     control method evaluates to an Integer.
 186
 187     This control method appears under a host bridge object. When the _CBA
 188     method appears under an active host bridge object, the operating system
 189     evaluates this structure to identify the memory mapped configuration
 190     base address corresponding to the PCI Segment Group for the bus number
 191     range specified in _CRS method. An ACPI name space object that contains
 192     the _CBA method must also contain a corresponding _SEG method.