1 Specifying GPIO information for devices
2 ============================================
7 Nodes that makes use of GPIOs should specify them using one or more
8 properties, each containing a 'gpio-list':
10 gpio-list ::= <single-gpio> [gpio-list]
11 single-gpio ::= <gpio-phandle> <gpio-specifier>
12 gpio-phandle : phandle to gpio controller node
13 gpio-specifier : Array of #gpio-cells specifying specific gpio
16 GPIO properties should be named "[<name>-]gpios". The exact
17 meaning of each gpios property must be documented in the device tree
18 binding for each device.
20 For example, the following could be used to describe GPIO pins used
21 as chip select lines; with chip selects 0, 1 and 3 populated, and chip
33 chipsel-gpios = <&gpio1 12 0>,
35 <0>, /* holes are permitted, means no GPIO 2 */
38 Note that gpio-specifier length is controller dependent. In the
39 above example, &gpio1 uses 2 cells to specify a gpio, while &gpio2
42 gpio-specifier may encode: bank, pin position inside the bank,
43 whether pin is open-drain and whether pin is logically inverted.
44 Exact meaning of each specifier cell is controller specific, and must
45 be documented in the device tree binding for the device.
47 Example of a node using GPIOs:
50 gpios = <&qe_pio_e 18 0>;
53 In this example gpio-specifier is "18 0" and encodes GPIO pin number,
54 and GPIO flags as accepted by the "qe_pio_e" gpio-controller.
56 1.1) GPIO specifier best practices
57 ----------------------------------
59 A gpio-specifier should contain a flag indicating the GPIO polarity; active-
60 high or active-low. If it does, the follow best practices should be followed:
62 The gpio-specifier's polarity flag should represent the physical level at the
63 GPIO controller that achieves (or represents, for inputs) a logically asserted
64 value at the device. The exact definition of logically asserted should be
65 defined by the binding for the device. If the board inverts the signal between
66 the GPIO controller and the device, then the gpio-specifier will represent the
67 opposite physical level than the signal at the device's pin.
69 When the device's signal polarity is configurable, the binding for the
72 a) Define a single static polarity for the signal, with the expectation that
73 any software using that binding would statically program the device to use
76 The static choice of polarity may be either:
78 a1) (Preferred) Dictated by a binding-specific DT property.
82 a2) Defined statically by the DT binding itself.
84 In particular, the polarity cannot be derived from the gpio-specifier, since
85 that would prevent the DT from separately representing the two orthogonal
86 concepts of configurable signal polarity in the device, and possible board-
87 level signal inversion.
91 b) Pick a single option for device signal polarity, and document this choice
92 in the binding. The gpio-specifier should represent the polarity of the signal
93 (at the GPIO controller) assuming that the device is configured for this
94 particular signal polarity choice. If software chooses to program the device
95 to generate or receive a signal of the opposite polarity, software will be
96 responsible for correctly interpreting (inverting) the GPIO signal at the GPIO
99 2) gpio-controller nodes
100 ------------------------
102 Every GPIO controller node must contain both an empty "gpio-controller"
103 property, and a #gpio-cells integer property, which indicates the number of
104 cells in a gpio-specifier.
106 Example of two SOC GPIO banks defined as gpio-controller nodes:
108 qe_pio_a: gpio-controller@1400 {
109 compatible = "fsl,qe-pario-bank-a", "fsl,qe-pario-bank";
115 qe_pio_e: gpio-controller@1460 {
116 compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
122 2.1) gpio- and pin-controller interaction
123 -----------------------------------------
125 Some or all of the GPIOs provided by a GPIO controller may be routed to pins
126 on the package via a pin controller. This allows muxing those pins between
127 GPIO and other functions.
129 It is useful to represent which GPIOs correspond to which pins on which pin
130 controllers. The gpio-ranges property described below represents this, and
131 contains information structures as follows:
133 gpio-range-list ::= <single-gpio-range> [gpio-range-list]
134 single-gpio-range ::= <numeric-gpio-range> | <named-gpio-range>
135 numeric-gpio-range ::=
136 <pinctrl-phandle> <gpio-base> <pinctrl-base> <count>
137 named-gpio-range ::= <pinctrl-phandle> <gpio-base> '<0 0>'
138 gpio-phandle : phandle to pin controller node.
139 gpio-base : Base GPIO ID in the GPIO controller
140 pinctrl-base : Base pinctrl pin ID in the pin controller
141 count : The number of GPIOs/pins in this range
143 The "pin controller node" mentioned above must conform to the bindings
144 described in ../pinctrl/pinctrl-bindings.txt.
146 In case named gpio ranges are used (ranges with both <pinctrl-base> and
147 <count> set to 0), the property gpio-ranges-group-names contains one string
148 for every single-gpio-range in gpio-ranges:
149 gpiorange-names-list ::= <gpiorange-name> [gpiorange-names-list]
150 gpiorange-name : Name of the pingroup associated to the GPIO range in
151 the respective pin controller.
153 Elements of gpiorange-names-list corresponding to numeric ranges contain
154 the empty string. Elements of gpiorange-names-list corresponding to named
155 ranges contain the name of a pin group defined in the respective pin
156 controller. The number of pins/GPIOs in the range is the number of pins in
159 Previous versions of this binding required all pin controller nodes that
160 were referenced by any gpio-ranges property to contain a property named
161 #gpio-range-cells with value <3>. This requirement is now deprecated.
162 However, that property may still exist in older device trees for
163 compatibility reasons, and would still be required even in new device
164 trees that need to be compatible with older software.
168 qe_pio_e: gpio-controller@1460 {
170 compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
173 gpio-ranges = <&pinctrl1 0 20 10>, <&pinctrl2 10 50 20>;
176 Here, a single GPIO controller has GPIOs 0..9 routed to pin controller
177 pinctrl1's pins 20..29, and GPIOs 10..19 routed to pin controller pinctrl2's
182 gpio_pio_i: gpio-controller@14B0 {
184 compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
187 gpio-ranges = <&pinctrl1 0 20 10>,
191 gpio-ranges-group-names = "",
197 Here, three GPIO ranges are defined wrt. two pin controllers. pinctrl1 GPIO
198 ranges are defined using pin numbers whereas the GPIO ranges wrt. pinctrl2
199 are named "foo" and "bar".