Blame view
Documentation/acpi/enumeration.txt
14.1 KB
59c398780 ACPI: add documen... |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 |
ACPI based device enumeration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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: #ifdef CONFIG_ACPI |
1a147ed75 ACPI: Constify AC... |
45 |
static const struct acpi_device_id mydrv_acpi_match[] = { |
59c398780 ACPI: add documen... |
46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 |
/* ACPI IDs here */ { } }; MODULE_DEVICE_TABLE(acpi, mydrv_acpi_match); #endif static struct platform_driver my_driver = { ... .driver = { .acpi_match_table = ACPI_PTR(mydrv_acpi_match), }, }; 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. |
1b2e98bc1 dma: acpi-dma: in... |
62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 |
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 */ ... }; static bool filter_func(struct dma_chan *chan, void *param) { /* Choose the proper channel */ ... } static struct dma_chan *xlate_func(struct acpi_dma_spec *dma_spec, struct acpi_dma *adma) { dma_cap_mask_t cap; struct filter_args args; /* Prepare arguments for filter_func */ ... return dma_request_channel(cap, filter_func, &args); } #else static struct dma_chan *xlate_func(struct acpi_dma_spec *dma_spec, struct acpi_dma *adma) { return NULL; } #endif 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: Device (I2C0) { ... Method (_CRS, 0, NotSerialized) { Name (DBUF, ResourceTemplate () { FixedDMA (0x0018, 0x0004, Width32bit, _Y48) FixedDMA (0x0019, 0x0005, Width32bit, ) }) ... } } 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. |
59c398780 ACPI: add documen... |
138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 |
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: Device (EEP0) { Name (_ADR, 1) Name (_CID, Package() { "ATML0025", "AT25", }) ... Method (_CRS, 0, NotSerialized) { SPISerialBus(1, PolarityLow, FourWireMode, 8, ControllerInitiated, 1000000, ClockPolarityLow, ClockPhaseFirst, "\\_SB.PCI0.SPI1",) } ... 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): #ifdef CONFIG_ACPI |
1a147ed75 ACPI: Constify AC... |
167 |
static const struct acpi_device_id at25_acpi_match[] = { |
59c398780 ACPI: add documen... |
168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 |
{ "AT25", 0 }, { }, }; MODULE_DEVICE_TABLE(acpi, at25_acpi_match); #endif static struct spi_driver at25_driver = { .driver = { ... .acpi_match_table = ACPI_PTR(at25_acpi_match), }, }; 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: Device (EEP0) { ... Method (_DSM, 4, NotSerialized) { Store (Package (6) { "byte-len", 1024, "addr-mode", 2, "page-size, 32 }, Local0) // Check UUIDs etc. Return (Local0) } |
2d6674b8e Documentation/acp... |
201 |
Then the at25 SPI driver can get this configuration by calling _DSM on its |
59c398780 ACPI: add documen... |
202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 |
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); I2C serial bus support ~~~~~~~~~~~~~~~~~~~~~~ The slaves behind I2C bus controller only need to add the ACPI IDs like |
55e71edb8 i2c: move ACPI he... |
222 223 224 |
with the platform and SPI drivers. The I2C core automatically enumerates any slave devices behind the controller device once the adapter is registered. |
59c398780 ACPI: add documen... |
225 226 227 228 229 |
Below is an example of how to add ACPI support to the existing mpu3050 input driver: #ifdef CONFIG_ACPI |
1a147ed75 ACPI: Constify AC... |
230 |
static const struct acpi_device_id mpu3050_acpi_match[] = { |
59c398780 ACPI: add documen... |
231 232 233 234 235 236 237 238 239 240 241 242 |
{ "MPU3050", 0 }, { }, }; MODULE_DEVICE_TABLE(acpi, mpu3050_acpi_match); #endif static struct i2c_driver mpu3050_i2c_driver = { .driver = { .name = "mpu3050", .owner = THIS_MODULE, .pm = &mpu3050_pm, .of_match_table = mpu3050_of_match, |
de14da2a7 ACPI / Documentat... |
243 |
.acpi_match_table = ACPI_PTR(mpu3050_acpi_match), |
59c398780 ACPI: add documen... |
244 245 |
}, .probe = mpu3050_probe, |
63a29f744 Documentation: re... |
246 |
.remove = mpu3050_remove, |
59c398780 ACPI: add documen... |
247 248 249 250 251 252 |
.id_table = mpu3050_ids, }; GPIO support ~~~~~~~~~~~~ ACPI 5 introduced two new resources to describe GPIO connections: GpioIo |
2375a212c ACPI / documentat... |
253 |
and GpioInt. These resources can be used to pass GPIO numbers used by |
56b858dfa ACPI: Update GPIO... |
254 255 |
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. |
59c398780 ACPI: add documen... |
256 |
|
56b858dfa ACPI: Update GPIO... |
257 258 259 260 |
For example: Device (DEV) { |
59c398780 ACPI: add documen... |
261 262 263 264 |
Method (_CRS, 0, NotSerialized) { Name (SBUF, ResourceTemplate() { |
12028d2d2 gpiolib-acpi: int... |
265 266 |
... // Used to power on/off the device |
59c398780 ACPI: add documen... |
267 268 269 270 271 272 273 |
GpioIo (Exclusive, PullDefault, 0x0000, 0x0000, IoRestrictionOutputOnly, "\\_SB.PCI0.GPI0", 0x00, ResourceConsumer,,) { // Pin List 0x0055 } |
12028d2d2 gpiolib-acpi: int... |
274 275 276 277 278 279 280 281 |
// Interrupt for the device GpioInt (Edge, ActiveHigh, ExclusiveAndWake, PullNone, 0x0000, "\\_SB.PCI0.GPI0", 0x00, ResourceConsumer,,) { // Pin list 0x0058 } |
59c398780 ACPI: add documen... |
282 |
... |
59c398780 ACPI: add documen... |
283 |
} |
12028d2d2 gpiolib-acpi: int... |
284 285 |
Return (SBUF) |
59c398780 ACPI: add documen... |
286 |
} |
56b858dfa ACPI: Update GPIO... |
287 288 289 290 291 292 293 294 295 296 297 |
// 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 }}, Package () {"irq-gpios", Package() {^DEV, 1, 0, 0 }}, } }) ... |
59c398780 ACPI: add documen... |
298 299 |
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 |
ccb6fbb99 Documentation / A... |
300 |
we need to translate them to the corresponding Linux GPIO descriptors. |
59c398780 ACPI: add documen... |
301 |
|
ccb6fbb99 Documentation / A... |
302 |
There is a standard GPIO API for that and is documented in |
51caa05a8 Documentation / A... |
303 |
Documentation/gpio/. |
12028d2d2 gpiolib-acpi: int... |
304 |
|
ccb6fbb99 Documentation / A... |
305 306 |
In the above example we can get the corresponding two GPIO descriptors with a code like this: |
45f394391 gpiolib / ACPI: d... |
307 308 309 310 311 |
#include <linux/gpio/consumer.h> ... struct gpio_desc *irq_desc, *power_desc; |
56b858dfa ACPI: Update GPIO... |
312 |
irq_desc = gpiod_get(dev, "irq"); |
45f394391 gpiolib / ACPI: d... |
313 314 |
if (IS_ERR(irq_desc)) /* handle error */ |
56b858dfa ACPI: Update GPIO... |
315 |
power_desc = gpiod_get(dev, "power"); |
45f394391 gpiolib / ACPI: d... |
316 317 318 319 |
if (IS_ERR(power_desc)) /* handle error */ /* Now we can use the GPIO descriptors */ |
ccb6fbb99 Documentation / A... |
320 321 |
There are also devm_* versions of these functions which release the descriptors once the device is released. |
6ab343012 mfd: Add ACPI sup... |
322 |
|
56b858dfa ACPI: Update GPIO... |
323 324 |
See Documentation/acpi/gpio-properties.txt for more information about the _DSD binding related to GPIOs. |
6ab343012 mfd: Add ACPI sup... |
325 326 327 328 329 330 331 332 333 334 335 336 337 |
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. |
98a3be44f mfd: core: redo A... |
338 339 340 341 342 343 344 |
If the ACPI namespace has a device that we can match using an ACPI id or ACPI adr, the cell should be set like: static struct mfd_cell_acpi_match my_subdevice_cell_acpi_match = { .pnpid = "XYZ0001", .adr = 0, }; |
6ab343012 mfd: Add ACPI sup... |
345 346 347 348 |
static struct mfd_cell my_subdevice_cell = { .name = "my_subdevice", /* set the resources relative to the parent */ |
98a3be44f mfd: core: redo A... |
349 |
.acpi_match = &my_subdevice_cell_acpi_match, |
6ab343012 mfd: Add ACPI sup... |
350 351 352 353 354 |
}; 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. |
eb3486646 ACPI / enumeratio... |
355 356 357 |
Device Tree namespace link device ID ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
f4baccdea Documentation: ac... |
358 |
The Device Tree protocol uses device identification based on the "compatible" |
eb3486646 ACPI / enumeratio... |
359 360 |
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 |
f4baccdea Documentation: ac... |
361 |
regarded as a device identification namespace analogous to the ACPI/PNP device |
eb3486646 ACPI / enumeratio... |
362 363 364 365 366 367 368 369 370 371 |
ID namespace. Consequently, in principle it should not be necessary to allocate a new (and arguably redundant) ACPI/PNP device ID for a devices with an existing identification string in the Device Tree (DT) namespace, especially if that ID is only needed to indicate that a given device is compatible with another one, presumably having a matching driver in the kernel already. In ACPI, the device identification object called _CID (Compatible ID) is used to list the IDs of devices the given one is compatible with, but those IDs must belong to one of the namespaces prescribed by the ACPI specification (see Section 6.1.2 of ACPI 6.0 for details) and the DT namespace is not one of them. |
f4baccdea Documentation: ac... |
372 |
Moreover, the specification mandates that either a _HID or an _ADR identification |
eb3486646 ACPI / enumeratio... |
373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 |
object be present for all ACPI objects representing devices (Section 6.1 of ACPI 6.0). For non-enumerable bus types that object must be _HID and its value must be a device ID from one of the namespaces prescribed by the specification too. The special DT namespace link device ID, PRP0001, provides a means to use the existing DT-compatible device identification in ACPI and to satisfy the above requirements following from the ACPI specification at the same time. Namely, if PRP0001 is returned by _HID, the ACPI subsystem will look for the "compatible" property in the device object's _DSD and will use the value of that property to identify the corresponding device in analogy with the original DT device identification algorithm. If the "compatible" property is not present or its value is not valid, the device will not be enumerated by the ACPI subsystem. Otherwise, it will be enumerated automatically as a platform device (except when an I2C or SPI link from the device to its parent is present, in which case the ACPI core will leave the device enumeration to the parent's driver) and the identification strings from the "compatible" property value will be used to find a driver for the device along with the device IDs listed by _CID (if present). Analogously, if PRP0001 is present in the list of device IDs returned by _CID, the identification strings listed by the "compatible" property value (if present and valid) will be used to look for a driver matching the device, but in that case their relative priority with respect to the other device IDs listed by _HID and _CID depends on the position of PRP0001 in the _CID return package. Specifically, the device IDs returned by _HID and preceding PRP0001 in the _CID return package will be checked first. Also in that case the bus type the device will be enumerated to depends on the device ID returned by _HID. It is valid to define device objects with a _HID returning PRP0001 and without the "compatible" property in the _DSD or a _CID as long as one of their ancestors provides a _DSD with a valid "compatible" property. Such device objects are then simply regarded as additional "blocks" providing hierarchical configuration information to the driver of the composite ancestor device. |
ee39222d4 ACPI / property: ... |
406 407 408 409 410 411 412 413 414 |
However, PRP0001 can only be returned from either _HID or _CID of a device object if all of the properties returned by the _DSD associated with it (either the _DSD of the device object itself or the _DSD of its ancestor in the "composite device" case described above) can be used in the ACPI environment. Otherwise, the _DSD itself is regarded as invalid and therefore the "compatible" property returned by it is meaningless. Refer to DSD-properties-rules.txt for more information. |