forked from ~ljy/RK356X_SDK_RELEASE

blame | history | patch | commit | commitdiff
hc
2024-01-03 2f7c68cb55ecb7331f2381deb497c27155f32faf 
 kernel/Documentation/devicetree/bindings/gpio/gpio.txt
....@@ -1,17 +1,8 @@
11 Specifying GPIO information for devices
2
-============================================
2
+=======================================
33 
44 1) gpios property
55 -----------------
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)
156 
167 GPIO properties should be named "[<name>-]gpios", with <name> being the purpose
178 of this GPIO for the device. While a non-existent <name> is considered valid
....@@ -33,33 +24,27 @@
3324 and bit-banged data signals:
3425 
3526 	gpio1: gpio1 {
36
-		gpio-controller
37
-		 #gpio-cells = <2>;
38
-	};
39
-	gpio2: gpio2 {
40
-		gpio-controller
41
-		 #gpio-cells = <1>;
27
+		gpio-controller;
28
+		#gpio-cells = <2>;
4229 	};
4330 	[...]
4431 
45
-	enable-gpios = <&gpio2 2>;
4632 	data-gpios = <&gpio1 12 0>,
4733 		     <&gpio1 13 0>,
4834 		     <&gpio1 14 0>,
4935 		     <&gpio1 15 0>;
5036 
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.
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,
39
+such as if the consumer desire the line to be active low (inverted) or open
40
+drain. This is the recommended practice.
5441 
55
-gpio-specifier may encode: bank, pin position inside the bank,
56
-whether pin is open-drain and whether pin is logically inverted.
42
+The exact meaning of each specifier cell is controller specific, and must be
43
+documented in the device tree binding for the device, but it is strongly
44
+recommended to use the two-cell approach.
5745 
58
-Exact meaning of each specifier cell is controller specific, and must
59
-be documented in the device tree binding for the device.
60
-
61
-Most controllers are however specifying a generic flag bitfield
62
-in the last cell, so for these, use the macros defined in
46
+Most controllers are specifying a generic flag bitfield in the last cell, so
47
+for these, use the macros defined in
6348 include/dt-bindings/gpio/gpio.h whenever possible:
6449 
6550 Example of a node using GPIOs:
....@@ -82,6 +67,18 @@
8267            https://en.wikipedia.org/wiki/Open_collector
8368 - Bit 3: 0 means the output should be maintained during sleep/low-power mode
8469          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.
8582 
8683 1.1) GPIO specifier best practices
8784 ----------------------------------
....@@ -236,46 +233,40 @@
236233 
237234 Some or all of the GPIOs provided by a GPIO controller may be routed to pins
238235 on the package via a pin controller. This allows muxing those pins between
239
-GPIO and other functions.
236
+GPIO and other functions. It is a fairly common practice among silicon
237
+engineers.
238
+
239
+2.2) Ordinary (numerical) GPIO ranges
240
+-------------------------------------
240241 
241242 It is useful to represent which GPIOs correspond to which pins on which pin
242
-controllers. The gpio-ranges property described below represents this, and
243
-contains information structures as follows:
243
+controllers. The gpio-ranges property described below represents this with
244
+a discrete set of ranges mapping pins from the pin controller local number space
245
+to pins in the GPIO controller local number space.
244246 
245
-	gpio-range-list ::= <single-gpio-range> [gpio-range-list]
246
-	single-gpio-range ::= <numeric-gpio-range> | <named-gpio-range>
247
-	numeric-gpio-range ::=
248
-			<pinctrl-phandle> <gpio-base> <pinctrl-base> <count>
249
-	named-gpio-range ::= <pinctrl-phandle> <gpio-base> '<0 0>'
250
-	pinctrl-phandle : phandle to pin controller node
251
-	gpio-base : Base GPIO ID in the GPIO controller
252
-	pinctrl-base : Base pinctrl pin ID in the pin controller
253
-	count : The number of GPIOs/pins in this range
247
+The format is: <[pin controller phandle], [GPIO controller offset],
248
+                [pin controller offset], [number of pins]>;
254249 
255
-The "pin controller node" mentioned above must conform to the bindings
256
-described in ../pinctrl/pinctrl-bindings.txt.
250
+The GPIO controller offset pertains to the GPIO controller node containing the
251
+range definition.
257252 
258
-In case named gpio ranges are used (ranges with both <pinctrl-base> and
259
-<count> set to 0), the property gpio-ranges-group-names contains one string
260
-for every single-gpio-range in gpio-ranges:
261
-	gpiorange-names-list ::= <gpiorange-name> [gpiorange-names-list]
262
-	gpiorange-name : Name of the pingroup associated to the GPIO range in
263
-			the respective pin controller.
253
+The pin controller node referenced by the phandle must conform to the bindings
254
+described in pinctrl/pinctrl-bindings.txt.
264255 
265
-Elements of gpiorange-names-list corresponding to numeric ranges contain
266
-the empty string. Elements of gpiorange-names-list corresponding to named
267
-ranges contain the name of a pin group defined in the respective pin
268
-controller. The number of pins/GPIOs in the range is the number of pins in
269
-that pin group.
256
+Each offset runs from 0 to N. It is perfectly fine to pile any number of
257
+ranges with just one pin-to-GPIO line mapping if the ranges are concocted, but
258
+in practice these ranges are often lumped in discrete sets.
270259 
271
-Previous versions of this binding required all pin controller nodes that
272
-were referenced by any gpio-ranges property to contain a property named
273
-#gpio-range-cells with value <3>. This requirement is now deprecated.
274
-However, that property may still exist in older device trees for
275
-compatibility reasons, and would still be required even in new device
276
-trees that need to be compatible with older software.
260
+Example:
277261 
278
-Example 1:
262
+    gpio-ranges = <&foo 0 20 10>, <&bar 10 50 20>;
263
+
264
+This means:
265
+- pins 20..29 on pin controller "foo" is mapped to GPIO line 0..9 and
266
+- pins 50..69 on pin controller "bar" is mapped to GPIO line 10..29
267
+
268
+
269
+Verbose example:
279270 
280271 	qe_pio_e: gpio-controller@1460 {
281272 		#gpio-cells = <2>;
....@@ -289,7 +280,28 @@
289280 pinctrl1's pins 20..29, and GPIOs 10..29 routed to pin controller pinctrl2's
290281 pins 50..69.
291282 
292
-Example 2:
283
+
284
+2.3) GPIO ranges from named pin groups
285
+--------------------------------------
286
+
287
+It is also possible to use pin groups for gpio ranges when pin groups are the
288
+easiest and most convenient mapping.
289
+
290
+Both both <pinctrl-base> and <count> must set to 0 when using named pin groups
291
+names.
292
+
293
+The property gpio-ranges-group-names must contain exactly one string for each
294
+range.
295
+
296
+Elements of gpio-ranges-group-names must contain the name of a pin group
297
+defined in the respective pin controller. The number of pins/GPIO lines in the
298
+range is the number of pins in that pin group. The number of pins of that
299
+group is defined int the implementation and not in the device tree.
300
+
301
+If numerical and named pin groups are mixed, the string corresponding to a
302
+numerical pin range in gpio-ranges-group-names must be empty.
303
+
304
+Example:
293305 
294306 	gpio_pio_i: gpio-controller@14b0 {
295307 		#gpio-cells = <2>;
....@@ -306,6 +318,14 @@
306318 						"bar";
307319 	};
308320 
309
-Here, three GPIO ranges are defined wrt. two pin controllers. pinctrl1 GPIO
310
-ranges are defined using pin numbers whereas the GPIO ranges wrt. pinctrl2
311
-are named "foo" and "bar".
321
+Here, three GPIO ranges are defined referring to two pin controllers.
322
+
323
+pinctrl1 GPIO ranges are defined using pin numbers whereas the GPIO ranges
324
+in pinctrl2 are defined using the pin groups named "foo" and "bar".
325
+
326
+Previous versions of this binding required all pin controller nodes that
327
+were referenced by any gpio-ranges property to contain a property named
328
+#gpio-range-cells with value <3>. This requirement is now deprecated.
329
+However, that property may still exist in older device trees for
330
+compatibility reasons, and would still be required even in new device
331
+trees that need to be compatible with older software.