tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
ACPI: Add ACPI namespace documentation
ACPI is implemented as a subsystem in Linux, it creates a device tree by
mapping specific ACPI namespace objects
(Device/Processor/PowerResource/ThermalZone) into Linux device objects.
This patch adds documentation for the ACPI device tree.
Signed-off-by: Lv Zheng <lv.zheng@intel.com>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
authored by
Lv Zheng
and committed by
Rafael J. Wysocki
c76911bc
89ca78a0
+395
+395
Documentation/acpi/namespace.txt
+395
Documentation/acpi/namespace.txt
···
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.
238
+
struct acpi_device objects are created for the ACPI namespace nodes
239
+
whose _STA control methods return PRESENT or FUNCTIONING. The power
240
+
resource nodes or nodes without _STA are assumed to be both PRESENT
241
+
and FUNCTIONING.
242
+
F:
243
+
The struct acpi_device object is created for a fixed hardware
244
+
feature (as indicated by the fixed feature flag's name in the second
245
+
column), so its sysfs directory will not contain the 'path'
246
+
attribute.
247
+
M:
248
+
The struct acpi_device object is created for an ACPI namespace node
249
+
with specific control methods (as indicated by the ACPI defined
250
+
device's type in the second column). The 'path' attribute containing
251
+
its namespace path will be present in its sysfs directory. For
252
+
example, if the _BCL method is present for an ACPI namespace node, a
253
+
struct acpi_device object with LNXVIDEO 'bus_id' will be created for
254
+
it.
255
+
256
+
The third column of the above table indicates which ACPI System
257
+
Description Tables contain information used for the creation of the
258
+
struct acpi_device objects represented by the given row (xSDT means DSDT
259
+
or SSDT).
260
+
261
+
The forth column of the above table indicates the 'bus_id' generation
262
+
rule of the struct acpi_device object:
263
+
_HID:
264
+
_HID in the last column of the table means that the object's bus_id
265
+
is derived from the _HID/_CID identification objects present under
266
+
the corresponding ACPI namespace node. The object's sysfs directory
267
+
will then contain the 'hid' and 'modalias' attributes that can be
268
+
used to retrieve the _HID and _CIDs of that object.
269
+
LNXxxxxx:
270
+
The 'modalias' attribute is also present for struct acpi_device
271
+
objects having bus_id of the "LNXxxxxx" form (pseudo devices), in
272
+
which cases it contains the bus_id string itself.
273
+
device:
274
+
'device' in the last column of the table indicates that the object's
275
+
bus_id cannot be determined from _HID/_CID of the corresponding
276
+
ACPI namespace node, although that object represents a device (for
277
+
example, it may be a PCI device with _ADR defined and without _HID
278
+
or _CID). In that case the string 'device' will be used as the
279
+
object's bus_id.
280
+
281
+
282
+
4. Linux ACPI Physical Device Glue
283
+
284
+
ACPI device (i.e. struct acpi_device) objects may be linked to other
285
+
objects in the Linux' device hierarchy that represent "physical" devices
286
+
(for example, devices on the PCI bus). If that happens, it means that
287
+
the ACPI device object is a "companion" of a device otherwise
288
+
represented in a different way and is used (1) to provide configuration
289
+
information on that device which cannot be obtained by other means and
290
+
(2) to do specific things to the device with the help of its ACPI
291
+
control methods. One ACPI device object may be linked this way to
292
+
multiple "physical" devices.
293
+
294
+
If an ACPI device object is linked to a "physical" device, its sysfs
295
+
directory contains the "physical_node" symbolic link to the sysfs
296
+
directory of the target device object. In turn, the target device's
297
+
sysfs directory will then contain the "firmware_node" symbolic link to
298
+
the sysfs directory of the companion ACPI device object.
299
+
The linking mechanism relies on device identification provided by the
300
+
ACPI namespace. For example, if there's an ACPI namespace object
301
+
representing a PCI device (i.e. a device object under an ACPI namespace
302
+
object representing a PCI bridge) whose _ADR returns 0x00020000 and the
303
+
bus number of the parent PCI bridge is 0, the sysfs directory
304
+
representing the struct acpi_device object created for that ACPI
305
+
namespace object will contain the 'physical_node' symbolic link to the
306
+
/sys/devices/pci0000:00/0000:00:02:0/ sysfs directory of the
307
+
corresponding PCI device.
308
+
309
+
The linking mechanism is generally bus-specific. The core of its
310
+
implementation is located in the drivers/acpi/glue.c file, but there are
311
+
complementary parts depending on the bus types in question located
312
+
elsewhere. For example, the PCI-specific part of it is located in
313
+
drivers/pci/pci-acpi.c.
314
+
315
+
316
+
5. Example Linux ACPI Device Tree
317
+
318
+
The sysfs hierarchy of struct acpi_device objects corresponding to the
319
+
example ACPI namespace illustrated in Figure 2 with the addition of
320
+
fixed PWR_BUTTON/SLP_BUTTON devices is shown below.
321
+
322
+
+--------------+---+-----------------+
323
+
| LNXSYSTEM:00 | \ | acpi:LNXSYSTEM: |
324
+
+--------------+---+-----------------+
325
+
|
326
+
| +-------------+-----+----------------+
327
+
+-| LNXPWRBN:00 | N/A | acpi:LNXPWRBN: |
328
+
| +-------------+-----+----------------+
329
+
|
330
+
| +-------------+-----+----------------+
331
+
+-| LNXSLPBN:00 | N/A | acpi:LNXSLPBN: |
332
+
| +-------------+-----+----------------+
333
+
|
334
+
| +-----------+------------+--------------+
335
+
+-| LNXCPU:00 | \_PR_.CPU0 | acpi:LNXCPU: |
336
+
| +-----------+------------+--------------+
337
+
|
338
+
| +-------------+-------+----------------+
339
+
+-| LNXSYBUS:00 | \_SB_ | acpi:LNXSYBUS: |
340
+
| +-------------+-------+----------------+
341
+
| |
342
+
| | +- - - - - - - +- - - - - - +- - - - - - - -+
343
+
| +-| * PNP0C0D:00 | \_SB_.LID0 | acpi:PNP0C0D: |
344
+
| | +- - - - - - - +- - - - - - +- - - - - - - -+
345
+
| |
346
+
| | +------------+------------+-----------------------+
347
+
| +-| PNP0A08:00 | \_SB_.PCI0 | acpi:PNP0A08:PNP0A03: |
348
+
| +------------+------------+-----------------------+
349
+
| |
350
+
| | +-----------+-----------------+-----+
351
+
| +-| device:00 | \_SB_.PCI0.RP03 | N/A |
352
+
| | +-----------+-----------------+-----+
353
+
| | |
354
+
| | | +-------------+----------------------+----------------+
355
+
| | +-| LNXPOWER:00 | \_SB_.PCI0.RP03.PXP3 | acpi:LNXPOWER: |
356
+
| | +-------------+----------------------+----------------+
357
+
| |
358
+
| | +-------------+-----------------+----------------+
359
+
| +-| LNXVIDEO:00 | \_SB_.PCI0.GFX0 | acpi:LNXVIDEO: |
360
+
| +-------------+-----------------+----------------+
361
+
| |
362
+
| | +-----------+-----------------+-----+
363
+
| +-| device:01 | \_SB_.PCI0.DD01 | N/A |
364
+
| +-----------+-----------------+-----+
365
+
|
366
+
| +-------------+-------+----------------+
367
+
+-| LNXSYBUS:01 | \_TZ_ | acpi:LNXSYBUS: |
368
+
+-------------+-------+----------------+
369
+
|
370
+
| +-------------+------------+----------------+
371
+
+-| LNXPOWER:0a | \_TZ_.FN00 | acpi:LNXPOWER: |
372
+
| +-------------+------------+----------------+
373
+
|
374
+
| +------------+------------+---------------+
375
+
+-| PNP0C0B:00 | \_TZ_.FAN0 | acpi:PNP0C0B: |
376
+
| +------------+------------+---------------+
377
+
|
378
+
| +-------------+------------+----------------+
379
+
+-| LNXTHERM:00 | \_TZ_.TZ00 | acpi:LNXTHERM: |
380
+
+-------------+------------+----------------+
381
+
382
+
Figure 3. Example Linux ACPI Device Tree
383
+
384
+
NOTE: Each node is represented as "object/path/modalias", where:
385
+
1. 'object' is the name of the object's directory in sysfs.
386
+
2. 'path' is the ACPI namespace path of the corresponding
387
+
ACPI namespace object, as returned by the object's 'path'
388
+
sysfs attribute.
389
+
3. 'modalias' is the value of the object's 'modalias' sysfs
390
+
attribute (as described earlier in this document).
391
+
NOTE: N/A indicates the device object does not have the 'path' or the
392
+
'modalias' attribute.
393
+
NOTE: The PNP0C0D device listed above is highlighted (marked by "*")
394
+
to indicate it will be created only when its _STA methods return
395
+
PRESENT or FUNCTIONING.