1 .. SPDX-License-Identifier: GPL-2.0
2
3 =============================
4 ACPI Based Device Enumeration
5 =============================
6
7 ACPI 5 introduced a set of new resources (Uart
8 SpiSerialBus, GpioIo and GpioInt) which can be
9 devices behind serial bus controllers.
10
11 In addition we are starting to see peripherals
12 SoC/Chipset to appear only in ACPI namespace.
13 that are accessed through memory-mapped regist
14
15 In order to support this and re-use the existi
16 possible we decided to do following:
17
18 - Devices that have no bus connector resourc
19 platform devices.
20
21 - Devices behind real busses where there is
22 are represented as struct spi_device or st
23 that standard UARTs are not busses so ther
24 although some of them may be represented b
25
26 As both ACPI and Device Tree represent a tree
27 resources) this implementation follows the Dev
28 possible.
29
30 The ACPI implementation enumerates devices beh
31 I2C, and in some cases UART), creates the phys
32 to their ACPI handle in the ACPI namespace.
33
34 This means that when ACPI_HANDLE(dev) returns
35 enumerated from ACPI namespace. This handle ca
36 device-specific configuration. There is an exa
37
38 Platform bus support
39 ====================
40
41 Since we are using platform devices to represe
42 connected to any physical bus we only need to
43 for the device and add supported ACPI IDs. If
44 some other non-ACPI platform, the driver might
45 some minor changes.
46
47 Adding ACPI support for an existing driver sho
48 straightforward. Here is the simplest example:
49
50 static const struct acpi_device_id myd
51 /* ACPI IDs here */
52 { }
53 };
54 MODULE_DEVICE_TABLE(acpi, mydrv_acpi_m
55
56 static struct platform_driver my_drive
57 ...
58 .driver = {
59 .acpi_match_table = my
60 },
61 };
62
63 If the driver needs to perform more complex in
64 configuring GPIOs it can get its ACPI handle a
65 from ACPI tables.
66
67 ACPI device objects
68 ===================
69
70 Generally speaking, there are two categories o
71 ACPI is used as an interface between the platf
72 that can be discovered and enumerated natively
73 the specific bus that they are on (for example
74 without the platform firmware assistance, and
75 by the platform firmware so that they can be d
76 known to the platform firmware, regardless of
77 there can be a corresponding ACPI device objec
78 case the Linux kernel will create a struct acp
79 that device.
80
81 Those struct acpi_device objects are never use
82 discoverable devices, because they are represe
83 objects (for example, struct pci_dev for PCI d
84 device drivers (the corresponding struct acpi_
85 an additional source of information on the con
86 Moreover, the core ACPI device enumeration cod
87 objects for the majority of devices that are d
88 help of the platform firmware and those platfo
89 by platform drivers in direct analogy with the
90 case. Therefore it is logically inconsistent
91 drivers to struct acpi_device objects, includi
92 discovered with the help of the platform firmw
93
94 Historically, ACPI drivers that bound directly
95 were implemented for some devices enumerated w
96 firmware, but this is not recommended for any
97 platform device objects are created for those
98 exceptions that are not relevant here) and so
99 for handling them, even though the correspondi
100 only source of device configuration informatio
101
102 For every device having a corresponding struct
103 to it is returned by the ACPI_COMPANION() macr
104 get to the device configuration information st
105 this way. Accordingly, struct acpi_device can
106 interface between the kernel and the ACPI Name
107 other types (for example, struct pci_dev or st
108 for interacting with the rest of the system.
109
110 DMA support
111 ===========
112
113 DMA controllers enumerated via ACPI should be
114 provide generic access to their resources. For
115 like to be accessible to slave devices via gen
116 dma_request_chan() must register itself at the
117 this::
118
119 err = devm_acpi_dma_controller_registe
120 /* Handle the error if it's not a case
121
122 and implement custom xlate function if needed
123 is enough) which converts the FixedDMA resourc
124 acpi_dma_spec into the corresponding DMA chann
125 could look like::
126
127 #ifdef CONFIG_ACPI
128 struct filter_args {
129 /* Provide necessary informati
130 ...
131 };
132
133 static bool filter_func(struct dma_cha
134 {
135 /* Choose the proper channel *
136 ...
137 }
138
139 static struct dma_chan *xlate_func(str
140 struct acpi_dma *adma)
141 {
142 dma_cap_mask_t cap;
143 struct filter_args args;
144
145 /* Prepare arguments for filte
146 ...
147 return dma_request_channel(cap
148 }
149 #else
150 static struct dma_chan *xlate_func(str
151 struct acpi_dma *adma)
152 {
153 return NULL;
154 }
155 #endif
156
157 dma_request_chan() will call xlate_func() for
158 In the xlate function the proper channel must
159 information in struct acpi_dma_spec and the pr
160 provided by struct acpi_dma.
161
162 Clients must call dma_request_chan() with the
163 to a specific FixedDMA resource. By default "t
164 FixedDMA resource array, "rx" means the second
165 layout::
166
167 Device (I2C0)
168 {
169 ...
170 Method (_CRS, 0, NotSerialized
171 {
172 Name (DBUF, ResourceTe
173 {
174 FixedDMA (0x00
175 FixedDMA (0x00
176 })
177 ...
178 }
179 }
180
181 So, the FixedDMA with request line 0x0018 is "
182 this example.
183
184 In robust cases the client unfortunately needs
185 acpi_dma_request_slave_chan_by_index() directl
186 specific FixedDMA resource by its index.
187
188 Named Interrupts
189 ================
190
191 Drivers enumerated via ACPI can have names to
192 which can be used to get the IRQ number in the
193
194 The interrupt name can be listed in _DSD as 'i
195 should be listed as an array of strings which
196 resource in the ACPI table corresponding to it
197
198 The table below shows an example of its usage:
199
200 Device (DEV0) {
201 ...
202 Name (_CRS, ResourceTemplate() {
203 ...
204 Interrupt (ResourceConsumer, Level
205 0x20,
206 0x24
207 }
208 })
209
210 Name (_DSD, Package () {
211 ToUUID("daffd814-6eba-4d8c-8a91-bc
212 Package () {
213 Package () { "interrupt-names"
214 }
215 ...
216 })
217 }
218
219 The interrupt name 'default' will correspond t
220 resource and 'alert' to 0x24. Note that only t
221 is mapped and not GpioInt() or similar.
222
223 The driver can call the function - fwnode_irq_
224 and interrupt name as arguments to get the cor
225
226 SPI serial bus support
227 ======================
228
229 Slave devices behind SPI bus have SpiSerialBus
230 This is extracted automatically by the SPI cor
231 enumerated once spi_register_master() is calle
232
233 Here is what the ACPI namespace for a SPI slav
234
235 Device (EEP0)
236 {
237 Name (_ADR, 1)
238 Name (_CID, Package () {
239 "ATML0025",
240 "AT25",
241 })
242 ...
243 Method (_CRS, 0, NotSerialized
244 {
245 SPISerialBus(1, Polari
246 ControllerInit
247 ClockPhaseFirs
248 }
249 ...
250
251 The SPI device drivers only need to add ACPI I
252 the platform device drivers. Below is an examp
253 to at25 SPI eeprom driver (this is meant for t
254
255 static const struct acpi_device_id at2
256 { "AT25", 0 },
257 { }
258 };
259 MODULE_DEVICE_TABLE(acpi, at25_acpi_ma
260
261 static struct spi_driver at25_driver =
262 .driver = {
263 ...
264 .acpi_match_table = at
265 },
266 };
267
268 Note that this driver actually needs more info
269 eeprom, etc. This information can be passed vi
270
271 Device (EEP0)
272 {
273 ...
274 Name (_DSD, Package ()
275 {
276 ToUUID("daffd814-6eba-
277 Package ()
278 {
279 Package () { "
280 Package () { "
281 Package () { "
282 }
283 })
284 }
285
286 Then the at25 SPI driver can get this configur
287 APIs during ->probe() phase like::
288
289 err = device_property_read_u32(dev, "s
290 if (err)
291 ...error handling...
292
293 err = device_property_read_u32(dev, "p
294 if (err)
295 ...error handling...
296
297 err = device_property_read_u32(dev, "a
298 if (err)
299 ...error handling...
300
301 I2C serial bus support
302 ======================
303
304 The slaves behind I2C bus controller only need
305 with the platform and SPI drivers. The I2C cor
306 any slave devices behind the controller device
307 registered.
308
309 Below is an example of how to add ACPI support
310 input driver::
311
312 static const struct acpi_device_id mpu
313 { "MPU3050", 0 },
314 { }
315 };
316 MODULE_DEVICE_TABLE(acpi, mpu3050_acpi
317
318 static struct i2c_driver mpu3050_i2c_d
319 .driver = {
320 .name = "mpu3050",
321 .pm = &mpu3050_pm,
322 .of_match_table = mpu3
323 .acpi_match_table = mp
324 },
325 .probe = mpu3050_prob
326 .remove = mpu3050_remo
327 .id_table = mpu3050_ids,
328 };
329 module_i2c_driver(mpu3050_i2c_driver);
330
331 Reference to PWM device
332 =======================
333
334 Sometimes a device can be a consumer of PWM ch
335 to know which one. To provide this mapping the
336 introduced, i.e.::
337
338 Device (DEV)
339 {
340 Name (_DSD, Package ()
341 {
342 ToUUID("daffd814-6eba-4d8c-8a91-bc
343 Package () {
344 Package () { "compatible", Pac
345 Package () { "label", "alarm-l
346 Package () { "pwms",
347 Package () {
348 "\\_SB.PCI0.PWM", //
349 0, //
350 600000000, //
351 0, //
352 }
353 }
354 }
355 })
356 ...
357 }
358
359 In the above example the PWM-based LED driver
360 of \_SB.PCI0.PWM device with initial period se
361 value is given in nanoseconds).
362
363 GPIO support
364 ============
365
366 ACPI 5 introduced two new resources to describ
367 and GpioInt. These resources can be used to pa
368 the device to the driver. ACPI 5.1 extended th
369 Specific Data) which made it possible to name
370
371 For example::
372
373 Device (DEV)
374 {
375 Method (_CRS, 0, NotSerialized
376 {
377 Name (SBUF, ResourceTe
378 {
379 // Used to pow
380 GpioIo (Exclus
381 "\\_SB
382
383 // Interrupt f
384 GpioInt (Edge,
385 "\\_S
386 }
387
388 Return (SBUF)
389 }
390
391 // ACPI 5.1 _DSD used for nami
392 Name (_DSD, Package ()
393 {
394 ToUUID("daffd814-6eba-
395 Package ()
396 {
397 Package () { "
398 Package () { "
399 }
400 })
401 ...
402 }
403
404 These GPIO numbers are controller relative and
405 specifies the path to the controller. In order
406 we need to translate them to the corresponding
407
408 There is a standard GPIO API for that and it i
409 Documentation/admin-guide/gpio/.
410
411 In the above example we can get the correspond
412 a code like this::
413
414 #include <linux/gpio/consumer.h>
415 ...
416
417 struct gpio_desc *irq_desc, *power_des
418
419 irq_desc = gpiod_get(dev, "irq");
420 if (IS_ERR(irq_desc))
421 /* handle error */
422
423 power_desc = gpiod_get(dev, "power");
424 if (IS_ERR(power_desc))
425 /* handle error */
426
427 /* Now we can use the GPIO descriptors
428
429 There are also devm_* versions of these functi
430 descriptors once the device is released.
431
432 See Documentation/firmware-guide/acpi/gpio-pro
433 about the _DSD binding related to GPIOs.
434
435 RS-485 support
436 ==============
437
438 ACPI _DSD (Device Specific Data) can be used t
439 of UART.
440
441 For example::
442
443 Device (DEV)
444 {
445 ...
446
447 // ACPI 5.1 _DSD used for RS-4
448 Name (_DSD, Package ()
449 {
450 ToUUID("daffd814-6eba-
451 Package ()
452 {
453 Package () {"r
454 Package () {"r
455 Package () {"r
456 }
457 })
458 ...
459
460 MFD devices
461 ===========
462
463 The MFD devices register their children as pla
464 devices there needs to be an ACPI handle that
465 parts of the ACPI namespace that relate to the
466 we provide two ways:
467
468 - The children share the parent ACPI handle.
469 - The MFD cell can specify the ACPI id of th
470
471 For the first case, the MFD drivers do not nee
472 resulting child platform device will have its
473 to the parent device.
474
475 If the ACPI namespace has a device that we can
476 adr, the cell should be set like::
477
478 static struct mfd_cell_acpi_match my_s
479 .pnpid = "XYZ0001",
480 .adr = 0,
481 };
482
483 static struct mfd_cell my_subdevice_ce
484 .name = "my_subdevice",
485 /* set the resources relative
486 .acpi_match = &my_subdevice_ce
487 };
488
489 The ACPI id "XYZ0001" is then used to lookup a
490 the MFD device and if found, that ACPI compani
491 resulting child platform device.
492
493 Device Tree namespace link device ID
494 ====================================
495
496 The Device Tree protocol uses device identific
497 property whose value is a string or an array o
498 identifiers by drivers and the driver core. T
499 regarded as a device identification namespace
500 ID namespace. Consequently, in principle it s
501 a new (and arguably redundant) ACPI/PNP device
502 identification string in the Device Tree (DT)
503 is only needed to indicate that a given device
504 presumably having a matching driver in the ker
505
506 In ACPI, the device identification object call
507 list the IDs of devices the given one is compa
508 belong to one of the namespaces prescribed by
509 Section 6.1.2 of ACPI 6.0 for details) and the
510 Moreover, the specification mandates that eith
511 object be present for all ACPI objects represe
512 6.0). For non-enumerable bus types that objec
513 be a device ID from one of the namespaces pres
514
515 The special DT namespace link device ID, PRP00
516 existing DT-compatible device identification i
517 requirements following from the ACPI specifica
518 if PRP0001 is returned by _HID, the ACPI subsy
519 "compatible" property in the device object's _
520 property to identify the corresponding device
521 device identification algorithm. If the "comp
522 or its value is not valid, the device will not
523 subsystem. Otherwise, it will be enumerated a
524 (except when an I2C or SPI link from the devic
525 which case the ACPI core will leave the device
526 driver) and the identification strings from th
527 be used to find a driver for the device along
528 (if present).
529
530 Analogously, if PRP0001 is present in the list
531 the identification strings listed by the "comp
532 and valid) will be used to look for a driver m
533 case their relative priority with respect to t
534 _HID and _CID depends on the position of PRP00
535 Specifically, the device IDs returned by _HID
536 return package will be checked first. Also in
537 will be enumerated to depends on the device ID
538
539 For example, the following ACPI sample might b
540 I2C temperature sensor and match it to the dri
541 namespace link::
542
543 Device (TMP0)
544 {
545 Name (_HID, "PRP0001")
546 Name (_DSD, Package () {
547 ToUUID("daffd814-6eba-
548 Package () {
549 Package () { "
550 }
551 })
552 Method (_CRS, 0, Serialized)
553 {
554 Name (SBUF, ResourceTe
555 {
556 I2cSerialBusV2
557 400000
558 "\\_SB
559 Resour
560 })
561 Return (SBUF)
562 }
563 }
564
565 It is valid to define device objects with a _H
566 the "compatible" property in the _DSD or a _CI
567 ancestors provides a _DSD with a valid "compat
568 objects are then simply regarded as additional
569 configuration information to the driver of the
570
571 However, PRP0001 can only be returned from eit
572 object if all of the properties returned by th
573 the _DSD of the device object itself or the _D
574 "composite device" case described above) can b
575 Otherwise, the _DSD itself is regarded as inva
576 property returned by it is meaningless.
577
578 Refer to Documentation/firmware-guide/acpi/DSD
579 information.
580
581 PCI hierarchy representation
582 ============================
583
584 Sometimes it could be useful to enumerate a PC
585 the PCI bus.
586
587 For example, some systems use PCI devices sold
588 in a fixed position (ethernet, Wi-Fi, serial p
589 is possible to refer to these PCI devices know
590 topology.
591
592 To identify a PCI device, a complete hierarchi
593 the chipset root port to the final device, thr
594 bridges/switches of the board.
595
596 For example, let's assume we have a system wit
597 Exar XR17V3521, soldered on the main board. Th
598 16 GPIOs and we want to add the property ``gpi
599 In this case, the ``lspci`` output for this co
600
601 07:00.0 Serial controller: Exar Corp.
602
603 The complete ``lspci`` output (manually reduce
604
605 00:00.0 Host bridge: Intel Corp... Hos
606 ...
607 00:13.0 PCI bridge: Intel Corp... PCI
608 00:13.1 PCI bridge: Intel Corp... PCI
609 00:13.2 PCI bridge: Intel Corp... PCI
610 00:14.0 PCI bridge: Intel Corp... PCI
611 00:14.1 PCI bridge: Intel Corp... PCI
612 ...
613 05:00.0 PCI bridge: Pericom Semiconduc
614 06:01.0 PCI bridge: Pericom Semiconduc
615 06:02.0 PCI bridge: Pericom Semiconduc
616 06:03.0 PCI bridge: Pericom Semiconduc
617 07:00.0 Serial controller: Exar Corp.
618 ...
619
620 The bus topology is::
621
622 -[0000:00]-+-00.0
623 ...
624 +-13.0-[01]----00.0
625 +-13.1-[02]----00.0
626 +-13.2-[03]--
627 +-14.0-[04]----00.0
628 +-14.1-[05-09]----00.0-[06-
629 |
630 |
631 ...
632 \-1f.1
633
634 To describe this Exar device on the PCI bus, w
635 of the chipset bridge (also called "root port"
636
637 Bus: 0 - Device: 14 - Function: 1
638
639 To find this information, it is necessary to d
640 in particular the DSDT (see also [2]_)::
641
642 mkdir ~/tables/
643 cd ~/tables/
644 acpidump > acpidump
645 acpixtract -a acpidump
646 iasl -e ssdt?.* -d dsdt.dat
647
648 Now, in the dsdt.dsl, we have to search the de
649 0x14 (device) and 0x01 (function). In this cas
650 device::
651
652 Scope (_SB.PCI0)
653 {
654 ... other definitions follow ...
655 Device (RP02)
656 {
657 Method (_ADR, 0, NotSe
658 {
659 If ((RPA2 != Z
660 {
661 Return
662 }
663 Else
664 {
665 Return
666 }
667 }
668 ... other definitions follow ...
669
670 and the _ADR method [3]_ returns exactly the d
671 we are looking for. With this information and
672 output (both the devices list and the devices
673 ACPI description for the Exar PCIe UART, also
674 names::
675
676 Scope (_SB.PCI0.RP02)
677 {
678 Device (BRG1) //Bridge
679 {
680 Name (_ADR, 0x0000)
681
682 Device (BRG2) //Bridge
683 {
684 Name (_ADR, 0x
685
686 Device (EXAR)
687 {
688 Name (
689
690 Name (
691 {
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714 })
715 }
716 }
717 }
718 }
719
720 The location "_SB.PCI0.RP02" is obtained by th
721 dsdt.dsl table, whereas the device names "BRG1
722 created analyzing the position of the Exar UAR
723
724 References
725 ==========
726
727 .. [1] Documentation/firmware-guide/acpi/gpio-
728
729 .. [2] Documentation/admin-guide/acpi/initrd_t
730
731 .. [3] ACPI Specifications, Version 6.3 - Para
732 https://uefi.org/sites/default/files/resou
733 referenced 2020-11-18
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.