[linux-2.6-block.git] / Documentation / acpi / enumeration.txt

ACPI based device enumeration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
ACPI 5 introduced a set of new resources (UartTSerialBus, I2cSerialBus,
SpiSerialBus, GpioIo and GpioInt) which can be used in enumerating slave
devices behind serial bus controllers.

In addition we are starting to see peripherals integrated in the
SoC/Chipset to appear only in ACPI namespace. These are typically devices
that are accessed through memory-mapped registers.

In order to support this and re-use the existing drivers as much as
possible we decided to do following:

	o Devices that have no bus connector resource are represented as
	  platform devices.

	o Devices behind real busses where there is a connector resource
	  are represented as struct spi_device or struct i2c_device
	  (standard UARTs are not busses so there is no struct uart_device).

As both ACPI and Device Tree represent a tree of devices (and their
resources) this implementation follows the Device Tree way as much as
possible.

The ACPI implementation enumerates devices behind busses (platform, SPI and
I2C), creates the physical devices and binds them to their ACPI handle in
the ACPI namespace.

This means that when ACPI_HANDLE(dev) returns non-NULL the device was
enumerated from ACPI namespace. This handle can be used to extract other
device-specific configuration. There is an example of this below.

Platform bus support
~~~~~~~~~~~~~~~~~~~~
Since we are using platform devices to represent devices that are not
connected to any physical bus we only need to implement a platform driver
for the device and add supported ACPI IDs. If this same IP-block is used on
some other non-ACPI platform, the driver might work out of the box or needs
some minor changes.

Adding ACPI support for an existing driver should be pretty
straightforward. Here is the simplest example:

	#ifdef CONFIG_ACPI
	static struct acpi_device_id mydrv_acpi_match[] = {
		/* ACPI IDs here */
		{ }
	};
	MODULE_DEVICE_TABLE(acpi, mydrv_acpi_match);
	#endif

	static struct platform_driver my_driver = {
		...
		.driver = {
			.acpi_match_table = ACPI_PTR(mydrv_acpi_match),
		},
	};

If the driver needs to perform more complex initialization like getting and
configuring GPIOs it can get its ACPI handle and extract this information
from ACPI tables.

Currently the kernel is not able to automatically determine from which ACPI
device it should make the corresponding platform device so we need to add
the ACPI device explicitly to acpi_platform_device_ids list defined in
drivers/acpi/acpi_platform.c. This limitation is only for the platform
devices, SPI and I2C devices are created automatically as described below.

DMA support
~~~~~~~~~~~
DMA controllers enumerated via ACPI should be registered in the system to
provide generic access to their resources. For example, a driver that would
like to be accessible to slave devices via generic API call
dma_request_slave_channel() must register itself at the end of the probe
function like this:

	err = devm_acpi_dma_controller_register(dev, xlate_func, dw);
	/* Handle the error if it's not a case of !CONFIG_ACPI */

and implement custom xlate function if needed (usually acpi_dma_simple_xlate()
is enough) which converts the FixedDMA resource provided by struct
acpi_dma_spec into the corresponding DMA channel. A piece of code for that case
could look like:

	#ifdef CONFIG_ACPI
	struct filter_args {
		/* Provide necessary information for the filter_func */
		...
	};

	static bool filter_func(struct dma_chan *chan, void *param)
	{
		/* Choose the proper channel */
		...
	}

	static struct dma_chan *xlate_func(struct acpi_dma_spec *dma_spec,
			struct acpi_dma *adma)
	{
		dma_cap_mask_t cap;
		struct filter_args args;

		/* Prepare arguments for filter_func */
		...
		return dma_request_channel(cap, filter_func, &args);
	}
	#else
	static struct dma_chan *xlate_func(struct acpi_dma_spec *dma_spec,
			struct acpi_dma *adma)
	{
		return NULL;
	}
	#endif

dma_request_slave_channel() will call xlate_func() for each registered DMA
controller. In the xlate function the proper channel must be chosen based on
information in struct acpi_dma_spec and the properties of the controller
provided by struct acpi_dma.

Clients must call dma_request_slave_channel() with the string parameter that
corresponds to a specific FixedDMA resource. By default "tx" means the first
entry of the FixedDMA resource array, "rx" means the second entry. The table
below shows a layout:

	Device (I2C0)
	{
		...
		Method (_CRS, 0, NotSerialized)
		{
			Name (DBUF, ResourceTemplate ()
			{
				FixedDMA (0x0018, 0x0004, Width32bit, _Y48)
				FixedDMA (0x0019, 0x0005, Width32bit, )
			})
		...
		}
	}

So, the FixedDMA with request line 0x0018 is "tx" and next one is "rx" in
this example.

In robust cases the client unfortunately needs to call
acpi_dma_request_slave_chan_by_index() directly and therefore choose the
specific FixedDMA resource by its index.

SPI serial bus support
~~~~~~~~~~~~~~~~~~~~~~
Slave devices behind SPI bus have SpiSerialBus resource attached to them.
This is extracted automatically by the SPI core and the slave devices are
enumerated once spi_register_master() is called by the bus driver.

