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 DMA support
  70 ~~~~~~~~~~~
  71 DMA controllers enumerated via ACPI should be registered in the system to
  72 provide generic access to their resources. For example, a driver that would
  73 like to be accessible to slave devices via generic API call
  74 dma_request_slave_channel() must register itself at the end of the probe
  75 function like this:
  76
  77         err = devm_acpi_dma_controller_register(dev, xlate_func, dw);
  78         /* Handle the error if it's not a case of !CONFIG_ACPI */
  79
  80 and implement custom xlate function if needed (usually acpi_dma_simple_xlate()
  81 is enough) which converts the FixedDMA resource provided by struct
  82 acpi_dma_spec into the corresponding DMA channel. A piece of code for that case
  83 could look like:
  84
  85         #ifdef CONFIG_ACPI
  86         struct filter_args {
  87                 /* Provide necessary information for the filter_func */
  88                 ...
  89         };
  90
  91         static bool filter_func(struct dma_chan *chan, void *param)
  92         {
  93                 /* Choose the proper channel */
  94                 ...
  95         }
  96
  97         static struct dma_chan *xlate_func(struct acpi_dma_spec *dma_spec,
  98                         struct acpi_dma *adma)
  99         {
 100                 dma_cap_mask_t cap;
 101                 struct filter_args args;
 102
 103                 /* Prepare arguments for filter_func */
 104                 ...
 105                 return dma_request_channel(cap, filter_func, &args);
 106         }
 107         #else
 108         static struct dma_chan *xlate_func(struct acpi_dma_spec *dma_spec,
 109                         struct acpi_dma *adma)
 110         {
 111                 return NULL;
 112         }
 113         #endif
 114
 115 dma_request_slave_channel() will call xlate_func() for each registered DMA
 116 controller. In the xlate function the proper channel must be chosen based on
 117 information in struct acpi_dma_spec and the properties of the controller
 118 provided by struct acpi_dma.
 119
 120 Clients must call dma_request_slave_channel() with the string parameter that
 121 corresponds to a specific FixedDMA resource. By default "tx" means the first
 122 entry of the FixedDMA resource array, "rx" means the second entry. The table
 123 below shows a layout:
 124
 125         Device (I2C0)
 126         {
 127                 ...
 128                 Method (_CRS, 0, NotSerialized)
 129                 {
 130                         Name (DBUF, ResourceTemplate ()
 131                         {
 132                                 FixedDMA (0x0018, 0x0004, Width32bit, _Y48)
 133                                 FixedDMA (0x0019, 0x0005, Width32bit, )
 134                         })
 135                 ...
 136                 }
 137         }
 138
 139 So, the FixedDMA with request line 0x0018 is "tx" and next one is "rx" in
 140 this example.
 141
 142 In robust cases the client unfortunately needs to call
 143 acpi_dma_request_slave_chan_by_index() directly and therefore choose the
 144 specific FixedDMA resource by its index.
 145
 146 SPI serial bus support
 147 ~~~~~~~~~~~~~~~~~~~~~~
 148 Slave devices behind SPI bus have SpiSerialBus resource attached to them.
 149 This is extracted automatically by the SPI core and the slave devices are
 150 enumerated once spi_register_master() is called by the bus driver.
 151
 152 Here is what the ACPI namespace for a SPI slave might look like:
 153
 154         Device (EEP0)
 155         {
 156                 Name (_ADR, 1)
 157                 Name (_CID, Package() {
 158                         "ATML0025",
 159                         "AT25",
 160                 })
 161                 ...
 162                 Method (_CRS, 0, NotSerialized)
 163                 {
 164                         SPISerialBus(1, PolarityLow, FourWireMode, 8,
 165                                 ControllerInitiated, 1000000, ClockPolarityLow,
 166                                 ClockPhaseFirst, "\\_SB.PCI0.SPI1",)
 167                 }
 168                 ...
 169
 170 The SPI device drivers only need to add ACPI IDs in a similar way than with
 171 the platform device drivers. Below is an example where we add ACPI support
 172 to at25 SPI eeprom driver (this is meant for the above ACPI snippet):
 173
 174         #ifdef CONFIG_ACPI
 175         static struct acpi_device_id at25_acpi_match[] = {
 176                 { "AT25", 0 },
 177                 { },
 178         };
 179         MODULE_DEVICE_TABLE(acpi, at25_acpi_match);
 180         #endif
 181
 182         static struct spi_driver at25_driver = {
 183                 .driver = {
 184                         ...
 185                         .acpi_match_table = ACPI_PTR(at25_acpi_match),
 186                 },
 187         };
 188
 189 Note that this driver actually needs more information like page size of the
 190 eeprom etc. but at the time writing this there is no standard way of
 191 passing those. One idea is to return this in _DSM method like:
 192
 193         Device (EEP0)
 194         {
 195                 ...
 196                 Method (_DSM, 4, NotSerialized)
 197                 {
 198                         Store (Package (6)
 199                         {
 200                                 "byte-len", 1024,
 201                                 "addr-mode", 2,
 202                                 "page-size, 32
 203                         }, Local0)
 204
 205                         // Check UUIDs etc.
 206
 207                         Return (Local0)
 208                 }
 209
 210 Then the at25 SPI driver can get this configuration by calling _DSM on its
 211 ACPI handle like:
 212
 213         struct acpi_buffer output = { ACPI_ALLOCATE_BUFFER, NULL };
 214         struct acpi_object_list input;
 215         acpi_status status;
 216
 217         /* Fill in the input buffer */
 218
 219         status = acpi_evaluate_object(ACPI_HANDLE(&spi->dev), "_DSM",
 220                                       &input, &output);
 221         if (ACPI_FAILURE(status))
 222                 /* Handle the error */
 223
 224         /* Extract the data here */
 225
 226         kfree(output.pointer);
 227
 228 I2C serial bus support
 229 ~~~~~~~~~~~~~~~~~~~~~~
 230 The slaves behind I2C bus controller only need to add the ACPI IDs like
 231 with the platform and SPI drivers. The I2C core automatically enumerates
 232 any slave devices behind the controller device once the adapter is
 233 registered.
 234
 235 Below is an example of how to add ACPI support to the existing mpu3050
 236 input driver:
 237
 238         #ifdef CONFIG_ACPI
 239         static struct acpi_device_id mpu3050_acpi_match[] = {
 240                 { "MPU3050", 0 },
 241                 { },
 242         };
 243         MODULE_DEVICE_TABLE(acpi, mpu3050_acpi_match);
 244         #endif
 245
 246         static struct i2c_driver mpu3050_i2c_driver = {
 247                 .driver = {
 248                         .name   = "mpu3050",
 249                         .owner  = THIS_MODULE,
 250                         .pm     = &mpu3050_pm,
 251                         .of_match_table = mpu3050_of_match,
 252                         .acpi_match_table  ACPI_PTR(mpu3050_acpi_match),
 253                 },
 254                 .probe          = mpu3050_probe,
 255                 .remove         = mpu3050_remove,
 256                 .id_table       = mpu3050_ids,
 257         };
 258
 259 GPIO support
 260 ~~~~~~~~~~~~
 261 ACPI 5 introduced two new resources to describe GPIO connections: GpioIo
 262 and GpioInt. These resources are used be used to pass GPIO numbers used by
 263 the device to the driver. For example:
 264
 265         Method (_CRS, 0, NotSerialized)
 266         {
 267                 Name (SBUF, ResourceTemplate()
 268                 {
 269                         ...
 270                         // Used to power on/off the device
 271                         GpioIo (Exclusive, PullDefault, 0x0000, 0x0000,
 272                                 IoRestrictionOutputOnly, "\\_SB.PCI0.GPI0",
 273                                 0x00, ResourceConsumer,,)
 274                         {
 275                                 // Pin List
 276                                 0x0055
 277                         }
 278
 279                         // Interrupt for the device
 280                         GpioInt (Edge, ActiveHigh, ExclusiveAndWake, PullNone,
 281                                  0x0000, "\\_SB.PCI0.GPI0", 0x00, ResourceConsumer,,)
 282                         {
 283                                 // Pin list
 284                                 0x0058
 285                         }
 286
 287                         ...
 288
 289                 }
 290
 291                 Return (SBUF)
 292         }
 293
 294 These GPIO numbers are controller relative and path "\\_SB.PCI0.GPI0"
 295 specifies the path to the controller. In order to use these GPIOs in Linux
 296 we need to translate them to the corresponding Linux GPIO descriptors.
 297
 298 There is a standard GPIO API for that and is documented in
 299 Documentation/gpio/.
 300
 301 In the above example we can get the corresponding two GPIO descriptors with
 302 a code like this:
 303
 304         #include <linux/gpio/consumer.h>
 305         ...
 306
 307         struct gpio_desc *irq_desc, *power_desc;
 308
 309         irq_desc = gpiod_get_index(dev, NULL, 1);
 310         if (IS_ERR(irq_desc))
 311                 /* handle error */
 312
 313         power_desc = gpiod_get_index(dev, NULL, 0);
 314         if (IS_ERR(power_desc))
 315                 /* handle error */
 316
 317         /* Now we can use the GPIO descriptors */
 318
 319 There are also devm_* versions of these functions which release the
 320 descriptors once the device is released.