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