1Specifying GPIO information for devices 2============================================ 3 41) gpios property 5----------------- 6 7Nodes that makes use of GPIOs should specify them using one or more 8properties, each containing a 'gpio-list': 9 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 16GPIO properties should be named "[<name>-]gpios". The exact 17meaning of each gpios property must be documented in the device tree 18binding for each device. 19 20For example, the following could be used to describe GPIO pins used 21as chip select lines; with chip selects 0, 1 and 3 populated, and chip 22select 2 left empty: 23 24 gpio1: gpio1 { 25 gpio-controller 26 #gpio-cells = <2>; 27 }; 28 gpio2: gpio2 { 29 gpio-controller 30 #gpio-cells = <1>; 31 }; 32 [...] 33 chipsel-gpios = <&gpio1 12 0>, 34 <&gpio1 13 0>, 35 <0>, /* holes are permitted, means no GPIO 2 */ 36 <&gpio2 2>; 37 38Note that gpio-specifier length is controller dependent. In the 39above example, &gpio1 uses 2 cells to specify a gpio, while &gpio2 40only uses one. 41 42gpio-specifier may encode: bank, pin position inside the bank, 43whether pin is open-drain and whether pin is logically inverted. 44Exact meaning of each specifier cell is controller specific, and must 45be documented in the device tree binding for the device. 46 47Example of a node using GPIOs: 48 49 node { 50 gpios = <&qe_pio_e 18 0>; 51 }; 52 53In this example gpio-specifier is "18 0" and encodes GPIO pin number, 54and GPIO flags as accepted by the "qe_pio_e" gpio-controller. 55 561.1) GPIO specifier best practices 57---------------------------------- 58 59A gpio-specifier should contain a flag indicating the GPIO polarity; active- 60high or active-low. If it does, the follow best practices should be followed: 61 62The gpio-specifier's polarity flag should represent the physical level at the 63GPIO controller that achieves (or represents, for inputs) a logically asserted 64value at the device. The exact definition of logically asserted should be 65defined by the binding for the device. If the board inverts the signal between 66the GPIO controller and the device, then the gpio-specifier will represent the 67opposite physical level than the signal at the device's pin. 68 69When the device's signal polarity is configurable, the binding for the 70device must either: 71 72a) Define a single static polarity for the signal, with the expectation that 73any software using that binding would statically program the device to use 74that signal polarity. 75 76The static choice of polarity may be either: 77 78a1) (Preferred) Dictated by a binding-specific DT property. 79 80or: 81 82a2) Defined statically by the DT binding itself. 83 84In particular, the polarity cannot be derived from the gpio-specifier, since 85that would prevent the DT from separately representing the two orthogonal 86concepts of configurable signal polarity in the device, and possible board- 87level signal inversion. 88 89or: 90 91b) Pick a single option for device signal polarity, and document this choice 92in 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 94particular signal polarity choice. If software chooses to program the device 95to generate or receive a signal of the opposite polarity, software will be 96responsible for correctly interpreting (inverting) the GPIO signal at the GPIO 97controller. 98 992) gpio-controller nodes 100------------------------ 101 102Every GPIO controller node must contain both an empty "gpio-controller" 103property, and a #gpio-cells integer property, which indicates the number of 104cells in a gpio-specifier. 105 106Example of two SOC GPIO banks defined as gpio-controller nodes: 107 108 qe_pio_a: gpio-controller@1400 { 109 compatible = "fsl,qe-pario-bank-a", "fsl,qe-pario-bank"; 110 reg = <0x1400 0x18>; 111 gpio-controller; 112 #gpio-cells = <2>; 113 }; 114 115 qe_pio_e: gpio-controller@1460 { 116 compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank"; 117 reg = <0x1460 0x18>; 118 gpio-controller; 119 #gpio-cells = <2>; 120 }; 121 1222.1) gpio- and pin-controller interaction 123----------------------------------------- 124 125Some or all of the GPIOs provided by a GPIO controller may be routed to pins 126on the package via a pin controller. This allows muxing those pins between 127GPIO and other functions. 128 129It is useful to represent which GPIOs correspond to which pins on which pin 130controllers. The gpio-ranges property described below represents this, and 131contains information structures as follows: 132 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 142 143The "pin controller node" mentioned above must conform to the bindings 144described in ../pinctrl/pinctrl-bindings.txt. 145 146In 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 148for 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. 152 153Elements of gpiorange-names-list corresponding to numeric ranges contain 154the empty string. Elements of gpiorange-names-list corresponding to named 155ranges contain the name of a pin group defined in the respective pin 156controller. The number of pins/GPIOs in the range is the number of pins in 157that pin group. 158 159Previous versions of this binding required all pin controller nodes that 160were referenced by any gpio-ranges property to contain a property named 161#gpio-range-cells with value <3>. This requirement is now deprecated. 162However, that property may still exist in older device trees for 163compatibility reasons, and would still be required even in new device 164trees that need to be compatible with older software. 165 166Example 1: 167 168 qe_pio_e: gpio-controller@1460 { 169 #gpio-cells = <2>; 170 compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank"; 171 reg = <0x1460 0x18>; 172 gpio-controller; 173 gpio-ranges = <&pinctrl1 0 20 10>, <&pinctrl2 10 50 20>; 174 }; 175 176Here, a single GPIO controller has GPIOs 0..9 routed to pin controller 177pinctrl1's pins 20..29, and GPIOs 10..19 routed to pin controller pinctrl2's 178pins 50..59. 179 180Example 2: 181 182 gpio_pio_i: gpio-controller@14B0 { 183 #gpio-cells = <2>; 184 compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank"; 185 reg = <0x1480 0x18>; 186 gpio-controller; 187 gpio-ranges = <&pinctrl1 0 20 10>, 188 <&pinctrl2 10 0 0>, 189 <&pinctrl1 15 0 10>, 190 <&pinctrl2 25 0 0>; 191 gpio-ranges-group-names = "", 192 "foo", 193 "", 194 "bar"; 195 }; 196 197Here, three GPIO ranges are defined wrt. two pin controllers. pinctrl1 GPIO 198ranges are defined using pin numbers whereas the GPIO ranges wrt. pinctrl2 199are named "foo" and "bar". 200