Commit | Line | Data |
---|---|---|
59c39878 MW |
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 | |
1a147ed7 | 45 | static const struct acpi_device_id mydrv_acpi_match[] = { |
59c39878 MW |
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 | ||
1b2e98bc AS |
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 | ||
59c39878 MW |
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 | |
1a147ed7 | 169 | static const struct acpi_device_id at25_acpi_match[] = { |
59c39878 MW |
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 | ||
2d6674b8 | 204 | Then the at25 SPI driver can get this configuration by calling _DSM on its |
59c39878 MW |
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 | |
55e71edb MW |
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. | |
59c39878 MW |
228 | |
229 | Below is an example of how to add ACPI support to the existing mpu3050 | |
230 | input driver: | |
231 | ||
232 | #ifdef CONFIG_ACPI | |
1a147ed7 | 233 | static const struct acpi_device_id mpu3050_acpi_match[] = { |
59c39878 MW |
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, | |
de14da2a | 246 | .acpi_match_table = ACPI_PTR(mpu3050_acpi_match), |
59c39878 MW |
247 | }, |
248 | .probe = mpu3050_probe, | |
63a29f74 | 249 | .remove = mpu3050_remove, |
59c39878 MW |
250 | .id_table = mpu3050_ids, |
251 | }; | |
252 | ||
253 | GPIO support | |
254 | ~~~~~~~~~~~~ | |
255 | ACPI 5 introduced two new resources to describe GPIO connections: GpioIo | |
2375a212 | 256 | and GpioInt. These resources can be used to pass GPIO numbers used by |
56b858df MW |
257 | the device to the driver. ACPI 5.1 extended this with _DSD (Device |
258 | Specific Data) which made it possible to name the GPIOs among other things. | |
59c39878 | 259 | |
56b858df MW |
260 | For example: |
261 | ||
262 | Device (DEV) | |
263 | { | |
59c39878 MW |
264 | Method (_CRS, 0, NotSerialized) |
265 | { | |
266 | Name (SBUF, ResourceTemplate() | |
267 | { | |
12028d2d MW |
268 | ... |
269 | // Used to power on/off the device | |
59c39878 MW |
270 | GpioIo (Exclusive, PullDefault, 0x0000, 0x0000, |
271 | IoRestrictionOutputOnly, "\\_SB.PCI0.GPI0", | |
272 | 0x00, ResourceConsumer,,) | |
273 | { | |
274 | // Pin List | |
275 | 0x0055 | |
276 | } | |
12028d2d MW |
277 | |
278 | // Interrupt for the device | |
279 | GpioInt (Edge, ActiveHigh, ExclusiveAndWake, PullNone, | |
280 | 0x0000, "\\_SB.PCI0.GPI0", 0x00, ResourceConsumer,,) | |
281 | { | |
282 | // Pin list | |
283 | 0x0058 | |
284 | } | |
285 | ||
59c39878 MW |
286 | ... |
287 | ||
59c39878 | 288 | } |
12028d2d MW |
289 | |
290 | Return (SBUF) | |
59c39878 MW |
291 | } |
292 | ||
56b858df MW |
293 | // ACPI 5.1 _DSD used for naming the GPIOs |
294 | Name (_DSD, Package () | |
295 | { | |
296 | ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), | |
297 | Package () | |
298 | { | |
299 | Package () {"power-gpios", Package() {^DEV, 0, 0, 0 }}, | |
300 | Package () {"irq-gpios", Package() {^DEV, 1, 0, 0 }}, | |
301 | } | |
302 | }) | |
303 | ... | |
304 | ||
59c39878 MW |
305 | These GPIO numbers are controller relative and path "\\_SB.PCI0.GPI0" |
306 | specifies the path to the controller. In order to use these GPIOs in Linux | |
ccb6fbb9 | 307 | we need to translate them to the corresponding Linux GPIO descriptors. |
59c39878 | 308 | |
ccb6fbb9 | 309 | There is a standard GPIO API for that and is documented in |
51caa05a | 310 | Documentation/gpio/. |
12028d2d | 311 | |
ccb6fbb9 MW |
312 | In the above example we can get the corresponding two GPIO descriptors with |
313 | a code like this: | |
45f39439 MW |
314 | |
315 | #include <linux/gpio/consumer.h> | |
316 | ... | |
317 | ||
318 | struct gpio_desc *irq_desc, *power_desc; | |
319 | ||
56b858df | 320 | irq_desc = gpiod_get(dev, "irq"); |
45f39439 MW |
321 | if (IS_ERR(irq_desc)) |
322 | /* handle error */ | |
323 | ||
56b858df | 324 | power_desc = gpiod_get(dev, "power"); |
45f39439 MW |
325 | if (IS_ERR(power_desc)) |
326 | /* handle error */ | |
327 | ||
328 | /* Now we can use the GPIO descriptors */ | |
329 | ||
ccb6fbb9 MW |
330 | There are also devm_* versions of these functions which release the |
331 | descriptors once the device is released. | |
6ab34301 | 332 | |
56b858df MW |
333 | See Documentation/acpi/gpio-properties.txt for more information about the |
334 | _DSD binding related to GPIOs. | |
335 | ||
6ab34301 MW |
336 | MFD devices |
337 | ~~~~~~~~~~~ | |
338 | The MFD devices register their children as platform devices. For the child | |
339 | devices there needs to be an ACPI handle that they can use to reference | |
340 | parts of the ACPI namespace that relate to them. In the Linux MFD subsystem | |
341 | we provide two ways: | |
342 | ||
343 | o The children share the parent ACPI handle. | |
344 | o The MFD cell can specify the ACPI id of the device. | |
345 | ||
346 | For the first case, the MFD drivers do not need to do anything. The | |
347 | resulting child platform device will have its ACPI_COMPANION() set to point | |
348 | to the parent device. | |
349 | ||
98a3be44 AS |
350 | If the ACPI namespace has a device that we can match using an ACPI id or ACPI |
351 | adr, the cell should be set like: | |
352 | ||
353 | static struct mfd_cell_acpi_match my_subdevice_cell_acpi_match = { | |
354 | .pnpid = "XYZ0001", | |
355 | .adr = 0, | |
356 | }; | |
6ab34301 MW |
357 | |
358 | static struct mfd_cell my_subdevice_cell = { | |
359 | .name = "my_subdevice", | |
360 | /* set the resources relative to the parent */ | |
98a3be44 | 361 | .acpi_match = &my_subdevice_cell_acpi_match, |
6ab34301 MW |
362 | }; |
363 | ||
364 | The ACPI id "XYZ0001" is then used to lookup an ACPI device directly under | |
365 | the MFD device and if found, that ACPI companion device is bound to the | |
366 | resulting child platform device. | |
eb348664 RW |
367 | |
368 | Device Tree namespace link device ID | |
369 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
370 | The Device Tree protocol uses device indentification based on the "compatible" | |
371 | property whose value is a string or an array of strings recognized as device | |
372 | identifiers by drivers and the driver core. The set of all those strings may be | |
373 | regarded as a device indentification namespace analogous to the ACPI/PNP device | |
374 | ID namespace. Consequently, in principle it should not be necessary to allocate | |
375 | a new (and arguably redundant) ACPI/PNP device ID for a devices with an existing | |
376 | identification string in the Device Tree (DT) namespace, especially if that ID | |
377 | is only needed to indicate that a given device is compatible with another one, | |
378 | presumably having a matching driver in the kernel already. | |
379 | ||
380 | In ACPI, the device identification object called _CID (Compatible ID) is used to | |
381 | list the IDs of devices the given one is compatible with, but those IDs must | |
382 | belong to one of the namespaces prescribed by the ACPI specification (see | |
383 | Section 6.1.2 of ACPI 6.0 for details) and the DT namespace is not one of them. | |
384 | Moreover, the specification mandates that either a _HID or an _ADR identificaion | |
385 | object be present for all ACPI objects representing devices (Section 6.1 of ACPI | |
386 | 6.0). For non-enumerable bus types that object must be _HID and its value must | |
387 | be a device ID from one of the namespaces prescribed by the specification too. | |
388 | ||
389 | The special DT namespace link device ID, PRP0001, provides a means to use the | |
390 | existing DT-compatible device identification in ACPI and to satisfy the above | |
391 | requirements following from the ACPI specification at the same time. Namely, | |
392 | if PRP0001 is returned by _HID, the ACPI subsystem will look for the | |
393 | "compatible" property in the device object's _DSD and will use the value of that | |
394 | property to identify the corresponding device in analogy with the original DT | |
395 | device identification algorithm. If the "compatible" property is not present | |
396 | or its value is not valid, the device will not be enumerated by the ACPI | |
397 | subsystem. Otherwise, it will be enumerated automatically as a platform device | |
398 | (except when an I2C or SPI link from the device to its parent is present, in | |
399 | which case the ACPI core will leave the device enumeration to the parent's | |
400 | driver) and the identification strings from the "compatible" property value will | |
401 | be used to find a driver for the device along with the device IDs listed by _CID | |
402 | (if present). | |
403 | ||
404 | Analogously, if PRP0001 is present in the list of device IDs returned by _CID, | |
405 | the identification strings listed by the "compatible" property value (if present | |
406 | and valid) will be used to look for a driver matching the device, but in that | |
407 | case their relative priority with respect to the other device IDs listed by | |
408 | _HID and _CID depends on the position of PRP0001 in the _CID return package. | |
409 | Specifically, the device IDs returned by _HID and preceding PRP0001 in the _CID | |
410 | return package will be checked first. Also in that case the bus type the device | |
411 | will be enumerated to depends on the device ID returned by _HID. | |
412 | ||
413 | It is valid to define device objects with a _HID returning PRP0001 and without | |
414 | the "compatible" property in the _DSD or a _CID as long as one of their | |
415 | ancestors provides a _DSD with a valid "compatible" property. Such device | |
416 | objects are then simply regarded as additional "blocks" providing hierarchical | |
417 | configuration information to the driver of the composite ancestor device. |