About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / acpi / enumeration.txt




Custom Search

Based on kernel version 3.15.4. Page generated on 2014-07-07 08:59 EST.

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/acpi_platform.c. This limitation is only for the platform
67	devices, SPI and I2C devices are created automatically as described below.
68	
69	DMA support
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_slave_channel() must register itself at the end of the probe
75	function like 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_slave_channel() will call xlate_func() for each registered DMA
116	controller. 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_slave_channel() with the string parameter that
121	corresponds to a specific FixedDMA resource. By default "tx" means the first
122	entry of the FixedDMA resource array, "rx" means the second entry. The table
123	below shows a 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	Slave devices behind SPI bus have SpiSerialBus resource attached to them.
149	This is extracted automatically by the SPI core and the slave devices are
150	enumerated once spi_register_master() is called by the bus driver.
151	
152	Here is what the ACPI namespace for a SPI slave might look like:
153	
154		Device (EEP0)
155		{
156			Name (_ADR, 1)
157			Name (_CID, Package() {
158				"ATML0025",
159				"AT25",
160			})
161			...
162			Method (_CRS, 0, NotSerialized)
163			{
164				SPISerialBus(1, PolarityLow, FourWireMode, 8,
165					ControllerInitiated, 1000000, ClockPolarityLow,
166					ClockPhaseFirst, "\\_SB.PCI0.SPI1",)
167			}
168			...
169	
170	The SPI device drivers only need to add ACPI IDs in a similar way than with
171	the platform device drivers. Below is an example where we add ACPI support
172	to at25 SPI eeprom driver (this is meant for the above ACPI snippet):
173	
174		#ifdef CONFIG_ACPI
175		static struct acpi_device_id at25_acpi_match[] = {
176			{ "AT25", 0 },
177			{ },
178		};
179		MODULE_DEVICE_TABLE(acpi, at25_acpi_match);
180		#endif
181	
182		static struct spi_driver at25_driver = {
183			.driver = {
184				...
185				.acpi_match_table = ACPI_PTR(at25_acpi_match),
186			},
187		};
188	
189	Note that this driver actually needs more information like page size of the
190	eeprom etc. but at the time writing this there is no standard way of
191	passing those. One idea is to return this in _DSM method like:
192	
193		Device (EEP0)
194		{
195			...
196			Method (_DSM, 4, NotSerialized)
197			{
198				Store (Package (6)
199				{
200					"byte-len", 1024,
201					"addr-mode", 2,
202					"page-size, 32
203				}, Local0)
204	
205				// Check UUIDs etc.
206	
207				Return (Local0)
208			}
209	
210	Then the at25 SPI driver can get this configuration by calling _DSM on its
211	ACPI handle like:
212	
213		struct acpi_buffer output = { ACPI_ALLOCATE_BUFFER, NULL };
214		struct acpi_object_list input;
215		acpi_status status;
216	
217		/* Fill in the input buffer */
218	
219		status = acpi_evaluate_object(ACPI_HANDLE(&spi->dev), "_DSM",
220					      &input, &output);
221		if (ACPI_FAILURE(status))
222			/* Handle the error */
223	
224		/* Extract the data here */
225	
226		kfree(output.pointer);
227	
228	I2C serial bus support
229	~~~~~~~~~~~~~~~~~~~~~~
230	The slaves behind I2C bus controller only need to add the ACPI IDs like
231	with the platform and SPI drivers. The I2C core automatically enumerates
232	any slave devices behind the controller device once the adapter is
233	registered.
234	
235	Below is an example of how to add ACPI support to the existing mpu3050
236	input driver:
237	
238		#ifdef CONFIG_ACPI
239		static struct acpi_device_id mpu3050_acpi_match[] = {
240			{ "MPU3050", 0 },
241			{ },
242		};
243		MODULE_DEVICE_TABLE(acpi, mpu3050_acpi_match);
244		#endif
245	
246		static struct i2c_driver mpu3050_i2c_driver = {
247			.driver	= {
248				.name	= "mpu3050",
249				.owner	= THIS_MODULE,
250				.pm	= &mpu3050_pm,
251				.of_match_table = mpu3050_of_match,
252				.acpi_match_table  ACPI_PTR(mpu3050_acpi_match),
253			},
254			.probe		= mpu3050_probe,
255			.remove		= mpu3050_remove,
256			.id_table	= mpu3050_ids,
257		};
258	
259	GPIO support
260	~~~~~~~~~~~~
261	ACPI 5 introduced two new resources to describe GPIO connections: GpioIo
262	and GpioInt. These resources are used be used to pass GPIO numbers used by
263	the device to the driver. For example:
264	
265		Method (_CRS, 0, NotSerialized)
266		{
267			Name (SBUF, ResourceTemplate()
268			{
269				...
270				// Used to power on/off the device
271				GpioIo (Exclusive, PullDefault, 0x0000, 0x0000,
272					IoRestrictionOutputOnly, "\\_SB.PCI0.GPI0",
273					0x00, ResourceConsumer,,)
274				{
275					// Pin List
276					0x0055
277				}
278	
279				// Interrupt for the device
280				GpioInt (Edge, ActiveHigh, ExclusiveAndWake, PullNone,
281					 0x0000, "\\_SB.PCI0.GPI0", 0x00, ResourceConsumer,,)
282				{
283					// Pin list
284					0x0058
285				}
286	
287				...
288	
289			}
290	
291			Return (SBUF)
292		}
293	
294	These GPIO numbers are controller relative and path "\\_SB.PCI0.GPI0"
295	specifies the path to the controller. In order to use these GPIOs in Linux
296	we need to translate them to the corresponding Linux GPIO descriptors.
297	
298	There is a standard GPIO API for that and is documented in
299	Documentation/gpio.txt.
300	
301	In the above example we can get the corresponding two GPIO descriptors with
302	a code like this:
303	
304		#include <linux/gpio/consumer.h>
305		...
306	
307		struct gpio_desc *irq_desc, *power_desc;
308	
309		irq_desc = gpiod_get_index(dev, NULL, 1);
310		if (IS_ERR(irq_desc))
311			/* handle error */
312	
313		power_desc = gpiod_get_index(dev, NULL, 0);
314		if (IS_ERR(power_desc))
315			/* handle error */
316	
317		/* Now we can use the GPIO descriptors */
318	
319	There are also devm_* versions of these functions which release the
320	descriptors once the device is released.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.