^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) Specifying GPIO information for devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) =======================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) 1) gpios property
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) -----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) GPIO properties should be named "[<name>-]gpios", with <name> being the purpose
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) of this GPIO for the device. While a non-existent <name> is considered valid
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) for compatibility reasons (resolving to the "gpios" property), it is not allowed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) for new bindings. Also, GPIO properties named "[<name>-]gpio" are valid and old
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) bindings use it, but are only supported for compatibility reasons and should not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) be used for newer bindings since it has been deprecated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) GPIO properties can contain one or more GPIO phandles, but only in exceptional
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) cases should they contain more than one. If your device uses several GPIOs with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) distinct functions, reference each of them under its own property, giving it a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) meaningful name. The only case where an array of GPIOs is accepted is when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) several GPIOs serve the same function (e.g. a parallel data line).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) The exact purpose of each gpios property must be documented in the device tree
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) binding of the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) The following example could be used to describe GPIO pins used as device enable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) and bit-banged data signals:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) gpio1: gpio1 {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) gpio-controller;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) #gpio-cells = <2>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) [...]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) data-gpios = <&gpio1 12 0>,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) <&gpio1 13 0>,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) <&gpio1 14 0>,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) <&gpio1 15 0>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) In the above example, &gpio1 uses 2 cells to specify a gpio. The first cell is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) a local offset to the GPIO line and the second cell represent consumer flags,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) such as if the consumer desire the line to be active low (inverted) or open
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) drain. This is the recommended practice.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) The exact meaning of each specifier cell is controller specific, and must be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) documented in the device tree binding for the device, but it is strongly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) recommended to use the two-cell approach.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) Most controllers are specifying a generic flag bitfield in the last cell, so
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) for these, use the macros defined in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) include/dt-bindings/gpio/gpio.h whenever possible:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) Example of a node using GPIOs:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) node {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) enable-gpios = <&qe_pio_e 18 GPIO_ACTIVE_HIGH>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) GPIO_ACTIVE_HIGH is 0, so in this example gpio-specifier is "18 0" and encodes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) GPIO pin number, and GPIO flags as accepted by the "qe_pio_e" gpio-controller.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) Optional standard bitfield specifiers for the last cell:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) - Bit 0: 0 means active high, 1 means active low
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) - Bit 1: 0 mean push-pull wiring, see:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) https://en.wikipedia.org/wiki/Push-pull_output
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) 1 means single-ended wiring, see:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) https://en.wikipedia.org/wiki/Single-ended_triode
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) - Bit 2: 0 means open-source, 1 means open drain, see:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) https://en.wikipedia.org/wiki/Open_collector
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) - Bit 3: 0 means the output should be maintained during sleep/low-power mode
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) 1 means the output state can be lost during sleep/low-power mode
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) - Bit 4: 0 means no pull-up resistor should be enabled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) 1 means a pull-up resistor should be enabled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) This setting only applies to hardware with a simple on/off
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) control for pull-up configuration. If the hardware has more
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) elaborate pull-up configuration, it should be represented
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) using a pin control binding.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) - Bit 5: 0 means no pull-down resistor should be enabled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) 1 means a pull-down resistor should be enabled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) This setting only applies to hardware with a simple on/off
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) control for pull-down configuration. If the hardware has more
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) elaborate pull-down configuration, it should be represented
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) using a pin control binding.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) 1.1) GPIO specifier best practices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) ----------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) A gpio-specifier should contain a flag indicating the GPIO polarity; active-
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) high or active-low. If it does, the following best practices should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) followed:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) The gpio-specifier's polarity flag should represent the physical level at the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) GPIO controller that achieves (or represents, for inputs) a logically asserted
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) value at the device. The exact definition of logically asserted should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) defined by the binding for the device. If the board inverts the signal between
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) the GPIO controller and the device, then the gpio-specifier will represent the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) opposite physical level than the signal at the device's pin.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) When the device's signal polarity is configurable, the binding for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) device must either:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) a) Define a single static polarity for the signal, with the expectation that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) any software using that binding would statically program the device to use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) that signal polarity.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) The static choice of polarity may be either:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) a1) (Preferred) Dictated by a binding-specific DT property.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) or:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) a2) Defined statically by the DT binding itself.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) In particular, the polarity cannot be derived from the gpio-specifier, since
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) that would prevent the DT from separately representing the two orthogonal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) concepts of configurable signal polarity in the device, and possible board-
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) level signal inversion.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) or:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) b) Pick a single option for device signal polarity, and document this choice
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) in the binding. The gpio-specifier should represent the polarity of the signal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) (at the GPIO controller) assuming that the device is configured for this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) particular signal polarity choice. If software chooses to program the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) to generate or receive a signal of the opposite polarity, software will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) responsible for correctly interpreting (inverting) the GPIO signal at the GPIO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) controller.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) 2) gpio-controller nodes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) ------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) Every GPIO controller node must contain both an empty "gpio-controller"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) property, and a #gpio-cells integer property, which indicates the number of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) cells in a gpio-specifier.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) Some system-on-chips (SoCs) use the concept of GPIO banks. A GPIO bank is an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) instance of a hardware IP core on a silicon die, usually exposed to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) programmer as a coherent range of I/O addresses. Usually each such bank is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) exposed in the device tree as an individual gpio-controller node, reflecting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) the fact that the hardware was synthesized by reusing the same IP block a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) few times over.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) Optionally, a GPIO controller may have a "ngpios" property. This property
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) indicates the number of in-use slots of available slots for GPIOs. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) typical example is something like this: the hardware register is 32 bits
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) wide, but only 18 of the bits have a physical counterpart. The driver is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) generally written so that all 32 bits can be used, but the IP block is reused
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) in a lot of designs, some using all 32 bits, some using 18 and some using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) 12. In this case, setting "ngpios = <18>;" informs the driver that only the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) first 18 GPIOs, at local offset 0 .. 17, are in use.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) If these GPIOs do not happen to be the first N GPIOs at offset 0...N-1, an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) additional set of tuples is needed to specify which GPIOs are unusable, with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) the gpio-reserved-ranges binding. This property indicates the start and size
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) of the GPIOs that can't be used.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) Optionally, a GPIO controller may have a "gpio-line-names" property. This is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) an array of strings defining the names of the GPIO lines going out of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) GPIO controller. This name should be the most meaningful producer name
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) for the system, such as a rail name indicating the usage. Package names
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) such as pin name are discouraged: such lines have opaque names (since they
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) are by definition generic purpose) and such names are usually not very
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) helpful. For example "MMC-CD", "Red LED Vdd" and "ethernet reset" are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) reasonable line names as they describe what the line is used for. "GPIO0"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) is not a good name to give to a GPIO line. Placeholders are discouraged:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) rather use the "" (blank string) if the use of the GPIO line is undefined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) in your design. The names are assigned starting from line offset 0 from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) left to right from the passed array. An incomplete array (where the number
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) of passed named are less than ngpios) will still be used up until the last
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) provided valid line index.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) Example:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) gpio-controller@00000000 {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) compatible = "foo";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) reg = <0x00000000 0x1000>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) gpio-controller;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) #gpio-cells = <2>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) ngpios = <18>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) gpio-reserved-ranges = <0 4>, <12 2>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) gpio-line-names = "MMC-CD", "MMC-WP", "VDD eth", "RST eth", "LED R",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) "LED G", "LED B", "Col A", "Col B", "Col C", "Col D",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) "Row A", "Row B", "Row C", "Row D", "NMI button",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) "poweroff", "reset";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) The GPIO chip may contain GPIO hog definitions. GPIO hogging is a mechanism
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) providing automatic GPIO request and configuration as part of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) gpio-controller's driver probe function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) Each GPIO hog definition is represented as a child node of the GPIO controller.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) Required properties:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) - gpio-hog: A property specifying that this child node represents a GPIO hog.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) - gpios: Store the GPIO information (id, flags, ...) for each GPIO to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) affect. Shall contain an integer multiple of the number of cells
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) specified in its parent node (GPIO controller node).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) Only one of the following properties scanned in the order shown below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) This means that when multiple properties are present they will be searched
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) in the order presented below and the first match is taken as the intended
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) configuration.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) - input: A property specifying to set the GPIO direction as input.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) - output-low A property specifying to set the GPIO direction as output with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) the value low.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) - output-high A property specifying to set the GPIO direction as output with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) the value high.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) Optional properties:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) - line-name: The GPIO label name. If not present the node name is used.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) Example of two SOC GPIO banks defined as gpio-controller nodes:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) qe_pio_a: gpio-controller@1400 {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) compatible = "fsl,qe-pario-bank-a", "fsl,qe-pario-bank";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) reg = <0x1400 0x18>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) gpio-controller;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) #gpio-cells = <2>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) line_b {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) gpio-hog;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) gpios = <6 0>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) output-low;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) line-name = "foo-bar-gpio";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) qe_pio_e: gpio-controller@1460 {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) reg = <0x1460 0x18>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) gpio-controller;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) #gpio-cells = <2>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) 2.1) gpio- and pin-controller interaction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) -----------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) Some or all of the GPIOs provided by a GPIO controller may be routed to pins
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) on the package via a pin controller. This allows muxing those pins between
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) GPIO and other functions. It is a fairly common practice among silicon
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) engineers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) 2.2) Ordinary (numerical) GPIO ranges
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) -------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) It is useful to represent which GPIOs correspond to which pins on which pin
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) controllers. The gpio-ranges property described below represents this with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) a discrete set of ranges mapping pins from the pin controller local number space
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) to pins in the GPIO controller local number space.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) The format is: <[pin controller phandle], [GPIO controller offset],
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) [pin controller offset], [number of pins]>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) The GPIO controller offset pertains to the GPIO controller node containing the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) range definition.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) The pin controller node referenced by the phandle must conform to the bindings
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) described in pinctrl/pinctrl-bindings.txt.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) Each offset runs from 0 to N. It is perfectly fine to pile any number of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) ranges with just one pin-to-GPIO line mapping if the ranges are concocted, but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) in practice these ranges are often lumped in discrete sets.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) Example:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) gpio-ranges = <&foo 0 20 10>, <&bar 10 50 20>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) This means:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) - pins 20..29 on pin controller "foo" is mapped to GPIO line 0..9 and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) - pins 50..69 on pin controller "bar" is mapped to GPIO line 10..29
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) Verbose example:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) qe_pio_e: gpio-controller@1460 {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) #gpio-cells = <2>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) reg = <0x1460 0x18>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) gpio-controller;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) gpio-ranges = <&pinctrl1 0 20 10>, <&pinctrl2 10 50 20>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) Here, a single GPIO controller has GPIOs 0..9 routed to pin controller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) pinctrl1's pins 20..29, and GPIOs 10..29 routed to pin controller pinctrl2's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) pins 50..69.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) 2.3) GPIO ranges from named pin groups
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) --------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) It is also possible to use pin groups for gpio ranges when pin groups are the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) easiest and most convenient mapping.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) Both both <pinctrl-base> and <count> must set to 0 when using named pin groups
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) names.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) The property gpio-ranges-group-names must contain exactly one string for each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) range.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) Elements of gpio-ranges-group-names must contain the name of a pin group
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) defined in the respective pin controller. The number of pins/GPIO lines in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) range is the number of pins in that pin group. The number of pins of that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) group is defined int the implementation and not in the device tree.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) If numerical and named pin groups are mixed, the string corresponding to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) numerical pin range in gpio-ranges-group-names must be empty.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) Example:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) gpio_pio_i: gpio-controller@14b0 {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) #gpio-cells = <2>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) reg = <0x1480 0x18>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) gpio-controller;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) gpio-ranges = <&pinctrl1 0 20 10>,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) <&pinctrl2 10 0 0>,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) <&pinctrl1 15 0 10>,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) <&pinctrl2 25 0 0>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) gpio-ranges-group-names = "",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) "foo",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) "",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) "bar";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) Here, three GPIO ranges are defined referring to two pin controllers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) pinctrl1 GPIO ranges are defined using pin numbers whereas the GPIO ranges
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) in pinctrl2 are defined using the pin groups named "foo" and "bar".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) Previous versions of this binding required all pin controller nodes that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) were referenced by any gpio-ranges property to contain a property named
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) #gpio-range-cells with value <3>. This requirement is now deprecated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) However, that property may still exist in older device trees for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) compatibility reasons, and would still be required even in new device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) trees that need to be compatible with older software.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags