Orange Pi5 kernel

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