1 .. SPDX-License-Identifier: GPL-2.0
2 .. include:: <isonum.txt>
3
4 ==============================================
5 ACPI Device Tree - Representation of ACPI Name
6 ==============================================
7
8 :Copyright: |copy| 2013, Intel Corporation
9
10 :Author: Lv Zheng <lv.zheng@intel.com>
11
12 :Credit: Thanks for the help from Zhang Rui <
13 Rafael J.Wysocki <rafael.j.wysocki@i
14
15 Abstract
16 ========
17 The Linux ACPI subsystem converts ACPI namespa
18 device tree under the /sys/devices/LNXSYSTM:00
19 receiving ACPI hotplug notification events. F
20 in this hierarchy there is a corresponding sym
21 /sys/bus/acpi/devices.
22
23 This document illustrates the structure of the
24
25 ACPI Definition Blocks
26 ======================
27
28 The ACPI firmware sets up RSDP (Root System De
29 system memory address space pointing to the XS
30 Description Table). The XSDT always points to
31 Description Table) using its first entry, the
32 includes various fixed-length entries that des
33 of the hardware. The FADT contains a pointer
34 (Differentiated System Description Table). Th
35 entries pointing to possibly multiple SSDTs (S
36 Description Table).
37
38 The DSDT and SSDT data is organized in data st
39 blocks that contain definitions of various obj
40 control methods, encoded in AML (ACPI Machine
41 of the DSDT along with the contents of SSDTs r
42 data structure called the ACPI namespace whose
43 structure of the underlying hardware platform.
44
45 The relationships between ACPI System Definiti
46 are illustrated in the following diagram::
47
48 +---------+ +-------+ +--------+ +
49 | RSDP | +->| XSDT | +->| FADT | |
50 +---------+ | +-------+ | +--------+ +-|
51 | Pointer | | | Entry |-+ | ...... | | |
52 +---------+ | +-------+ | X_DSDT |--+ |
53 | Pointer |-+ | ..... | | ...... | |
54 +---------+ +-------+ +--------+ |
55 | Entry |------------------|
56 +- - - -+ |
57 | Entry | - - - - - - - -+ |
58 +- - - -+ | |
59 | |
60 +-|
61 |
62 |
63 |
64 +
65
66 O
67
68
69
70
71
72 Figure 1. ACPI Definition Bl
73
74 .. note:: RSDP can also contain a pointer to t
75 Description Table). Platforms provide RSDT
76 compatibility with ACPI 1.0 operating syste
77 to use XSDT, if present.
78
79
80 Example ACPI Namespace
81 ======================
82
83 All definition blocks are loaded into a single
84 is a hierarchy of objects identified by names
85 The following naming conventions apply to obje
86 namespace:
87
88 1. All names are 32 bits long.
89 2. The first byte of a name must be one of
90 3. Each of the remaining bytes of a name mu
91 - '9', '_'.
92 4. Names starting with '_' are reserved by
93 5. The '\' symbol represents the root of th
94 prepended with '\' are relative to the n
95 6. The '^' symbol represents the parent of
96 (i.e. names prepended with '^' are relat
97 current namespace node).
98
99 The figure below shows an example ACPI namespa
100
101 +------+
102 | \ | Root
103 +------+
104 |
105 | +------+
106 +-| _PR | Scope(_PR): th
107 | +------+
108 | |
109 | | +------+
110 | +-| CPU0 | Processor(CPU0
111 | +------+
112 |
113 | +------+
114 +-| _SB | Scope(_SB): th
115 | +------+
116 | |
117 | | +------+
118 | +-| LID0 | Device(LID0);
119 | | +------+
120 | | |
121 | | | +------+
122 | | +-| _HID | Name(_HID, "PN
123 | | | +------+
124 | | |
125 | | | +------+
126 | | +-| _STA | Method(_STA):
127 | | +------+
128 | |
129 | | +------+
130 | +-| PCI0 | Device(PCI0);
131 | +------+
132 | |
133 | | +------+
134 | +-| _HID | Name(_HID, "PN
135 | | +------+
136 | |
137 | | +------+
138 | +-| _CID | Name(_CID, "PN
139 | | +------+
140 | |
141 | | +------+
142 | +-| RP03 | Scope(RP03): t
143 | | +------+
144 | | |
145 | | | +------+
146 | | +-| PXP3 | PowerResource(
147 | | +------+
148 | |
149 | | +------+
150 | +-| GFX0 | Device(GFX0):
151 | +------+
152 | |
153 | | +------+
154 | +-| _ADR | Name(_ADR, 0x0
155 | | +------+
156 | |
157 | | +------+
158 | +-| DD01 | Device(DD01):
159 | +------+
160 | |
161 | | +------+
162 | +-| _BCL | Method(_BCL):
163 | +------+
164 |
165 | +------+
166 +-| _TZ | Scope(_TZ): th
167 | +------+
168 | |
169 | | +------+
170 | +-| FN00 | PowerResource(
171 | | +------+
172 | |
173 | | +------+
174 | +-| FAN0 | Device(FAN0):
175 | | +------+
176 | | |
177 | | | +------+
178 | | +-| _HID | Name(_HID, "PN
179 | | +------+
180 | |
181 | | +------+
182 | +-| TZ00 | ThermalZone(TZ
183 | +------+
184 |
185 | +------+
186 +-| _GPE | Scope(_GPE): t
187 +------+
188
189 Figure 2. Example ACPI Na
190
191
192 Linux ACPI Device Objects
193 =========================
194
195 The Linux kernel's core ACPI subsystem creates
196 objects for ACPI namespace objects representin
197 processors, thermal zones. Those objects are
198 sysfs as directories in the subtree under /sys
199 format of their names is <bus_id:instance>, wh
200 ACPI namespace representation of the given obj
201 for distinguishing different object of the sam
202 two-digit decimal representation of an unsigne
203
204 The value of 'bus_id' depends on the type of t
205 part of as listed in the table below::
206
207 +---+-----------------+-------
208 | | Object/Feature | Table
209 +---+-----------------+-------
210 | N | Root | xSDT
211 +---+-----------------+-------
212 | N | Device | xSDT
213 +---+-----------------+-------
214 | N | Processor | xSDT
215 +---+-----------------+-------
216 | N | ThermalZone | xSDT
217 +---+-----------------+-------
218 | N | PowerResource | xSDT
219 +---+-----------------+-------
220 | N | Other Devices | xSDT
221 +---+-----------------+-------
222 | F | PWR_BUTTON | FADT
223 +---+-----------------+-------
224 | F | SLP_BUTTON | FADT
225 +---+-----------------+-------
226 | M | Video Extension | xSDT
227 +---+-----------------+-------
228 | M | ATA Controller | xSDT
229 +---+-----------------+-------
230 | M | Docking Station | xSDT
231 +---+-----------------+-------
232
233 Table 1. ACPI Namespace Objec
234
235 The following rules apply when creating struct
236 the basis of the contents of ACPI System Descr
237 indicated by the letter in the first column an
238 second column of the table above):
239
240 N:
241 The object's source is an ACPI namespace
242 named object's type in the second column
243 directory in sysfs will contain the 'pat
244 the full path to the node from the names
245 F:
246 The struct acpi_device object is created
247 feature (as indicated by the fixed featu
248 column), so its sysfs directory will not
249 attribute.
250 M:
251 The struct acpi_device object is created
252 with specific control methods (as indica
253 device's type in the second column). Th
254 its namespace path will be present in it
255 example, if the _BCL method is present f
256 struct acpi_device object with LNXVIDEO
257 it.
258
259 The third column of the above table indicates
260 Description Tables contain information used fo
261 struct acpi_device objects represented by the
262 or SSDT).
263
264 The fourth column of the above table indicates
265 rule of the struct acpi_device object:
266
267 _HID:
268 _HID in the last column of the table mea
269 is derived from the _HID/_CID identifica
270 the corresponding ACPI namespace node. T
271 will then contain the 'hid' and 'modalia
272 used to retrieve the _HID and _CIDs of t
273 LNXxxxxx:
274 The 'modalias' attribute is also present
275 objects having bus_id of the "LNXxxxxx"
276 which cases it contains the bus_id strin
277 device:
278 'device' in the last column of the table
279 bus_id cannot be determined from _HID/_C
280 ACPI namespace node, although that objec
281 example, it may be a PCI device with _AD
282 or _CID). In that case the string 'devi
283 object's bus_id.
284
285
286 Linux ACPI Physical Device Glue
287 ===============================
288
289 ACPI device (i.e. struct acpi_device) objects
290 objects in the Linux' device hierarchy that re
291 (for example, devices on the PCI bus). If tha
292 the ACPI device object is a "companion" of a d
293 represented in a different way and is used (1)
294 information on that device which cannot be obt
295 (2) to do specific things to the device with t
296 control methods. One ACPI device object may b
297 multiple "physical" devices.
298
299 If an ACPI device object is linked to a "physi
300 directory contains the "physical_node" symboli
301 directory of the target device object. In tur
302 sysfs directory will then contain the "firmwar
303 the sysfs directory of the companion ACPI devi
304 The linking mechanism relies on device identif
305 ACPI namespace. For example, if there's an AC
306 representing a PCI device (i.e. a device objec
307 object representing a PCI bridge) whose _ADR r
308 bus number of the parent PCI bridge is 0, the
309 representing the struct acpi_device object cre
310 namespace object will contain the 'physical_no
311 /sys/devices/pci0000:00/0000:00:02:0/ sysfs di
312 corresponding PCI device.
313
314 The linking mechanism is generally bus-specifi
315 implementation is located in the drivers/acpi/
316 complementary parts depending on the bus types
317 elsewhere. For example, the PCI-specific part
318 drivers/pci/pci-acpi.c.
319
320
321 Example Linux ACPI Device Tree
322 =================================
323
324 The sysfs hierarchy of struct acpi_device obje
325 example ACPI namespace illustrated in Figure 2
326 fixed PWR_BUTTON/SLP_BUTTON devices is shown b
327
328 +--------------+---+-----------------+
329 | LNXSYSTM:00 | \ | acpi:LNXSYSTM: |
330 +--------------+---+-----------------+
331 |
332 | +-------------+-----+----------------+
333 +-| LNXPWRBN:00 | N/A | acpi:LNXPWRBN: |
334 | +-------------+-----+----------------+
335 |
336 | +-------------+-----+----------------+
337 +-| LNXSLPBN:00 | N/A | acpi:LNXSLPBN: |
338 | +-------------+-----+----------------+
339 |
340 | +-----------+------------+-------------
341 +-| LNXCPU:00 | \_PR_.CPU0 | acpi:LNXCPU:
342 | +-----------+------------+-------------
343 |
344 | +-------------+-------+----------------
345 +-| LNXSYBUS:00 | \_SB_ | acpi:LNXSYBUS:
346 | +-------------+-------+----------------
347 | |
348 | | +- - - - - - - +- - - - - - +- - -
349 | +-| PNP0C0D:00 | \_SB_.LID0 | acpi:PN
350 | | +- - - - - - - +- - - - - - +- - -
351 | |
352 | | +------------+------------+--------
353 | +-| PNP0A08:00 | \_SB_.PCI0 | acpi:PN
354 | +------------+------------+--------
355 | |
356 | | +-----------+-----------------+
357 | +-| device:00 | \_SB_.PCI0.RP03 |
358 | | +-----------+-----------------+
359 | | |
360 | | | +-------------+------------
361 | | +-| LNXPOWER:00 | \_SB_.PCI0.
362 | | +-------------+------------
363 | |
364 | | +-------------+----------------
365 | +-| LNXVIDEO:00 | \_SB_.PCI0.GFX0
366 | +-------------+----------------
367 | |
368 | | +-----------+--------------
369 | +-| device:01 | \_SB_.PCI0.DD
370 | +-----------+--------------
371 |
372 | +-------------+-------+----------------
373 +-| LNXSYBUS:01 | \_TZ_ | acpi:LNXSYBUS:
374 +-------------+-------+----------------
375 |
376 | +-------------+------------+-------
377 +-| LNXPOWER:0a | \_TZ_.FN00 | acpi:L
378 | +-------------+------------+-------
379 |
380 | +------------+------------+--------
381 +-| PNP0C0B:00 | \_TZ_.FAN0 | acpi:PN
382 | +------------+------------+--------
383 |
384 | +-------------+------------+-------
385 +-| LNXTHERM:00 | \_TZ_.TZ00 | acpi:L
386 +-------------+------------+-------
387
388 Figure 3. Example Linux ACPI
389
390 .. note:: Each node is represented as "object/
391
392 1. 'object' is the name of the object's dir
393 2. 'path' is the ACPI namespace path of the
394 ACPI namespace object, as returned by th
395 sysfs attribute.
396 3. 'modalias' is the value of the object's
397 attribute (as described earlier in this
398
399 .. note:: N/A indicates the device object does
400 'modalias' attribute.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.