[linux.git] / Documentation / gpio / board.txt

GPIO Mappings
=============

This document explains how GPIOs can be assigned to given devices and functions.
Note that it only applies to the new descriptor-based interface. For a
description of the deprecated integer-based GPIO interface please refer to
gpio-legacy.txt (actually, there is no real mapping possible with the old
interface; you just fetch an integer from somewhere and request the
corresponding GPIO.

Platforms that make use of GPIOs must select ARCH_REQUIRE_GPIOLIB (if GPIO usage
is mandatory) or ARCH_WANT_OPTIONAL_GPIOLIB (if GPIO support can be omitted) in
their Kconfig. Then, how GPIOs are mapped depends on what the platform uses to
describe its hardware layout. Currently, mappings can be defined through device
tree, ACPI, and platform data.

Device Tree
-----------
GPIOs can easily be mapped to devices and functions in the device tree. The
exact way to do it depends on the GPIO controller providing the GPIOs, see the
device tree bindings for your controller.

GPIOs mappings are defined in the consumer device's node, in a property named
<function>-gpios, where <function> is the function the driver will request
through gpiod_get(). For example:

	foo_device {
		compatible = "acme,foo";
		...
		led-gpios = <&gpio 15 GPIO_ACTIVE_HIGH>, /* red */
			    <&gpio 16 GPIO_ACTIVE_HIGH>, /* green */
			    <&gpio 17 GPIO_ACTIVE_HIGH>; /* blue */

		power-gpios = <&gpio 1 GPIO_ACTIVE_LOW>;
	};

Properties named <function>-gpio are also considered valid and old bindings use
it but are only supported for compatibility reasons and should not be used for
newer bindings since it has been deprecated.

This property will make GPIOs 15, 16 and 17 available to the driver under the
"led" function, and GPIO 1 as the "power" GPIO:

	struct gpio_desc *red, *green, *blue, *power;

	red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH);
	green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH);
	blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH);

	power = gpiod_get(dev, "power", GPIOD_OUT_HIGH);

The led GPIOs will be active-high, while the power GPIO will be active-low (i.e.
gpiod_is_active_low(power) will be true).

The second parameter of the gpiod_get() functions, the con_id string, has to be
the <function>-prefix of the GPIO suffixes ("gpios" or "gpio", automatically
looked up by the gpiod functions internally) used in the device tree. With above
"led-gpios" example, use the prefix without the "-" as con_id parameter: "led".

Internally, the GPIO subsystem prefixes the GPIO suffix ("gpios" or "gpio")
with the string passed in con_id to get the resulting string
(snprintf(... "%s-%s", con_id, gpio_suffixes[]).

ACPI
----
ACPI also supports function names for GPIOs in a similar fashion to DT.
The above DT example can be converted to an equivalent ACPI description
with the help of _DSD (Device Specific Data), introduced in ACPI 5.1:

	Device (FOO) {
		Name (_CRS, ResourceTemplate () {
			GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
				"\\_SB.GPI0") {15} // red
			GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
				"\\_SB.GPI0") {16} // green
			GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
				"\\_SB.GPI0") {17} // blue
			GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
				"\\_SB.GPI0") {1} // power
		})

		Name (_DSD, Package () {
			ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
			Package () {
				Package () {
					"led-gpios",
					Package () {
						^FOO, 0, 0, 1,
						^FOO, 1, 0, 1,
						^FOO, 2, 0, 1,
					}
				},
				Package () {
					"power-gpios",
					Package () {^FOO, 3, 0, 0},
				},
			}
		})
	}

For more information about the ACPI GPIO bindings see
Documentation/acpi/gpio-properties.txt.

Platform Data
-------------
Finally, GPIOs can be bound to devices and functions using platform data. Board
files that desire to do so need to include the following header:

	#include <linux/gpio/machine.h>

GPIOs are mapped by the means of tables of lookups, containing instances of the
gpiod_lookup structure. Two macros are defined to help declaring such mappings:

	GPIO_LOOKUP(chip_label, chip_hwnum, con_id, flags)
	GPIO_LOOKUP_IDX(chip_label, chip_hwnum, con_id, idx, flags)

where

  - chip_label is the label of the gpiod_chip instance providing the GPIO
  - chip_hwnum is the hardware number of the GPIO within the chip
  - con_id is the name of the GPIO function from the device point of view. It
	can be NULL, in which case it will match any function.
  - idx is the index of the GPIO within the function.
  - flags is defined to specify the following properties:
	* GPIOF_ACTIVE_LOW	- to configure the GPIO as active-low
	* GPIOF_OPEN_DRAIN	- GPIO pin is open drain type.
	* GPIOF_OPEN_SOURCE	- GPIO pin is open source type.

In the future, these flags might be extended to support more properties.

Note that GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0.

