Commit c24bc66e authored by Changbin Du's avatar Changbin Du Committed by Rafael J. Wysocki

Documentation: ACPI: move enumeration.txt to firmware-guide/acpi and convert to reST

This converts the plain text documentation to reStructuredText format
and adds it to Sphinx TOC tree.

No essential content change.
Signed-off-by: default avatarChangbin Du <changbin.du@gmail.com>
Reviewed-by: default avatarMauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: default avatarRafael J. Wysocki <rafael.j.wysocki@intel.com>
parent 8a2fe04b
ACPI based device enumeration .. SPDX-License-Identifier: GPL-2.0
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=============================
ACPI Based Device Enumeration
=============================
ACPI 5 introduced a set of new resources (UartTSerialBus, I2cSerialBus, ACPI 5 introduced a set of new resources (UartTSerialBus, I2cSerialBus,
SpiSerialBus, GpioIo and GpioInt) which can be used in enumerating slave SpiSerialBus, GpioIo and GpioInt) which can be used in enumerating slave
devices behind serial bus controllers. devices behind serial bus controllers.
...@@ -11,12 +15,12 @@ that are accessed through memory-mapped registers. ...@@ -11,12 +15,12 @@ that are accessed through memory-mapped registers.
In order to support this and re-use the existing drivers as much as In order to support this and re-use the existing drivers as much as
possible we decided to do following: possible we decided to do following:
o Devices that have no bus connector resource are represented as - Devices that have no bus connector resource are represented as
platform devices. platform devices.
o Devices behind real busses where there is a connector resource - Devices behind real busses where there is a connector resource
are represented as struct spi_device or struct i2c_device are represented as struct spi_device or struct i2c_device
(standard UARTs are not busses so there is no struct uart_device). (standard UARTs are not busses so there is no struct uart_device).
As both ACPI and Device Tree represent a tree of devices (and their As both ACPI and Device Tree represent a tree of devices (and their
resources) this implementation follows the Device Tree way as much as resources) this implementation follows the Device Tree way as much as
...@@ -31,7 +35,8 @@ enumerated from ACPI namespace. This handle can be used to extract other ...@@ -31,7 +35,8 @@ enumerated from ACPI namespace. This handle can be used to extract other
device-specific configuration. There is an example of this below. device-specific configuration. There is an example of this below.
Platform bus support Platform bus support
~~~~~~~~~~~~~~~~~~~~ ====================
Since we are using platform devices to represent devices that are not Since we are using platform devices to represent devices that are not
connected to any physical bus we only need to implement a platform driver connected to any physical bus we only need to implement a platform driver
for the device and add supported ACPI IDs. If this same IP-block is used on for the device and add supported ACPI IDs. If this same IP-block is used on
...@@ -39,7 +44,7 @@ some other non-ACPI platform, the driver might work out of the box or needs ...@@ -39,7 +44,7 @@ some other non-ACPI platform, the driver might work out of the box or needs
some minor changes. some minor changes.
Adding ACPI support for an existing driver should be pretty Adding ACPI support for an existing driver should be pretty
straightforward. Here is the simplest example: straightforward. Here is the simplest example::
#ifdef CONFIG_ACPI #ifdef CONFIG_ACPI
static const struct acpi_device_id mydrv_acpi_match[] = { static const struct acpi_device_id mydrv_acpi_match[] = {
...@@ -61,12 +66,13 @@ configuring GPIOs it can get its ACPI handle and extract this information ...@@ -61,12 +66,13 @@ configuring GPIOs it can get its ACPI handle and extract this information
from ACPI tables. from ACPI tables.
DMA support DMA support
~~~~~~~~~~~ ===========
DMA controllers enumerated via ACPI should be registered in the system to DMA controllers enumerated via ACPI should be registered in the system to
provide generic access to their resources. For example, a driver that would provide generic access to their resources. For example, a driver that would
like to be accessible to slave devices via generic API call like to be accessible to slave devices via generic API call
dma_request_slave_channel() must register itself at the end of the probe dma_request_slave_channel() must register itself at the end of the probe
function like this: function like this::
err = devm_acpi_dma_controller_register(dev, xlate_func, dw); err = devm_acpi_dma_controller_register(dev, xlate_func, dw);
/* Handle the error if it's not a case of !CONFIG_ACPI */ /* Handle the error if it's not a case of !CONFIG_ACPI */
...@@ -74,7 +80,7 @@ function like this: ...@@ -74,7 +80,7 @@ function like this:
and implement custom xlate function if needed (usually acpi_dma_simple_xlate() and implement custom xlate function if needed (usually acpi_dma_simple_xlate()
is enough) which converts the FixedDMA resource provided by struct is enough) which converts the FixedDMA resource provided by struct
acpi_dma_spec into the corresponding DMA channel. A piece of code for that case acpi_dma_spec into the corresponding DMA channel. A piece of code for that case
could look like: could look like::
#ifdef CONFIG_ACPI #ifdef CONFIG_ACPI
struct filter_args { struct filter_args {
...@@ -114,7 +120,7 @@ provided by struct acpi_dma. ...@@ -114,7 +120,7 @@ provided by struct acpi_dma.
Clients must call dma_request_slave_channel() with the string parameter that Clients must call dma_request_slave_channel() with the string parameter that
corresponds to a specific FixedDMA resource. By default "tx" means the first corresponds to a specific FixedDMA resource. By default "tx" means the first
entry of the FixedDMA resource array, "rx" means the second entry. The table entry of the FixedDMA resource array, "rx" means the second entry. The table
below shows a layout: below shows a layout::
Device (I2C0) Device (I2C0)
{ {
...@@ -138,12 +144,13 @@ acpi_dma_request_slave_chan_by_index() directly and therefore choose the ...@@ -138,12 +144,13 @@ acpi_dma_request_slave_chan_by_index() directly and therefore choose the
specific FixedDMA resource by its index. specific FixedDMA resource by its index.
SPI serial bus support SPI serial bus support
~~~~~~~~~~~~~~~~~~~~~~ ======================
Slave devices behind SPI bus have SpiSerialBus resource attached to them. Slave devices behind SPI bus have SpiSerialBus resource attached to them.
This is extracted automatically by the SPI core and the slave devices are This is extracted automatically by the SPI core and the slave devices are
enumerated once spi_register_master() is called by the bus driver. enumerated once spi_register_master() is called by the bus driver.
Here is what the ACPI namespace for a SPI slave might look like: Here is what the ACPI namespace for a SPI slave might look like::
Device (EEP0) Device (EEP0)
{ {
...@@ -163,7 +170,7 @@ Here is what the ACPI namespace for a SPI slave might look like: ...@@ -163,7 +170,7 @@ Here is what the ACPI namespace for a SPI slave might look like:
The SPI device drivers only need to add ACPI IDs in a similar way than with The SPI device drivers only need to add ACPI IDs in a similar way than with
the platform device drivers. Below is an example where we add ACPI support the platform device drivers. Below is an example where we add ACPI support
to at25 SPI eeprom driver (this is meant for the above ACPI snippet): to at25 SPI eeprom driver (this is meant for the above ACPI snippet)::
#ifdef CONFIG_ACPI #ifdef CONFIG_ACPI
static const struct acpi_device_id at25_acpi_match[] = { static const struct acpi_device_id at25_acpi_match[] = {
...@@ -182,7 +189,7 @@ to at25 SPI eeprom driver (this is meant for the above ACPI snippet): ...@@ -182,7 +189,7 @@ to at25 SPI eeprom driver (this is meant for the above ACPI snippet):
Note that this driver actually needs more information like page size of the Note that this driver actually needs more information like page size of the
eeprom etc. but at the time writing this there is no standard way of eeprom etc. but at the time writing this there is no standard way of
passing those. One idea is to return this in _DSM method like: passing those. One idea is to return this in _DSM method like::
Device (EEP0) Device (EEP0)
{ {
...@@ -202,7 +209,7 @@ passing those. One idea is to return this in _DSM method like: ...@@ -202,7 +209,7 @@ passing those. One idea is to return this in _DSM method like:
} }
Then the at25 SPI driver can get this configuration by calling _DSM on its Then the at25 SPI driver can get this configuration by calling _DSM on its
ACPI handle like: ACPI handle like::
struct acpi_buffer output = { ACPI_ALLOCATE_BUFFER, NULL }; struct acpi_buffer output = { ACPI_ALLOCATE_BUFFER, NULL };
struct acpi_object_list input; struct acpi_object_list input;
...@@ -220,14 +227,15 @@ ACPI handle like: ...@@ -220,14 +227,15 @@ ACPI handle like:
kfree(output.pointer); kfree(output.pointer);
I2C serial bus support I2C serial bus support
~~~~~~~~~~~~~~~~~~~~~~ ======================
The slaves behind I2C bus controller only need to add the ACPI IDs like The slaves behind I2C bus controller only need to add the ACPI IDs like
with the platform and SPI drivers. The I2C core automatically enumerates with the platform and SPI drivers. The I2C core automatically enumerates
any slave devices behind the controller device once the adapter is any slave devices behind the controller device once the adapter is
registered. registered.
Below is an example of how to add ACPI support to the existing mpu3050 Below is an example of how to add ACPI support to the existing mpu3050
input driver: input driver::
#ifdef CONFIG_ACPI #ifdef CONFIG_ACPI
static const struct acpi_device_id mpu3050_acpi_match[] = { static const struct acpi_device_id mpu3050_acpi_match[] = {
...@@ -251,56 +259,57 @@ input driver: ...@@ -251,56 +259,57 @@ input driver:
}; };
GPIO support GPIO support
~~~~~~~~~~~~ ============
ACPI 5 introduced two new resources to describe GPIO connections: GpioIo ACPI 5 introduced two new resources to describe GPIO connections: GpioIo
and GpioInt. These resources can be used to pass GPIO numbers used by and GpioInt. These resources can be used to pass GPIO numbers used by
the device to the driver. ACPI 5.1 extended this with _DSD (Device the device to the driver. ACPI 5.1 extended this with _DSD (Device
Specific Data) which made it possible to name the GPIOs among other things. Specific Data) which made it possible to name the GPIOs among other things.
For example: For example::
Device (DEV) Device (DEV)
{
Method (_CRS, 0, NotSerialized)
{ {
Name (SBUF, ResourceTemplate() Method (_CRS, 0, NotSerialized)
{ {
... Name (SBUF, ResourceTemplate()
// Used to power on/off the device
GpioIo (Exclusive, PullDefault, 0x0000, 0x0000,
IoRestrictionOutputOnly, "\\_SB.PCI0.GPI0",
0x00, ResourceConsumer,,)
{ {
// Pin List ...
0x0055 // Used to power on/off the device
} GpioIo (Exclusive, PullDefault, 0x0000, 0x0000,
IoRestrictionOutputOnly, "\\_SB.PCI0.GPI0",
0x00, ResourceConsumer,,)
{
// Pin List
0x0055
}
// Interrupt for the device
GpioInt (Edge, ActiveHigh, ExclusiveAndWake, PullNone,
0x0000, "\\_SB.PCI0.GPI0", 0x00, ResourceConsumer,,)
{
// Pin list
0x0058
}
...
// Interrupt for the device
GpioInt (Edge, ActiveHigh, ExclusiveAndWake, PullNone,
0x0000, "\\_SB.PCI0.GPI0", 0x00, ResourceConsumer,,)
{
// Pin list
0x0058
} }
... Return (SBUF)
} }
Return (SBUF) // ACPI 5.1 _DSD used for naming the GPIOs
} Name (_DSD, Package ()
// ACPI 5.1 _DSD used for naming the GPIOs
Name (_DSD, Package ()
{
ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
Package ()
{ {
Package () {"power-gpios", Package() {^DEV, 0, 0, 0 }}, ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
Package () {"irq-gpios", Package() {^DEV, 1, 0, 0 }}, Package ()
} {
}) Package () {"power-gpios", Package() {^DEV, 0, 0, 0 }},
... Package () {"irq-gpios", Package() {^DEV, 1, 0, 0 }},
}
})
...
These GPIO numbers are controller relative and path "\\_SB.PCI0.GPI0" These GPIO numbers are controller relative and path "\\_SB.PCI0.GPI0"
specifies the path to the controller. In order to use these GPIOs in Linux specifies the path to the controller. In order to use these GPIOs in Linux
...@@ -310,7 +319,7 @@ There is a standard GPIO API for that and is documented in ...@@ -310,7 +319,7 @@ There is a standard GPIO API for that and is documented in
Documentation/gpio/. Documentation/gpio/.
In the above example we can get the corresponding two GPIO descriptors with In the above example we can get the corresponding two GPIO descriptors with
a code like this: a code like this::
#include <linux/gpio/consumer.h> #include <linux/gpio/consumer.h>
... ...
...@@ -334,21 +343,22 @@ See Documentation/acpi/gpio-properties.txt for more information about the ...@@ -334,21 +343,22 @@ See Documentation/acpi/gpio-properties.txt for more information about the
_DSD binding related to GPIOs. _DSD binding related to GPIOs.
MFD devices MFD devices
~~~~~~~~~~~ ===========
The MFD devices register their children as platform devices. For the child The MFD devices register their children as platform devices. For the child
devices there needs to be an ACPI handle that they can use to reference devices there needs to be an ACPI handle that they can use to reference
parts of the ACPI namespace that relate to them. In the Linux MFD subsystem parts of the ACPI namespace that relate to them. In the Linux MFD subsystem
we provide two ways: we provide two ways:
o The children share the parent ACPI handle. - The children share the parent ACPI handle.
o The MFD cell can specify the ACPI id of the device. - The MFD cell can specify the ACPI id of the device.
For the first case, the MFD drivers do not need to do anything. The For the first case, the MFD drivers do not need to do anything. The
resulting child platform device will have its ACPI_COMPANION() set to point resulting child platform device will have its ACPI_COMPANION() set to point
to the parent device. to the parent device.
If the ACPI namespace has a device that we can match using an ACPI id or ACPI If the ACPI namespace has a device that we can match using an ACPI id or ACPI
adr, the cell should be set like: adr, the cell should be set like::
static struct mfd_cell_acpi_match my_subdevice_cell_acpi_match = { static struct mfd_cell_acpi_match my_subdevice_cell_acpi_match = {
.pnpid = "XYZ0001", .pnpid = "XYZ0001",
...@@ -366,7 +376,8 @@ the MFD device and if found, that ACPI companion device is bound to the ...@@ -366,7 +376,8 @@ the MFD device and if found, that ACPI companion device is bound to the
resulting child platform device. resulting child platform device.
Device Tree namespace link device ID Device Tree namespace link device ID
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ====================================
The Device Tree protocol uses device identification based on the "compatible" The Device Tree protocol uses device identification based on the "compatible"
property whose value is a string or an array of strings recognized as device property whose value is a string or an array of strings recognized as device
identifiers by drivers and the driver core. The set of all those strings may be identifiers by drivers and the driver core. The set of all those strings may be
...@@ -449,4 +460,4 @@ the _DSD of the device object itself or the _DSD of its ancestor in the ...@@ -449,4 +460,4 @@ the _DSD of the device object itself or the _DSD of its ancestor in the
Otherwise, the _DSD itself is regarded as invalid and therefore the "compatible" Otherwise, the _DSD itself is regarded as invalid and therefore the "compatible"
property returned by it is meaningless. property returned by it is meaningless.
Refer to DSD-properties-rules.txt for more information. Refer to :doc:`DSD-properties-rules` for more information.
...@@ -8,3 +8,4 @@ ACPI Support ...@@ -8,3 +8,4 @@ ACPI Support
:maxdepth: 1 :maxdepth: 1
namespace namespace
enumeration
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment