Documentation/devicetree/bindings/gpio/gpio.txt

   1 Specifying GPIO information for devices
   2 ============================================
   3
   4 1) gpios property
   5 -----------------
   6
   7 Nodes that makes use of GPIOs should specify them using one or more
   8 properties, 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
  16 GPIO properties should be named "[<name>-]gpios".  Exact
  17 meaning of each gpios property must be documented in the device tree
  18 binding for each device.
  19
  20 For example, the following could be used to describe gpios pins to use
  21 as chip select lines; with chip selects 0, 1 and 3 populated, and chip
  22 select 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
  38 Note that gpio-specifier length is controller dependent.  In the
  39 above example, &gpio1 uses 2 cells to specify a gpio, while &gpio2
  40 only uses one.
  41
  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.
  46
  47 Example of the node using GPIOs:
  48
  49         node {
  50                 gpios = <&qe_pio_e 18 0>;
  51         };
  52
  53 In this example gpio-specifier is "18 0" and encodes GPIO pin number,
  54 and empty GPIO flags as accepted by the "qe_pio_e" gpio-controller.
  55
  56 2) gpio-controller nodes
  57 ------------------------
  58
  59 Every GPIO controller node must both an empty "gpio-controller"
  60 property, and have #gpio-cells contain the size of the gpio-specifier.
  61
  62 Example of two SOC GPIO banks defined as gpio-controller nodes:
  63
  64         qe_pio_a: gpio-controller@1400 {
  65                 #gpio-cells = <2>;
  66                 compatible = "fsl,qe-pario-bank-a", "fsl,qe-pario-bank";
  67                 reg = <0x1400 0x18>;
  68                 gpio-controller;
  69         };
  70
  71         qe_pio_e: gpio-controller@1460 {
  72                 #gpio-cells = <2>;
  73                 compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
  74                 reg = <0x1460 0x18>;
  75                 gpio-controller;
  76         };
  77
  78 2.1) gpio- and pin-controller interaction
  79 -----------------------------------------
  80
  81 Some or all of the GPIOs provided by a GPIO controller may be routed to pins
  82 on the package via a pin controller. This allows muxing those pins between
  83 GPIO and other functions.
  84
  85 It is useful to represent which GPIOs correspond to which pins on which pin
  86 controllers. The gpio-ranges property described below represents this, and
  87 contains information structures as follows:
  88
  89         gpio-range-list ::= <single-gpio-range> [gpio-range-list]
  90         single-gpio-range ::= <numeric-gpio-range> | <named-gpio-range>
  91         numeric-gpio-range ::=
  92                         <pinctrl-phandle> <gpio-base> <pinctrl-base> <count>
  93         named-gpio-range ::= <pinctrl-phandle> <gpio-base> '<0 0>'
  94         gpio-phandle : phandle to pin controller node.
  95         gpio-base : Base GPIO ID in the GPIO controller
  96         pinctrl-base : Base pinctrl pin ID in the pin controller
  97         count : The number of GPIOs/pins in this range
  98
  99 The "pin controller node" mentioned above must conform to the bindings
 100 described in ../pinctrl/pinctrl-bindings.txt.
 101
 102 In case named gpio ranges are used (ranges with both <pinctrl-base> and
 103 <count> set to 0), the property gpio-ranges-group-names contains one string
 104 for every single-gpio-range in gpio-ranges:
 105         gpiorange-names-list ::= <gpiorange-name> [gpiorange-names-list]
 106         gpiorange-name : Name of the pingroup associated to the GPIO range in
 107                         the respective pin controller.
 108
 109 Elements of gpiorange-names-list corresponding to numeric ranges contain
 110 the empty string. Elements of gpiorange-names-list corresponding to named
 111 ranges contain the name of a pin group defined in the respective pin
 112 controller. The number of pins/GPIOs in the range is the number of pins in
 113 that pin group.
 114
 115 Previous versions of this binding required all pin controller nodes that
 116 were referenced by any gpio-ranges property to contain a property named
 117 #gpio-range-cells with value <3>. This requirement is now deprecated.
 118 However, that property may still exist in older device trees for
 119 compatibility reasons, and would still be required even in new device
 120 trees that need to be compatible with older software.
 121
 122 Example 1:
 123
 124         qe_pio_e: gpio-controller@1460 {
 125                 #gpio-cells = <2>;
 126                 compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
 127                 reg = <0x1460 0x18>;
 128                 gpio-controller;
 129                 gpio-ranges = <&pinctrl1 0 20 10>, <&pinctrl2 10 50 20>;
 130         };
 131
 132 Here, a single GPIO controller has GPIOs 0..9 routed to pin controller
 133 pinctrl1's pins 20..29, and GPIOs 10..19 routed to pin controller pinctrl2's
 134 pins 50..59.
 135
 136 Example 2:
 137
 138         gpio_pio_i: gpio-controller@14B0 {
 139                 #gpio-cells = <2>;
 140                 compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
 141                 reg = <0x1480 0x18>;
 142                 gpio-controller;
 143                 gpio-ranges =                   <&pinctrl1 0 20 10>,
 144                                                 <&pinctrl2 10 0 0>,
 145                                                 <&pinctrl1 15 0 10>,
 146                                                 <&pinctrl2 25 0 0>;
 147                 gpio-ranges-group-names =       "",
 148                                                 "foo",
 149                                                 "",
 150                                                 "bar";
 151         };
 152
 153 Here, three GPIO ranges are defined wrt. two pin controllers. pinctrl1 GPIO
 154 ranges are defined using pin numbers whereas the GPIO ranges wrt. pinctrl2
 155 are named "foo" and "bar".