A lookup table can then be defined as follows, with an empty entry defining its
end. The 'dev_id' field of the table is the identifier of the device that will
make use of these GPIOs. It can be NULL, in which case it will be matched for
calls to gpiod_get() with a NULL device.

struct gpiod_lookup_table gpios_table = {
	.dev_id = "foo.0",
	.table = {
		GPIO_LOOKUP_IDX("gpio.0", 15, "led", 0, GPIO_ACTIVE_HIGH),
		GPIO_LOOKUP_IDX("gpio.0", 16, "led", 1, GPIO_ACTIVE_HIGH),
		GPIO_LOOKUP_IDX("gpio.0", 17, "led", 2, GPIO_ACTIVE_HIGH),
		GPIO_LOOKUP("gpio.0", 1, "power", GPIO_ACTIVE_LOW),
		{ },
	},
};

And the table can be added by the board code as follows:

	gpiod_add_lookup_table(&gpios_table);

The driver controlling "foo.0" will then be able to obtain its GPIOs as follows:

	struct gpio_desc *red, *green, *blue, *power;

	red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH);
	green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH);
	blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH);

	power = gpiod_get(dev, "power", GPIOD_OUT_HIGH);

Since the "led" GPIOs are mapped as active-high, this example will switch their
signals to 1, i.e. enabling the LEDs. And for the "power" GPIO, which is mapped
as active-low, its actual signal will be 0 after this code. Contrary to the legacy
integer GPIO interface, the active-low property is handled during mapping and is
thus transparent to GPIO consumers.
Commit	Line	Data
fd8e198c AC	1	GPIO Mappings
	2	=============
	3
	4	This document explains how GPIOs can be assigned to given devices and functions.
	5	Note that it only applies to the new descriptor-based interface. For a
	6	description of the deprecated integer-based GPIO interface please refer to
	7	gpio-legacy.txt (actually, there is no real mapping possible with the old
	8	interface; you just fetch an integer from somewhere and request the
	9	corresponding GPIO.
	10
	11	Platforms that make use of GPIOs must select ARCH_REQUIRE_GPIOLIB (if GPIO usage
	12	is mandatory) or ARCH_WANT_OPTIONAL_GPIOLIB (if GPIO support can be omitted) in
	13	their Kconfig. Then, how GPIOs are mapped depends on what the platform uses to
	14	describe its hardware layout. Currently, mappings can be defined through device
	15	tree, ACPI, and platform data.
	16
	17	Device Tree
	18	-----------
	19	GPIOs can easily be mapped to devices and functions in the device tree. The
	20	exact way to do it depends on the GPIO controller providing the GPIOs, see the
	21	device tree bindings for your controller.
	22
	23	GPIOs mappings are defined in the consumer device's node, in a property named
2b71920e JMC	24	<function>-gpios, where <function> is the function the driver will request
2b71920e JMC	25	through gpiod_get(). For example:
fd8e198c AC	26
	27	foo_device {
	28	compatible = "acme,foo";
	29	...
	30	led-gpios = <&gpio 15 GPIO_ACTIVE_HIGH>, /* red */
	31	<&gpio 16 GPIO_ACTIVE_HIGH>, /* green */
	32	<&gpio 17 GPIO_ACTIVE_HIGH>; /* blue */
	33
2b71920e	34	power-gpios = <&gpio 1 GPIO_ACTIVE_LOW>;
fd8e198c AC	35	};
fd8e198c AC	36
2b71920e JMC	37	Properties named <function>-gpio are also considered valid and old bindings use
	38	it but are only supported for compatibility reasons and should not be used for
	39	newer bindings since it has been deprecated.
	40
fd8e198c AC	41	This property will make GPIOs 15, 16 and 17 available to the driver under the
	42	"led" function, and GPIO 1 as the "power" GPIO:
	43
	44	struct gpio_desc red, green, blue, power;
	45
69de52ba DB	46	red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH);
	47	green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH);
	48	blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH);
fd8e198c	49
69de52ba	50	power = gpiod_get(dev, "power", GPIOD_OUT_HIGH);
fd8e198c AC	51
	52	The led GPIOs will be active-high, while the power GPIO will be active-low (i.e.
	53	gpiod_is_active_low(power) will be true).
	54
