GNU Linux-libre 5.10.219-gnu1
[releases.git] / Documentation / firmware-guide / acpi / enumeration.rst
1 .. SPDX-License-Identifier: GPL-2.0
2
3 =============================
4 ACPI Based Device Enumeration
5 =============================
6
7 ACPI 5 introduced a set of new resources (UartTSerialBus, I2cSerialBus,
8 SpiSerialBus, GpioIo and GpioInt) which can be used in enumerating slave
9 devices behind serial bus controllers.
10
11 In addition we are starting to see peripherals integrated in the
12 SoC/Chipset to appear only in ACPI namespace. These are typically devices
13 that are accessed through memory-mapped registers.
14
15 In order to support this and re-use the existing drivers as much as
16 possible we decided to do following:
17
18   - Devices that have no bus connector resource are represented as
19     platform devices.
20
21   - Devices behind real busses where there is a connector resource
22     are represented as struct spi_device or struct i2c_device
23     (standard UARTs are not busses so there is no struct uart_device).
24
25 As both ACPI and Device Tree represent a tree of devices (and their
26 resources) this implementation follows the Device Tree way as much as
27 possible.
28
29 The ACPI implementation enumerates devices behind busses (platform, SPI and
30 I2C), creates the physical devices and binds them to their ACPI handle in
31 the ACPI namespace.
32
33 This means that when ACPI_HANDLE(dev) returns non-NULL the device was
34 enumerated from ACPI namespace. This handle can be used to extract other
35 device-specific configuration. There is an example of this below.
36
37 Platform bus support
38 ====================
39
40 Since we are using platform devices to represent devices that are not
41 connected to any physical bus we only need to implement a platform driver
42 for the device and add supported ACPI IDs. If this same IP-block is used on
43 some other non-ACPI platform, the driver might work out of the box or needs
44 some minor changes.
45
46 Adding ACPI support for an existing driver should be pretty
47 straightforward. Here is the simplest example::
48
49         #ifdef CONFIG_ACPI
50         static const struct acpi_device_id mydrv_acpi_match[] = {
51                 /* ACPI IDs here */
52                 { }
53         };
54         MODULE_DEVICE_TABLE(acpi, mydrv_acpi_match);
55         #endif
56
57         static struct platform_driver my_driver = {
58                 ...
59                 .driver = {
60                         .acpi_match_table = ACPI_PTR(mydrv_acpi_match),
61                 },
62         };
63
64 If the driver needs to perform more complex initialization like getting and
65 configuring GPIOs it can get its ACPI handle and extract this information
66 from ACPI tables.
67
68 DMA support
69 ===========
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_chan() must register itself at the end of the probe function like
75 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_chan() will call xlate_func() for each registered DMA controller.
116 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_chan() with the string parameter that corresponds
121 to a specific FixedDMA resource. By default "tx" means the first entry of the
122 FixedDMA resource array, "rx" means the second entry. The table below shows a
123 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
149 Slave devices behind SPI bus have SpiSerialBus resource attached to them.
150 This is extracted automatically by the SPI core and the slave devices are
151 enumerated once spi_register_master() is called by the bus driver.
152
153 Here is what the ACPI namespace for a SPI slave might look like::
154
155         Device (EEP0)
156         {
157                 Name (_ADR, 1)
158                 Name (_CID, Package() {
159                         "ATML0025",
160                         "AT25",
161                 })
162                 ...
163                 Method (_CRS, 0, NotSerialized)
164                 {
165                         SPISerialBus(1, PolarityLow, FourWireMode, 8,
166                                 ControllerInitiated, 1000000, ClockPolarityLow,
167                                 ClockPhaseFirst, "\\_SB.PCI0.SPI1",)
168                 }
169                 ...
170
171 The SPI device drivers only need to add ACPI IDs in a similar way than with
172 the platform device drivers. Below is an example where we add ACPI support
173 to at25 SPI eeprom driver (this is meant for the above ACPI snippet)::
174
175         #ifdef CONFIG_ACPI
176         static const struct acpi_device_id at25_acpi_match[] = {
177                 { "AT25", 0 },
178                 { },
179         };
180         MODULE_DEVICE_TABLE(acpi, at25_acpi_match);
181         #endif
182
183         static struct spi_driver at25_driver = {
184                 .driver = {
185                         ...
186                         .acpi_match_table = ACPI_PTR(at25_acpi_match),
187                 },
188         };
189
190 Note that this driver actually needs more information like page size of the
191 eeprom etc. but at the time writing this there is no standard way of
192 passing those. One idea is to return this in _DSM method like::
193
194         Device (EEP0)
195         {
196                 ...
197                 Method (_DSM, 4, NotSerialized)
198                 {
199                         Store (Package (6)
200                         {
201                                 "byte-len", 1024,
202                                 "addr-mode", 2,
203                                 "page-size, 32
204                         }, Local0)
205
206                         // Check UUIDs etc.
207
208                         Return (Local0)
209                 }
210
211 Then the at25 SPI driver can get this configuration by calling _DSM on its
212 ACPI handle like::
213
214         struct acpi_buffer output = { ACPI_ALLOCATE_BUFFER, NULL };
215         struct acpi_object_list input;
216         acpi_status status;
217
218         /* Fill in the input buffer */
219
220         status = acpi_evaluate_object(ACPI_HANDLE(&spi->dev), "_DSM",
221                                       &input, &output);
222         if (ACPI_FAILURE(status))
223                 /* Handle the error */
224
225         /* Extract the data here */
226
227         kfree(output.pointer);
228
229 I2C serial bus support
230 ======================
231
232 The slaves behind I2C bus controller only need to add the ACPI IDs like
233 with the platform and SPI drivers. The I2C core automatically enumerates
234 any slave devices behind the controller device once the adapter is
235 registered.
236
237 Below is an example of how to add ACPI support to the existing mpu3050
238 input driver::
239
240         #ifdef CONFIG_ACPI
241         static const struct acpi_device_id mpu3050_acpi_match[] = {
242                 { "MPU3050", 0 },
243                 { },
244         };
245         MODULE_DEVICE_TABLE(acpi, mpu3050_acpi_match);
246         #endif
247
248         static struct i2c_driver mpu3050_i2c_driver = {
249                 .driver = {
250                         .name   = "mpu3050",
251                         .owner  = THIS_MODULE,
252                         .pm     = &mpu3050_pm,
253                         .of_match_table = mpu3050_of_match,
254                         .acpi_match_table = ACPI_PTR(mpu3050_acpi_match),
255                 },
256                 .probe          = mpu3050_probe,
257                 .remove         = mpu3050_remove,
258                 .id_table       = mpu3050_ids,
259         };
260
261 GPIO support
262 ============
263
264 ACPI 5 introduced two new resources to describe GPIO connections: GpioIo
265 and GpioInt. These resources can be used to pass GPIO numbers used by
266 the device to the driver. ACPI 5.1 extended this with _DSD (Device
267 Specific Data) which made it possible to name the GPIOs among other things.
268
269 For example::
270
271         Device (DEV)
272         {
273                 Method (_CRS, 0, NotSerialized)
274                 {
275                         Name (SBUF, ResourceTemplate()
276                         {
277                                 ...
278                                 // Used to power on/off the device
279                                 GpioIo (Exclusive, PullDefault, 0x0000, 0x0000,
280                                         IoRestrictionOutputOnly, "\\_SB.PCI0.GPI0",
281                                         0x00, ResourceConsumer,,)
282                                 {
283                                         // Pin List
284                                         0x0055
285                                 }
286
287                                 // Interrupt for the device
288                                 GpioInt (Edge, ActiveHigh, ExclusiveAndWake, PullNone,
289                                         0x0000, "\\_SB.PCI0.GPI0", 0x00, ResourceConsumer,,)
290                                 {
291                                         // Pin list
292                                         0x0058
293                                 }
294
295                                 ...
296
297                         }
298
299                         Return (SBUF)
300                 }
301
302                 // ACPI 5.1 _DSD used for naming the GPIOs
303                 Name (_DSD, Package ()
304                 {
305                         ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
306                         Package ()
307                         {
308                                 Package () {"power-gpios", Package() {^DEV, 0, 0, 0 }},
309                                 Package () {"irq-gpios", Package() {^DEV, 1, 0, 0 }},
310                         }
311                 })
312                 ...
313
314 These GPIO numbers are controller relative and path "\\_SB.PCI0.GPI0"
315 specifies the path to the controller. In order to use these GPIOs in Linux
316 we need to translate them to the corresponding Linux GPIO descriptors.
317
318 There is a standard GPIO API for that and is documented in
319 Documentation/admin-guide/gpio/.
320
321 In the above example we can get the corresponding two GPIO descriptors with
322 a code like this::
323
324         #include <linux/gpio/consumer.h>
325         ...
326
327         struct gpio_desc *irq_desc, *power_desc;
328
329         irq_desc = gpiod_get(dev, "irq");
330         if (IS_ERR(irq_desc))
331                 /* handle error */
332
333         power_desc = gpiod_get(dev, "power");
334         if (IS_ERR(power_desc))
335                 /* handle error */
336
337         /* Now we can use the GPIO descriptors */
338
339 There are also devm_* versions of these functions which release the
340 descriptors once the device is released.
341
342 See Documentation/firmware-guide/acpi/gpio-properties.rst for more information about the
343 _DSD binding related to GPIOs.
344
345 MFD devices
346 ===========
347
348 The MFD devices register their children as platform devices. For the child
349 devices there needs to be an ACPI handle that they can use to reference
350 parts of the ACPI namespace that relate to them. In the Linux MFD subsystem
351 we provide two ways:
352
353   - The children share the parent ACPI handle.
354   - The MFD cell can specify the ACPI id of the device.
355
356 For the first case, the MFD drivers do not need to do anything. The
357 resulting child platform device will have its ACPI_COMPANION() set to point
358 to the parent device.
359
360 If the ACPI namespace has a device that we can match using an ACPI id or ACPI
361 adr, the cell should be set like::
362
363         static struct mfd_cell_acpi_match my_subdevice_cell_acpi_match = {
364                 .pnpid = "XYZ0001",
365                 .adr = 0,
366         };
367
368         static struct mfd_cell my_subdevice_cell = {
369                 .name = "my_subdevice",
370                 /* set the resources relative to the parent */
371                 .acpi_match = &my_subdevice_cell_acpi_match,
372         };
373
374 The ACPI id "XYZ0001" is then used to lookup an ACPI device directly under
375 the MFD device and if found, that ACPI companion device is bound to the
376 resulting child platform device.
377
378 Device Tree namespace link device ID
379 ====================================
380
381 The Device Tree protocol uses device identification based on the "compatible"
382 property whose value is a string or an array of strings recognized as device
383 identifiers by drivers and the driver core.  The set of all those strings may be
384 regarded as a device identification namespace analogous to the ACPI/PNP device
385 ID namespace.  Consequently, in principle it should not be necessary to allocate
386 a new (and arguably redundant) ACPI/PNP device ID for a devices with an existing
387 identification string in the Device Tree (DT) namespace, especially if that ID
388 is only needed to indicate that a given device is compatible with another one,
389 presumably having a matching driver in the kernel already.
390
391 In ACPI, the device identification object called _CID (Compatible ID) is used to
392 list the IDs of devices the given one is compatible with, but those IDs must
393 belong to one of the namespaces prescribed by the ACPI specification (see
394 Section 6.1.2 of ACPI 6.0 for details) and the DT namespace is not one of them.
395 Moreover, the specification mandates that either a _HID or an _ADR identification
396 object be present for all ACPI objects representing devices (Section 6.1 of ACPI
397 6.0).  For non-enumerable bus types that object must be _HID and its value must
398 be a device ID from one of the namespaces prescribed by the specification too.
399
400 The special DT namespace link device ID, PRP0001, provides a means to use the
401 existing DT-compatible device identification in ACPI and to satisfy the above
402 requirements following from the ACPI specification at the same time.  Namely,
403 if PRP0001 is returned by _HID, the ACPI subsystem will look for the
404 "compatible" property in the device object's _DSD and will use the value of that
405 property to identify the corresponding device in analogy with the original DT
406 device identification algorithm.  If the "compatible" property is not present
407 or its value is not valid, the device will not be enumerated by the ACPI
408 subsystem.  Otherwise, it will be enumerated automatically as a platform device
409 (except when an I2C or SPI link from the device to its parent is present, in
410 which case the ACPI core will leave the device enumeration to the parent's
411 driver) and the identification strings from the "compatible" property value will
412 be used to find a driver for the device along with the device IDs listed by _CID
413 (if present).
414
415 Analogously, if PRP0001 is present in the list of device IDs returned by _CID,
416 the identification strings listed by the "compatible" property value (if present
417 and valid) will be used to look for a driver matching the device, but in that
418 case their relative priority with respect to the other device IDs listed by
419 _HID and _CID depends on the position of PRP0001 in the _CID return package.
420 Specifically, the device IDs returned by _HID and preceding PRP0001 in the _CID
421 return package will be checked first.  Also in that case the bus type the device
422 will be enumerated to depends on the device ID returned by _HID.
423
424 For example, the following ACPI sample might be used to enumerate an lm75-type
425 I2C temperature sensor and match it to the driver using the Device Tree
426 namespace link::
427
428         Device (TMP0)
429         {
430                 Name (_HID, "PRP0001")
431                 Name (_DSD, Package() {
432                         ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
433                         Package () {
434                                 Package (2) { "compatible", "ti,tmp75" },
435                         }
436                 })
437                 Method (_CRS, 0, Serialized)
438                 {
439                         Name (SBUF, ResourceTemplate ()
440                         {
441                                 I2cSerialBusV2 (0x48, ControllerInitiated,
442                                         400000, AddressingMode7Bit,
443                                         "\\_SB.PCI0.I2C1", 0x00,
444                                         ResourceConsumer, , Exclusive,)
445                         })
446                         Return (SBUF)
447                 }
448         }
449
450 It is valid to define device objects with a _HID returning PRP0001 and without
451 the "compatible" property in the _DSD or a _CID as long as one of their
452 ancestors provides a _DSD with a valid "compatible" property.  Such device
453 objects are then simply regarded as additional "blocks" providing hierarchical
454 configuration information to the driver of the composite ancestor device.
455
456 However, PRP0001 can only be returned from either _HID or _CID of a device
457 object if all of the properties returned by the _DSD associated with it (either
458 the _DSD of the device object itself or the _DSD of its ancestor in the
459 "composite device" case described above) can be used in the ACPI environment.
460 Otherwise, the _DSD itself is regarded as invalid and therefore the "compatible"
461 property returned by it is meaningless.
462
463 Refer to :doc:`DSD-properties-rules` for more information.