Commit | Line | Data |
---|---|---|
b66357f3 CD |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | ======================================== | |
4 | ACPI considerations for PCI host bridges | |
5 | ======================================== | |
39a212ad BH |
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) | |
b66357f3 | 138 | General Flags: Bit [0] Ignored |
39a212ad BH |
139 | |
140 | Extended Address Space Descriptor (.4) | |
b66357f3 CD |
141 | General Flags: Bit [0] Consumer/Producer: |
142 | ||
143 | * 1 – This device consumes this resource | |
144 | * 0 – This device produces and consumes this resource | |
39a212ad BH |
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. |