Here is what the ACPI namespace for a SPI slave might look like:

	Device (EEP0)
	{
		Name (_ADR, 1)
		Name (_CID, Package() {
			"ATML0025",
			"AT25",
		})
		...
		Method (_CRS, 0, NotSerialized)
		{
			SPISerialBus(1, PolarityLow, FourWireMode, 8,
				ControllerInitiated, 1000000, ClockPolarityLow,
				ClockPhaseFirst, "\\_SB.PCI0.SPI1",)
		}
		...

The SPI device drivers only need to add ACPI IDs in a similar way than with
the platform device drivers. Below is an example where we add ACPI support
to at25 SPI eeprom driver (this is meant for the above ACPI snippet):

	#ifdef CONFIG_ACPI
	static struct acpi_device_id at25_acpi_match[] = {
		{ "AT25", 0 },
		{ },
	};
	MODULE_DEVICE_TABLE(acpi, at25_acpi_match);
	#endif

	static struct spi_driver at25_driver = {
		.driver = {
			...
			.acpi_match_table = ACPI_PTR(at25_acpi_match),
		},
	};

Note that this driver actually needs more information like page size of the
eeprom etc. but at the time writing this there is no standard way of
passing those. One idea is to return this in _DSM method like:

	Device (EEP0)
	{
		...
		Method (_DSM, 4, NotSerialized)
		{
			Store (Package (6)
			{
				"byte-len", 1024,
				"addr-mode", 2,
				"page-size, 32
			}, Local0)

			// Check UUIDs etc.

			Return (Local0)
		}

Then the at25 SPI driver can get this configation by calling _DSM on its
ACPI handle like:

	struct acpi_buffer output = { ACPI_ALLOCATE_BUFFER, NULL };
	struct acpi_object_list input;
	acpi_status status;

	/* Fill in the input buffer */

	status = acpi_evaluate_object(ACPI_HANDLE(&spi->dev), "_DSM",
				      &input, &output);
	if (ACPI_FAILURE(status))
		/* Handle the error */

	/* Extract the data here */

	kfree(output.pointer);

I2C serial bus support
~~~~~~~~~~~~~~~~~~~~~~
The slaves behind I2C bus controller only need to add the ACPI IDs like
with the platform and SPI drivers. However the I2C bus controller driver
needs to call acpi_i2c_register_devices() after it has added the adapter.

An I2C bus (controller) driver does:

	...
	ret = i2c_add_numbered_adapter(adapter);
	if (ret)
		/* handle error */

	/* Enumerate the slave devices behind this bus via ACPI */
	acpi_i2c_register_devices(adapter);

Below is an example of how to add ACPI support to the existing mpu3050
input driver:

	#ifdef CONFIG_ACPI
	static struct acpi_device_id mpu3050_acpi_match[] = {
		{ "MPU3050", 0 },
		{ },
	};
	MODULE_DEVICE_TABLE(acpi, mpu3050_acpi_match);
	#endif

	static struct i2c_driver mpu3050_i2c_driver = {
		.driver	= {
			.name	= "mpu3050",
			.owner	= THIS_MODULE,
			.pm	= &mpu3050_pm,
			.of_match_table = mpu3050_of_match,
			.acpi_match_table  ACPI_PTR(mpu3050_acpi_match),
		},
		.probe		= mpu3050_probe,
		.remove		= mpu3050_remove,
		.id_table	= mpu3050_ids,
	};

GPIO support
~~~~~~~~~~~~
ACPI 5 introduced two new resources to describe GPIO connections: GpioIo
and GpioInt. These resources are used be used to pass GPIO numbers used by
the device to the driver. For example:

	Method (_CRS, 0, NotSerialized)
	{
		Name (SBUF, ResourceTemplate()
		{
			...
			// Used to power on/off the device
			GpioIo (Exclusive, PullDefault, 0x0000, 0x0000,
				IoRestrictionOutputOnly, "\\_SB.PCI0.GPI0",
				0x00, ResourceConsumer,,)
			{
				// Pin List
				0x0055
			}

			// Interrupt for the device
			GpioInt (Edge, ActiveHigh, ExclusiveAndWake, PullNone,
				 0x0000, "\\_SB.PCI0.GPI0", 0x00, ResourceConsumer,,)
			{
				// Pin list
				0x0058
			}

			...

		}

		Return (SBUF)
	}

These GPIO numbers are controller relative and path "\\_SB.PCI0.GPI0"
specifies the path to the controller. In order to use these GPIOs in Linux
we need to translate them to the Linux GPIO numbers.

The driver can do this by including <linux/acpi_gpio.h> and then calling
acpi_get_gpio(path, gpio). This will return the Linux GPIO number or
negative errno if there was no translation found.

In a simple case of just getting the Linux GPIO number from device
resources one can use acpi_get_gpio_by_index() helper function. It takes
pointer to the device and index of the GpioIo/GpioInt descriptor in the
device resources list. For example:

	int gpio_irq, gpio_power;
	int ret;

	gpio_irq = acpi_get_gpio_by_index(dev, 1, NULL);
	if (gpio_irq < 0)
		/* handle error */

	gpio_power = acpi_get_gpio_by_index(dev, 0, NULL);
	if (gpio_power < 0)
		/* handle error */

	/* Now we can use the GPIO numbers */

Other GpioIo parameters must be converted first by the driver to be
suitable to the gpiolib before passing them.

In case of GpioInt resource an additional call to gpio_to_irq() must be
done before calling request_irq().
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
e253673e MW	66	drivers/acpi/acpi_platform.c. This limitation is only for the platform
e253673e MW	67	devices, SPI and I2C devices are created automatically as described below.
59c39878	68
1b2e98bc AS	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
59c39878 MW	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 configation 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. However the I2C bus controller driver
232	needs to call acpi_i2c_register_devices() after it has added the adapter.
233
234	An I2C bus (controller) driver does:
235
236	...
237	ret = i2c_add_numbered_adapter(adapter);
238	if (ret)
239	/* handle error */
240
59c39878 MW	241	/* Enumerate the slave devices behind this bus via ACPI */
	242	acpi_i2c_register_devices(adapter);
	243
	244	Below is an example of how to add ACPI support to the existing mpu3050
	245	input driver:
	246
	247	#ifdef CONFIG_ACPI
	248	static struct acpi_device_id mpu3050_acpi_match[] = {
	249	{ "MPU3050", 0 },
	250	{ },
	251	};
	252	MODULE_DEVICE_TABLE(acpi, mpu3050_acpi_match);
	253	#endif
	254
	255	static struct i2c_driver mpu3050_i2c_driver = {
	256	.driver = {
	257	.name = "mpu3050",
	258	.owner = THIS_MODULE,
	259	.pm = &mpu3050_pm,
	260	.of_match_table = mpu3050_of_match,
	261	.acpi_match_table ACPI_PTR(mpu3050_acpi_match),
	262	},
	263	.probe = mpu3050_probe,
63a29f74	264	.remove = mpu3050_remove,
59c39878 MW	265	.id_table = mpu3050_ids,
	266	};
	267
	268	GPIO support
	269	~~~~~~~~~~~~
	270	ACPI 5 introduced two new resources to describe GPIO connections: GpioIo
	271	and GpioInt. These resources are used be used to pass GPIO numbers used by
	272	the device to the driver. For example:
	273
	274	Method (_CRS, 0, NotSerialized)
	275	{
	276	Name (SBUF, ResourceTemplate()
	277	{
12028d2d MW	278	...
12028d2d MW	279	// Used to power on/off the device
59c39878 MW	280	GpioIo (Exclusive, PullDefault, 0x0000, 0x0000,
	281	IoRestrictionOutputOnly, "\\_SB.PCI0.GPI0",
	282	0x00, ResourceConsumer,,)
	283	{
	284	// Pin List
	285	0x0055
	286	}
12028d2d MW	287
	288	// Interrupt for the device
	289	GpioInt (Edge, ActiveHigh, ExclusiveAndWake, PullNone,
	290	0x0000, "\\_SB.PCI0.GPI0", 0x00, ResourceConsumer,,)
	291	{
	292	// Pin list
	293	0x0058
	294	}
	295
59c39878 MW	296	...
59c39878 MW	297
59c39878	298	}
12028d2d MW	299
12028d2d MW	300	Return (SBUF)
59c39878 MW	301	}
	302
	303	These GPIO numbers are controller relative and path "\\_SB.PCI0.GPI0"
	304	specifies the path to the controller. In order to use these GPIOs in Linux
	305	we need to translate them to the Linux GPIO numbers.
	306
	307	The driver can do this by including <linux/acpi_gpio.h> and then calling
	308	acpi_get_gpio(path, gpio). This will return the Linux GPIO number or
	309	negative errno if there was no translation found.
	310
12028d2d MW	311	In a simple case of just getting the Linux GPIO number from device
	312	resources one can use acpi_get_gpio_by_index() helper function. It takes
	313	pointer to the device and index of the GpioIo/GpioInt descriptor in the
	314	device resources list. For example:
	315
	316	int gpio_irq, gpio_power;
	317	int ret;
	318
	319	gpio_irq = acpi_get_gpio_by_index(dev, 1, NULL);
	320	if (gpio_irq < 0)
	321	/* handle error */
	322
	323	gpio_power = acpi_get_gpio_by_index(dev, 0, NULL);
	324	if (gpio_power < 0)
	325	/* handle error */
	326
	327	/* Now we can use the GPIO numbers */
	328
59c39878 MW	329	Other GpioIo parameters must be converted first by the driver to be
	330	suitable to the gpiolib before passing them.
	331
	332	In case of GpioInt resource an additional call to gpio_to_irq() must be
	333	done before calling request_irq().