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 | |
45 | static struct acpi_device_id mydrv_acpi_match[] = { | |
46 | /* ACPI IDs here */ | |
47 | { } | |
48 | }; | |
49 | MODULE_DEVICE_TABLE(acpi, mydrv_acpi_match); | |
50 | #endif | |
51 | ||
52 | static struct platform_driver my_driver = { | |
53 | ... | |
54 | .driver = { | |
55 | .acpi_match_table = ACPI_PTR(mydrv_acpi_match), | |
56 | }, | |
57 | }; | |
58 | ||
59 | If the driver needs to perform more complex initialization like getting and | |
60 | configuring GPIOs it can get its ACPI handle and extract this information | |
61 | from ACPI tables. | |
62 | ||
63 | Currently the kernel is not able to automatically determine from which ACPI | |
64 | device it should make the corresponding platform device so we need to add | |
65 | the ACPI device explicitly to acpi_platform_device_ids list defined in | |
66 | drivers/acpi/scan.c. This limitation is only for the platform devices, SPI | |
67 | and I2C devices are created automatically as described below. | |
68 | ||
69 | SPI serial bus support | |
70 | ~~~~~~~~~~~~~~~~~~~~~~ | |
71 | Slave devices behind SPI bus have SpiSerialBus resource attached to them. | |
72 | This is extracted automatically by the SPI core and the slave devices are | |
73 | enumerated once spi_register_master() is called by the bus driver. | |
74 | ||
75 | Here is what the ACPI namespace for a SPI slave might look like: | |
76 | ||
77 | Device (EEP0) | |
78 | { | |
79 | Name (_ADR, 1) | |
80 | Name (_CID, Package() { | |
81 | "ATML0025", | |
82 | "AT25", | |
83 | }) | |
84 | ... | |
85 | Method (_CRS, 0, NotSerialized) | |
86 | { | |
87 | SPISerialBus(1, PolarityLow, FourWireMode, 8, | |
88 | ControllerInitiated, 1000000, ClockPolarityLow, | |
89 | ClockPhaseFirst, "\\_SB.PCI0.SPI1",) | |
90 | } | |
91 | ... | |
92 | ||
93 | The SPI device drivers only need to add ACPI IDs in a similar way than with | |
94 | the platform device drivers. Below is an example where we add ACPI support | |
95 | to at25 SPI eeprom driver (this is meant for the above ACPI snippet): | |
96 | ||
97 | #ifdef CONFIG_ACPI | |
98 | static struct acpi_device_id at25_acpi_match[] = { | |
99 | { "AT25", 0 }, | |
100 | { }, | |
101 | }; | |
102 | MODULE_DEVICE_TABLE(acpi, at25_acpi_match); | |
103 | #endif | |
104 | ||
105 | static struct spi_driver at25_driver = { | |
106 | .driver = { | |
107 | ... | |
108 | .acpi_match_table = ACPI_PTR(at25_acpi_match), | |
109 | }, | |
110 | }; | |
111 | ||
112 | Note that this driver actually needs more information like page size of the | |
113 | eeprom etc. but at the time writing this there is no standard way of | |
114 | passing those. One idea is to return this in _DSM method like: | |
115 | ||
116 | Device (EEP0) | |
117 | { | |
118 | ... | |
119 | Method (_DSM, 4, NotSerialized) | |
120 | { | |
121 | Store (Package (6) | |
122 | { | |
123 | "byte-len", 1024, | |
124 | "addr-mode", 2, | |
125 | "page-size, 32 | |
126 | }, Local0) | |
127 | ||
128 | // Check UUIDs etc. | |
129 | ||
130 | Return (Local0) | |
131 | } | |
132 | ||
133 | Then the at25 SPI driver can get this configation by calling _DSM on its | |
134 | ACPI handle like: | |
135 | ||
136 | struct acpi_buffer output = { ACPI_ALLOCATE_BUFFER, NULL }; | |
137 | struct acpi_object_list input; | |
138 | acpi_status status; | |
139 | ||
140 | /* Fill in the input buffer */ | |
141 | ||
142 | status = acpi_evaluate_object(ACPI_HANDLE(&spi->dev), "_DSM", | |
143 | &input, &output); | |
144 | if (ACPI_FAILURE(status)) | |
145 | /* Handle the error */ | |
146 | ||
147 | /* Extract the data here */ | |
148 | ||
149 | kfree(output.pointer); | |
150 | ||
151 | I2C serial bus support | |
152 | ~~~~~~~~~~~~~~~~~~~~~~ | |
153 | The slaves behind I2C bus controller only need to add the ACPI IDs like | |
154 | with the platform and SPI drivers. However the I2C bus controller driver | |
155 | needs to call acpi_i2c_register_devices() after it has added the adapter. | |
156 | ||
157 | An I2C bus (controller) driver does: | |
158 | ||
159 | ... | |
160 | ret = i2c_add_numbered_adapter(adapter); | |
161 | if (ret) | |
162 | /* handle error */ | |
163 | ||
164 | of_i2c_register_devices(adapter); | |
165 | /* Enumerate the slave devices behind this bus via ACPI */ | |
166 | acpi_i2c_register_devices(adapter); | |
167 | ||
168 | Below is an example of how to add ACPI support to the existing mpu3050 | |
169 | input driver: | |
170 | ||
171 | #ifdef CONFIG_ACPI | |
172 | static struct acpi_device_id mpu3050_acpi_match[] = { | |
173 | { "MPU3050", 0 }, | |
174 | { }, | |
175 | }; | |
176 | MODULE_DEVICE_TABLE(acpi, mpu3050_acpi_match); | |
177 | #endif | |
178 | ||
179 | static struct i2c_driver mpu3050_i2c_driver = { | |
180 | .driver = { | |
181 | .name = "mpu3050", | |
182 | .owner = THIS_MODULE, | |
183 | .pm = &mpu3050_pm, | |
184 | .of_match_table = mpu3050_of_match, | |
185 | .acpi_match_table ACPI_PTR(mpu3050_acpi_match), | |
186 | }, | |
187 | .probe = mpu3050_probe, | |
63a29f74 | 188 | .remove = mpu3050_remove, |
59c39878 MW |
189 | .id_table = mpu3050_ids, |
190 | }; | |
191 | ||
192 | GPIO support | |
193 | ~~~~~~~~~~~~ | |
194 | ACPI 5 introduced two new resources to describe GPIO connections: GpioIo | |
195 | and GpioInt. These resources are used be used to pass GPIO numbers used by | |
196 | the device to the driver. For example: | |
197 | ||
198 | Method (_CRS, 0, NotSerialized) | |
199 | { | |
200 | Name (SBUF, ResourceTemplate() | |
201 | { | |
202 | GpioIo (Exclusive, PullDefault, 0x0000, 0x0000, | |
203 | IoRestrictionOutputOnly, "\\_SB.PCI0.GPI0", | |
204 | 0x00, ResourceConsumer,,) | |
205 | { | |
206 | // Pin List | |
207 | 0x0055 | |
208 | } | |
209 | ... | |
210 | ||
211 | Return (SBUF) | |
212 | } | |
213 | } | |
214 | ||
215 | These GPIO numbers are controller relative and path "\\_SB.PCI0.GPI0" | |
216 | specifies the path to the controller. In order to use these GPIOs in Linux | |
217 | we need to translate them to the Linux GPIO numbers. | |
218 | ||
219 | The driver can do this by including <linux/acpi_gpio.h> and then calling | |
220 | acpi_get_gpio(path, gpio). This will return the Linux GPIO number or | |
221 | negative errno if there was no translation found. | |
222 | ||
223 | Other GpioIo parameters must be converted first by the driver to be | |
224 | suitable to the gpiolib before passing them. | |
225 | ||
226 | In case of GpioInt resource an additional call to gpio_to_irq() must be | |
227 | done before calling request_irq(). |