87e77e46 DB	55	The second parameter of the gpiod_get() functions, the con_id string, has to be
	56	the <function>-prefix of the GPIO suffixes ("gpios" or "gpio", automatically
	57	looked up by the gpiod functions internally) used in the device tree. With above
	58	"led-gpios" example, use the prefix without the "-" as con_id parameter: "led".
	59
	60	Internally, the GPIO subsystem prefixes the GPIO suffix ("gpios" or "gpio")
	61	with the string passed in con_id to get the resulting string
	62	(snprintf(... "%s-%s", con_id, gpio_suffixes[]).
	63
fd8e198c AC	64	ACPI
fd8e198c AC	65	----
cfc50764 MW	66	ACPI also supports function names for GPIOs in a similar fashion to DT.
	67	The above DT example can be converted to an equivalent ACPI description
	68	with the help of _DSD (Device Specific Data), introduced in ACPI 5.1:
	69
	70	Device (FOO) {
	71	Name (_CRS, ResourceTemplate () {
	72	GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
	73	"\\_SB.GPI0") {15} // red
	74	GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
	75	"\\_SB.GPI0") {16} // green
	76	GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
	77	"\\_SB.GPI0") {17} // blue
	78	GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
	79	"\\_SB.GPI0") {1} // power
	80	})
	81
	82	Name (_DSD, Package () {
	83	ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
	84	Package () {
	85	Package () {
	86	"led-gpios",
	87	Package () {
	88	^FOO, 0, 0, 1,
	89	^FOO, 1, 0, 1,
	90	^FOO, 2, 0, 1,
	91	}
	92	},
	93	Package () {
	94	"power-gpios",
	95	Package () {^FOO, 3, 0, 0},
	96	},
	97	}
	98	})
	99	}
	100
	101	For more information about the ACPI GPIO bindings see
	102	Documentation/acpi/gpio-properties.txt.
fd8e198c AC	103
	104	Platform Data
	105	-------------
	106	Finally, GPIOs can be bound to devices and functions using platform data. Board
	107	files that desire to do so need to include the following header:
	108
0a6d3158	109	#include <linux/gpio/machine.h>
fd8e198c AC	110
	111	GPIOs are mapped by the means of tables of lookups, containing instances of the
	112	gpiod_lookup structure. Two macros are defined to help declaring such mappings:
	113
cfb7428c GJ	114	GPIO_LOOKUP(chip_label, chip_hwnum, con_id, flags)
cfb7428c GJ	115	GPIO_LOOKUP_IDX(chip_label, chip_hwnum, con_id, idx, flags)
fd8e198c AC	116
	117	where
	118
	119	- chip_label is the label of the gpiod_chip instance providing the GPIO
	120	- chip_hwnum is the hardware number of the GPIO within the chip
fd8e198c	121	- con_id is the name of the GPIO function from the device point of view. It
ad824783	122	can be NULL, in which case it will match any function.
fd8e198c AC	123	- idx is the index of the GPIO within the function.
	124	- flags is defined to specify the following properties:
	125	* GPIOF_ACTIVE_LOW - to configure the GPIO as active-low
	126	* GPIOF_OPEN_DRAIN - GPIO pin is open drain type.
	127	* GPIOF_OPEN_SOURCE - GPIO pin is open source type.
	128
	129	In the future, these flags might be extended to support more properties.
	130
	131	Note that GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0.
	132
ad824783	133	A lookup table can then be defined as follows, with an empty entry defining its
cfb7428c GJ	134	end. The 'dev_id' field of the table is the identifier of the device that will
	135	make use of these GPIOs. It can be NULL, in which case it will be matched for
	136	calls to gpiod_get() with a NULL device.
fd8e198c	137
ad824783 AC	138	struct gpiod_lookup_table gpios_table = {
	139	.dev_id = "foo.0",
	140	.table = {
	141	GPIO_LOOKUP_IDX("gpio.0", 15, "led", 0, GPIO_ACTIVE_HIGH),
	142	GPIO_LOOKUP_IDX("gpio.0", 16, "led", 1, GPIO_ACTIVE_HIGH),
	143	GPIO_LOOKUP_IDX("gpio.0", 17, "led", 2, GPIO_ACTIVE_HIGH),
	144	GPIO_LOOKUP("gpio.0", 1, "power", GPIO_ACTIVE_LOW),
	145	{ },
	146	},
	147	};
fd8e198c AC	148
	149	And the table can be added by the board code as follows:
	150
ad824783	151	gpiod_add_lookup_table(&gpios_table);
fd8e198c AC	152
	153	The driver controlling "foo.0" will then be able to obtain its GPIOs as follows:
	154
	155	struct gpio_desc red, green, blue, power;
	156
69de52ba DB	157	red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH);
	158	green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH);
	159	blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH);
fd8e198c	160
69de52ba	161	power = gpiod_get(dev, "power", GPIOD_OUT_HIGH);
fd8e198c	162
69de52ba DB	163	Since the "led" GPIOs are mapped as active-high, this example will switch their
	164	signals to 1, i.e. enabling the LEDs. And for the "power" GPIO, which is mapped
	165	as active-low, its actual signal will be 0 after this code. Contrary to the legacy
	166	integer GPIO interface, the active-low property is handled during mapping and is
	167	thus transparent to GPIO consumers.