About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / acpi / enumeration.txt




Custom Search

Based on kernel version 4.1. Page generated on 2015-06-28 12:07 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	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	
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
169		static struct acpi_device_id at25_acpi_match[] = {
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	
204	Then the at25 SPI driver can get this configuration by calling _DSM on its
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
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.
228	
229	Below is an example of how to add ACPI support to the existing mpu3050
230	input driver:
231	
232		#ifdef CONFIG_ACPI
233		static struct acpi_device_id mpu3050_acpi_match[] = {
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,
246				.acpi_match_table = ACPI_PTR(mpu3050_acpi_match),
247			},
248			.probe		= mpu3050_probe,
249			.remove		= mpu3050_remove,
250			.id_table	= mpu3050_ids,
251		};
252	
253	GPIO support
254	~~~~~~~~~~~~
255	ACPI 5 introduced two new resources to describe GPIO connections: GpioIo
256	and GpioInt. These resources can be used to pass GPIO numbers used by
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.
259	
260	For example:
261	
262	Device (DEV)
263	{
264		Method (_CRS, 0, NotSerialized)
265		{
266			Name (SBUF, ResourceTemplate()
267			{
268				...
269				// Used to power on/off the device
270				GpioIo (Exclusive, PullDefault, 0x0000, 0x0000,
271					IoRestrictionOutputOnly, "\\_SB.PCI0.GPI0",
272					0x00, ResourceConsumer,,)
273				{
274					// Pin List
275					0x0055
276				}
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	
286				...
287	
288			}
289	
290			Return (SBUF)
291		}
292	
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	
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
307	we need to translate them to the corresponding Linux GPIO descriptors.
308	
309	There is a standard GPIO API for that and is documented in
310	Documentation/gpio/.
311	
312	In the above example we can get the corresponding two GPIO descriptors with
313	a code like this:
314	
315		#include <linux/gpio/consumer.h>
316		...
317	
318		struct gpio_desc *irq_desc, *power_desc;
319	
320		irq_desc = gpiod_get(dev, "irq");
321		if (IS_ERR(irq_desc))
322			/* handle error */
323	
324		power_desc = gpiod_get(dev, "power");
325		if (IS_ERR(power_desc))
326			/* handle error */
327	
328		/* Now we can use the GPIO descriptors */
329	
330	There are also devm_* versions of these functions which release the
331	descriptors once the device is released.
332	
333	See Documentation/acpi/gpio-properties.txt for more information about the
334	_DSD binding related to GPIOs.
335	
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	
350	If the ACPI namespace has a device that we can match using an ACPI id,
351	the id should be set like:
352	
353		static struct mfd_cell my_subdevice_cell = {
354			.name = "my_subdevice",
355			/* set the resources relative to the parent */
356			.acpi_pnpid = "XYZ0001",
357		};
358	
359	The ACPI id "XYZ0001" is then used to lookup an ACPI device directly under
360	the MFD device and if found, that ACPI companion device is bound to the
361	resulting child platform device.
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.