ACPI 5 introduced a set of new resources (UartTSerialBus, I2cSerialBus, SpiSerialBus, GpioIo and GpioInt) which can be used in enumerating slave devices behind serial bus controllers.
In addition we are starting to see peripherals integrated in the SoC/Chipset to appear only in ACPI namespace. These are typically devices that are accessed through memory-mapped registers.
In order to support this and re-use the existing drivers as much as possible we decided to do following:
o Devices that have no bus connector resource are represented as platform devices.
o Devices behind real busses where there is a connector resource are represented as struct spi_device or struct i2c_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 resources) this implementation follows the Device Tree way as much as possible.
The ACPI implementation enumerates devices behind busses (platform, SPI and I2C), creates the physical devices and binds them to their ACPI handle in the ACPI namespace.
This means that when ACPI_HANDLE(dev) returns non-NULL the device was enumerated from ACPI namespace. This handle can be used to extract other device-specific configuration. There is an example of this below.
Platform bus support ~~~~~~~~~~~~~~~~~~~~ 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 for the device and add supported ACPI IDs. If this same IP-block is used on some other non-ACPI platform, the driver might work out of the box or needs some minor changes.
Adding ACPI support for an existing driver should be pretty straightforward. Here is the simplest example:
If the driver needs to perform more complex initialization like getting and configuring GPIOs it can get its ACPI handle and extract this information from ACPI tables.
Currently the kernel is not able to automatically determine from which ACPI device it should make the corresponding platform device so we need to add the ACPI device explicitly to acpi_platform_device_ids list defined in drivers/acpi/acpi_platform.c. This limitation is only for the platform devices, SPI and I2C devices are created automatically as described below.
DMA support ~~~~~~~~~~~ DMA controllers enumerated via ACPI should be registered in the system to provide generic access to their resources. For example, a driver that would like to be accessible to slave devices via generic API call dma_request_slave_channel() must register itself at the end of the probe function like this:
err = devm_acpi_dma_controller_register(dev, xlate_func, dw); /* Handle the error if it's not a case of !CONFIG_ACPI */
and implement custom xlate function if needed (usually acpi_dma_simple_xlate() 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 could look like:
#ifdef CONFIG_ACPI struct filter_args { /* Provide necessary information for the filter_func */ ... };
dma_request_slave_channel() will call xlate_func() for each registered DMA controller. In the xlate function the proper channel must be chosen based on information in struct acpi_dma_spec and the properties of the controller provided by struct acpi_dma.
Clients must call dma_request_slave_channel() with the string parameter that 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 below shows a layout:
So, the FixedDMA with request line 0x0018 is "tx" and next one is "rx" in this example.
In robust cases the client unfortunately needs to call acpi_dma_request_slave_chan_by_index() directly and therefore choose the specific FixedDMA resource by its index.
SPI serial bus support
Slave devices behind SPI bus have SpiSerialBus resource attached to them. This is extracted automatically by the SPI core and the slave devices are enumerated once spi_register_master() is called by the bus driver.
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 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):
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 passing those. One idea is to return this in _DSM method like:
Then the at25 SPI driver can get this configation by calling _DSM on its ACPI handle like:
struct acpi_buffer output = { ACPI_ALLOCATE_BUFFER, NULL };
struct acpi_object_list input;
acpi_status status;
/* Fill in the input buffer */
status = acpi_evaluate_object(ACPI_HANDLE(&spi->dev), "_DSM",
&input, &output);
if (ACPI_FAILURE(status))
/* Handle the error */
/* Extract the data here */
kfree(output.pointer);
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 any slave devices behind the controller device once the adapter is registered.
Below is an example of how to add ACPI support to the existing mpu3050 input driver:
ACPI 5 introduced two new resources to describe GPIO connections: GpioIo and GpioInt. These resources are used be used to pass GPIO numbers used by the device to the driver. For example:
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
}
// Interrupt for the device
GpioInt (Edge, ActiveHigh, ExclusiveAndWake, PullNone,
0x0000, "\\_SB.PCI0.GPI0", 0x00, ResourceConsumer,,)
{
// Pin list
0x0058
}
...
}
Return (SBUF)
}
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 we need to translate them to the Linux GPIO numbers.
The driver can do this by including <linux/acpi_gpio.h> and then calling acpi_get_gpio(path, gpio). This will return the Linux GPIO number or negative errno if there was no translation found.
In a simple case of just getting the Linux GPIO number from device resources one can use acpi_get_gpio_by_index() helper function. It takes pointer to the device and index of the GpioIo/GpioInt descriptor in the device resources list. For example:
int gpio_irq, gpio_power;
int ret;
gpio_irq = acpi_get_gpio_by_index(dev, 1, NULL);
if (gpio_irq < 0)
/* handle error */
gpio_power = acpi_get_gpio_by_index(dev, 0, NULL);
if (gpio_power < 0)
/* handle error */
/* Now we can use the GPIO numbers */
Other GpioIo parameters must be converted first by the driver to be suitable to the gpiolib before passing them.
In case of GpioInt resource an additional call to gpio_to_irq() must be done before calling request_irq().
MFD devices
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
parts of the ACPI namespace that relate to them. In the Linux MFD subsystem
we provide two ways:
o The children share the parent ACPI handle.
o 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
resulting child platform device will have its ACPI_COMPANION() set to point
to the parent device.
If the ACPI namespace has a device that we can match using an ACPI id,
the id should be set like:
static struct mfd_cell my_subdevice_cell = {
.name = "my_subdevice",
/* set the resources relative to the parent */
.acpi_pnpid = "XYZ0001",
};
The ACPI id "XYZ0001" is then used to lookup an ACPI device directly under
the MFD device and if found, that ACPI companion device is bound to the
resulting child platform device.
