1 .. SPDX-License-Identifier: GPL-2.0
3 =============================
4 ACPI Based Device Enumeration
5 =============================
7 ACPI 5 introduced a set of new resources (UartTSerialBus, I2cSerialBus,
8 SpiSerialBus, GpioIo and GpioInt) which can be used in enumerating slave
9 devices behind serial bus controllers.
11 In addition we are starting to see peripherals integrated in the
12 SoC/Chipset to appear only in ACPI namespace. These are typically devices
13 that are accessed through memory-mapped registers.
15 In order to support this and re-use the existing drivers as much as
16 possible we decided to do following:
18 - Devices that have no bus connector resource are represented as
21 - Devices behind real busses where there is a connector resource
22 are represented as struct spi_device or struct i2c_device. Note
23 that standard UARTs are not busses so there is no struct uart_device,
24 although some of them may be represented by struct serdev_device.
26 As both ACPI and Device Tree represent a tree of devices (and their
27 resources) this implementation follows the Device Tree way as much as
30 The ACPI implementation enumerates devices behind busses (platform, SPI,
31 I2C, and in some cases UART), creates the physical devices and binds them
32 to their ACPI handle in the ACPI namespace.
34 This means that when ACPI_HANDLE(dev) returns non-NULL the device was
35 enumerated from ACPI namespace. This handle can be used to extract other
36 device-specific configuration. There is an example of this below.
41 Since we are using platform devices to represent devices that are not
42 connected to any physical bus we only need to implement a platform driver
43 for the device and add supported ACPI IDs. If this same IP-block is used on
44 some other non-ACPI platform, the driver might work out of the box or needs
47 Adding ACPI support for an existing driver should be pretty
48 straightforward. Here is the simplest example::
50 static const struct acpi_device_id mydrv_acpi_match[] = {
54 MODULE_DEVICE_TABLE(acpi, mydrv_acpi_match);
56 static struct platform_driver my_driver = {
59 .acpi_match_table = mydrv_acpi_match,
63 If the driver needs to perform more complex initialization like getting and
64 configuring GPIOs it can get its ACPI handle and extract this information
70 DMA controllers enumerated via ACPI should be registered in the system to
71 provide generic access to their resources. For example, a driver that would
72 like to be accessible to slave devices via generic API call
73 dma_request_chan() must register itself at the end of the probe function like
76 err = devm_acpi_dma_controller_register(dev, xlate_func, dw);
77 /* Handle the error if it's not a case of !CONFIG_ACPI */
79 and implement custom xlate function if needed (usually acpi_dma_simple_xlate()
80 is enough) which converts the FixedDMA resource provided by struct
81 acpi_dma_spec into the corresponding DMA channel. A piece of code for that case
86 /* Provide necessary information for the filter_func */
90 static bool filter_func(struct dma_chan *chan, void *param)
92 /* Choose the proper channel */
96 static struct dma_chan *xlate_func(struct acpi_dma_spec *dma_spec,
97 struct acpi_dma *adma)
100 struct filter_args args;
102 /* Prepare arguments for filter_func */
104 return dma_request_channel(cap, filter_func, &args);
107 static struct dma_chan *xlate_func(struct acpi_dma_spec *dma_spec,
108 struct acpi_dma *adma)
114 dma_request_chan() will call xlate_func() for each registered DMA controller.
115 In the xlate function the proper channel must be chosen based on
116 information in struct acpi_dma_spec and the properties of the controller
117 provided by struct acpi_dma.
119 Clients must call dma_request_chan() with the string parameter that corresponds
120 to a specific FixedDMA resource. By default "tx" means the first entry of the
121 FixedDMA resource array, "rx" means the second entry. The table below shows a
127 Method (_CRS, 0, NotSerialized)
129 Name (DBUF, ResourceTemplate ()
131 FixedDMA (0x0018, 0x0004, Width32bit, _Y48)
132 FixedDMA (0x0019, 0x0005, Width32bit, )
138 So, the FixedDMA with request line 0x0018 is "tx" and next one is "rx" in
141 In robust cases the client unfortunately needs to call
142 acpi_dma_request_slave_chan_by_index() directly and therefore choose the
143 specific FixedDMA resource by its index.
148 Drivers enumerated via ACPI can have names to interrupts in the ACPI table
149 which can be used to get the IRQ number in the driver.
151 The interrupt name can be listed in _DSD as 'interrupt-names'. The names
152 should be listed as an array of strings which will map to the Interrupt()
153 resource in the ACPI table corresponding to its index.
155 The table below shows an example of its usage::
159 Name (_CRS, ResourceTemplate() {
161 Interrupt (ResourceConsumer, Level, ActiveHigh, Exclusive) {
167 Name (_DSD, Package () {
168 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
170 Package () { "interrupt-names", Package () { "default", "alert" } },
176 The interrupt name 'default' will correspond to 0x20 in Interrupt()
177 resource and 'alert' to 0x24. Note that only the Interrupt() resource
178 is mapped and not GpioInt() or similar.
180 The driver can call the function - fwnode_irq_get_byname() with the fwnode
181 and interrupt name as arguments to get the corresponding IRQ number.
183 SPI serial bus support
184 ======================
186 Slave devices behind SPI bus have SpiSerialBus resource attached to them.
187 This is extracted automatically by the SPI core and the slave devices are
188 enumerated once spi_register_master() is called by the bus driver.
190 Here is what the ACPI namespace for a SPI slave might look like::
195 Name (_CID, Package () {
200 Method (_CRS, 0, NotSerialized)
202 SPISerialBus(1, PolarityLow, FourWireMode, 8,
203 ControllerInitiated, 1000000, ClockPolarityLow,
204 ClockPhaseFirst, "\\_SB.PCI0.SPI1",)
208 The SPI device drivers only need to add ACPI IDs in a similar way to
209 the platform device drivers. Below is an example where we add ACPI support
210 to at25 SPI eeprom driver (this is meant for the above ACPI snippet)::
212 static const struct acpi_device_id at25_acpi_match[] = {
216 MODULE_DEVICE_TABLE(acpi, at25_acpi_match);
218 static struct spi_driver at25_driver = {
221 .acpi_match_table = at25_acpi_match,
225 Note that this driver actually needs more information like page size of the
226 eeprom, etc. This information can be passed via _DSD method like::
231 Name (_DSD, Package ()
233 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
236 Package () { "size", 1024 },
237 Package () { "pagesize", 32 },
238 Package () { "address-width", 16 },
243 Then the at25 SPI driver can get this configuration by calling device property
244 APIs during ->probe() phase like::
246 err = device_property_read_u32(dev, "size", &size);
250 err = device_property_read_u32(dev, "pagesize", &page_size);
254 err = device_property_read_u32(dev, "address-width", &addr_width);
258 I2C serial bus support
259 ======================
261 The slaves behind I2C bus controller only need to add the ACPI IDs like
262 with the platform and SPI drivers. The I2C core automatically enumerates
263 any slave devices behind the controller device once the adapter is
266 Below is an example of how to add ACPI support to the existing mpu3050
269 static const struct acpi_device_id mpu3050_acpi_match[] = {
273 MODULE_DEVICE_TABLE(acpi, mpu3050_acpi_match);
275 static struct i2c_driver mpu3050_i2c_driver = {
279 .of_match_table = mpu3050_of_match,
280 .acpi_match_table = mpu3050_acpi_match,
282 .probe = mpu3050_probe,
283 .remove = mpu3050_remove,
284 .id_table = mpu3050_ids,
286 module_i2c_driver(mpu3050_i2c_driver);
288 Reference to PWM device
289 =======================
291 Sometimes a device can be a consumer of PWM channel. Obviously OS would like
292 to know which one. To provide this mapping the special property has been
297 Name (_DSD, Package ()
299 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
301 Package () { "compatible", Package () { "pwm-leds" } },
302 Package () { "label", "alarm-led" },
305 "\\_SB.PCI0.PWM", // <PWM device reference>
307 600000000, // <PWM period>
316 In the above example the PWM-based LED driver references to the PWM channel 0
317 of \_SB.PCI0.PWM device with initial period setting equal to 600 ms (note that
318 value is given in nanoseconds).
323 ACPI 5 introduced two new resources to describe GPIO connections: GpioIo
324 and GpioInt. These resources can be used to pass GPIO numbers used by
325 the device to the driver. ACPI 5.1 extended this with _DSD (Device
326 Specific Data) which made it possible to name the GPIOs among other things.
332 Method (_CRS, 0, NotSerialized)
334 Name (SBUF, ResourceTemplate()
336 // Used to power on/off the device
337 GpioIo (Exclusive, PullNone, 0, 0, IoRestrictionOutputOnly,
338 "\\_SB.PCI0.GPI0", 0, ResourceConsumer) { 85 }
340 // Interrupt for the device
341 GpioInt (Edge, ActiveHigh, ExclusiveAndWake, PullNone, 0,
342 "\\_SB.PCI0.GPI0", 0, ResourceConsumer) { 88 }
348 // ACPI 5.1 _DSD used for naming the GPIOs
349 Name (_DSD, Package ()
351 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
354 Package () { "power-gpios", Package () { ^DEV, 0, 0, 0 } },
355 Package () { "irq-gpios", Package () { ^DEV, 1, 0, 0 } },
361 These GPIO numbers are controller relative and path "\\_SB.PCI0.GPI0"
362 specifies the path to the controller. In order to use these GPIOs in Linux
363 we need to translate them to the corresponding Linux GPIO descriptors.
365 There is a standard GPIO API for that and it is documented in
366 Documentation/admin-guide/gpio/.
368 In the above example we can get the corresponding two GPIO descriptors with
371 #include <linux/gpio/consumer.h>
374 struct gpio_desc *irq_desc, *power_desc;
376 irq_desc = gpiod_get(dev, "irq");
377 if (IS_ERR(irq_desc))
380 power_desc = gpiod_get(dev, "power");
381 if (IS_ERR(power_desc))
384 /* Now we can use the GPIO descriptors */
386 There are also devm_* versions of these functions which release the
387 descriptors once the device is released.
389 See Documentation/firmware-guide/acpi/gpio-properties.rst for more information
390 about the _DSD binding related to GPIOs.
395 ACPI _DSD (Device Specific Data) can be used to describe RS-485 capability
404 // ACPI 5.1 _DSD used for RS-485 capabilities
405 Name (_DSD, Package ()
407 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
410 Package () {"rs485-rts-active-low", Zero},
411 Package () {"rs485-rx-active-high", Zero},
412 Package () {"rs485-rx-during-tx", Zero},
420 The MFD devices register their children as platform devices. For the child
421 devices there needs to be an ACPI handle that they can use to reference
422 parts of the ACPI namespace that relate to them. In the Linux MFD subsystem
425 - The children share the parent ACPI handle.
426 - The MFD cell can specify the ACPI id of the device.
428 For the first case, the MFD drivers do not need to do anything. The
429 resulting child platform device will have its ACPI_COMPANION() set to point
430 to the parent device.
432 If the ACPI namespace has a device that we can match using an ACPI id or ACPI
433 adr, the cell should be set like::
435 static struct mfd_cell_acpi_match my_subdevice_cell_acpi_match = {
440 static struct mfd_cell my_subdevice_cell = {
441 .name = "my_subdevice",
442 /* set the resources relative to the parent */
443 .acpi_match = &my_subdevice_cell_acpi_match,
446 The ACPI id "XYZ0001" is then used to lookup an ACPI device directly under
447 the MFD device and if found, that ACPI companion device is bound to the
448 resulting child platform device.
450 Device Tree namespace link device ID
451 ====================================
453 The Device Tree protocol uses device identification based on the "compatible"
454 property whose value is a string or an array of strings recognized as device
455 identifiers by drivers and the driver core. The set of all those strings may be
456 regarded as a device identification namespace analogous to the ACPI/PNP device
457 ID namespace. Consequently, in principle it should not be necessary to allocate
458 a new (and arguably redundant) ACPI/PNP device ID for a devices with an existing
459 identification string in the Device Tree (DT) namespace, especially if that ID
460 is only needed to indicate that a given device is compatible with another one,
461 presumably having a matching driver in the kernel already.
463 In ACPI, the device identification object called _CID (Compatible ID) is used to
464 list the IDs of devices the given one is compatible with, but those IDs must
465 belong to one of the namespaces prescribed by the ACPI specification (see
466 Section 6.1.2 of ACPI 6.0 for details) and the DT namespace is not one of them.
467 Moreover, the specification mandates that either a _HID or an _ADR identification
468 object be present for all ACPI objects representing devices (Section 6.1 of ACPI
469 6.0). For non-enumerable bus types that object must be _HID and its value must
470 be a device ID from one of the namespaces prescribed by the specification too.
472 The special DT namespace link device ID, PRP0001, provides a means to use the
473 existing DT-compatible device identification in ACPI and to satisfy the above
474 requirements following from the ACPI specification at the same time. Namely,
475 if PRP0001 is returned by _HID, the ACPI subsystem will look for the
476 "compatible" property in the device object's _DSD and will use the value of that
477 property to identify the corresponding device in analogy with the original DT
478 device identification algorithm. If the "compatible" property is not present
479 or its value is not valid, the device will not be enumerated by the ACPI
480 subsystem. Otherwise, it will be enumerated automatically as a platform device
481 (except when an I2C or SPI link from the device to its parent is present, in
482 which case the ACPI core will leave the device enumeration to the parent's
483 driver) and the identification strings from the "compatible" property value will
484 be used to find a driver for the device along with the device IDs listed by _CID
487 Analogously, if PRP0001 is present in the list of device IDs returned by _CID,
488 the identification strings listed by the "compatible" property value (if present
489 and valid) will be used to look for a driver matching the device, but in that
490 case their relative priority with respect to the other device IDs listed by
491 _HID and _CID depends on the position of PRP0001 in the _CID return package.
492 Specifically, the device IDs returned by _HID and preceding PRP0001 in the _CID
493 return package will be checked first. Also in that case the bus type the device
494 will be enumerated to depends on the device ID returned by _HID.
496 For example, the following ACPI sample might be used to enumerate an lm75-type
497 I2C temperature sensor and match it to the driver using the Device Tree
502 Name (_HID, "PRP0001")
503 Name (_DSD, Package () {
504 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
506 Package () { "compatible", "ti,tmp75" },
509 Method (_CRS, 0, Serialized)
511 Name (SBUF, ResourceTemplate ()
513 I2cSerialBusV2 (0x48, ControllerInitiated,
514 400000, AddressingMode7Bit,
515 "\\_SB.PCI0.I2C1", 0x00,
516 ResourceConsumer, , Exclusive,)
522 It is valid to define device objects with a _HID returning PRP0001 and without
523 the "compatible" property in the _DSD or a _CID as long as one of their
524 ancestors provides a _DSD with a valid "compatible" property. Such device
525 objects are then simply regarded as additional "blocks" providing hierarchical
526 configuration information to the driver of the composite ancestor device.
528 However, PRP0001 can only be returned from either _HID or _CID of a device
529 object if all of the properties returned by the _DSD associated with it (either
530 the _DSD of the device object itself or the _DSD of its ancestor in the
531 "composite device" case described above) can be used in the ACPI environment.
532 Otherwise, the _DSD itself is regarded as invalid and therefore the "compatible"
533 property returned by it is meaningless.
535 Refer to Documentation/firmware-guide/acpi/DSD-properties-rules.rst for more
538 PCI hierarchy representation
539 ============================
541 Sometimes it could be useful to enumerate a PCI device, knowing its position on
544 For example, some systems use PCI devices soldered directly on the mother board,
545 in a fixed position (ethernet, Wi-Fi, serial ports, etc.). In this conditions it
546 is possible to refer to these PCI devices knowing their position on the PCI bus
549 To identify a PCI device, a complete hierarchical description is required, from
550 the chipset root port to the final device, through all the intermediate
551 bridges/switches of the board.
553 For example, let's assume we have a system with a PCIe serial port, an
554 Exar XR17V3521, soldered on the main board. This UART chip also includes
555 16 GPIOs and we want to add the property ``gpio-line-names`` [1] to these pins.
556 In this case, the ``lspci`` output for this component is::
558 07:00.0 Serial controller: Exar Corp. XR17V3521 Dual PCIe UART (rev 03)
560 The complete ``lspci`` output (manually reduced in length) is::
562 00:00.0 Host bridge: Intel Corp... Host Bridge (rev 0d)
564 00:13.0 PCI bridge: Intel Corp... PCI Express Port A #1 (rev fd)
565 00:13.1 PCI bridge: Intel Corp... PCI Express Port A #2 (rev fd)
566 00:13.2 PCI bridge: Intel Corp... PCI Express Port A #3 (rev fd)
567 00:14.0 PCI bridge: Intel Corp... PCI Express Port B #1 (rev fd)
568 00:14.1 PCI bridge: Intel Corp... PCI Express Port B #2 (rev fd)
570 05:00.0 PCI bridge: Pericom Semiconductor Device 2404 (rev 05)
571 06:01.0 PCI bridge: Pericom Semiconductor Device 2404 (rev 05)
572 06:02.0 PCI bridge: Pericom Semiconductor Device 2404 (rev 05)
573 06:03.0 PCI bridge: Pericom Semiconductor Device 2404 (rev 05)
574 07:00.0 Serial controller: Exar Corp. XR17V3521 Dual PCIe UART (rev 03) <-- Exar
577 The bus topology is::
585 +-14.1-[05-09]----00.0-[06-09]--+-01.0-[07]----00.0 <-- Exar
586 | +-02.0-[08]----00.0
591 To describe this Exar device on the PCI bus, we must start from the ACPI name
592 of the chipset bridge (also called "root port") with address::
594 Bus: 0 - Device: 14 - Function: 1
596 To find this information, it is necessary to disassemble the BIOS ACPI tables,
597 in particular the DSDT (see also [2])::
602 acpixtract -a acpidump
603 iasl -e ssdt?.* -d dsdt.dat
605 Now, in the dsdt.dsl, we have to search the device whose address is related to
606 0x14 (device) and 0x01 (function). In this case we can find the following
611 ... other definitions follow ...
614 Method (_ADR, 0, NotSerialized) // _ADR: Address
618 Return (RPA2) /* \RPA2 */
625 ... other definitions follow ...
627 and the _ADR method [3] returns exactly the device/function couple that
628 we are looking for. With this information and analyzing the above ``lspci``
629 output (both the devices list and the devices tree), we can write the following
630 ACPI description for the Exar PCIe UART, also adding the list of its GPIO line
633 Scope (_SB.PCI0.RP02)
635 Device (BRG1) //Bridge
639 Device (BRG2) //Bridge
641 Name (_ADR, 0x00010000)
647 Name (_DSD, Package ()
649 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
677 The location "_SB.PCI0.RP02" is obtained by the above investigation in the
678 dsdt.dsl table, whereas the device names "BRG1", "BRG2" and "EXAR" are
679 created analyzing the position of the Exar UART in the PCI bus topology.
684 [1] Documentation/firmware-guide/acpi/gpio-properties.rst
686 [2] Documentation/admin-guide/acpi/initrd_table_override.rst
688 [3] ACPI Specifications, Version 6.3 - Paragraph 6.1.1 _ADR Address)
689 https://uefi.org/sites/default/files/resources/ACPI_6_3_May16.pdf,
690 referenced 2020-11-18