Documentation/acpi/enumeration.txt

   1 ACPI based device enumeration
   2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   3 ACPI 5 introduced a set of new resources (UartTSerialBus, I2cSerialBus,
   4 SpiSerialBus, GpioIo and GpioInt) which can be used in enumerating slave
   5 devices behind serial bus controllers.
   6
   7 In addition we are starting to see peripherals integrated in the
   8 SoC/Chipset to appear only in ACPI namespace. These are typically devices
   9 that are accessed through memory-mapped registers.
  10
  11 In order to support this and re-use the existing drivers as much as
  12 possible we decided to do following:
  13
  14         o Devices that have no bus connector resource are represented as
  15           platform devices.
  16
  17         o Devices behind real busses where there is a connector resource
  18           are represented as struct spi_device or struct i2c_device
  19           (standard UARTs are not busses so there is no struct uart_device).
  20
  21 As both ACPI and Device Tree represent a tree of devices (and their
  22 resources) this implementation follows the Device Tree way as much as
  23 possible.
  24
  25 The ACPI implementation enumerates devices behind busses (platform, SPI and
  26 I2C), creates the physical devices and binds them to their ACPI handle in
  27 the ACPI namespace.
  28
  29 This means that when ACPI_HANDLE(dev) returns non-NULL the device was
  30 enumerated from ACPI namespace. This handle can be used to extract other
  31 device-specific configuration. There is an example of this below.
  32
  33 Platform bus support
  34 ~~~~~~~~~~~~~~~~~~~~
  35 Since we are using platform devices to represent devices that are not
  36 connected to any physical bus we only need to implement a platform driver
  37 for the device and add supported ACPI IDs. If this same IP-block is used on
  38 some other non-ACPI platform, the driver might work out of the box or needs
  39 some minor changes.
  40
  41 Adding ACPI support for an existing driver should be pretty
  42 straightforward. Here is the simplest example:
  43
  44         #ifdef CONFIG_ACPI
  45         static struct acpi_device_id mydrv_acpi_match[] = {
  46                 /* ACPI IDs here */
  47                 { }
  48         };
  49         MODULE_DEVICE_TABLE(acpi, mydrv_acpi_match);
  50         #endif
  51
  52         static struct platform_driver my_driver = {
  53                 ...
  54                 .driver = {
  55                         .acpi_match_table = ACPI_PTR(mydrv_acpi_match),
  56                 },
  57         };
  58
  59 If the driver needs to perform more complex initialization like getting and
  60 configuring GPIOs it can get its ACPI handle and extract this information
  61 from ACPI tables.
  62
  63 Currently the kernel is not able to automatically determine from which ACPI
  64 device it should make the corresponding platform device so we need to add
  65 the ACPI device explicitly to acpi_platform_device_ids list defined in
  66 drivers/acpi/acpi_platform.c. This limitation is only for the platform
  67 devices, SPI and I2C devices are created automatically as described below.
  68
  69 SPI serial bus support
  70 ~~~~~~~~~~~~~~~~~~~~~~
  71 Slave devices behind SPI bus have SpiSerialBus resource attached to them.
  72 This is extracted automatically by the SPI core and the slave devices are
  73 enumerated once spi_register_master() is called by the bus driver.
  74
  75 Here is what the ACPI namespace for a SPI slave might look like:
  76
  77         Device (EEP0)
  78         {
  79                 Name (_ADR, 1)
  80                 Name (_CID, Package() {
  81                         "ATML0025",
  82                         "AT25",
  83                 })
  84                 ...
  85                 Method (_CRS, 0, NotSerialized)
  86                 {
  87                         SPISerialBus(1, PolarityLow, FourWireMode, 8,
  88                                 ControllerInitiated, 1000000, ClockPolarityLow,
  89                                 ClockPhaseFirst, "\\_SB.PCI0.SPI1",)
  90                 }
  91                 ...
  92
  93 The SPI device drivers only need to add ACPI IDs in a similar way than with
  94 the platform device drivers. Below is an example where we add ACPI support
  95 to at25 SPI eeprom driver (this is meant for the above ACPI snippet):
  96
  97         #ifdef CONFIG_ACPI
  98         static struct acpi_device_id at25_acpi_match[] = {
  99                 { "AT25", 0 },
 100                 { },
 101         };
 102         MODULE_DEVICE_TABLE(acpi, at25_acpi_match);
 103         #endif
 104
 105         static struct spi_driver at25_driver = {
 106                 .driver = {
 107                         ...
 108                         .acpi_match_table = ACPI_PTR(at25_acpi_match),
 109                 },
 110         };
 111
 112 Note that this driver actually needs more information like page size of the
 113 eeprom etc. but at the time writing this there is no standard way of
 114 passing those. One idea is to return this in _DSM method like:
 115
 116         Device (EEP0)
 117         {
 118                 ...
 119                 Method (_DSM, 4, NotSerialized)
 120                 {
 121                         Store (Package (6)
 122                         {
 123                                 "byte-len", 1024,
 124                                 "addr-mode", 2,
 125                                 "page-size, 32
 126                         }, Local0)
 127
 128                         // Check UUIDs etc.
 129
 130                         Return (Local0)
 131                 }
 132
 133 Then the at25 SPI driver can get this configation by calling _DSM on its
 134 ACPI handle like:
 135
 136         struct acpi_buffer output = { ACPI_ALLOCATE_BUFFER, NULL };
 137         struct acpi_object_list input;
 138         acpi_status status;
 139
 140         /* Fill in the input buffer */
 141
 142         status = acpi_evaluate_object(ACPI_HANDLE(&spi->dev), "_DSM",
 143                                       &input, &output);
 144         if (ACPI_FAILURE(status))
 145                 /* Handle the error */
 146
 147         /* Extract the data here */
 148
 149         kfree(output.pointer);
 150
 151 I2C serial bus support
 152 ~~~~~~~~~~~~~~~~~~~~~~
 153 The slaves behind I2C bus controller only need to add the ACPI IDs like
 154 with the platform and SPI drivers. However the I2C bus controller driver
 155 needs to call acpi_i2c_register_devices() after it has added the adapter.
 156
 157 An I2C bus (controller) driver does:
 158
 159         ...
 160         ret = i2c_add_numbered_adapter(adapter);
 161         if (ret)
 162                 /* handle error */
 163
 164         of_i2c_register_devices(adapter);
 165         /* Enumerate the slave devices behind this bus via ACPI */
 166         acpi_i2c_register_devices(adapter);
 167
 168 Below is an example of how to add ACPI support to the existing mpu3050
 169 input driver:
 170
 171         #ifdef CONFIG_ACPI
 172         static struct acpi_device_id mpu3050_acpi_match[] = {
 173                 { "MPU3050", 0 },
 174                 { },
 175         };
 176         MODULE_DEVICE_TABLE(acpi, mpu3050_acpi_match);
 177         #endif
 178
 179         static struct i2c_driver mpu3050_i2c_driver = {
 180                 .driver = {
 181                         .name   = "mpu3050",
 182                         .owner  = THIS_MODULE,
 183                         .pm     = &mpu3050_pm,
 184                         .of_match_table = mpu3050_of_match,
 185                         .acpi_match_table  ACPI_PTR(mpu3050_acpi_match),
 186                 },
 187                 .probe          = mpu3050_probe,
 188                 .remove         = mpu3050_remove,
 189                 .id_table       = mpu3050_ids,
 190         };
 191
 192 GPIO support
 193 ~~~~~~~~~~~~
 194 ACPI 5 introduced two new resources to describe GPIO connections: GpioIo
 195 and GpioInt. These resources are used be used to pass GPIO numbers used by
 196 the device to the driver. For example:
 197
 198         Method (_CRS, 0, NotSerialized)
 199         {
 200                 Name (SBUF, ResourceTemplate()
 201                 {
 202                         ...
 203                         // Used to power on/off the device
 204                         GpioIo (Exclusive, PullDefault, 0x0000, 0x0000,
 205                                 IoRestrictionOutputOnly, "\\_SB.PCI0.GPI0",
 206                                 0x00, ResourceConsumer,,)
 207                         {
 208                                 // Pin List
 209                                 0x0055
 210                         }
 211
 212                         // Interrupt for the device
 213                         GpioInt (Edge, ActiveHigh, ExclusiveAndWake, PullNone,
 214                                  0x0000, "\\_SB.PCI0.GPI0", 0x00, ResourceConsumer,,)
 215                         {
 216                                 // Pin list
 217                                 0x0058
 218                         }
 219
 220                         ...
 221
 222                 }
 223
 224                 Return (SBUF)
 225         }
 226
 227 These GPIO numbers are controller relative and path "\\_SB.PCI0.GPI0"
 228 specifies the path to the controller. In order to use these GPIOs in Linux
 229 we need to translate them to the Linux GPIO numbers.
 230
 231 The driver can do this by including <linux/acpi_gpio.h> and then calling
 232 acpi_get_gpio(path, gpio). This will return the Linux GPIO number or
 233 negative errno if there was no translation found.
 234
 235 In a simple case of just getting the Linux GPIO number from device
 236 resources one can use acpi_get_gpio_by_index() helper function. It takes
 237 pointer to the device and index of the GpioIo/GpioInt descriptor in the
 238 device resources list. For example:
 239
 240         int gpio_irq, gpio_power;
 241         int ret;
 242
 243         gpio_irq = acpi_get_gpio_by_index(dev, 1, NULL);
 244         if (gpio_irq < 0)
 245                 /* handle error */
 246
 247         gpio_power = acpi_get_gpio_by_index(dev, 0, NULL);
 248         if (gpio_power < 0)
 249                 /* handle error */
 250
 251         /* Now we can use the GPIO numbers */
 252
 253 Other GpioIo parameters must be converted first by the driver to be
 254 suitable to the gpiolib before passing them.
 255
 256 In case of GpioInt resource an additional call to gpio_to_irq() must be
 257 done before calling request_irq().