[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.

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 configuration 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. The I2C core automatically enumerates
any slave devices behind the controller device once the adapter is
registered.

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 can be used to pass GPIO numbers used by
the device to the driver. ACPI 5.1 extended this with _DSD (Device
Specific Data) which made it possible to name the GPIOs among other things.

For example:

Device (DEV)
{
	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)
	}

	// ACPI 5.1 _DSD used for naming the GPIOs
	Name (_DSD, Package ()
	{
		ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
		Package ()
		{
			Package () {"power-gpios", Package() {^DEV, 0, 0, 0 }},
			Package () {"irq-gpios", Package() {^DEV, 1, 0, 0 }},
		}
	})
	...

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 corresponding Linux GPIO descriptors.

There is a standard GPIO API for that and is documented in
Documentation/gpio/.

In the above example we can get the corresponding two GPIO descriptors with
a code like this:

	#include <linux/gpio/consumer.h>
	...

	struct gpio_desc *irq_desc, *power_desc;

	irq_desc = gpiod_get(dev, "irq");
	if (IS_ERR(irq_desc))
		/* handle error */

	power_desc = gpiod_get(dev, "power");
	if (IS_ERR(power_desc))
		/* handle error */

	/* Now we can use the GPIO descriptors */

There are also devm_* versions of these functions which release the
descriptors once the device is released.

See Documentation/acpi/gpio-properties.txt for more information about the
_DSD binding related to GPIOs.

MFD devices
~~~~~~~~~~~
The MFD devices register their children as platform devices. For the child
devices there needs to be an ACPI handle that they can use to reference
parts of the ACPI namespace that relate to them. In the Linux MFD subsystem
we provide two ways:

	o The children share the parent ACPI handle.
	o The MFD cell can specify the ACPI id of the device.

For the first case, the MFD drivers do not need to do anything. The
resulting child platform device will have its ACPI_COMPANION() set to point
to the parent device.

If the ACPI namespace has a device that we can match using an ACPI id,
the id should be set like:

	static struct mfd_cell my_subdevice_cell = {
		.name = "my_subdevice",
		/* set the resources relative to the parent */
		.acpi_pnpid = "XYZ0001",
	};

The ACPI id "XYZ0001" is then used to lookup an ACPI device directly under
the MFD device and if found, that ACPI companion device is bound to the
resulting child platform device.
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
1b2e98bc AS	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
59c39878 MW	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
2d6674b8	204	Then the at25 SPI driver can get this configuration by calling _DSM on its
59c39878 MW	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
55e71edb MW	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.
59c39878 MW	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,
de14da2a	246	.acpi_match_table = ACPI_PTR(mpu3050_acpi_match),
59c39878 MW	247	},
59c39878 MW	248	.probe = mpu3050_probe,
63a29f74	249	.remove = mpu3050_remove,
59c39878 MW	250	.id_table = mpu3050_ids,
	251	};
	252
	253	GPIO support
	254	~~~~~~~~~~~~
	255	ACPI 5 introduced two new resources to describe GPIO connections: GpioIo
2375a212	256	and GpioInt. These resources can be used to pass GPIO numbers used by
56b858df MW	257	the device to the driver. ACPI 5.1 extended this with _DSD (Device
56b858df MW	258	Specific Data) which made it possible to name the GPIOs among other things.
59c39878	259
56b858df MW	260	For example:
	261
	262	Device (DEV)
	263	{
59c39878 MW	264	Method (_CRS, 0, NotSerialized)
	265	{
	266	Name (SBUF, ResourceTemplate()
	267	{
12028d2d MW	268	...
12028d2d MW	269	// Used to power on/off the device
59c39878 MW	270	GpioIo (Exclusive, PullDefault, 0x0000, 0x0000,
	271	IoRestrictionOutputOnly, "\\_SB.PCI0.GPI0",
	272	0x00, ResourceConsumer,,)
	273	{
	274	// Pin List
	275	0x0055
	276	}
12028d2d MW	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
59c39878 MW	286	...
59c39878 MW	287
59c39878	288	}
12028d2d MW	289
12028d2d MW	290	Return (SBUF)
59c39878 MW	291	}
59c39878 MW	292
56b858df MW	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
59c39878 MW	305	These GPIO numbers are controller relative and path "\\_SB.PCI0.GPI0"
59c39878 MW	306	specifies the path to the controller. In order to use these GPIOs in Linux
ccb6fbb9	307	we need to translate them to the corresponding Linux GPIO descriptors.
59c39878	308
ccb6fbb9	309	There is a standard GPIO API for that and is documented in
51caa05a	310	Documentation/gpio/.
12028d2d	311
ccb6fbb9 MW	312	In the above example we can get the corresponding two GPIO descriptors with
ccb6fbb9 MW	313	a code like this:
45f39439 MW	314
	315	#include <linux/gpio/consumer.h>
	316	...
	317
	318	struct gpio_desc irq_desc, power_desc;
	319
56b858df	320	irq_desc = gpiod_get(dev, "irq");
45f39439 MW	321	if (IS_ERR(irq_desc))
	322	/* handle error */
	323
56b858df	324	power_desc = gpiod_get(dev, "power");
45f39439 MW	325	if (IS_ERR(power_desc))
	326	/* handle error */
	327
	328	/* Now we can use the GPIO descriptors */
	329
ccb6fbb9 MW	330	There are also devm_* versions of these functions which release the
ccb6fbb9 MW	331	descriptors once the device is released.
6ab34301	332
56b858df MW	333	See Documentation/acpi/gpio-properties.txt for more information about the
	334	_DSD binding related to GPIOs.
	335
6ab34301 MW	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.