bindings/gpio/gpio.txt

5 -----------------
7 GPIO properties should be named "[<name>-]gpios", with <name> being the purpose
8 of this GPIO for the device. While a non-existent <name> is considered valid
10 for new bindings. Also, GPIO properties named "[<name>-]gpio" are valid and old
21 binding of the device.
24 and bit-banged data signals:
27 		gpio-controller;
28 		#gpio-cells = <2>;
32 	data-gpios = <&gpio1 12 0>,
43 documented in the device tree binding for the device, but it is strongly
44 recommended to use the two-cell approach.
48 include/dt-bindings/gpio/gpio.h whenever possible:
53 		enable-gpios = <&qe_pio_e 18 GPIO_ACTIVE_HIGH>;
56 GPIO_ACTIVE_HIGH is 0, so in this example gpio-specifier is "18 0" and encodes
57 GPIO pin number, and GPIO flags as accepted by the "qe_pio_e" gpio-controller.
61 - Bit 0: 0 means active high, 1 means active low
62 - Bit 1: 0 mean push-pull wiring, see:
63            https://en.wikipedia.org/wiki/Push-pull_output
64          1 means single-ended wiring, see:
65            https://en.wikipedia.org/wiki/Single-ended_triode
66 - Bit 2: 0 means open-source, 1 means open drain, see:
68 - Bit 3: 0 means the output should be maintained during sleep/low-power mode
69          1 means the output state can be lost during sleep/low-power mode
70 - Bit 4: 0 means no pull-up resistor should be enabled
71          1 means a pull-up resistor should be enabled
73          control for pull-up configuration. If the hardware has more
74          elaborate pull-up configuration, it should be represented
75          using a pin control binding.
76 - Bit 5: 0 means no pull-down resistor should be enabled
77          1 means a pull-down resistor should be enabled
79          control for pull-down configuration. If the hardware has more
80          elaborate pull-down configuration, it should be represented
81          using a pin control binding.
84 ----------------------------------
86 A gpio-specifier should contain a flag indicating the GPIO polarity; active-
87 high or active-low. If it does, the following best practices should be
90 The gpio-specifier's polarity flag should represent the physical level at the
93 defined by the binding for the device. If the board inverts the signal between
94 the GPIO controller and the device, then the gpio-specifier will represent the
97 When the device's signal polarity is configurable, the binding for the
101 any software using that binding would statically program the device to use
106 a1) (Preferred) Dictated by a binding-specific DT property.
110 a2) Defined statically by the DT binding itself.
112 In particular, the polarity cannot be derived from the gpio-specifier, since
113 that would prevent the DT from separately representing the two orthogonal
114 concepts of configurable signal polarity in the device, and possible board-
120 in the binding. The gpio-specifier should represent the polarity of the signal
127 2) gpio-controller nodes
128 ------------------------
130 Every GPIO controller node must contain both an empty "gpio-controller"
131 property, and a #gpio-cells integer property, which indicates the number of
132 cells in a gpio-specifier.
134 Some system-on-chips (SoCs) use the concept of GPIO banks. A GPIO bank is an
137 exposed in the device tree as an individual gpio-controller node, reflecting
142 indicates the number of in-use slots of available slots for GPIOs. The
150 If these GPIOs do not happen to be the first N GPIOs at offset 0...N-1, an
152 the gpio-reserved-ranges binding. This property indicates the start and size
155 Optionally, a GPIO controller may have a "gpio-line-names" property. This is
159 For lines which are routed to on-board devices, this name should be
162 such lines have opaque names (since they are by definition general-purpose)
163 and such names are usually not very helpful. For example "MMC-CD", "Red LED
166 that is hard-wired to a specific device.
169 (e.g. the Raspberry Pi 40-pin header), and therefore are not hard-wired to
172 or package name, or names made up from kernel-internal software constructs,
189 gpio-controller@00000000 {
192 	gpio-controller;
193 	#gpio-cells = <2>;
195 	gpio-reserved-ranges = <0 4>, <12 2>;
196 	gpio-line-names = "MMC-CD", "MMC-WP", "VDD eth", "RST eth", "LED R",
204 gpio-controller's driver probe function.
208 - gpio-hog:   A property specifying that this child node represents a GPIO hog.
209 - gpios:      Store the GPIO information (id, flags, ...) for each GPIO to
216 - input:      A property specifying to set the GPIO direction as input.
217 - output-low  A property specifying to set the GPIO direction as output with
219 - output-high A property specifying to set the GPIO direction as output with
223 - line-name:  The GPIO label name. If not present the node name is used.
225 Example of two SOC GPIO banks defined as gpio-controller nodes:
227 	qe_pio_a: gpio-controller@1400 {
228 		compatible = "fsl,qe-pario-bank-a", "fsl,qe-pario-bank";
230 		gpio-controller;
231 		#gpio-cells = <2>;
233 		line_b-hog {
234 			gpio-hog;
236 			output-low;
237 			line-name = "foo-bar-gpio";
241 	qe_pio_e: gpio-controller@1460 {
242 		compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
244 		gpio-controller;
245 		#gpio-cells = <2>;
248 2.1) gpio- and pin-controller interaction
249 -----------------------------------------
257 -------------------------------------
260 controllers. The gpio-ranges property described below represents this with
271 described in pinctrl/pinctrl-bindings.txt.
274 ranges with just one pin-to-GPIO line mapping if the ranges are concocted, but
279     gpio-ranges = <&foo 0 20 10>, <&bar 10 50 20>;
282 - pins 20..29 on pin controller "foo" is mapped to GPIO line 0..9 and
283 - pins 50..69 on pin controller "bar" is mapped to GPIO line 10..29
288 	qe_pio_e: gpio-controller@1460 {
289 		#gpio-cells = <2>;
290 		compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
292 		gpio-controller;
293 		gpio-ranges = <&pinctrl1 0 20 10>, <&pinctrl2 10 50 20>;
302 --------------------------------------
307 Both both <pinctrl-base> and <count> must set to 0 when using named pin groups
310 The property gpio-ranges-group-names must contain exactly one string for each
313 Elements of gpio-ranges-group-names must contain the name of a pin group
319 numerical pin range in gpio-ranges-group-names must be empty.
323 	gpio_pio_i: gpio-controller@14b0 {
324 		#gpio-cells = <2>;
325 		compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
327 		gpio-controller;
328 		gpio-ranges =			<&pinctrl1 0 20 10>,
332 		gpio-ranges-group-names =	"",
343 Previous versions of this binding required all pin controller nodes that
344 were referenced by any gpio-ranges property to contain a property named
345 #gpio-range-cells with value <3>. This requirement is now deprecated.