Documentation/devicetree/bindings/gpio/gpio.txt

Source file repositories/reference/linux-study-clean/Documentation/devicetree/bindings/gpio/gpio.txt

File Facts

System
Linux kernel
Corpus path
Documentation/devicetree/bindings/gpio/gpio.txt
Extension
.txt
Size
14300 bytes
Lines
349
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

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

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

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. Also, GPIO properties named "[<name>-]gpio" are 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.

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>;
	};
	[...]

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

In the above example, &gpio1 uses 2 cells to specify a gpio. The first cell is
a local offset to the GPIO line and the second cell represents consumer flags,
such as if the consumer desires the line to be active low (inverted) or open
drain. This is the recommended practice.

The exact meaning of each specifier cell is controller specific, and must be
documented in the device tree binding for the device, but it is strongly
recommended to use the two-cell approach.

Most controllers are specifying a generic flag bitfield in the last cell, so
for these, 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.

Optional standard bitfield specifiers for the last cell:

- Bit 0: 0 means active high, 1 means active low
- Bit 1: 0 means push-pull wiring, see:
           https://en.wikipedia.org/wiki/Push-pull_output
         1 means single-ended wiring, see:
           https://en.wikipedia.org/wiki/Single-ended_triode
- Bit 2: 0 means open-source, 1 means open drain, see:
           https://en.wikipedia.org/wiki/Open_collector
- Bit 3: 0 means the output should be maintained during sleep/low-power mode
         1 means the output state can be lost during sleep/low-power mode
- Bit 4: 0 means no pull-up resistor should be enabled

Annotation

Implementation Notes