734 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3=============================4ACPI Based Device Enumeration5=============================6 7ACPI 5 introduced a set of new resources (UartTSerialBus, I2cSerialBus,8SpiSerialBus, GpioIo and GpioInt) which can be used in enumerating slave9devices behind serial bus controllers.10 11In addition we are starting to see peripherals integrated in the12SoC/Chipset to appear only in ACPI namespace. These are typically devices13that are accessed through memory-mapped registers.14 15In order to support this and re-use the existing drivers as much as16possible we decided to do following:17 18 - Devices that have no bus connector resource are represented as19 platform devices.20 21 - Devices behind real busses where there is a connector resource22 are represented as struct spi_device or struct i2c_client. Note23 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.25 26As both ACPI and Device Tree represent a tree of devices (and their27resources) this implementation follows the Device Tree way as much as28possible.29 30The ACPI implementation enumerates devices behind busses (platform, SPI,31I2C, and in some cases UART), creates the physical devices and binds them32to their ACPI handle in the ACPI namespace.33 34This means that when ACPI_HANDLE(dev) returns non-NULL the device was35enumerated from ACPI namespace. This handle can be used to extract other36device-specific configuration. There is an example of this below.37 38Platform bus support39====================40 41Since we are using platform devices to represent devices that are not42connected to any physical bus we only need to implement a platform driver43for the device and add supported ACPI IDs. If this same IP-block is used on44some other non-ACPI platform, the driver might work out of the box or needs45some minor changes.46 47Adding ACPI support for an existing driver should be pretty48straightforward. Here is the simplest example::49 50 static const struct acpi_device_id mydrv_acpi_match[] = {51 /* ACPI IDs here */52 { }53 };54 MODULE_DEVICE_TABLE(acpi, mydrv_acpi_match);55 56 static struct platform_driver my_driver = {57 ...58 .driver = {59 .acpi_match_table = mydrv_acpi_match,60 },61 };62 63If the driver needs to perform more complex initialization like getting and64configuring GPIOs it can get its ACPI handle and extract this information65from ACPI tables.66 67ACPI device objects68===================69 70Generally speaking, there are two categories of devices in a system in which71ACPI is used as an interface between the platform firmware and the OS: Devices72that can be discovered and enumerated natively, through a protocol defined for73the specific bus that they are on (for example, configuration space in PCI),74without the platform firmware assistance, and devices that need to be described75by the platform firmware so that they can be discovered. Still, for any device76known to the platform firmware, regardless of which category it falls into,77there can be a corresponding ACPI device object in the ACPI Namespace in which78case the Linux kernel will create a struct acpi_device object based on it for79that device.80 81Those struct acpi_device objects are never used for binding drivers to natively82discoverable devices, because they are represented by other types of device83objects (for example, struct pci_dev for PCI devices) that are bound to by84device drivers (the corresponding struct acpi_device object is then used as85an additional source of information on the configuration of the given device).86Moreover, the core ACPI device enumeration code creates struct platform_device87objects for the majority of devices that are discovered and enumerated with the88help of the platform firmware and those platform device objects can be bound to89by platform drivers in direct analogy with the natively enumerable devices90case. Therefore it is logically inconsistent and so generally invalid to bind91drivers to struct acpi_device objects, including drivers for devices that are92discovered with the help of the platform firmware.93 94Historically, ACPI drivers that bound directly to struct acpi_device objects95were implemented for some devices enumerated with the help of the platform96firmware, but this is not recommended for any new drivers. As explained above,97platform device objects are created for those devices as a rule (with a few98exceptions that are not relevant here) and so platform drivers should be used99for handling them, even though the corresponding ACPI device objects are the100only source of device configuration information in that case.101 102For every device having a corresponding struct acpi_device object, the pointer103to it is returned by the ACPI_COMPANION() macro, so it is always possible to104get to the device configuration information stored in the ACPI device object105this way. Accordingly, struct acpi_device can be regarded as a part of the106interface between the kernel and the ACPI Namespace, whereas device objects of107other types (for example, struct pci_dev or struct platform_device) are used108for interacting with the rest of the system.109 110DMA support111===========112 113DMA controllers enumerated via ACPI should be registered in the system to114provide generic access to their resources. For example, a driver that would115like to be accessible to slave devices via generic API call116dma_request_chan() must register itself at the end of the probe function like117this::118 119 err = devm_acpi_dma_controller_register(dev, xlate_func, dw);120 /* Handle the error if it's not a case of !CONFIG_ACPI */121 122and implement custom xlate function if needed (usually acpi_dma_simple_xlate()123is enough) which converts the FixedDMA resource provided by struct124acpi_dma_spec into the corresponding DMA channel. A piece of code for that case125could look like::126 127 #ifdef CONFIG_ACPI128 struct filter_args {129 /* Provide necessary information for the filter_func */130 ...131 };132 133 static bool filter_func(struct dma_chan *chan, void *param)134 {135 /* Choose the proper channel */136 ...137 }138 139 static struct dma_chan *xlate_func(struct acpi_dma_spec *dma_spec,140 struct acpi_dma *adma)141 {142 dma_cap_mask_t cap;143 struct filter_args args;144 145 /* Prepare arguments for filter_func */146 ...147 return dma_request_channel(cap, filter_func, &args);148 }149 #else150 static struct dma_chan *xlate_func(struct acpi_dma_spec *dma_spec,151 struct acpi_dma *adma)152 {153 return NULL;154 }155 #endif156 157dma_request_chan() will call xlate_func() for each registered DMA controller.158In the xlate function the proper channel must be chosen based on159information in struct acpi_dma_spec and the properties of the controller160provided by struct acpi_dma.161 162Clients must call dma_request_chan() with the string parameter that corresponds163to a specific FixedDMA resource. By default "tx" means the first entry of the164FixedDMA resource array, "rx" means the second entry. The table below shows a165layout::166 167 Device (I2C0)168 {169 ...170 Method (_CRS, 0, NotSerialized)171 {172 Name (DBUF, ResourceTemplate ()173 {174 FixedDMA (0x0018, 0x0004, Width32bit, _Y48)175 FixedDMA (0x0019, 0x0005, Width32bit, )176 })177 ...178 }179 }180 181So, the FixedDMA with request line 0x0018 is "tx" and next one is "rx" in182this example.183 184In robust cases the client unfortunately needs to call185acpi_dma_request_slave_chan_by_index() directly and therefore choose the186specific FixedDMA resource by its index.187 188Named Interrupts189================190 191Drivers enumerated via ACPI can have names to interrupts in the ACPI table192which can be used to get the IRQ number in the driver.193 194The interrupt name can be listed in _DSD as 'interrupt-names'. The names195should be listed as an array of strings which will map to the Interrupt()196resource in the ACPI table corresponding to its index.197 198The table below shows an example of its usage::199 200 Device (DEV0) {201 ...202 Name (_CRS, ResourceTemplate() {203 ...204 Interrupt (ResourceConsumer, Level, ActiveHigh, Exclusive) {205 0x20,206 0x24207 }208 })209 210 Name (_DSD, Package () {211 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),212 Package () {213 Package () { "interrupt-names", Package () { "default", "alert" } },214 }215 ...216 })217 }218 219The interrupt name 'default' will correspond to 0x20 in Interrupt()220resource and 'alert' to 0x24. Note that only the Interrupt() resource221is mapped and not GpioInt() or similar.222 223The driver can call the function - fwnode_irq_get_byname() with the fwnode224and interrupt name as arguments to get the corresponding IRQ number.225 226SPI serial bus support227======================228 229Slave devices behind SPI bus have SpiSerialBus resource attached to them.230This is extracted automatically by the SPI core and the slave devices are231enumerated once spi_register_master() is called by the bus driver.232 233Here is what the ACPI namespace for a SPI slave might look like::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, PolarityLow, FourWireMode, 8,246 ControllerInitiated, 1000000, ClockPolarityLow,247 ClockPhaseFirst, "\\_SB.PCI0.SPI1",)248 }249 ...250 251The SPI device drivers only need to add ACPI IDs in a similar way to252the platform device drivers. Below is an example where we add ACPI support253to at25 SPI eeprom driver (this is meant for the above ACPI snippet)::254 255 static const struct acpi_device_id at25_acpi_match[] = {256 { "AT25", 0 },257 { }258 };259 MODULE_DEVICE_TABLE(acpi, at25_acpi_match);260 261 static struct spi_driver at25_driver = {262 .driver = {263 ...264 .acpi_match_table = at25_acpi_match,265 },266 };267 268Note that this driver actually needs more information like page size of the269eeprom, etc. This information can be passed via _DSD method like::270 271 Device (EEP0)272 {273 ...274 Name (_DSD, Package ()275 {276 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),277 Package ()278 {279 Package () { "size", 1024 },280 Package () { "pagesize", 32 },281 Package () { "address-width", 16 },282 }283 })284 }285 286Then the at25 SPI driver can get this configuration by calling device property287APIs during ->probe() phase like::288 289 err = device_property_read_u32(dev, "size", &size);290 if (err)291 ...error handling...292 293 err = device_property_read_u32(dev, "pagesize", &page_size);294 if (err)295 ...error handling...296 297 err = device_property_read_u32(dev, "address-width", &addr_width);298 if (err)299 ...error handling...300 301I2C serial bus support302======================303 304The slaves behind I2C bus controller only need to add the ACPI IDs like305with the platform and SPI drivers. The I2C core automatically enumerates306any slave devices behind the controller device once the adapter is307registered.308 309Below is an example of how to add ACPI support to the existing mpu3050310input driver::311 312 static const struct acpi_device_id mpu3050_acpi_match[] = {313 { "MPU3050", 0 },314 { }315 };316 MODULE_DEVICE_TABLE(acpi, mpu3050_acpi_match);317 318 static struct i2c_driver mpu3050_i2c_driver = {319 .driver = {320 .name = "mpu3050",321 .pm = &mpu3050_pm,322 .of_match_table = mpu3050_of_match,323 .acpi_match_table = mpu3050_acpi_match,324 },325 .probe = mpu3050_probe,326 .remove = mpu3050_remove,327 .id_table = mpu3050_ids,328 };329 module_i2c_driver(mpu3050_i2c_driver);330 331Reference to PWM device332=======================333 334Sometimes a device can be a consumer of PWM channel. Obviously OS would like335to know which one. To provide this mapping the special property has been336introduced, i.e.::337 338 Device (DEV)339 {340 Name (_DSD, Package ()341 {342 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),343 Package () {344 Package () { "compatible", Package () { "pwm-leds" } },345 Package () { "label", "alarm-led" },346 Package () { "pwms",347 Package () {348 "\\_SB.PCI0.PWM", // <PWM device reference>349 0, // <PWM index>350 600000000, // <PWM period>351 0, // <PWM flags>352 }353 }354 }355 })356 ...357 }358 359In the above example the PWM-based LED driver references to the PWM channel 0360of \_SB.PCI0.PWM device with initial period setting equal to 600 ms (note that361value is given in nanoseconds).362 363GPIO support364============365 366ACPI 5 introduced two new resources to describe GPIO connections: GpioIo367and GpioInt. These resources can be used to pass GPIO numbers used by368the device to the driver. ACPI 5.1 extended this with _DSD (Device369Specific Data) which made it possible to name the GPIOs among other things.370 371For example::372 373 Device (DEV)374 {375 Method (_CRS, 0, NotSerialized)376 {377 Name (SBUF, ResourceTemplate()378 {379 // Used to power on/off the device380 GpioIo (Exclusive, PullNone, 0, 0, IoRestrictionOutputOnly,381 "\\_SB.PCI0.GPI0", 0, ResourceConsumer) { 85 }382 383 // Interrupt for the device384 GpioInt (Edge, ActiveHigh, ExclusiveAndWake, PullNone, 0,385 "\\_SB.PCI0.GPI0", 0, ResourceConsumer) { 88 }386 }387 388 Return (SBUF)389 }390 391 // ACPI 5.1 _DSD used for naming the GPIOs392 Name (_DSD, Package ()393 {394 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),395 Package ()396 {397 Package () { "power-gpios", Package () { ^DEV, 0, 0, 0 } },398 Package () { "irq-gpios", Package () { ^DEV, 1, 0, 0 } },399 }400 })401 ...402 }403 404These GPIO numbers are controller relative and path "\\_SB.PCI0.GPI0"405specifies the path to the controller. In order to use these GPIOs in Linux406we need to translate them to the corresponding Linux GPIO descriptors.407 408There is a standard GPIO API for that and it is documented in409Documentation/admin-guide/gpio/.410 411In the above example we can get the corresponding two GPIO descriptors with412a code like this::413 414 #include <linux/gpio/consumer.h>415 ...416 417 struct gpio_desc *irq_desc, *power_desc;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 429There are also devm_* versions of these functions which release the430descriptors once the device is released.431 432See Documentation/firmware-guide/acpi/gpio-properties.rst for more information433about the _DSD binding related to GPIOs.434 435RS-485 support436==============437 438ACPI _DSD (Device Specific Data) can be used to describe RS-485 capability439of UART.440 441For example::442 443 Device (DEV)444 {445 ...446 447 // ACPI 5.1 _DSD used for RS-485 capabilities448 Name (_DSD, Package ()449 {450 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),451 Package ()452 {453 Package () {"rs485-rts-active-low", Zero},454 Package () {"rs485-rx-active-high", Zero},455 Package () {"rs485-rx-during-tx", Zero},456 }457 })458 ...459 460MFD devices461===========462 463The MFD devices register their children as platform devices. For the child464devices there needs to be an ACPI handle that they can use to reference465parts of the ACPI namespace that relate to them. In the Linux MFD subsystem466we provide two ways:467 468 - The children share the parent ACPI handle.469 - The MFD cell can specify the ACPI id of the device.470 471For the first case, the MFD drivers do not need to do anything. The472resulting child platform device will have its ACPI_COMPANION() set to point473to the parent device.474 475If the ACPI namespace has a device that we can match using an ACPI id or ACPI476adr, the cell should be set like::477 478 static struct mfd_cell_acpi_match my_subdevice_cell_acpi_match = {479 .pnpid = "XYZ0001",480 .adr = 0,481 };482 483 static struct mfd_cell my_subdevice_cell = {484 .name = "my_subdevice",485 /* set the resources relative to the parent */486 .acpi_match = &my_subdevice_cell_acpi_match,487 };488 489The ACPI id "XYZ0001" is then used to lookup an ACPI device directly under490the MFD device and if found, that ACPI companion device is bound to the491resulting child platform device.492 493Device Tree namespace link device ID494====================================495 496The Device Tree protocol uses device identification based on the "compatible"497property whose value is a string or an array of strings recognized as device498identifiers by drivers and the driver core. The set of all those strings may be499regarded as a device identification namespace analogous to the ACPI/PNP device500ID namespace. Consequently, in principle it should not be necessary to allocate501a new (and arguably redundant) ACPI/PNP device ID for a devices with an existing502identification string in the Device Tree (DT) namespace, especially if that ID503is only needed to indicate that a given device is compatible with another one,504presumably having a matching driver in the kernel already.505 506In ACPI, the device identification object called _CID (Compatible ID) is used to507list the IDs of devices the given one is compatible with, but those IDs must508belong to one of the namespaces prescribed by the ACPI specification (see509Section 6.1.2 of ACPI 6.0 for details) and the DT namespace is not one of them.510Moreover, the specification mandates that either a _HID or an _ADR identification511object be present for all ACPI objects representing devices (Section 6.1 of ACPI5126.0). For non-enumerable bus types that object must be _HID and its value must513be a device ID from one of the namespaces prescribed by the specification too.514 515The special DT namespace link device ID, PRP0001, provides a means to use the516existing DT-compatible device identification in ACPI and to satisfy the above517requirements following from the ACPI specification at the same time. Namely,518if PRP0001 is returned by _HID, the ACPI subsystem will look for the519"compatible" property in the device object's _DSD and will use the value of that520property to identify the corresponding device in analogy with the original DT521device identification algorithm. If the "compatible" property is not present522or its value is not valid, the device will not be enumerated by the ACPI523subsystem. Otherwise, it will be enumerated automatically as a platform device524(except when an I2C or SPI link from the device to its parent is present, in525which case the ACPI core will leave the device enumeration to the parent's526driver) and the identification strings from the "compatible" property value will527be used to find a driver for the device along with the device IDs listed by _CID528(if present).529 530Analogously, if PRP0001 is present in the list of device IDs returned by _CID,531the identification strings listed by the "compatible" property value (if present532and valid) will be used to look for a driver matching the device, but in that533case their relative priority with respect to the other device IDs listed by534_HID and _CID depends on the position of PRP0001 in the _CID return package.535Specifically, the device IDs returned by _HID and preceding PRP0001 in the _CID536return package will be checked first. Also in that case the bus type the device537will be enumerated to depends on the device ID returned by _HID.538 539For example, the following ACPI sample might be used to enumerate an lm75-type540I2C temperature sensor and match it to the driver using the Device Tree541namespace link::542 543 Device (TMP0)544 {545 Name (_HID, "PRP0001")546 Name (_DSD, Package () {547 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),548 Package () {549 Package () { "compatible", "ti,tmp75" },550 }551 })552 Method (_CRS, 0, Serialized)553 {554 Name (SBUF, ResourceTemplate ()555 {556 I2cSerialBusV2 (0x48, ControllerInitiated,557 400000, AddressingMode7Bit,558 "\\_SB.PCI0.I2C1", 0x00,559 ResourceConsumer, , Exclusive,)560 })561 Return (SBUF)562 }563 }564 565It is valid to define device objects with a _HID returning PRP0001 and without566the "compatible" property in the _DSD or a _CID as long as one of their567ancestors provides a _DSD with a valid "compatible" property. Such device568objects are then simply regarded as additional "blocks" providing hierarchical569configuration information to the driver of the composite ancestor device.570 571However, PRP0001 can only be returned from either _HID or _CID of a device572object if all of the properties returned by the _DSD associated with it (either573the _DSD of the device object itself or the _DSD of its ancestor in the574"composite device" case described above) can be used in the ACPI environment.575Otherwise, the _DSD itself is regarded as invalid and therefore the "compatible"576property returned by it is meaningless.577 578Refer to Documentation/firmware-guide/acpi/DSD-properties-rules.rst for more579information.580 581PCI hierarchy representation582============================583 584Sometimes it could be useful to enumerate a PCI device, knowing its position on585the PCI bus.586 587For example, some systems use PCI devices soldered directly on the mother board,588in a fixed position (ethernet, Wi-Fi, serial ports, etc.). In this conditions it589is possible to refer to these PCI devices knowing their position on the PCI bus590topology.591 592To identify a PCI device, a complete hierarchical description is required, from593the chipset root port to the final device, through all the intermediate594bridges/switches of the board.595 596For example, let's assume we have a system with a PCIe serial port, an597Exar XR17V3521, soldered on the main board. This UART chip also includes59816 GPIOs and we want to add the property ``gpio-line-names`` [1]_ to these pins.599In this case, the ``lspci`` output for this component is::600 601 07:00.0 Serial controller: Exar Corp. XR17V3521 Dual PCIe UART (rev 03)602 603The complete ``lspci`` output (manually reduced in length) is::604 605 00:00.0 Host bridge: Intel Corp... Host Bridge (rev 0d)606 ...607 00:13.0 PCI bridge: Intel Corp... PCI Express Port A #1 (rev fd)608 00:13.1 PCI bridge: Intel Corp... PCI Express Port A #2 (rev fd)609 00:13.2 PCI bridge: Intel Corp... PCI Express Port A #3 (rev fd)610 00:14.0 PCI bridge: Intel Corp... PCI Express Port B #1 (rev fd)611 00:14.1 PCI bridge: Intel Corp... PCI Express Port B #2 (rev fd)612 ...613 05:00.0 PCI bridge: Pericom Semiconductor Device 2404 (rev 05)614 06:01.0 PCI bridge: Pericom Semiconductor Device 2404 (rev 05)615 06:02.0 PCI bridge: Pericom Semiconductor Device 2404 (rev 05)616 06:03.0 PCI bridge: Pericom Semiconductor Device 2404 (rev 05)617 07:00.0 Serial controller: Exar Corp. XR17V3521 Dual PCIe UART (rev 03) <-- Exar618 ...619 620The bus topology is::621 622 -[0000:00]-+-00.0623 ...624 +-13.0-[01]----00.0625 +-13.1-[02]----00.0626 +-13.2-[03]--627 +-14.0-[04]----00.0628 +-14.1-[05-09]----00.0-[06-09]--+-01.0-[07]----00.0 <-- Exar629 | +-02.0-[08]----00.0630 | \-03.0-[09]--631 ...632 \-1f.1633 634To describe this Exar device on the PCI bus, we must start from the ACPI name635of the chipset bridge (also called "root port") with address::636 637 Bus: 0 - Device: 14 - Function: 1638 639To find this information, it is necessary to disassemble the BIOS ACPI tables,640in particular the DSDT (see also [2]_)::641 642 mkdir ~/tables/643 cd ~/tables/644 acpidump > acpidump645 acpixtract -a acpidump646 iasl -e ssdt?.* -d dsdt.dat647 648Now, in the dsdt.dsl, we have to search the device whose address is related to6490x14 (device) and 0x01 (function). In this case we can find the following650device::651 652 Scope (_SB.PCI0)653 {654 ... other definitions follow ...655 Device (RP02)656 {657 Method (_ADR, 0, NotSerialized) // _ADR: Address658 {659 If ((RPA2 != Zero))660 {661 Return (RPA2) /* \RPA2 */662 }663 Else664 {665 Return (0x00140001)666 }667 }668 ... other definitions follow ...669 670and the _ADR method [3]_ returns exactly the device/function couple that671we are looking for. With this information and analyzing the above ``lspci``672output (both the devices list and the devices tree), we can write the following673ACPI description for the Exar PCIe UART, also adding the list of its GPIO line674names::675 676 Scope (_SB.PCI0.RP02)677 {678 Device (BRG1) //Bridge679 {680 Name (_ADR, 0x0000)681 682 Device (BRG2) //Bridge683 {684 Name (_ADR, 0x00010000)685 686 Device (EXAR)687 {688 Name (_ADR, 0x0000)689 690 Name (_DSD, Package ()691 {692 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),693 Package ()694 {695 Package ()696 {697 "gpio-line-names",698 Package ()699 {700 "mode_232",701 "mode_422",702 "mode_485",703 "misc_1",704 "misc_2",705 "misc_3",706 "",707 "",708 "aux_1",709 "aux_2",710 "aux_3",711 }712 }713 }714 })715 }716 }717 }718 }719 720The location "_SB.PCI0.RP02" is obtained by the above investigation in the721dsdt.dsl table, whereas the device names "BRG1", "BRG2" and "EXAR" are722created analyzing the position of the Exar UART in the PCI bus topology.723 724References725==========726 727.. [1] Documentation/firmware-guide/acpi/gpio-properties.rst728 729.. [2] Documentation/admin-guide/acpi/initrd_table_override.rst730 731.. [3] ACPI Specifications, Version 6.3 - Paragraph 6.1.1 _ADR Address)732 https://uefi.org/sites/default/files/resources/ACPI_6_3_May16.pdf,733 referenced 2020-11-18734