doc/device-tree-bindings/gpio/gpio.txt - filogic/uboot - Gitiles

 Specifying GPIO information for devices
 ============================================

 1) gpios property
 -----------------

 Nodes that makes use of GPIOs should specify them using one or more
 properties, each containing a 'gpio-list':

 	gpio-list ::= <single-gpio> [gpio-list]
 	single-gpio ::= <gpio-phandle> <gpio-specifier>
 	gpio-phandle : phandle to gpio controller node
 	gpio-specifier : Array of #gpio-cells specifying specific gpio
 			 (controller specific)

 GPIO properties should be named "[<name>-]gpios", with <name> being the purpose
 of this GPIO for the device. While a non-existent <name> is considered valid
 for compatibility reasons (resolving to the "gpios" property), it is not allowed
 for new bindings.

 GPIO properties can contain one or more GPIO phandles, but only in exceptional
 cases should they contain more than one. If your device uses several GPIOs with
 distinct functions, reference each of them under its own property, giving it a
 meaningful name. The only case where an array of GPIOs is accepted is when
 several GPIOs serve the same function (e.g. a parallel data line).

 The exact purpose of each gpios property must be documented in the device tree
 binding of the device.

 The following example could be used to describe GPIO pins used as device enable
 and bit-banged data signals:

 	gpio1: gpio1 {
 		gpio-controller
 		 #gpio-cells = <2>;
 	};
 	gpio2: gpio2 {
 		gpio-controller
 		 #gpio-cells = <1>;
 	};
 	[...]

 	enable-gpios = <&gpio2 2>;
 	data-gpios = <&gpio1 12 0>,
 		     <&gpio1 13 0>,
 		     <&gpio1 14 0>,
 		     <&gpio1 15 0>;

 Note that gpio-specifier length is controller dependent.  In the
 above example, &gpio1 uses 2 cells to specify a gpio, while &gpio2
 only uses one.

 gpio-specifier may encode: bank, pin position inside the bank,
 whether pin is open-drain and whether pin is logically inverted.
 Exact meaning of each specifier cell is controller specific, and must
 be documented in the device tree binding for the device. Use the macros
 defined in include/dt-bindings/gpio/gpio.h whenever possible:

 Example of a node using GPIOs:

 	node {
 		enable-gpios = <&qe_pio_e 18 GPIO_ACTIVE_HIGH>;
 	};

 GPIO_ACTIVE_HIGH is 0, so in this example gpio-specifier is "18 0" and encodes
 GPIO pin number, and GPIO flags as accepted by the "qe_pio_e" gpio-controller.

 1.1) GPIO specifier best practices
 ----------------------------------

 A gpio-specifier should contain a flag indicating the GPIO polarity; active-
 high or active-low. If it does, the following best practices should be
 followed:

 The gpio-specifier's polarity flag should represent the physical level at the
 GPIO controller that achieves (or represents, for inputs) a logically asserted
 value at the device. The exact definition of logically asserted should be
 defined by the binding for the device. If the board inverts the signal between
 the GPIO controller and the device, then the gpio-specifier will represent the
 opposite physical level than the signal at the device's pin.

 When the device's signal polarity is configurable, the binding for the
 device must either:

 a) Define a single static polarity for the signal, with the expectation that
 any software using that binding would statically program the device to use
 that signal polarity.

 The static choice of polarity may be either:

 a1) (Preferred) Dictated by a binding-specific DT property.

 or:

 a2) Defined statically by the DT binding itself.

 In particular, the polarity cannot be derived from the gpio-specifier, since
 that would prevent the DT from separately representing the two orthogonal
 concepts of configurable signal polarity in the device, and possible board-
 level signal inversion.

 or:

 b) Pick a single option for device signal polarity, and document this choice
 in the binding. The gpio-specifier should represent the polarity of the signal
 (at the GPIO controller) assuming that the device is configured for this
 particular signal polarity choice. If software chooses to program the device
 to generate or receive a signal of the opposite polarity, software will be
 responsible for correctly interpreting (inverting) the GPIO signal at the GPIO
 controller.

 2) gpio-controller nodes
 ------------------------

 Every GPIO controller node must contain both an empty "gpio-controller"
 property, and a #gpio-cells integer property, which indicates the number of
 cells in a gpio-specifier.

 Example of two SOC GPIO banks defined as gpio-controller nodes:

 	qe_pio_a: gpio-controller@1400 {
 		compatible = "fsl,qe-pario-bank-a", "fsl,qe-pario-bank";
 		reg = <0x1400 0x18>;
 		gpio-controller;
 		#gpio-cells = <2>;
 	};

 	qe_pio_e: gpio-controller@1460 {
 		compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
 		reg = <0x1460 0x18>;
 		gpio-controller;
 		#gpio-cells = <2>;
 	};

 2.1) gpio- and pin-controller interaction
 -----------------------------------------

 Some or all of the GPIOs provided by a GPIO controller may be routed to pins
 on the package via a pin controller. This allows muxing those pins between
 GPIO and other functions.

 It is useful to represent which GPIOs correspond to which pins on which pin
 controllers. The gpio-ranges property described below represents this, and
 contains information structures as follows:

 	gpio-range-list ::= <single-gpio-range> [gpio-range-list]
 	single-gpio-range ::= <numeric-gpio-range> | <named-gpio-range>
 	numeric-gpio-range ::=
 			<pinctrl-phandle> <gpio-base> <pinctrl-base> <count>
 	named-gpio-range ::= <pinctrl-phandle> <gpio-base> '<0 0>'
 	pinctrl-phandle : phandle to pin controller node
 	gpio-base : Base GPIO ID in the GPIO controller
 	pinctrl-base : Base pinctrl pin ID in the pin controller
 	count : The number of GPIOs/pins in this range

 The "pin controller node" mentioned above must conform to the bindings
 described in ../pinctrl/pinctrl-bindings.txt.

 In case named gpio ranges are used (ranges with both <pinctrl-base> and
 <count> set to 0), the property gpio-ranges-group-names contains one string
 for every single-gpio-range in gpio-ranges:
 	gpiorange-names-list ::= <gpiorange-name> [gpiorange-names-list]
 	gpiorange-name : Name of the pingroup associated to the GPIO range in
 			the respective pin controller.

 Elements of gpiorange-names-list corresponding to numeric ranges contain
 the empty string. Elements of gpiorange-names-list corresponding to named
 ranges contain the name of a pin group defined in the respective pin
 controller. The number of pins/GPIOs in the range is the number of pins in
 that pin group.

 Previous versions of this binding required all pin controller nodes that
 were referenced by any gpio-ranges property to contain a property named
 #gpio-range-cells with value <3>. This requirement is now deprecated.
 However, that property may still exist in older device trees for
 compatibility reasons, and would still be required even in new device
 trees that need to be compatible with older software.

 Example 1:

 	qe_pio_e: gpio-controller@1460 {
 		#gpio-cells = <2>;
 		compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
 		reg = <0x1460 0x18>;
 		gpio-controller;
 		gpio-ranges = <&pinctrl1 0 20 10>, <&pinctrl2 10 50 20>;
 	};

 Here, a single GPIO controller has GPIOs 0..9 routed to pin controller
 pinctrl1's pins 20..29, and GPIOs 10..19 routed to pin controller pinctrl2's
 pins 50..59.

 Example 2:

 	gpio_pio_i: gpio-controller@14B0 {
 		#gpio-cells = <2>;
 		compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
 		reg = <0x1480 0x18>;
 		gpio-controller;
 		gpio-ranges =			<&pinctrl1 0 20 10>,
 						<&pinctrl2 10 0 0>,
 						<&pinctrl1 15 0 10>,
 						<&pinctrl2 25 0 0>;
 		gpio-ranges-group-names =	"",
 						"foo",
 						"",
 						"bar";
 	};

 Here, three GPIO ranges are defined wrt. two pin controllers. pinctrl1 GPIO
 ranges are defined using pin numbers whereas the GPIO ranges wrt. pinctrl2
 are named "foo" and "bar".

 3) GPIO hog definitions
 -----------------------

 The GPIO chip may contain GPIO hog definitions. GPIO hogging is a mechanism
 providing automatic GPIO request and configuration as part of the
 gpio-controller's driver probe function.

 Each GPIO hog definition is represented as a child node of the GPIO controller.
 Required properties:
 - gpio-hog:   A property specifying that this child node represents a GPIO hog.
 - gpios:      Store the GPIO information (id, flags) for the GPIO to
 	      affect.

               ! Not yet support more than one gpio !

 Only one of the following properties scanned in the order shown below.
 - input:      A property specifying to set the GPIO direction as input.
 - output-low  A property specifying to set the GPIO direction as output with
 	      the value low.
 - output-high A property specifying to set the GPIO direction as output with
 	      the value high.

 Optional properties:
 - line-name:  The GPIO label name. If not present the node name is used.

 Example:

         tca6416@20 {
                 compatible = "ti,tca6416";
                 reg = <0x20>;
                 #gpio-cells = <2>;
                 gpio-controller;

                 env_reset {
                         gpio-hog;
                         input;
                         gpios = <6 GPIO_ACTIVE_LOW>;
                 };
                 boot_rescue {
                         gpio-hog;
                         input;
                         gpios = <7 GPIO_ACTIVE_LOW>;
                 };
         };

 For the above Example you can than access the gpio in your boardcode
 with:

         desc = gpio_hog_lookup_name("boot_rescue.gpio-hog");
         if (desc) {
                 if (dm_gpio_get_value(desc))
                         printf("\nBooting into Rescue System\n");
 		else
 			printf("\nBoot normal\n");
	Specifying GPIO information for devices
	============================================

	1) gpios property
	-----------------

	Nodes that makes use of GPIOs should specify them using one or more
	properties, each containing a 'gpio-list':

	gpio-list ::= <single-gpio> [gpio-list]
	single-gpio ::= <gpio-phandle> <gpio-specifier>
	gpio-phandle : phandle to gpio controller node
	gpio-specifier : Array of #gpio-cells specifying specific gpio
	(controller specific)

	GPIO properties should be named "[<name>-]gpios", with <name> being the purpose
	of this GPIO for the device. While a non-existent <name> is considered valid
	for compatibility reasons (resolving to the "gpios" property), it is not allowed
	for new bindings.

	GPIO properties can contain one or more GPIO phandles, but only in exceptional
	cases should they contain more than one. If your device uses several GPIOs with
	distinct functions, reference each of them under its own property, giving it a
	meaningful name. The only case where an array of GPIOs is accepted is when
	several GPIOs serve the same function (e.g. a parallel data line).

	The exact purpose of each gpios property must be documented in the device tree
	binding of the device.

	The following example could be used to describe GPIO pins used as device enable
	and bit-banged data signals:

	gpio1: gpio1 {
	gpio-controller
	#gpio-cells = <2>;
	};
	gpio2: gpio2 {
	gpio-controller
	#gpio-cells = <1>;
	};
	[...]

	enable-gpios = <&gpio2 2>;
	data-gpios = <&gpio1 12 0>,
	<&gpio1 13 0>,
	<&gpio1 14 0>,
	<&gpio1 15 0>;

	Note that gpio-specifier length is controller dependent. In the
	above example, &gpio1 uses 2 cells to specify a gpio, while &gpio2
	only uses one.

	gpio-specifier may encode: bank, pin position inside the bank,
	whether pin is open-drain and whether pin is logically inverted.
	Exact meaning of each specifier cell is controller specific, and must
	be documented in the device tree binding for the device. Use the macros
	defined in include/dt-bindings/gpio/gpio.h whenever possible:

	Example of a node using GPIOs:

	node {
	enable-gpios = <&qe_pio_e 18 GPIO_ACTIVE_HIGH>;
	};

	GPIO_ACTIVE_HIGH is 0, so in this example gpio-specifier is "18 0" and encodes
	GPIO pin number, and GPIO flags as accepted by the "qe_pio_e" gpio-controller.

	1.1) GPIO specifier best practices
	----------------------------------

	A gpio-specifier should contain a flag indicating the GPIO polarity; active-
	high or active-low. If it does, the following best practices should be
	followed:

	The gpio-specifier's polarity flag should represent the physical level at the
	GPIO controller that achieves (or represents, for inputs) a logically asserted
	value at the device. The exact definition of logically asserted should be
	defined by the binding for the device. If the board inverts the signal between
	the GPIO controller and the device, then the gpio-specifier will represent the
	opposite physical level than the signal at the device's pin.

	When the device's signal polarity is configurable, the binding for the
	device must either:

	a) Define a single static polarity for the signal, with the expectation that
	any software using that binding would statically program the device to use
	that signal polarity.

	The static choice of polarity may be either:

	a1) (Preferred) Dictated by a binding-specific DT property.

	or:

	a2) Defined statically by the DT binding itself.

	In particular, the polarity cannot be derived from the gpio-specifier, since
	that would prevent the DT from separately representing the two orthogonal
	concepts of configurable signal polarity in the device, and possible board-
	level signal inversion.

	or:

	b) Pick a single option for device signal polarity, and document this choice
	in the binding. The gpio-specifier should represent the polarity of the signal
	(at the GPIO controller) assuming that the device is configured for this
	particular signal polarity choice. If software chooses to program the device
	to generate or receive a signal of the opposite polarity, software will be
	responsible for correctly interpreting (inverting) the GPIO signal at the GPIO
	controller.

	2) gpio-controller nodes
	------------------------

	Every GPIO controller node must contain both an empty "gpio-controller"
	property, and a #gpio-cells integer property, which indicates the number of
	cells in a gpio-specifier.

	Example of two SOC GPIO banks defined as gpio-controller nodes:

	qe_pio_a: gpio-controller@1400 {
	compatible = "fsl,qe-pario-bank-a", "fsl,qe-pario-bank";
	reg = <0x1400 0x18>;
	gpio-controller;
	#gpio-cells = <2>;
	};

	qe_pio_e: gpio-controller@1460 {
	compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
	reg = <0x1460 0x18>;
	gpio-controller;
	#gpio-cells = <2>;
	};

	2.1) gpio- and pin-controller interaction
	-----------------------------------------

	Some or all of the GPIOs provided by a GPIO controller may be routed to pins
	on the package via a pin controller. This allows muxing those pins between
	GPIO and other functions.

	It is useful to represent which GPIOs correspond to which pins on which pin
	controllers. The gpio-ranges property described below represents this, and
	contains information structures as follows:

	gpio-range-list ::= <single-gpio-range> [gpio-range-list]
	single-gpio-range ::= <numeric-gpio-range> \| <named-gpio-range>
	numeric-gpio-range ::=
	<pinctrl-phandle> <gpio-base> <pinctrl-base> <count>
	named-gpio-range ::= <pinctrl-phandle> <gpio-base> '<0 0>'
	pinctrl-phandle : phandle to pin controller node
	gpio-base : Base GPIO ID in the GPIO controller
	pinctrl-base : Base pinctrl pin ID in the pin controller
	count : The number of GPIOs/pins in this range

	The "pin controller node" mentioned above must conform to the bindings
	described in ../pinctrl/pinctrl-bindings.txt.

	In case named gpio ranges are used (ranges with both <pinctrl-base> and
	<count> set to 0), the property gpio-ranges-group-names contains one string
	for every single-gpio-range in gpio-ranges:
	gpiorange-names-list ::= <gpiorange-name> [gpiorange-names-list]
	gpiorange-name : Name of the pingroup associated to the GPIO range in
	the respective pin controller.

	Elements of gpiorange-names-list corresponding to numeric ranges contain
	the empty string. Elements of gpiorange-names-list corresponding to named
	ranges contain the name of a pin group defined in the respective pin
	controller. The number of pins/GPIOs in the range is the number of pins in
	that pin group.

	Previous versions of this binding required all pin controller nodes that
	were referenced by any gpio-ranges property to contain a property named
	#gpio-range-cells with value <3>. This requirement is now deprecated.
	However, that property may still exist in older device trees for
	compatibility reasons, and would still be required even in new device
	trees that need to be compatible with older software.

	Example 1:

	qe_pio_e: gpio-controller@1460 {
	#gpio-cells = <2>;
	compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
	reg = <0x1460 0x18>;
	gpio-controller;
	gpio-ranges = <&pinctrl1 0 20 10>, <&pinctrl2 10 50 20>;
	};

	Here, a single GPIO controller has GPIOs 0..9 routed to pin controller
	pinctrl1's pins 20..29, and GPIOs 10..19 routed to pin controller pinctrl2's
	pins 50..59.

	Example 2:

	gpio_pio_i: gpio-controller@14B0 {
	#gpio-cells = <2>;
	compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
	reg = <0x1480 0x18>;
	gpio-controller;
	gpio-ranges = <&pinctrl1 0 20 10>,
	<&pinctrl2 10 0 0>,
	<&pinctrl1 15 0 10>,
	<&pinctrl2 25 0 0>;
	gpio-ranges-group-names = "",
	"foo",
	"",
	"bar";
	};

	Here, three GPIO ranges are defined wrt. two pin controllers. pinctrl1 GPIO
	ranges are defined using pin numbers whereas the GPIO ranges wrt. pinctrl2
	are named "foo" and "bar".

	3) GPIO hog definitions
	-----------------------

	The GPIO chip may contain GPIO hog definitions. GPIO hogging is a mechanism
	providing automatic GPIO request and configuration as part of the
	gpio-controller's driver probe function.

	Each GPIO hog definition is represented as a child node of the GPIO controller.
	Required properties:
	- gpio-hog: A property specifying that this child node represents a GPIO hog.
	- gpios: Store the GPIO information (id, flags) for the GPIO to
	affect.

	! Not yet support more than one gpio !

	Only one of the following properties scanned in the order shown below.
	- input: A property specifying to set the GPIO direction as input.
	- output-low A property specifying to set the GPIO direction as output with
	the value low.
	- output-high A property specifying to set the GPIO direction as output with
	the value high.

	Optional properties:
	- line-name: The GPIO label name. If not present the node name is used.

	Example:

	tca6416@20 {
	compatible = "ti,tca6416";
	reg = <0x20>;
	#gpio-cells = <2>;
	gpio-controller;

	env_reset {
	gpio-hog;
	input;
	gpios = <6 GPIO_ACTIVE_LOW>;
	};
	boot_rescue {
	gpio-hog;
	input;
	gpios = <7 GPIO_ACTIVE_LOW>;
	};
	};

	For the above Example you can than access the gpio in your boardcode
	with:

	desc = gpio_hog_lookup_name("boot_rescue.gpio-hog");
	if (desc) {
	if (dm_gpio_get_value(desc))
	printf("\nBooting into Rescue System\n");
	else
	printf("\nBoot normal\n");