1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 ============================= 3 =============================
4 ACPI Based Device Enumeration 4 ACPI Based Device Enumeration
5 ============================= 5 =============================
6 6
7 ACPI 5 introduced a set of new resources (Uart 7 ACPI 5 introduced a set of new resources (UartTSerialBus, I2cSerialBus,
8 SpiSerialBus, GpioIo and GpioInt) which can be 8 SpiSerialBus, GpioIo and GpioInt) which can be used in enumerating slave
9 devices behind serial bus controllers. 9 devices behind serial bus controllers.
10 10
11 In addition we are starting to see peripherals 11 In addition we are starting to see peripherals integrated in the
12 SoC/Chipset to appear only in ACPI namespace. 12 SoC/Chipset to appear only in ACPI namespace. These are typically devices
13 that are accessed through memory-mapped regist 13 that are accessed through memory-mapped registers.
14 14
15 In order to support this and re-use the existi 15 In order to support this and re-use the existing drivers as much as
16 possible we decided to do following: 16 possible we decided to do following:
17 17
18 - Devices that have no bus connector resourc 18 - Devices that have no bus connector resource are represented as
19 platform devices. 19 platform devices.
20 20
21 - Devices behind real busses where there is 21 - Devices behind real busses where there is a connector resource
22 are represented as struct spi_device or st 22 are represented as struct spi_device or struct i2c_client. Note
23 that standard UARTs are not busses so ther 23 that standard UARTs are not busses so there is no struct uart_device,
24 although some of them may be represented b 24 although some of them may be represented by struct serdev_device.
25 25
26 As both ACPI and Device Tree represent a tree 26 As both ACPI and Device Tree represent a tree of devices (and their
27 resources) this implementation follows the Dev 27 resources) this implementation follows the Device Tree way as much as
28 possible. 28 possible.
29 29
30 The ACPI implementation enumerates devices beh 30 The ACPI implementation enumerates devices behind busses (platform, SPI,
31 I2C, and in some cases UART), creates the phys 31 I2C, and in some cases UART), creates the physical devices and binds them
32 to their ACPI handle in the ACPI namespace. 32 to their ACPI handle in the ACPI namespace.
33 33
34 This means that when ACPI_HANDLE(dev) returns 34 This means that when ACPI_HANDLE(dev) returns non-NULL the device was
35 enumerated from ACPI namespace. This handle ca 35 enumerated from ACPI namespace. This handle can be used to extract other
36 device-specific configuration. There is an exa 36 device-specific configuration. There is an example of this below.
37 37
38 Platform bus support 38 Platform bus support
39 ==================== 39 ====================
40 40
41 Since we are using platform devices to represe 41 Since we are using platform devices to represent devices that are not
42 connected to any physical bus we only need to 42 connected to any physical bus we only need to implement a platform driver
43 for the device and add supported ACPI IDs. If 43 for the device and add supported ACPI IDs. If this same IP-block is used on
44 some other non-ACPI platform, the driver might 44 some other non-ACPI platform, the driver might work out of the box or needs
45 some minor changes. 45 some minor changes.
46 46
47 Adding ACPI support for an existing driver sho 47 Adding ACPI support for an existing driver should be pretty
48 straightforward. Here is the simplest example: 48 straightforward. Here is the simplest example::
49 49
50 static const struct acpi_device_id myd 50 static const struct acpi_device_id mydrv_acpi_match[] = {
51 /* ACPI IDs here */ 51 /* ACPI IDs here */
52 { } 52 { }
53 }; 53 };
54 MODULE_DEVICE_TABLE(acpi, mydrv_acpi_m 54 MODULE_DEVICE_TABLE(acpi, mydrv_acpi_match);
55 55
56 static struct platform_driver my_drive 56 static struct platform_driver my_driver = {
57 ... 57 ...
58 .driver = { 58 .driver = {
59 .acpi_match_table = my 59 .acpi_match_table = mydrv_acpi_match,
60 }, 60 },
61 }; 61 };
62 62
63 If the driver needs to perform more complex in 63 If the driver needs to perform more complex initialization like getting and
64 configuring GPIOs it can get its ACPI handle a 64 configuring GPIOs it can get its ACPI handle and extract this information
65 from ACPI tables. 65 from ACPI tables.
66 66
67 ACPI device objects 67 ACPI device objects
68 =================== 68 ===================
69 69
70 Generally speaking, there are two categories o 70 Generally speaking, there are two categories of devices in a system in which
71 ACPI is used as an interface between the platf 71 ACPI is used as an interface between the platform firmware and the OS: Devices
72 that can be discovered and enumerated natively 72 that can be discovered and enumerated natively, through a protocol defined for
73 the specific bus that they are on (for example 73 the specific bus that they are on (for example, configuration space in PCI),
74 without the platform firmware assistance, and 74 without the platform firmware assistance, and devices that need to be described
75 by the platform firmware so that they can be d 75 by the platform firmware so that they can be discovered. Still, for any device
76 known to the platform firmware, regardless of 76 known to the platform firmware, regardless of which category it falls into,
77 there can be a corresponding ACPI device objec 77 there can be a corresponding ACPI device object in the ACPI Namespace in which
78 case the Linux kernel will create a struct acp 78 case the Linux kernel will create a struct acpi_device object based on it for
79 that device. 79 that device.
80 80
81 Those struct acpi_device objects are never use 81 Those struct acpi_device objects are never used for binding drivers to natively
82 discoverable devices, because they are represe 82 discoverable devices, because they are represented by other types of device
83 objects (for example, struct pci_dev for PCI d 83 objects (for example, struct pci_dev for PCI devices) that are bound to by
84 device drivers (the corresponding struct acpi_ 84 device drivers (the corresponding struct acpi_device object is then used as
85 an additional source of information on the con 85 an additional source of information on the configuration of the given device).
86 Moreover, the core ACPI device enumeration cod 86 Moreover, the core ACPI device enumeration code creates struct platform_device
87 objects for the majority of devices that are d 87 objects for the majority of devices that are discovered and enumerated with the
88 help of the platform firmware and those platfo 88 help of the platform firmware and those platform device objects can be bound to
89 by platform drivers in direct analogy with the 89 by platform drivers in direct analogy with the natively enumerable devices
90 case. Therefore it is logically inconsistent 90 case. Therefore it is logically inconsistent and so generally invalid to bind
91 drivers to struct acpi_device objects, includi 91 drivers to struct acpi_device objects, including drivers for devices that are
92 discovered with the help of the platform firmw 92 discovered with the help of the platform firmware.
93 93
94 Historically, ACPI drivers that bound directly 94 Historically, ACPI drivers that bound directly to struct acpi_device objects
95 were implemented for some devices enumerated w 95 were implemented for some devices enumerated with the help of the platform
96 firmware, but this is not recommended for any 96 firmware, but this is not recommended for any new drivers. As explained above,
97 platform device objects are created for those 97 platform device objects are created for those devices as a rule (with a few
98 exceptions that are not relevant here) and so 98 exceptions that are not relevant here) and so platform drivers should be used
99 for handling them, even though the correspondi 99 for handling them, even though the corresponding ACPI device objects are the
100 only source of device configuration informatio 100 only source of device configuration information in that case.
101 101
102 For every device having a corresponding struct 102 For every device having a corresponding struct acpi_device object, the pointer
103 to it is returned by the ACPI_COMPANION() macr 103 to it is returned by the ACPI_COMPANION() macro, so it is always possible to
104 get to the device configuration information st 104 get to the device configuration information stored in the ACPI device object
105 this way. Accordingly, struct acpi_device can 105 this way. Accordingly, struct acpi_device can be regarded as a part of the
106 interface between the kernel and the ACPI Name 106 interface between the kernel and the ACPI Namespace, whereas device objects of
107 other types (for example, struct pci_dev or st 107 other types (for example, struct pci_dev or struct platform_device) are used
108 for interacting with the rest of the system. 108 for interacting with the rest of the system.
109 109
110 DMA support 110 DMA support
111 =========== 111 ===========
112 112
113 DMA controllers enumerated via ACPI should be 113 DMA controllers enumerated via ACPI should be registered in the system to
114 provide generic access to their resources. For 114 provide generic access to their resources. For example, a driver that would
115 like to be accessible to slave devices via gen 115 like to be accessible to slave devices via generic API call
116 dma_request_chan() must register itself at the 116 dma_request_chan() must register itself at the end of the probe function like
117 this:: 117 this::
118 118
119 err = devm_acpi_dma_controller_registe 119 err = devm_acpi_dma_controller_register(dev, xlate_func, dw);
120 /* Handle the error if it's not a case 120 /* Handle the error if it's not a case of !CONFIG_ACPI */
121 121
122 and implement custom xlate function if needed 122 and implement custom xlate function if needed (usually acpi_dma_simple_xlate()
123 is enough) which converts the FixedDMA resourc 123 is enough) which converts the FixedDMA resource provided by struct
124 acpi_dma_spec into the corresponding DMA chann 124 acpi_dma_spec into the corresponding DMA channel. A piece of code for that case
125 could look like:: 125 could look like::
126 126
127 #ifdef CONFIG_ACPI 127 #ifdef CONFIG_ACPI
128 struct filter_args { 128 struct filter_args {
129 /* Provide necessary informati 129 /* Provide necessary information for the filter_func */
130 ... 130 ...
131 }; 131 };
132 132
133 static bool filter_func(struct dma_cha 133 static bool filter_func(struct dma_chan *chan, void *param)
134 { 134 {
135 /* Choose the proper channel * 135 /* Choose the proper channel */
136 ... 136 ...
137 } 137 }
138 138
139 static struct dma_chan *xlate_func(str 139 static struct dma_chan *xlate_func(struct acpi_dma_spec *dma_spec,
140 struct acpi_dma *adma) 140 struct acpi_dma *adma)
141 { 141 {
142 dma_cap_mask_t cap; 142 dma_cap_mask_t cap;
143 struct filter_args args; 143 struct filter_args args;
144 144
145 /* Prepare arguments for filte 145 /* Prepare arguments for filter_func */
146 ... 146 ...
147 return dma_request_channel(cap 147 return dma_request_channel(cap, filter_func, &args);
148 } 148 }
149 #else 149 #else
150 static struct dma_chan *xlate_func(str 150 static struct dma_chan *xlate_func(struct acpi_dma_spec *dma_spec,
151 struct acpi_dma *adma) 151 struct acpi_dma *adma)
152 { 152 {
153 return NULL; 153 return NULL;
154 } 154 }
155 #endif 155 #endif
156 156
157 dma_request_chan() will call xlate_func() for 157 dma_request_chan() will call xlate_func() for each registered DMA controller.
158 In the xlate function the proper channel must 158 In the xlate function the proper channel must be chosen based on
159 information in struct acpi_dma_spec and the pr 159 information in struct acpi_dma_spec and the properties of the controller
160 provided by struct acpi_dma. 160 provided by struct acpi_dma.
161 161
162 Clients must call dma_request_chan() with the 162 Clients must call dma_request_chan() with the string parameter that corresponds
163 to a specific FixedDMA resource. By default "t 163 to a specific FixedDMA resource. By default "tx" means the first entry of the
164 FixedDMA resource array, "rx" means the second 164 FixedDMA resource array, "rx" means the second entry. The table below shows a
165 layout:: 165 layout::
166 166
167 Device (I2C0) 167 Device (I2C0)
168 { 168 {
169 ... 169 ...
170 Method (_CRS, 0, NotSerialized 170 Method (_CRS, 0, NotSerialized)
171 { 171 {
172 Name (DBUF, ResourceTe 172 Name (DBUF, ResourceTemplate ()
173 { 173 {
174 FixedDMA (0x00 174 FixedDMA (0x0018, 0x0004, Width32bit, _Y48)
175 FixedDMA (0x00 175 FixedDMA (0x0019, 0x0005, Width32bit, )
176 }) 176 })
177 ... 177 ...
178 } 178 }
179 } 179 }
180 180
181 So, the FixedDMA with request line 0x0018 is " 181 So, the FixedDMA with request line 0x0018 is "tx" and next one is "rx" in
182 this example. 182 this example.
183 183
184 In robust cases the client unfortunately needs 184 In robust cases the client unfortunately needs to call
185 acpi_dma_request_slave_chan_by_index() directl 185 acpi_dma_request_slave_chan_by_index() directly and therefore choose the
186 specific FixedDMA resource by its index. 186 specific FixedDMA resource by its index.
187 187
188 Named Interrupts 188 Named Interrupts
189 ================ 189 ================
190 190
191 Drivers enumerated via ACPI can have names to 191 Drivers enumerated via ACPI can have names to interrupts in the ACPI table
192 which can be used to get the IRQ number in the 192 which can be used to get the IRQ number in the driver.
193 193
194 The interrupt name can be listed in _DSD as 'i 194 The interrupt name can be listed in _DSD as 'interrupt-names'. The names
195 should be listed as an array of strings which 195 should be listed as an array of strings which will map to the Interrupt()
196 resource in the ACPI table corresponding to it 196 resource in the ACPI table corresponding to its index.
197 197
198 The table below shows an example of its usage: 198 The table below shows an example of its usage::
199 199
200 Device (DEV0) { 200 Device (DEV0) {
201 ... 201 ...
202 Name (_CRS, ResourceTemplate() { 202 Name (_CRS, ResourceTemplate() {
203 ... 203 ...
204 Interrupt (ResourceConsumer, Level 204 Interrupt (ResourceConsumer, Level, ActiveHigh, Exclusive) {
205 0x20, 205 0x20,
206 0x24 206 0x24
207 } 207 }
208 }) 208 })
209 209
210 Name (_DSD, Package () { 210 Name (_DSD, Package () {
211 ToUUID("daffd814-6eba-4d8c-8a91-bc 211 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
212 Package () { 212 Package () {
213 Package () { "interrupt-names" 213 Package () { "interrupt-names", Package () { "default", "alert" } },
214 } 214 }
215 ... 215 ...
216 }) 216 })
217 } 217 }
218 218
219 The interrupt name 'default' will correspond t 219 The interrupt name 'default' will correspond to 0x20 in Interrupt()
220 resource and 'alert' to 0x24. Note that only t 220 resource and 'alert' to 0x24. Note that only the Interrupt() resource
221 is mapped and not GpioInt() or similar. 221 is mapped and not GpioInt() or similar.
222 222
223 The driver can call the function - fwnode_irq_ 223 The driver can call the function - fwnode_irq_get_byname() with the fwnode
224 and interrupt name as arguments to get the cor 224 and interrupt name as arguments to get the corresponding IRQ number.
225 225
226 SPI serial bus support 226 SPI serial bus support
227 ====================== 227 ======================
228 228
229 Slave devices behind SPI bus have SpiSerialBus 229 Slave devices behind SPI bus have SpiSerialBus resource attached to them.
230 This is extracted automatically by the SPI cor 230 This is extracted automatically by the SPI core and the slave devices are
231 enumerated once spi_register_master() is calle 231 enumerated once spi_register_master() is called by the bus driver.
232 232
233 Here is what the ACPI namespace for a SPI slav 233 Here is what the ACPI namespace for a SPI slave might look like::
234 234
235 Device (EEP0) 235 Device (EEP0)
236 { 236 {
237 Name (_ADR, 1) 237 Name (_ADR, 1)
238 Name (_CID, Package () { 238 Name (_CID, Package () {
239 "ATML0025", 239 "ATML0025",
240 "AT25", 240 "AT25",
241 }) 241 })
242 ... 242 ...
243 Method (_CRS, 0, NotSerialized 243 Method (_CRS, 0, NotSerialized)
244 { 244 {
245 SPISerialBus(1, Polari 245 SPISerialBus(1, PolarityLow, FourWireMode, 8,
246 ControllerInit 246 ControllerInitiated, 1000000, ClockPolarityLow,
247 ClockPhaseFirs 247 ClockPhaseFirst, "\\_SB.PCI0.SPI1",)
248 } 248 }
249 ... 249 ...
250 250
251 The SPI device drivers only need to add ACPI I 251 The SPI device drivers only need to add ACPI IDs in a similar way to
252 the platform device drivers. Below is an examp 252 the platform device drivers. Below is an example where we add ACPI support
253 to at25 SPI eeprom driver (this is meant for t 253 to at25 SPI eeprom driver (this is meant for the above ACPI snippet)::
254 254
255 static const struct acpi_device_id at2 255 static const struct acpi_device_id at25_acpi_match[] = {
256 { "AT25", 0 }, 256 { "AT25", 0 },
257 { } 257 { }
258 }; 258 };
259 MODULE_DEVICE_TABLE(acpi, at25_acpi_ma 259 MODULE_DEVICE_TABLE(acpi, at25_acpi_match);
260 260
261 static struct spi_driver at25_driver = 261 static struct spi_driver at25_driver = {
262 .driver = { 262 .driver = {
263 ... 263 ...
264 .acpi_match_table = at 264 .acpi_match_table = at25_acpi_match,
265 }, 265 },
266 }; 266 };
267 267
268 Note that this driver actually needs more info 268 Note that this driver actually needs more information like page size of the
269 eeprom, etc. This information can be passed vi 269 eeprom, etc. This information can be passed via _DSD method like::
270 270
271 Device (EEP0) 271 Device (EEP0)
272 { 272 {
273 ... 273 ...
274 Name (_DSD, Package () 274 Name (_DSD, Package ()
275 { 275 {
276 ToUUID("daffd814-6eba- 276 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
277 Package () 277 Package ()
278 { 278 {
279 Package () { " 279 Package () { "size", 1024 },
280 Package () { " 280 Package () { "pagesize", 32 },
281 Package () { " 281 Package () { "address-width", 16 },
282 } 282 }
283 }) 283 })
284 } 284 }
285 285
286 Then the at25 SPI driver can get this configur 286 Then the at25 SPI driver can get this configuration by calling device property
287 APIs during ->probe() phase like:: 287 APIs during ->probe() phase like::
288 288
289 err = device_property_read_u32(dev, "s 289 err = device_property_read_u32(dev, "size", &size);
290 if (err) 290 if (err)
291 ...error handling... 291 ...error handling...
292 292
293 err = device_property_read_u32(dev, "p 293 err = device_property_read_u32(dev, "pagesize", &page_size);
294 if (err) 294 if (err)
295 ...error handling... 295 ...error handling...
296 296
297 err = device_property_read_u32(dev, "a 297 err = device_property_read_u32(dev, "address-width", &addr_width);
298 if (err) 298 if (err)
299 ...error handling... 299 ...error handling...
300 300
301 I2C serial bus support 301 I2C serial bus support
302 ====================== 302 ======================
303 303
304 The slaves behind I2C bus controller only need 304 The slaves behind I2C bus controller only need to add the ACPI IDs like
305 with the platform and SPI drivers. The I2C cor 305 with the platform and SPI drivers. The I2C core automatically enumerates
306 any slave devices behind the controller device 306 any slave devices behind the controller device once the adapter is
307 registered. 307 registered.
308 308
309 Below is an example of how to add ACPI support 309 Below is an example of how to add ACPI support to the existing mpu3050
310 input driver:: 310 input driver::
311 311
312 static const struct acpi_device_id mpu 312 static const struct acpi_device_id mpu3050_acpi_match[] = {
313 { "MPU3050", 0 }, 313 { "MPU3050", 0 },
314 { } 314 { }
315 }; 315 };
316 MODULE_DEVICE_TABLE(acpi, mpu3050_acpi 316 MODULE_DEVICE_TABLE(acpi, mpu3050_acpi_match);
317 317
318 static struct i2c_driver mpu3050_i2c_d 318 static struct i2c_driver mpu3050_i2c_driver = {
319 .driver = { 319 .driver = {
320 .name = "mpu3050", 320 .name = "mpu3050",
321 .pm = &mpu3050_pm, 321 .pm = &mpu3050_pm,
322 .of_match_table = mpu3 322 .of_match_table = mpu3050_of_match,
323 .acpi_match_table = mp 323 .acpi_match_table = mpu3050_acpi_match,
324 }, 324 },
325 .probe = mpu3050_prob 325 .probe = mpu3050_probe,
326 .remove = mpu3050_remo 326 .remove = mpu3050_remove,
327 .id_table = mpu3050_ids, 327 .id_table = mpu3050_ids,
328 }; 328 };
329 module_i2c_driver(mpu3050_i2c_driver); 329 module_i2c_driver(mpu3050_i2c_driver);
330 330
331 Reference to PWM device 331 Reference to PWM device
332 ======================= 332 =======================
333 333
334 Sometimes a device can be a consumer of PWM ch 334 Sometimes a device can be a consumer of PWM channel. Obviously OS would like
335 to know which one. To provide this mapping the 335 to know which one. To provide this mapping the special property has been
336 introduced, i.e.:: 336 introduced, i.e.::
337 337
338 Device (DEV) 338 Device (DEV)
339 { 339 {
340 Name (_DSD, Package () 340 Name (_DSD, Package ()
341 { 341 {
342 ToUUID("daffd814-6eba-4d8c-8a91-bc 342 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
343 Package () { 343 Package () {
344 Package () { "compatible", Pac 344 Package () { "compatible", Package () { "pwm-leds" } },
345 Package () { "label", "alarm-l 345 Package () { "label", "alarm-led" },
346 Package () { "pwms", 346 Package () { "pwms",
347 Package () { 347 Package () {
348 "\\_SB.PCI0.PWM", // 348 "\\_SB.PCI0.PWM", // <PWM device reference>
349 0, // 349 0, // <PWM index>
350 600000000, // 350 600000000, // <PWM period>
351 0, // 351 0, // <PWM flags>
352 } 352 }
353 } 353 }
354 } 354 }
355 }) 355 })
356 ... 356 ...
357 } 357 }
358 358
359 In the above example the PWM-based LED driver 359 In the above example the PWM-based LED driver references to the PWM channel 0
360 of \_SB.PCI0.PWM device with initial period se 360 of \_SB.PCI0.PWM device with initial period setting equal to 600 ms (note that
361 value is given in nanoseconds). 361 value is given in nanoseconds).
362 362
363 GPIO support 363 GPIO support
364 ============ 364 ============
365 365
366 ACPI 5 introduced two new resources to describ 366 ACPI 5 introduced two new resources to describe GPIO connections: GpioIo
367 and GpioInt. These resources can be used to pa 367 and GpioInt. These resources can be used to pass GPIO numbers used by
368 the device to the driver. ACPI 5.1 extended th 368 the device to the driver. ACPI 5.1 extended this with _DSD (Device
369 Specific Data) which made it possible to name 369 Specific Data) which made it possible to name the GPIOs among other things.
370 370
371 For example:: 371 For example::
372 372
373 Device (DEV) 373 Device (DEV)
374 { 374 {
375 Method (_CRS, 0, NotSerialized 375 Method (_CRS, 0, NotSerialized)
376 { 376 {
377 Name (SBUF, ResourceTe 377 Name (SBUF, ResourceTemplate()
378 { 378 {
379 // Used to pow 379 // Used to power on/off the device
380 GpioIo (Exclus 380 GpioIo (Exclusive, PullNone, 0, 0, IoRestrictionOutputOnly,
381 "\\_SB 381 "\\_SB.PCI0.GPI0", 0, ResourceConsumer) { 85 }
382 382
383 // Interrupt f 383 // Interrupt for the device
384 GpioInt (Edge, 384 GpioInt (Edge, ActiveHigh, ExclusiveAndWake, PullNone, 0,
385 "\\_S 385 "\\_SB.PCI0.GPI0", 0, ResourceConsumer) { 88 }
386 } 386 }
387 387
388 Return (SBUF) 388 Return (SBUF)
389 } 389 }
390 390
391 // ACPI 5.1 _DSD used for nami 391 // ACPI 5.1 _DSD used for naming the GPIOs
392 Name (_DSD, Package () 392 Name (_DSD, Package ()
393 { 393 {
394 ToUUID("daffd814-6eba- 394 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
395 Package () 395 Package ()
396 { 396 {
397 Package () { " 397 Package () { "power-gpios", Package () { ^DEV, 0, 0, 0 } },
398 Package () { " 398 Package () { "irq-gpios", Package () { ^DEV, 1, 0, 0 } },
399 } 399 }
400 }) 400 })
401 ... 401 ...
402 } 402 }
403 403
404 These GPIO numbers are controller relative and 404 These GPIO numbers are controller relative and path "\\_SB.PCI0.GPI0"
405 specifies the path to the controller. In order 405 specifies the path to the controller. In order to use these GPIOs in Linux
406 we need to translate them to the corresponding 406 we need to translate them to the corresponding Linux GPIO descriptors.
407 407
408 There is a standard GPIO API for that and it i 408 There is a standard GPIO API for that and it is documented in
409 Documentation/admin-guide/gpio/. 409 Documentation/admin-guide/gpio/.
410 410
411 In the above example we can get the correspond 411 In the above example we can get the corresponding two GPIO descriptors with
412 a code like this:: 412 a code like this::
413 413
414 #include <linux/gpio/consumer.h> 414 #include <linux/gpio/consumer.h>
415 ... 415 ...
416 416
417 struct gpio_desc *irq_desc, *power_des 417 struct gpio_desc *irq_desc, *power_desc;
418 418
419 irq_desc = gpiod_get(dev, "irq"); 419 irq_desc = gpiod_get(dev, "irq");
420 if (IS_ERR(irq_desc)) 420 if (IS_ERR(irq_desc))
421 /* handle error */ 421 /* handle error */
422 422
423 power_desc = gpiod_get(dev, "power"); 423 power_desc = gpiod_get(dev, "power");
424 if (IS_ERR(power_desc)) 424 if (IS_ERR(power_desc))
425 /* handle error */ 425 /* handle error */
426 426
427 /* Now we can use the GPIO descriptors 427 /* Now we can use the GPIO descriptors */
428 428
429 There are also devm_* versions of these functi 429 There are also devm_* versions of these functions which release the
430 descriptors once the device is released. 430 descriptors once the device is released.
431 431
432 See Documentation/firmware-guide/acpi/gpio-pro 432 See Documentation/firmware-guide/acpi/gpio-properties.rst for more information
433 about the _DSD binding related to GPIOs. 433 about the _DSD binding related to GPIOs.
434 434
435 RS-485 support 435 RS-485 support
436 ============== 436 ==============
437 437
438 ACPI _DSD (Device Specific Data) can be used t 438 ACPI _DSD (Device Specific Data) can be used to describe RS-485 capability
439 of UART. 439 of UART.
440 440
441 For example:: 441 For example::
442 442
443 Device (DEV) 443 Device (DEV)
444 { 444 {
445 ... 445 ...
446 446
447 // ACPI 5.1 _DSD used for RS-4 447 // ACPI 5.1 _DSD used for RS-485 capabilities
448 Name (_DSD, Package () 448 Name (_DSD, Package ()
449 { 449 {
450 ToUUID("daffd814-6eba- 450 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
451 Package () 451 Package ()
452 { 452 {
453 Package () {"r 453 Package () {"rs485-rts-active-low", Zero},
454 Package () {"r 454 Package () {"rs485-rx-active-high", Zero},
455 Package () {"r 455 Package () {"rs485-rx-during-tx", Zero},
456 } 456 }
457 }) 457 })
458 ... 458 ...
459 459
460 MFD devices 460 MFD devices
461 =========== 461 ===========
462 462
463 The MFD devices register their children as pla 463 The MFD devices register their children as platform devices. For the child
464 devices there needs to be an ACPI handle that 464 devices there needs to be an ACPI handle that they can use to reference
465 parts of the ACPI namespace that relate to the 465 parts of the ACPI namespace that relate to them. In the Linux MFD subsystem
466 we provide two ways: 466 we provide two ways:
467 467
468 - The children share the parent ACPI handle. 468 - The children share the parent ACPI handle.
469 - The MFD cell can specify the ACPI id of th 469 - The MFD cell can specify the ACPI id of the device.
470 470
471 For the first case, the MFD drivers do not nee 471 For the first case, the MFD drivers do not need to do anything. The
472 resulting child platform device will have its 472 resulting child platform device will have its ACPI_COMPANION() set to point
473 to the parent device. 473 to the parent device.
474 474
475 If the ACPI namespace has a device that we can 475 If the ACPI namespace has a device that we can match using an ACPI id or ACPI
476 adr, the cell should be set like:: 476 adr, the cell should be set like::
477 477
478 static struct mfd_cell_acpi_match my_s 478 static struct mfd_cell_acpi_match my_subdevice_cell_acpi_match = {
479 .pnpid = "XYZ0001", 479 .pnpid = "XYZ0001",
480 .adr = 0, 480 .adr = 0,
481 }; 481 };
482 482
483 static struct mfd_cell my_subdevice_ce 483 static struct mfd_cell my_subdevice_cell = {
484 .name = "my_subdevice", 484 .name = "my_subdevice",
485 /* set the resources relative 485 /* set the resources relative to the parent */
486 .acpi_match = &my_subdevice_ce 486 .acpi_match = &my_subdevice_cell_acpi_match,
487 }; 487 };
488 488
489 The ACPI id "XYZ0001" is then used to lookup a 489 The ACPI id "XYZ0001" is then used to lookup an ACPI device directly under
490 the MFD device and if found, that ACPI compani 490 the MFD device and if found, that ACPI companion device is bound to the
491 resulting child platform device. 491 resulting child platform device.
492 492
493 Device Tree namespace link device ID 493 Device Tree namespace link device ID
494 ==================================== 494 ====================================
495 495
496 The Device Tree protocol uses device identific 496 The Device Tree protocol uses device identification based on the "compatible"
497 property whose value is a string or an array o 497 property whose value is a string or an array of strings recognized as device
498 identifiers by drivers and the driver core. T 498 identifiers by drivers and the driver core. The set of all those strings may be
499 regarded as a device identification namespace 499 regarded as a device identification namespace analogous to the ACPI/PNP device
500 ID namespace. Consequently, in principle it s 500 ID namespace. Consequently, in principle it should not be necessary to allocate
501 a new (and arguably redundant) ACPI/PNP device 501 a new (and arguably redundant) ACPI/PNP device ID for a devices with an existing
502 identification string in the Device Tree (DT) 502 identification string in the Device Tree (DT) namespace, especially if that ID
503 is only needed to indicate that a given device 503 is only needed to indicate that a given device is compatible with another one,
504 presumably having a matching driver in the ker 504 presumably having a matching driver in the kernel already.
505 505
506 In ACPI, the device identification object call 506 In ACPI, the device identification object called _CID (Compatible ID) is used to
507 list the IDs of devices the given one is compa 507 list the IDs of devices the given one is compatible with, but those IDs must
508 belong to one of the namespaces prescribed by 508 belong to one of the namespaces prescribed by the ACPI specification (see
509 Section 6.1.2 of ACPI 6.0 for details) and the 509 Section 6.1.2 of ACPI 6.0 for details) and the DT namespace is not one of them.
510 Moreover, the specification mandates that eith 510 Moreover, the specification mandates that either a _HID or an _ADR identification
511 object be present for all ACPI objects represe 511 object be present for all ACPI objects representing devices (Section 6.1 of ACPI
512 6.0). For non-enumerable bus types that objec 512 6.0). For non-enumerable bus types that object must be _HID and its value must
513 be a device ID from one of the namespaces pres 513 be a device ID from one of the namespaces prescribed by the specification too.
514 514
515 The special DT namespace link device ID, PRP00 515 The special DT namespace link device ID, PRP0001, provides a means to use the
516 existing DT-compatible device identification i 516 existing DT-compatible device identification in ACPI and to satisfy the above
517 requirements following from the ACPI specifica 517 requirements following from the ACPI specification at the same time. Namely,
518 if PRP0001 is returned by _HID, the ACPI subsy 518 if PRP0001 is returned by _HID, the ACPI subsystem will look for the
519 "compatible" property in the device object's _ 519 "compatible" property in the device object's _DSD and will use the value of that
520 property to identify the corresponding device 520 property to identify the corresponding device in analogy with the original DT
521 device identification algorithm. If the "comp 521 device identification algorithm. If the "compatible" property is not present
522 or its value is not valid, the device will not 522 or its value is not valid, the device will not be enumerated by the ACPI
523 subsystem. Otherwise, it will be enumerated a 523 subsystem. Otherwise, it will be enumerated automatically as a platform device
524 (except when an I2C or SPI link from the devic 524 (except when an I2C or SPI link from the device to its parent is present, in
525 which case the ACPI core will leave the device 525 which case the ACPI core will leave the device enumeration to the parent's
526 driver) and the identification strings from th 526 driver) and the identification strings from the "compatible" property value will
527 be used to find a driver for the device along 527 be used to find a driver for the device along with the device IDs listed by _CID
528 (if present). 528 (if present).
529 529
530 Analogously, if PRP0001 is present in the list 530 Analogously, if PRP0001 is present in the list of device IDs returned by _CID,
531 the identification strings listed by the "comp 531 the identification strings listed by the "compatible" property value (if present
532 and valid) will be used to look for a driver m 532 and valid) will be used to look for a driver matching the device, but in that
533 case their relative priority with respect to t 533 case their relative priority with respect to the other device IDs listed by
534 _HID and _CID depends on the position of PRP00 534 _HID and _CID depends on the position of PRP0001 in the _CID return package.
535 Specifically, the device IDs returned by _HID 535 Specifically, the device IDs returned by _HID and preceding PRP0001 in the _CID
536 return package will be checked first. Also in 536 return package will be checked first. Also in that case the bus type the device
537 will be enumerated to depends on the device ID 537 will be enumerated to depends on the device ID returned by _HID.
538 538
539 For example, the following ACPI sample might b 539 For example, the following ACPI sample might be used to enumerate an lm75-type
540 I2C temperature sensor and match it to the dri 540 I2C temperature sensor and match it to the driver using the Device Tree
541 namespace link:: 541 namespace link::
542 542
543 Device (TMP0) 543 Device (TMP0)
544 { 544 {
545 Name (_HID, "PRP0001") 545 Name (_HID, "PRP0001")
546 Name (_DSD, Package () { 546 Name (_DSD, Package () {
547 ToUUID("daffd814-6eba- 547 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
548 Package () { 548 Package () {
549 Package () { " 549 Package () { "compatible", "ti,tmp75" },
550 } 550 }
551 }) 551 })
552 Method (_CRS, 0, Serialized) 552 Method (_CRS, 0, Serialized)
553 { 553 {
554 Name (SBUF, ResourceTe 554 Name (SBUF, ResourceTemplate ()
555 { 555 {
556 I2cSerialBusV2 556 I2cSerialBusV2 (0x48, ControllerInitiated,
557 400000 557 400000, AddressingMode7Bit,
558 "\\_SB 558 "\\_SB.PCI0.I2C1", 0x00,
559 Resour 559 ResourceConsumer, , Exclusive,)
560 }) 560 })
561 Return (SBUF) 561 Return (SBUF)
562 } 562 }
563 } 563 }
564 564
565 It is valid to define device objects with a _H 565 It is valid to define device objects with a _HID returning PRP0001 and without
566 the "compatible" property in the _DSD or a _CI 566 the "compatible" property in the _DSD or a _CID as long as one of their
567 ancestors provides a _DSD with a valid "compat 567 ancestors provides a _DSD with a valid "compatible" property. Such device
568 objects are then simply regarded as additional 568 objects are then simply regarded as additional "blocks" providing hierarchical
569 configuration information to the driver of the 569 configuration information to the driver of the composite ancestor device.
570 570
571 However, PRP0001 can only be returned from eit 571 However, PRP0001 can only be returned from either _HID or _CID of a device
572 object if all of the properties returned by th 572 object if all of the properties returned by the _DSD associated with it (either
573 the _DSD of the device object itself or the _D 573 the _DSD of the device object itself or the _DSD of its ancestor in the
574 "composite device" case described above) can b 574 "composite device" case described above) can be used in the ACPI environment.
575 Otherwise, the _DSD itself is regarded as inva 575 Otherwise, the _DSD itself is regarded as invalid and therefore the "compatible"
576 property returned by it is meaningless. 576 property returned by it is meaningless.
577 577
578 Refer to Documentation/firmware-guide/acpi/DSD 578 Refer to Documentation/firmware-guide/acpi/DSD-properties-rules.rst for more
579 information. 579 information.
580 580
581 PCI hierarchy representation 581 PCI hierarchy representation
582 ============================ 582 ============================
583 583
584 Sometimes it could be useful to enumerate a PC 584 Sometimes it could be useful to enumerate a PCI device, knowing its position on
585 the PCI bus. 585 the PCI bus.
586 586
587 For example, some systems use PCI devices sold 587 For example, some systems use PCI devices soldered directly on the mother board,
588 in a fixed position (ethernet, Wi-Fi, serial p 588 in a fixed position (ethernet, Wi-Fi, serial ports, etc.). In this conditions it
589 is possible to refer to these PCI devices know 589 is possible to refer to these PCI devices knowing their position on the PCI bus
590 topology. 590 topology.
591 591
592 To identify a PCI device, a complete hierarchi 592 To identify a PCI device, a complete hierarchical description is required, from
593 the chipset root port to the final device, thr 593 the chipset root port to the final device, through all the intermediate
594 bridges/switches of the board. 594 bridges/switches of the board.
595 595
596 For example, let's assume we have a system wit 596 For example, let's assume we have a system with a PCIe serial port, an
597 Exar XR17V3521, soldered on the main board. Th 597 Exar XR17V3521, soldered on the main board. This UART chip also includes
598 16 GPIOs and we want to add the property ``gpi 598 16 GPIOs and we want to add the property ``gpio-line-names`` [1]_ to these pins.
599 In this case, the ``lspci`` output for this co 599 In this case, the ``lspci`` output for this component is::
600 600
601 07:00.0 Serial controller: Exar Corp. 601 07:00.0 Serial controller: Exar Corp. XR17V3521 Dual PCIe UART (rev 03)
602 602
603 The complete ``lspci`` output (manually reduce 603 The complete ``lspci`` output (manually reduced in length) is::
604 604
605 00:00.0 Host bridge: Intel Corp... Hos 605 00:00.0 Host bridge: Intel Corp... Host Bridge (rev 0d)
606 ... 606 ...
607 00:13.0 PCI bridge: Intel Corp... PCI 607 00:13.0 PCI bridge: Intel Corp... PCI Express Port A #1 (rev fd)
608 00:13.1 PCI bridge: Intel Corp... PCI 608 00:13.1 PCI bridge: Intel Corp... PCI Express Port A #2 (rev fd)
609 00:13.2 PCI bridge: Intel Corp... PCI 609 00:13.2 PCI bridge: Intel Corp... PCI Express Port A #3 (rev fd)
610 00:14.0 PCI bridge: Intel Corp... PCI 610 00:14.0 PCI bridge: Intel Corp... PCI Express Port B #1 (rev fd)
611 00:14.1 PCI bridge: Intel Corp... PCI 611 00:14.1 PCI bridge: Intel Corp... PCI Express Port B #2 (rev fd)
612 ... 612 ...
613 05:00.0 PCI bridge: Pericom Semiconduc 613 05:00.0 PCI bridge: Pericom Semiconductor Device 2404 (rev 05)
614 06:01.0 PCI bridge: Pericom Semiconduc 614 06:01.0 PCI bridge: Pericom Semiconductor Device 2404 (rev 05)
615 06:02.0 PCI bridge: Pericom Semiconduc 615 06:02.0 PCI bridge: Pericom Semiconductor Device 2404 (rev 05)
616 06:03.0 PCI bridge: Pericom Semiconduc 616 06:03.0 PCI bridge: Pericom Semiconductor Device 2404 (rev 05)
617 07:00.0 Serial controller: Exar Corp. 617 07:00.0 Serial controller: Exar Corp. XR17V3521 Dual PCIe UART (rev 03) <-- Exar
618 ... 618 ...
619 619
620 The bus topology is:: 620 The bus topology is::
621 621
622 -[0000:00]-+-00.0 622 -[0000:00]-+-00.0
623 ... 623 ...
624 +-13.0-[01]----00.0 624 +-13.0-[01]----00.0
625 +-13.1-[02]----00.0 625 +-13.1-[02]----00.0
626 +-13.2-[03]-- 626 +-13.2-[03]--
627 +-14.0-[04]----00.0 627 +-14.0-[04]----00.0
628 +-14.1-[05-09]----00.0-[06- 628 +-14.1-[05-09]----00.0-[06-09]--+-01.0-[07]----00.0 <-- Exar
629 | 629 | +-02.0-[08]----00.0
630 | 630 | \-03.0-[09]--
631 ... 631 ...
632 \-1f.1 632 \-1f.1
633 633
634 To describe this Exar device on the PCI bus, w 634 To describe this Exar device on the PCI bus, we must start from the ACPI name
635 of the chipset bridge (also called "root port" 635 of the chipset bridge (also called "root port") with address::
636 636
637 Bus: 0 - Device: 14 - Function: 1 637 Bus: 0 - Device: 14 - Function: 1
638 638
639 To find this information, it is necessary to d 639 To find this information, it is necessary to disassemble the BIOS ACPI tables,
640 in particular the DSDT (see also [2]_):: 640 in particular the DSDT (see also [2]_)::
641 641
642 mkdir ~/tables/ 642 mkdir ~/tables/
643 cd ~/tables/ 643 cd ~/tables/
644 acpidump > acpidump 644 acpidump > acpidump
645 acpixtract -a acpidump 645 acpixtract -a acpidump
646 iasl -e ssdt?.* -d dsdt.dat 646 iasl -e ssdt?.* -d dsdt.dat
647 647
648 Now, in the dsdt.dsl, we have to search the de 648 Now, in the dsdt.dsl, we have to search the device whose address is related to
649 0x14 (device) and 0x01 (function). In this cas 649 0x14 (device) and 0x01 (function). In this case we can find the following
650 device:: 650 device::
651 651
652 Scope (_SB.PCI0) 652 Scope (_SB.PCI0)
653 { 653 {
654 ... other definitions follow ... 654 ... other definitions follow ...
655 Device (RP02) 655 Device (RP02)
656 { 656 {
657 Method (_ADR, 0, NotSe 657 Method (_ADR, 0, NotSerialized) // _ADR: Address
658 { 658 {
659 If ((RPA2 != Z 659 If ((RPA2 != Zero))
660 { 660 {
661 Return 661 Return (RPA2) /* \RPA2 */
662 } 662 }
663 Else 663 Else
664 { 664 {
665 Return 665 Return (0x00140001)
666 } 666 }
667 } 667 }
668 ... other definitions follow ... 668 ... other definitions follow ...
669 669
670 and the _ADR method [3]_ returns exactly the d 670 and the _ADR method [3]_ returns exactly the device/function couple that
671 we are looking for. With this information and 671 we are looking for. With this information and analyzing the above ``lspci``
672 output (both the devices list and the devices 672 output (both the devices list and the devices tree), we can write the following
673 ACPI description for the Exar PCIe UART, also 673 ACPI description for the Exar PCIe UART, also adding the list of its GPIO line
674 names:: 674 names::
675 675
676 Scope (_SB.PCI0.RP02) 676 Scope (_SB.PCI0.RP02)
677 { 677 {
678 Device (BRG1) //Bridge 678 Device (BRG1) //Bridge
679 { 679 {
680 Name (_ADR, 0x0000) 680 Name (_ADR, 0x0000)
681 681
682 Device (BRG2) //Bridge 682 Device (BRG2) //Bridge
683 { 683 {
684 Name (_ADR, 0x 684 Name (_ADR, 0x00010000)
685 685
686 Device (EXAR) 686 Device (EXAR)
687 { 687 {
688 Name ( 688 Name (_ADR, 0x0000)
689 689
690 Name ( 690 Name (_DSD, Package ()
691 { 691 {
692 692 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
693 693 Package ()
694 694 {
695 695 Package ()
696 696 {
697 697 "gpio-line-names",
698 698 Package ()
699 699 {
700 700 "mode_232",
701 701 "mode_422",
702 702 "mode_485",
703 703 "misc_1",
704 704 "misc_2",
705 705 "misc_3",
706 706 "",
707 707 "",
708 708 "aux_1",
709 709 "aux_2",
710 710 "aux_3",
711 711 }
712 712 }
713 713 }
714 }) 714 })
715 } 715 }
716 } 716 }
717 } 717 }
718 } 718 }
719 719
720 The location "_SB.PCI0.RP02" is obtained by th 720 The location "_SB.PCI0.RP02" is obtained by the above investigation in the
721 dsdt.dsl table, whereas the device names "BRG1 721 dsdt.dsl table, whereas the device names "BRG1", "BRG2" and "EXAR" are
722 created analyzing the position of the Exar UAR 722 created analyzing the position of the Exar UART in the PCI bus topology.
723 723
724 References 724 References
725 ========== 725 ==========
726 726
727 .. [1] Documentation/firmware-guide/acpi/gpio- 727 .. [1] Documentation/firmware-guide/acpi/gpio-properties.rst
728 728
729 .. [2] Documentation/admin-guide/acpi/initrd_t 729 .. [2] Documentation/admin-guide/acpi/initrd_table_override.rst
730 730
731 .. [3] ACPI Specifications, Version 6.3 - Para 731 .. [3] ACPI Specifications, Version 6.3 - Paragraph 6.1.1 _ADR Address)
732 https://uefi.org/sites/default/files/resou 732 https://uefi.org/sites/default/files/resources/ACPI_6_3_May16.pdf,
733 referenced 2020-11-18 733 referenced 2020-11-18
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.