Lines Matching +full:a +full:- +full:gpio
1 Specifying GPIO information for devices
5 -----------------
7 GPIO properties should be named "[<name>-]gpios", with <name> being the purpose
8 of this GPIO for the device. While a non-existent <name> is considered valid
10 for new bindings. Also, GPIO properties named "[<name>-]gpio" are valid and old
14 GPIO properties can contain one or more GPIO phandles, but only in exceptional
16 distinct functions, reference each of them under its own property, giving it a
18 several GPIOs serve the same function (e.g. a parallel data line).
23 The following example could be used to describe GPIO pins used as device enable
24 and bit-banged data signals:
27 gpio-controller;
28 #gpio-cells = <2>;
32 data-gpios = <&gpio1 12 0>,
37 In the above example, &gpio1 uses 2 cells to specify a gpio. The first cell is
38 a local offset to the GPIO line and the second cell represent consumer flags,
44 recommended to use the two-cell approach.
46 Most controllers are specifying a generic flag bitfield in the last cell, so
48 include/dt-bindings/gpio/gpio.h whenever possible:
50 Example of a node using GPIOs:
53 enable-gpios = <&qe_pio_e 18 GPIO_ACTIVE_HIGH>;
56 GPIO_ACTIVE_HIGH is 0, so in this example gpio-specifier is "18 0" and encodes
57 GPIO pin number, and GPIO flags as accepted by the "qe_pio_e" gpio-controller.
61 - Bit 0: 0 means active high, 1 means active low
62 - Bit 1: 0 mean push-pull wiring, see:
63 https://en.wikipedia.org/wiki/Push-pull_output
64 1 means single-ended wiring, see:
65 https://en.wikipedia.org/wiki/Single-ended_triode
66 - Bit 2: 0 means open-source, 1 means open drain, see:
68 - Bit 3: 0 means the output should be maintained during sleep/low-power mode
69 1 means the output state can be lost during sleep/low-power mode
70 - Bit 4: 0 means no pull-up resistor should be enabled
71 1 means a pull-up resistor should be enabled
72 This setting only applies to hardware with a simple on/off
73 control for pull-up configuration. If the hardware has more
74 elaborate pull-up configuration, it should be represented
75 using a pin control binding.
76 - Bit 5: 0 means no pull-down resistor should be enabled
77 1 means a pull-down resistor should be enabled
78 This setting only applies to hardware with a simple on/off
79 control for pull-down configuration. If the hardware has more
80 elaborate pull-down configuration, it should be represented
81 using a pin control binding.
83 1.1) GPIO specifier best practices
84 ----------------------------------
86 A gpio-specifier should contain a flag indicating the GPIO polarity; active-
87 high or active-low. If it does, the following best practices should be
90 The gpio-specifier's polarity flag should represent the physical level at the
91 GPIO controller that achieves (or represents, for inputs) a logically asserted
94 the GPIO controller and the device, then the gpio-specifier will represent the
100 a) Define a single static polarity for the signal, with the expectation that
106 a1) (Preferred) Dictated by a binding-specific DT property.
112 In particular, the polarity cannot be derived from the gpio-specifier, since
114 concepts of configurable signal polarity in the device, and possible board-
119 b) Pick a single option for device signal polarity, and document this choice
120 in the binding. The gpio-specifier should represent the polarity of the signal
121 (at the GPIO controller) assuming that the device is configured for this
123 to generate or receive a signal of the opposite polarity, software will be
124 responsible for correctly interpreting (inverting) the GPIO signal at the GPIO
127 2) gpio-controller nodes
128 ------------------------
130 Every GPIO controller node must contain both an empty "gpio-controller"
131 property, and a #gpio-cells integer property, which indicates the number of
132 cells in a gpio-specifier.
134 Some system-on-chips (SoCs) use the concept of GPIO banks. A GPIO bank is an
135 instance of a hardware IP core on a silicon die, usually exposed to the
136 programmer as a coherent range of I/O addresses. Usually each such bank is
137 exposed in the device tree as an individual gpio-controller node, reflecting
138 the fact that the hardware was synthesized by reusing the same IP block a
141 Optionally, a GPIO controller may have a "ngpios" property. This property
142 indicates the number of in-use slots of available slots for GPIOs. The
144 wide, but only 18 of the bits have a physical counterpart. The driver is
146 in a lot of designs, some using all 32 bits, some using 18 and some using
150 If these GPIOs do not happen to be the first N GPIOs at offset 0...N-1, an
152 the gpio-reserved-ranges binding. This property indicates the start and size
155 Optionally, a GPIO controller may have a "gpio-line-names" property. This is
156 an array of strings defining the names of the GPIO lines going out of the
157 GPIO controller.
159 For lines which are routed to on-board devices, this name should be
160 the most meaningful producer name for the system, such as a rail name
161 indicating the usage. Package names, such as a pin name, are discouraged:
162 such lines have opaque names (since they are by definition general-purpose)
163 and such names are usually not very helpful. For example "MMC-CD", "Red LED
165 the line is used for. "GPIO0" is not a good name to give to a GPIO line
166 that is hard-wired to a specific device.
168 However, in the case of lines that are routed to a general purpose header
169 (e.g. the Raspberry Pi 40-pin header), and therefore are not hard-wired to
170 specific devices, using a pin number or the names on the header is fine
172 or package name, or names made up from kernel-internal software constructs,
175 example of a name from an SoC's reference manual) would not be desirable.
178 string) if the use of the GPIO line is undefined in your design. Ideally,
189 gpio-controller@00000000 {
192 gpio-controller;
193 #gpio-cells = <2>;
195 gpio-reserved-ranges = <0 4>, <12 2>;
196 gpio-line-names = "MMC-CD", "MMC-WP", "VDD eth", "RST eth", "LED R",
197 "LED G", "LED B", "Col A", "Col B", "Col C", "Col D",
198 "Row A", "Row B", "Row C", "Row D", "NMI button",
202 The GPIO chip may contain GPIO hog definitions. GPIO hogging is a mechanism
203 providing automatic GPIO request and configuration as part of the
204 gpio-controller's driver probe function.
206 Each GPIO hog definition is represented as a child node of the GPIO controller.
208 - gpio-hog: A property specifying that this child node represents a GPIO hog.
209 - gpios: Store the GPIO information (id, flags, ...) for each GPIO to
211 specified in its parent node (GPIO controller node).
216 - input: A property specifying to set the GPIO direction as input.
217 - output-low A property specifying to set the GPIO direction as output with
219 - output-high A property specifying to set the GPIO direction as output with
223 - line-name: The GPIO label name. If not present the node name is used.
225 Example of two SOC GPIO banks defined as gpio-controller nodes:
227 qe_pio_a: gpio-controller@1400 {
228 compatible = "fsl,qe-pario-bank-a", "fsl,qe-pario-bank";
230 gpio-controller;
231 #gpio-cells = <2>;
233 line_b-hog {
234 gpio-hog;
236 output-low;
237 line-name = "foo-bar-gpio";
241 qe_pio_e: gpio-controller@1460 {
242 compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
244 gpio-controller;
245 #gpio-cells = <2>;
248 2.1) gpio- and pin-controller interaction
249 -----------------------------------------
251 Some or all of the GPIOs provided by a GPIO controller may be routed to pins
252 on the package via a pin controller. This allows muxing those pins between
253 GPIO and other functions. It is a fairly common practice among silicon
256 2.2) Ordinary (numerical) GPIO ranges
257 -------------------------------------
260 controllers. The gpio-ranges property described below represents this with
261 a discrete set of ranges mapping pins from the pin controller local number space
262 to pins in the GPIO controller local number space.
264 The format is: <[pin controller phandle], [GPIO controller offset],
267 The GPIO controller offset pertains to the GPIO controller node containing the
271 described in pinctrl/pinctrl-bindings.txt.
274 ranges with just one pin-to-GPIO line mapping if the ranges are concocted, but
279 gpio-ranges = <&foo 0 20 10>, <&bar 10 50 20>;
282 - pins 20..29 on pin controller "foo" is mapped to GPIO line 0..9 and
283 - pins 50..69 on pin controller "bar" is mapped to GPIO line 10..29
288 qe_pio_e: gpio-controller@1460 {
289 #gpio-cells = <2>;
290 compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
292 gpio-controller;
293 gpio-ranges = <&pinctrl1 0 20 10>, <&pinctrl2 10 50 20>;
296 Here, a single GPIO controller has GPIOs 0..9 routed to pin controller
301 2.3) GPIO ranges from named pin groups
302 --------------------------------------
304 It is also possible to use pin groups for gpio ranges when pin groups are the
307 Both both <pinctrl-base> and <count> must set to 0 when using named pin groups
310 The property gpio-ranges-group-names must contain exactly one string for each
313 Elements of gpio-ranges-group-names must contain the name of a pin group
314 defined in the respective pin controller. The number of pins/GPIO lines in the
318 If numerical and named pin groups are mixed, the string corresponding to a
319 numerical pin range in gpio-ranges-group-names must be empty.
323 gpio_pio_i: gpio-controller@14b0 {
324 #gpio-cells = <2>;
325 compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
327 gpio-controller;
328 gpio-ranges = <&pinctrl1 0 20 10>,
332 gpio-ranges-group-names = "",
338 Here, three GPIO ranges are defined referring to two pin controllers.
340 pinctrl1 GPIO ranges are defined using pin numbers whereas the GPIO ranges
344 were referenced by any gpio-ranges property to contain a property named
345 #gpio-range-cells with value <3>. This requirement is now deprecated.