Commit | Line | Data |
---|---|---|
c76911bc LZ |
1 | ACPI Device Tree - Representation of ACPI Namespace |
2 | ||
3 | Copyright (C) 2013, Intel Corporation | |
4 | Author: Lv Zheng <lv.zheng@intel.com> | |
5 | ||
6 | ||
7 | Abstract: | |
8 | ||
9 | The Linux ACPI subsystem converts ACPI namespace objects into a Linux | |
10 | device tree under the /sys/devices/LNXSYSTEM:00 and updates it upon | |
11 | receiving ACPI hotplug notification events. For each device object in this | |
12 | hierarchy there is a corresponding symbolic link in the | |
13 | /sys/bus/acpi/devices. | |
14 | This document illustrates the structure of the ACPI device tree. | |
15 | ||
16 | ||
17 | Credit: | |
18 | ||
19 | Thanks for the help from Zhang Rui <rui.zhang@intel.com> and Rafael J. | |
20 | Wysocki <rafael.j.wysocki@intel.com>. | |
21 | ||
22 | ||
23 | 1. ACPI Definition Blocks | |
24 | ||
25 | The ACPI firmware sets up RSDP (Root System Description Pointer) in the | |
26 | system memory address space pointing to the XSDT (Extended System | |
27 | Description Table). The XSDT always points to the FADT (Fixed ACPI | |
28 | Description Table) using its first entry, the data within the FADT | |
29 | includes various fixed-length entries that describe fixed ACPI features | |
30 | of the hardware. The FADT contains a pointer to the DSDT | |
31 | (Differentiated System Descripition Table). The XSDT also contains | |
32 | entries pointing to possibly multiple SSDTs (Secondary System | |
33 | Description Table). | |
34 | ||
35 | The DSDT and SSDT data is organized in data structures called definition | |
36 | blocks that contain definitions of various objects, including ACPI | |
37 | control methods, encoded in AML (ACPI Machine Language). The data block | |
38 | of the DSDT along with the contents of SSDTs represents a hierarchical | |
39 | data structure called the ACPI namespace whose topology reflects the | |
40 | structure of the underlying hardware platform. | |
41 | ||
42 | The relationships between ACPI System Definition Tables described above | |
43 | are illustrated in the following diagram. | |
44 | ||
45 | +---------+ +-------+ +--------+ +------------------------+ | |
46 | | RSDP | +->| XSDT | +->| FADT | | +-------------------+ | | |
47 | +---------+ | +-------+ | +--------+ +-|->| DSDT | | | |
48 | | Pointer | | | Entry |-+ | ...... | | | +-------------------+ | | |
49 | +---------+ | +-------+ | X_DSDT |--+ | | Definition Blocks | | | |
50 | | Pointer |-+ | ..... | | ...... | | +-------------------+ | | |
51 | +---------+ +-------+ +--------+ | +-------------------+ | | |
52 | | Entry |------------------|->| SSDT | | | |
53 | +- - - -+ | +-------------------| | | |
54 | | Entry | - - - - - - - -+ | | Definition Blocks | | | |
55 | +- - - -+ | | +-------------------+ | | |
56 | | | +- - - - - - - - - -+ | | |
57 | +-|->| SSDT | | | |
58 | | +-------------------+ | | |
59 | | | Definition Blocks | | | |
60 | | +- - - - - - - - - -+ | | |
61 | +------------------------+ | |
62 | | | |
63 | OSPM Loading | | |
64 | \|/ | |
65 | +----------------+ | |
66 | | ACPI Namespace | | |
67 | +----------------+ | |
68 | ||
69 | Figure 1. ACPI Definition Blocks | |
70 | ||
71 | NOTE: RSDP can also contain a pointer to the RSDT (Root System | |
72 | Description Table). Platforms provide RSDT to enable | |
73 | compatibility with ACPI 1.0 operating systems. The OS is expected | |
74 | to use XSDT, if present. | |
75 | ||
76 | ||
77 | 2. Example ACPI Namespace | |
78 | ||
79 | All definition blocks are loaded into a single namespace. The namespace | |
80 | is a hierarchy of objects identified by names and paths. | |
81 | The following naming conventions apply to object names in the ACPI | |
82 | namespace: | |
83 | 1. All names are 32 bits long. | |
84 | 2. The first byte of a name must be one of 'A' - 'Z', '_'. | |
85 | 3. Each of the remaining bytes of a name must be one of 'A' - 'Z', '0' | |
86 | - '9', '_'. | |
87 | 4. Names starting with '_' are reserved by the ACPI specification. | |
88 | 5. The '\' symbol represents the root of the namespace (i.e. names | |
89 | prepended with '\' are relative to the namespace root). | |
90 | 6. The '^' symbol represents the parent of the current namespace node | |
91 | (i.e. names prepended with '^' are relative to the parent of the | |
92 | current namespace node). | |
93 | ||
94 | The figure below shows an example ACPI namespace. | |
95 | ||
96 | +------+ | |
97 | | \ | Root | |
98 | +------+ | |
99 | | | |
100 | | +------+ | |
101 | +-| _PR | Scope(_PR): the processor namespace | |
102 | | +------+ | |
103 | | | | |
104 | | | +------+ | |
105 | | +-| CPU0 | Processor(CPU0): the first processor | |
106 | | +------+ | |
107 | | | |
108 | | +------+ | |
109 | +-| _SB | Scope(_SB): the system bus namespace | |
110 | | +------+ | |
111 | | | | |
112 | | | +------+ | |
113 | | +-| LID0 | Device(LID0); the lid device | |
114 | | | +------+ | |
115 | | | | | |
116 | | | | +------+ | |
117 | | | +-| _HID | Name(_HID, "PNP0C0D"): the hardware ID | |
118 | | | | +------+ | |
119 | | | | | |
120 | | | | +------+ | |
121 | | | +-| _STA | Method(_STA): the status control method | |
122 | | | +------+ | |
123 | | | | |
124 | | | +------+ | |
125 | | +-| PCI0 | Device(PCI0); the PCI root bridge | |
126 | | +------+ | |
127 | | | | |
128 | | | +------+ | |
129 | | +-| _HID | Name(_HID, "PNP0A08"): the hardware ID | |
130 | | | +------+ | |
131 | | | | |
132 | | | +------+ | |
133 | | +-| _CID | Name(_CID, "PNP0A03"): the compatible ID | |
134 | | | +------+ | |
135 | | | | |
136 | | | +------+ | |
137 | | +-| RP03 | Scope(RP03): the PCI0 power scope | |
138 | | | +------+ | |
139 | | | | | |
140 | | | | +------+ | |
141 | | | +-| PXP3 | PowerResource(PXP3): the PCI0 power resource | |
142 | | | +------+ | |
143 | | | | |
144 | | | +------+ | |
145 | | +-| GFX0 | Device(GFX0): the graphics adapter | |
146 | | +------+ | |
147 | | | | |
148 | | | +------+ | |
149 | | +-| _ADR | Name(_ADR, 0x00020000): the PCI bus address | |
150 | | | +------+ | |
151 | | | | |
152 | | | +------+ | |
153 | | +-| DD01 | Device(DD01): the LCD output device | |
154 | | +------+ | |
155 | | | | |
156 | | | +------+ | |
157 | | +-| _BCL | Method(_BCL): the backlight control method | |
158 | | +------+ | |
159 | | | |
160 | | +------+ | |
161 | +-| _TZ | Scope(_TZ): the thermal zone namespace | |
162 | | +------+ | |
163 | | | | |
164 | | | +------+ | |
165 | | +-| FN00 | PowerResource(FN00): the FAN0 power resource | |
166 | | | +------+ | |
167 | | | | |
168 | | | +------+ | |
169 | | +-| FAN0 | Device(FAN0): the FAN0 cooling device | |
170 | | | +------+ | |
171 | | | | | |
172 | | | | +------+ | |
173 | | | +-| _HID | Name(_HID, "PNP0A0B"): the hardware ID | |
174 | | | +------+ | |
175 | | | | |
176 | | | +------+ | |
177 | | +-| TZ00 | ThermalZone(TZ00); the FAN thermal zone | |
178 | | +------+ | |
179 | | | |
180 | | +------+ | |
181 | +-| _GPE | Scope(_GPE): the GPE namespace | |
182 | +------+ | |
183 | ||
184 | Figure 2. Example ACPI Namespace | |
185 | ||
186 | ||
187 | 3. Linux ACPI Device Objects | |
188 | ||
189 | The Linux kernel's core ACPI subsystem creates struct acpi_device | |
190 | objects for ACPI namespace objects representing devices, power resources | |
191 | processors, thermal zones. Those objects are exported to user space via | |
192 | sysfs as directories in the subtree under /sys/devices/LNXSYSTM:00. The | |
193 | format of their names is <bus_id:instance>, where 'bus_id' refers to the | |
194 | ACPI namespace representation of the given object and 'instance' is used | |
195 | for distinguishing different object of the same 'bus_id' (it is | |
196 | two-digit decimal representation of an unsigned integer). | |
197 | ||
198 | The value of 'bus_id' depends on the type of the object whose name it is | |
199 | part of as listed in the table below. | |
200 | ||
201 | +---+-----------------+-------+----------+ | |
202 | | | Object/Feature | Table | bus_id | | |
203 | +---+-----------------+-------+----------+ | |
204 | | N | Root | xSDT | LNXSYSTM | | |
205 | +---+-----------------+-------+----------+ | |
206 | | N | Device | xSDT | _HID | | |
207 | +---+-----------------+-------+----------+ | |
208 | | N | Processor | xSDT | LNXCPU | | |
209 | +---+-----------------+-------+----------+ | |
210 | | N | ThermalZone | xSDT | LNXTHERM | | |
211 | +---+-----------------+-------+----------+ | |
212 | | N | PowerResource | xSDT | LNXPOWER | | |
213 | +---+-----------------+-------+----------+ | |
214 | | N | Other Devices | xSDT | device | | |
215 | +---+-----------------+-------+----------+ | |
216 | | F | PWR_BUTTON | FADT | LNXPWRBN | | |
217 | +---+-----------------+-------+----------+ | |
218 | | F | SLP_BUTTON | FADT | LNXSLPBN | | |
219 | +---+-----------------+-------+----------+ | |
220 | | M | Video Extension | xSDT | LNXVIDEO | | |
221 | +---+-----------------+-------+----------+ | |
222 | | M | ATA Controller | xSDT | LNXIOBAY | | |
223 | +---+-----------------+-------+----------+ | |
224 | | M | Docking Station | xSDT | LNXDOCK | | |
225 | +---+-----------------+-------+----------+ | |
226 | ||
227 | Table 1. ACPI Namespace Objects Mapping | |
228 | ||
229 | The following rules apply when creating struct acpi_device objects on | |
230 | the basis of the contents of ACPI System Description Tables (as | |
231 | indicated by the letter in the first column and the notation in the | |
232 | second column of the table above): | |
233 | N: | |
234 | The object's source is an ACPI namespace node (as indicated by the | |
235 | named object's type in the second column). In that case the object's | |
236 | directory in sysfs will contain the 'path' attribute whose value is | |
237 | the full path to the node from the namespace root. | |
c76911bc LZ |
238 | F: |
239 | The struct acpi_device object is created for a fixed hardware | |
240 | feature (as indicated by the fixed feature flag's name in the second | |
241 | column), so its sysfs directory will not contain the 'path' | |
242 | attribute. | |
243 | M: | |
244 | The struct acpi_device object is created for an ACPI namespace node | |
245 | with specific control methods (as indicated by the ACPI defined | |
246 | device's type in the second column). The 'path' attribute containing | |
247 | its namespace path will be present in its sysfs directory. For | |
248 | example, if the _BCL method is present for an ACPI namespace node, a | |
249 | struct acpi_device object with LNXVIDEO 'bus_id' will be created for | |
250 | it. | |
251 | ||
252 | The third column of the above table indicates which ACPI System | |
253 | Description Tables contain information used for the creation of the | |
254 | struct acpi_device objects represented by the given row (xSDT means DSDT | |
255 | or SSDT). | |
256 | ||
257 | The forth column of the above table indicates the 'bus_id' generation | |
258 | rule of the struct acpi_device object: | |
259 | _HID: | |
260 | _HID in the last column of the table means that the object's bus_id | |
261 | is derived from the _HID/_CID identification objects present under | |
262 | the corresponding ACPI namespace node. The object's sysfs directory | |
263 | will then contain the 'hid' and 'modalias' attributes that can be | |
264 | used to retrieve the _HID and _CIDs of that object. | |
265 | LNXxxxxx: | |
266 | The 'modalias' attribute is also present for struct acpi_device | |
267 | objects having bus_id of the "LNXxxxxx" form (pseudo devices), in | |
268 | which cases it contains the bus_id string itself. | |
269 | device: | |
270 | 'device' in the last column of the table indicates that the object's | |
271 | bus_id cannot be determined from _HID/_CID of the corresponding | |
272 | ACPI namespace node, although that object represents a device (for | |
273 | example, it may be a PCI device with _ADR defined and without _HID | |
274 | or _CID). In that case the string 'device' will be used as the | |
275 | object's bus_id. | |
276 | ||
277 | ||
278 | 4. Linux ACPI Physical Device Glue | |
279 | ||
280 | ACPI device (i.e. struct acpi_device) objects may be linked to other | |
281 | objects in the Linux' device hierarchy that represent "physical" devices | |
282 | (for example, devices on the PCI bus). If that happens, it means that | |
283 | the ACPI device object is a "companion" of a device otherwise | |
284 | represented in a different way and is used (1) to provide configuration | |
285 | information on that device which cannot be obtained by other means and | |
286 | (2) to do specific things to the device with the help of its ACPI | |
287 | control methods. One ACPI device object may be linked this way to | |
288 | multiple "physical" devices. | |
289 | ||
290 | If an ACPI device object is linked to a "physical" device, its sysfs | |
291 | directory contains the "physical_node" symbolic link to the sysfs | |
292 | directory of the target device object. In turn, the target device's | |
293 | sysfs directory will then contain the "firmware_node" symbolic link to | |
294 | the sysfs directory of the companion ACPI device object. | |
295 | The linking mechanism relies on device identification provided by the | |
296 | ACPI namespace. For example, if there's an ACPI namespace object | |
297 | representing a PCI device (i.e. a device object under an ACPI namespace | |
298 | object representing a PCI bridge) whose _ADR returns 0x00020000 and the | |
299 | bus number of the parent PCI bridge is 0, the sysfs directory | |
300 | representing the struct acpi_device object created for that ACPI | |
301 | namespace object will contain the 'physical_node' symbolic link to the | |
302 | /sys/devices/pci0000:00/0000:00:02:0/ sysfs directory of the | |
303 | corresponding PCI device. | |
304 | ||
305 | The linking mechanism is generally bus-specific. The core of its | |
306 | implementation is located in the drivers/acpi/glue.c file, but there are | |
307 | complementary parts depending on the bus types in question located | |
308 | elsewhere. For example, the PCI-specific part of it is located in | |
309 | drivers/pci/pci-acpi.c. | |
310 | ||
311 | ||
312 | 5. Example Linux ACPI Device Tree | |
313 | ||
314 | The sysfs hierarchy of struct acpi_device objects corresponding to the | |
315 | example ACPI namespace illustrated in Figure 2 with the addition of | |
316 | fixed PWR_BUTTON/SLP_BUTTON devices is shown below. | |
317 | ||
318 | +--------------+---+-----------------+ | |
319 | | LNXSYSTEM:00 | \ | acpi:LNXSYSTEM: | | |
320 | +--------------+---+-----------------+ | |
321 | | | |
322 | | +-------------+-----+----------------+ | |
323 | +-| LNXPWRBN:00 | N/A | acpi:LNXPWRBN: | | |
324 | | +-------------+-----+----------------+ | |
325 | | | |
326 | | +-------------+-----+----------------+ | |
327 | +-| LNXSLPBN:00 | N/A | acpi:LNXSLPBN: | | |
328 | | +-------------+-----+----------------+ | |
329 | | | |
330 | | +-----------+------------+--------------+ | |
331 | +-| LNXCPU:00 | \_PR_.CPU0 | acpi:LNXCPU: | | |
332 | | +-----------+------------+--------------+ | |
333 | | | |
334 | | +-------------+-------+----------------+ | |
335 | +-| LNXSYBUS:00 | \_SB_ | acpi:LNXSYBUS: | | |
336 | | +-------------+-------+----------------+ | |
337 | | | | |
338 | | | +- - - - - - - +- - - - - - +- - - - - - - -+ | |
202317a5 | 339 | | +-| PNP0C0D:00 | \_SB_.LID0 | acpi:PNP0C0D: | |
c76911bc LZ |
340 | | | +- - - - - - - +- - - - - - +- - - - - - - -+ |
341 | | | | |
342 | | | +------------+------------+-----------------------+ | |
343 | | +-| PNP0A08:00 | \_SB_.PCI0 | acpi:PNP0A08:PNP0A03: | | |
344 | | +------------+------------+-----------------------+ | |
345 | | | | |
346 | | | +-----------+-----------------+-----+ | |
347 | | +-| device:00 | \_SB_.PCI0.RP03 | N/A | | |
348 | | | +-----------+-----------------+-----+ | |
349 | | | | | |
350 | | | | +-------------+----------------------+----------------+ | |
351 | | | +-| LNXPOWER:00 | \_SB_.PCI0.RP03.PXP3 | acpi:LNXPOWER: | | |
352 | | | +-------------+----------------------+----------------+ | |
353 | | | | |
354 | | | +-------------+-----------------+----------------+ | |
355 | | +-| LNXVIDEO:00 | \_SB_.PCI0.GFX0 | acpi:LNXVIDEO: | | |
356 | | +-------------+-----------------+----------------+ | |
357 | | | | |
358 | | | +-----------+-----------------+-----+ | |
359 | | +-| device:01 | \_SB_.PCI0.DD01 | N/A | | |
360 | | +-----------+-----------------+-----+ | |
361 | | | |
362 | | +-------------+-------+----------------+ | |
363 | +-| LNXSYBUS:01 | \_TZ_ | acpi:LNXSYBUS: | | |
364 | +-------------+-------+----------------+ | |
365 | | | |
366 | | +-------------+------------+----------------+ | |
367 | +-| LNXPOWER:0a | \_TZ_.FN00 | acpi:LNXPOWER: | | |
368 | | +-------------+------------+----------------+ | |
369 | | | |
370 | | +------------+------------+---------------+ | |
371 | +-| PNP0C0B:00 | \_TZ_.FAN0 | acpi:PNP0C0B: | | |
372 | | +------------+------------+---------------+ | |
373 | | | |
374 | | +-------------+------------+----------------+ | |
375 | +-| LNXTHERM:00 | \_TZ_.TZ00 | acpi:LNXTHERM: | | |
376 | +-------------+------------+----------------+ | |
377 | ||
378 | Figure 3. Example Linux ACPI Device Tree | |
379 | ||
380 | NOTE: Each node is represented as "object/path/modalias", where: | |
381 | 1. 'object' is the name of the object's directory in sysfs. | |
382 | 2. 'path' is the ACPI namespace path of the corresponding | |
383 | ACPI namespace object, as returned by the object's 'path' | |
384 | sysfs attribute. | |
385 | 3. 'modalias' is the value of the object's 'modalias' sysfs | |
386 | attribute (as described earlier in this document). | |
387 | NOTE: N/A indicates the device object does not have the 'path' or the | |
388 | 'modalias' attribute. |