<commit_before>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". The exact
meaning of each gpios property must be documented in the device tree
binding for each device.

For example, the following could be used to describe GPIO pins used
as chip select lines; with chip selects 0, 1 and 3 populated, and chip
select 2 left empty:

	gpio1: gpio1 {
		gpio-controller
		 #gpio-cells = <2>;
	};
	gpio2: gpio2 {
		gpio-controller
		 #gpio-cells = <1>;
	};
	[...]
	 chipsel-gpios = <&gpio1 12 0>,
			 <&gpio1 13 0>,
			 <0>, /* holes are permitted, means no GPIO 2 */
			 <&gpio2 2>;

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.

Example of a node using GPIOs:

	node {
		gpios = <&qe_pio_e 18 0>;
	};

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 follow 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<commit_msg>Documentation: gpio: guidelines for bindings<commit_after>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 follow 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
{'fraction_non_alphanumeric': 0.09914367269267364, 'fraction_numerical': 0.013320647002854425, 'mean_word_length': 3.8308823529411766, 'pattern_counts': {'":': 0, '<': 28, '<?xml version=': 0, '>': 28, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2759040', 'n_tokens_mistral': 1549, 'n_tokens_neox': 1424, 'n_words': 726}