Kumar Gala | b053dc5 | 2009-06-19 08:31:05 -0500 | [diff] [blame] | 1 | Specifying GPIO information for devices |
| 2 | ============================================ |
| 3 | |
| 4 | 1) gpios property |
| 5 | ----------------- |
| 6 | |
Grant Likely | bf859f8 | 2011-06-03 11:07:16 -0600 | [diff] [blame] | 7 | Nodes that makes use of GPIOs should specify them using one or more |
| 8 | properties, each containing a 'gpio-list': |
Kumar Gala | b053dc5 | 2009-06-19 08:31:05 -0500 | [diff] [blame] | 9 | |
Grant Likely | bf859f8 | 2011-06-03 11:07:16 -0600 | [diff] [blame] | 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 |
| 14 | (controller specific) |
| 15 | |
Alexandre Courbot | 2071d09 | 2014-10-29 17:13:14 +0900 | [diff] [blame] | 16 | GPIO properties should be named "[<name>-]gpios", with <name> being the purpose |
| 17 | of this GPIO for the device. While a non-existent <name> is considered valid |
| 18 | for compatibility reasons (resolving to the "gpios" property), it is not allowed |
Javier Martinez Canillas | e7ae65c | 2015-09-21 14:57:25 +0200 | [diff] [blame] | 19 | for new bindings. Also, GPIO properties named "[<name>-]gpio" are valid and old |
| 20 | bindings use it, but are only supported for compatibility reasons and should not |
| 21 | be used for newer bindings since it has been deprecated. |
Grant Likely | bf859f8 | 2011-06-03 11:07:16 -0600 | [diff] [blame] | 22 | |
Alexandre Courbot | 2071d09 | 2014-10-29 17:13:14 +0900 | [diff] [blame] | 23 | GPIO properties can contain one or more GPIO phandles, but only in exceptional |
| 24 | cases should they contain more than one. If your device uses several GPIOs with |
| 25 | distinct functions, reference each of them under its own property, giving it a |
| 26 | meaningful name. The only case where an array of GPIOs is accepted is when |
| 27 | several GPIOs serve the same function (e.g. a parallel data line). |
| 28 | |
| 29 | The exact purpose of each gpios property must be documented in the device tree |
| 30 | binding of the device. |
| 31 | |
| 32 | The following example could be used to describe GPIO pins used as device enable |
| 33 | and bit-banged data signals: |
Grant Likely | bf859f8 | 2011-06-03 11:07:16 -0600 | [diff] [blame] | 34 | |
| 35 | gpio1: gpio1 { |
| 36 | gpio-controller |
| 37 | #gpio-cells = <2>; |
| 38 | }; |
| 39 | gpio2: gpio2 { |
| 40 | gpio-controller |
| 41 | #gpio-cells = <1>; |
| 42 | }; |
| 43 | [...] |
Alexandre Courbot | 2071d09 | 2014-10-29 17:13:14 +0900 | [diff] [blame] | 44 | |
| 45 | enable-gpios = <&gpio2 2>; |
| 46 | data-gpios = <&gpio1 12 0>, |
| 47 | <&gpio1 13 0>, |
| 48 | <&gpio1 14 0>, |
| 49 | <&gpio1 15 0>; |
Grant Likely | bf859f8 | 2011-06-03 11:07:16 -0600 | [diff] [blame] | 50 | |
| 51 | Note that gpio-specifier length is controller dependent. In the |
| 52 | above example, &gpio1 uses 2 cells to specify a gpio, while &gpio2 |
| 53 | only uses one. |
Kumar Gala | b053dc5 | 2009-06-19 08:31:05 -0500 | [diff] [blame] | 54 | |
| 55 | gpio-specifier may encode: bank, pin position inside the bank, |
| 56 | whether pin is open-drain and whether pin is logically inverted. |
Grant Likely | bf859f8 | 2011-06-03 11:07:16 -0600 | [diff] [blame] | 57 | Exact meaning of each specifier cell is controller specific, and must |
Alexandre Courbot | 2071d09 | 2014-10-29 17:13:14 +0900 | [diff] [blame] | 58 | be documented in the device tree binding for the device. Use the macros |
| 59 | defined in include/dt-bindings/gpio/gpio.h whenever possible: |
Kumar Gala | b053dc5 | 2009-06-19 08:31:05 -0500 | [diff] [blame] | 60 | |
Stephen Warren | 51e8afc | 2014-02-19 11:43:26 -0700 | [diff] [blame] | 61 | Example of a node using GPIOs: |
Kumar Gala | b053dc5 | 2009-06-19 08:31:05 -0500 | [diff] [blame] | 62 | |
| 63 | node { |
Alexandre Courbot | 2071d09 | 2014-10-29 17:13:14 +0900 | [diff] [blame] | 64 | enable-gpios = <&qe_pio_e 18 GPIO_ACTIVE_HIGH>; |
Kumar Gala | b053dc5 | 2009-06-19 08:31:05 -0500 | [diff] [blame] | 65 | }; |
| 66 | |
Alexandre Courbot | 2071d09 | 2014-10-29 17:13:14 +0900 | [diff] [blame] | 67 | GPIO_ACTIVE_HIGH is 0, so in this example gpio-specifier is "18 0" and encodes |
| 68 | GPIO pin number, and GPIO flags as accepted by the "qe_pio_e" gpio-controller. |
Stephen Warren | 51e8afc | 2014-02-19 11:43:26 -0700 | [diff] [blame] | 69 | |
| 70 | 1.1) GPIO specifier best practices |
| 71 | ---------------------------------- |
| 72 | |
| 73 | A gpio-specifier should contain a flag indicating the GPIO polarity; active- |
Masahiro Yamada | 74981fb | 2015-01-15 17:52:40 +0900 | [diff] [blame] | 74 | high or active-low. If it does, the following best practices should be |
| 75 | followed: |
Stephen Warren | 51e8afc | 2014-02-19 11:43:26 -0700 | [diff] [blame] | 76 | |
| 77 | The gpio-specifier's polarity flag should represent the physical level at the |
| 78 | GPIO controller that achieves (or represents, for inputs) a logically asserted |
| 79 | value at the device. The exact definition of logically asserted should be |
| 80 | defined by the binding for the device. If the board inverts the signal between |
| 81 | the GPIO controller and the device, then the gpio-specifier will represent the |
| 82 | opposite physical level than the signal at the device's pin. |
| 83 | |
| 84 | When the device's signal polarity is configurable, the binding for the |
| 85 | device must either: |
| 86 | |
| 87 | a) Define a single static polarity for the signal, with the expectation that |
| 88 | any software using that binding would statically program the device to use |
| 89 | that signal polarity. |
| 90 | |
| 91 | The static choice of polarity may be either: |
| 92 | |
| 93 | a1) (Preferred) Dictated by a binding-specific DT property. |
| 94 | |
| 95 | or: |
| 96 | |
| 97 | a2) Defined statically by the DT binding itself. |
| 98 | |
| 99 | In particular, the polarity cannot be derived from the gpio-specifier, since |
| 100 | that would prevent the DT from separately representing the two orthogonal |
| 101 | concepts of configurable signal polarity in the device, and possible board- |
| 102 | level signal inversion. |
| 103 | |
| 104 | or: |
| 105 | |
| 106 | b) Pick a single option for device signal polarity, and document this choice |
| 107 | in the binding. The gpio-specifier should represent the polarity of the signal |
| 108 | (at the GPIO controller) assuming that the device is configured for this |
| 109 | particular signal polarity choice. If software chooses to program the device |
| 110 | to generate or receive a signal of the opposite polarity, software will be |
| 111 | responsible for correctly interpreting (inverting) the GPIO signal at the GPIO |
| 112 | controller. |
Kumar Gala | b053dc5 | 2009-06-19 08:31:05 -0500 | [diff] [blame] | 113 | |
| 114 | 2) gpio-controller nodes |
| 115 | ------------------------ |
| 116 | |
Stephen Warren | 51e8afc | 2014-02-19 11:43:26 -0700 | [diff] [blame] | 117 | Every GPIO controller node must contain both an empty "gpio-controller" |
| 118 | property, and a #gpio-cells integer property, which indicates the number of |
| 119 | cells in a gpio-specifier. |
Kumar Gala | b053dc5 | 2009-06-19 08:31:05 -0500 | [diff] [blame] | 120 | |
Benoit Parrot | 6b516a1 | 2015-02-02 11:44:45 -0600 | [diff] [blame] | 121 | The GPIO chip may contain GPIO hog definitions. GPIO hogging is a mechanism |
| 122 | providing automatic GPIO request and configuration as part of the |
| 123 | gpio-controller's driver probe function. |
| 124 | |
| 125 | Each GPIO hog definition is represented as a child node of the GPIO controller. |
| 126 | Required properties: |
| 127 | - gpio-hog: A property specifying that this child node represent a GPIO hog. |
| 128 | - gpios: Store the GPIO information (id, flags, ...). Shall contain the |
| 129 | number of cells specified in its parent node (GPIO controller |
| 130 | node). |
| 131 | Only one of the following properties scanned in the order shown below. |
| 132 | This means that when multiple properties are present they will be searched |
| 133 | in the order presented below and the first match is taken as the intended |
| 134 | configuration. |
| 135 | - input: A property specifying to set the GPIO direction as input. |
| 136 | - output-low A property specifying to set the GPIO direction as output with |
| 137 | the value low. |
| 138 | - output-high A property specifying to set the GPIO direction as output with |
| 139 | the value high. |
| 140 | |
| 141 | Optional properties: |
| 142 | - line-name: The GPIO label name. If not present the node name is used. |
| 143 | |
Kumar Gala | b053dc5 | 2009-06-19 08:31:05 -0500 | [diff] [blame] | 144 | Example of two SOC GPIO banks defined as gpio-controller nodes: |
| 145 | |
| 146 | qe_pio_a: gpio-controller@1400 { |
Kumar Gala | b053dc5 | 2009-06-19 08:31:05 -0500 | [diff] [blame] | 147 | compatible = "fsl,qe-pario-bank-a", "fsl,qe-pario-bank"; |
| 148 | reg = <0x1400 0x18>; |
| 149 | gpio-controller; |
Stephen Warren | 51e8afc | 2014-02-19 11:43:26 -0700 | [diff] [blame] | 150 | #gpio-cells = <2>; |
Benoit Parrot | 6b516a1 | 2015-02-02 11:44:45 -0600 | [diff] [blame] | 151 | |
| 152 | line_b { |
| 153 | gpio-hog; |
| 154 | gpios = <6 0>; |
| 155 | output-low; |
| 156 | line-name = "foo-bar-gpio"; |
| 157 | }; |
Kumar Gala | b053dc5 | 2009-06-19 08:31:05 -0500 | [diff] [blame] | 158 | }; |
| 159 | |
| 160 | qe_pio_e: gpio-controller@1460 { |
Kumar Gala | b053dc5 | 2009-06-19 08:31:05 -0500 | [diff] [blame] | 161 | compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank"; |
| 162 | reg = <0x1460 0x18>; |
| 163 | gpio-controller; |
Stephen Warren | 51e8afc | 2014-02-19 11:43:26 -0700 | [diff] [blame] | 164 | #gpio-cells = <2>; |
Kumar Gala | b053dc5 | 2009-06-19 08:31:05 -0500 | [diff] [blame] | 165 | }; |
| 166 | |
Stephen Warren | a1bc260 | 2013-08-09 10:57:46 -0600 | [diff] [blame] | 167 | 2.1) gpio- and pin-controller interaction |
| 168 | ----------------------------------------- |
Kumar Gala | b053dc5 | 2009-06-19 08:31:05 -0500 | [diff] [blame] | 169 | |
Stephen Warren | a1bc260 | 2013-08-09 10:57:46 -0600 | [diff] [blame] | 170 | Some or all of the GPIOs provided by a GPIO controller may be routed to pins |
| 171 | on the package via a pin controller. This allows muxing those pins between |
| 172 | GPIO and other functions. |
Shiraz Hashim | f23f151 | 2012-10-27 15:21:36 +0530 | [diff] [blame] | 173 | |
Stephen Warren | a1bc260 | 2013-08-09 10:57:46 -0600 | [diff] [blame] | 174 | It is useful to represent which GPIOs correspond to which pins on which pin |
| 175 | controllers. The gpio-ranges property described below represents this, and |
| 176 | contains information structures as follows: |
Shiraz Hashim | f23f151 | 2012-10-27 15:21:36 +0530 | [diff] [blame] | 177 | |
Stephen Warren | a1bc260 | 2013-08-09 10:57:46 -0600 | [diff] [blame] | 178 | gpio-range-list ::= <single-gpio-range> [gpio-range-list] |
Christian Ruppert | 586a87e | 2013-10-15 15:37:54 +0200 | [diff] [blame] | 179 | single-gpio-range ::= <numeric-gpio-range> | <named-gpio-range> |
| 180 | numeric-gpio-range ::= |
Stephen Warren | a1bc260 | 2013-08-09 10:57:46 -0600 | [diff] [blame] | 181 | <pinctrl-phandle> <gpio-base> <pinctrl-base> <count> |
Christian Ruppert | 586a87e | 2013-10-15 15:37:54 +0200 | [diff] [blame] | 182 | named-gpio-range ::= <pinctrl-phandle> <gpio-base> '<0 0>' |
Masahiro Yamada | 74981fb | 2015-01-15 17:52:40 +0900 | [diff] [blame] | 183 | pinctrl-phandle : phandle to pin controller node |
Stephen Warren | a1bc260 | 2013-08-09 10:57:46 -0600 | [diff] [blame] | 184 | gpio-base : Base GPIO ID in the GPIO controller |
| 185 | pinctrl-base : Base pinctrl pin ID in the pin controller |
| 186 | count : The number of GPIOs/pins in this range |
Shiraz Hashim | f23f151 | 2012-10-27 15:21:36 +0530 | [diff] [blame] | 187 | |
Stephen Warren | a1bc260 | 2013-08-09 10:57:46 -0600 | [diff] [blame] | 188 | The "pin controller node" mentioned above must conform to the bindings |
| 189 | described in ../pinctrl/pinctrl-bindings.txt. |
| 190 | |
Christian Ruppert | 586a87e | 2013-10-15 15:37:54 +0200 | [diff] [blame] | 191 | In case named gpio ranges are used (ranges with both <pinctrl-base> and |
| 192 | <count> set to 0), the property gpio-ranges-group-names contains one string |
| 193 | for every single-gpio-range in gpio-ranges: |
| 194 | gpiorange-names-list ::= <gpiorange-name> [gpiorange-names-list] |
| 195 | gpiorange-name : Name of the pingroup associated to the GPIO range in |
| 196 | the respective pin controller. |
| 197 | |
| 198 | Elements of gpiorange-names-list corresponding to numeric ranges contain |
| 199 | the empty string. Elements of gpiorange-names-list corresponding to named |
| 200 | ranges contain the name of a pin group defined in the respective pin |
| 201 | controller. The number of pins/GPIOs in the range is the number of pins in |
| 202 | that pin group. |
| 203 | |
Stephen Warren | a1bc260 | 2013-08-09 10:57:46 -0600 | [diff] [blame] | 204 | Previous versions of this binding required all pin controller nodes that |
| 205 | were referenced by any gpio-ranges property to contain a property named |
| 206 | #gpio-range-cells with value <3>. This requirement is now deprecated. |
| 207 | However, that property may still exist in older device trees for |
| 208 | compatibility reasons, and would still be required even in new device |
| 209 | trees that need to be compatible with older software. |
| 210 | |
Christian Ruppert | 586a87e | 2013-10-15 15:37:54 +0200 | [diff] [blame] | 211 | Example 1: |
Shiraz Hashim | f23f151 | 2012-10-27 15:21:36 +0530 | [diff] [blame] | 212 | |
| 213 | qe_pio_e: gpio-controller@1460 { |
| 214 | #gpio-cells = <2>; |
| 215 | compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank"; |
| 216 | reg = <0x1460 0x18>; |
| 217 | gpio-controller; |
Haojian Zhuang | 86853c8 | 2013-02-17 19:42:47 +0800 | [diff] [blame] | 218 | gpio-ranges = <&pinctrl1 0 20 10>, <&pinctrl2 10 50 20>; |
Stephen Warren | a1bc260 | 2013-08-09 10:57:46 -0600 | [diff] [blame] | 219 | }; |
Shiraz Hashim | f23f151 | 2012-10-27 15:21:36 +0530 | [diff] [blame] | 220 | |
Stephen Warren | a1bc260 | 2013-08-09 10:57:46 -0600 | [diff] [blame] | 221 | Here, a single GPIO controller has GPIOs 0..9 routed to pin controller |
| 222 | pinctrl1's pins 20..29, and GPIOs 10..19 routed to pin controller pinctrl2's |
| 223 | pins 50..59. |
Christian Ruppert | 586a87e | 2013-10-15 15:37:54 +0200 | [diff] [blame] | 224 | |
| 225 | Example 2: |
| 226 | |
| 227 | gpio_pio_i: gpio-controller@14B0 { |
| 228 | #gpio-cells = <2>; |
| 229 | compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank"; |
| 230 | reg = <0x1480 0x18>; |
| 231 | gpio-controller; |
| 232 | gpio-ranges = <&pinctrl1 0 20 10>, |
| 233 | <&pinctrl2 10 0 0>, |
| 234 | <&pinctrl1 15 0 10>, |
| 235 | <&pinctrl2 25 0 0>; |
| 236 | gpio-ranges-group-names = "", |
| 237 | "foo", |
| 238 | "", |
| 239 | "bar"; |
| 240 | }; |
| 241 | |
| 242 | Here, three GPIO ranges are defined wrt. two pin controllers. pinctrl1 GPIO |
| 243 | ranges are defined using pin numbers whereas the GPIO ranges wrt. pinctrl2 |
| 244 | are named "foo" and "bar". |