1 # SPDX-License-Identifier: GPL-2.0-only 1 # SPDX-License-Identifier: GPL-2.0-only
2 %YAML 1.2 2 %YAML 1.2
3 --- 3 ---
4 $id: http://devicetree.org/schemas/pinctrl/pin 4 $id: http://devicetree.org/schemas/pinctrl/pinmux-node.yaml#
5 $schema: http://devicetree.org/meta-schemas/co 5 $schema: http://devicetree.org/meta-schemas/core.yaml#
6 6
7 title: Generic Pin Multiplexing Node !! 7 title: Generic pin multiplexing node schema
8 8
9 maintainers: 9 maintainers:
10 - Linus Walleij <linus.walleij@linaro.org> 10 - Linus Walleij <linus.walleij@linaro.org>
11 11
12 description: | 12 description: |
13 The contents of the pin configuration child 13 The contents of the pin configuration child nodes are defined by the binding
14 for the individual pin controller device. Th 14 for the individual pin controller device. The pin configuration nodes need not
15 be direct children of the pin controller dev 15 be direct children of the pin controller device; they may be grandchildren,
16 for example. Whether this is legal, and whet 16 for example. Whether this is legal, and whether there is any interaction
17 between the child and intermediate parent no 17 between the child and intermediate parent nodes, is again defined entirely by
18 the binding for the individual pin controlle 18 the binding for the individual pin controller device.
19 19
20 While not required to be used, there are 3 g 20 While not required to be used, there are 3 generic forms of pin muxing nodes
21 which pin controller devices can use. 21 which pin controller devices can use.
22 22
23 pin multiplexing nodes: 23 pin multiplexing nodes:
24 24
25 Example: 25 Example:
26 26
27 state_0_node_a { 27 state_0_node_a {
28 uart0 { 28 uart0 {
29 function = "uart0"; 29 function = "uart0";
30 groups = "u0rxtx", "u0rtscts"; 30 groups = "u0rxtx", "u0rtscts";
31 }; 31 };
32 }; 32 };
33 state_1_node_a { 33 state_1_node_a {
34 spi { !! 34 spi0 {
35 function = "spi0"; 35 function = "spi0";
36 groups = "spi0pins"; 36 groups = "spi0pins";
37 }; 37 };
38 }; 38 };
39 state_2_node_a { 39 state_2_node_a {
40 function = "i2c0"; 40 function = "i2c0";
41 pins = "mfio29", "mfio30"; 41 pins = "mfio29", "mfio30";
42 }; 42 };
43 43
44 Optionally an alternative binding can be use 44 Optionally an alternative binding can be used if more suitable depending on the
45 pin controller hardware. For hardware where 45 pin controller hardware. For hardware where there is a large number of identical
46 pin controller instances, naming each pin an 46 pin controller instances, naming each pin and function can easily become
47 unmaintainable. This is especially the case 47 unmaintainable. This is especially the case if the same controller is used for
48 different pins and functions depending on th 48 different pins and functions depending on the SoC revision and packaging.
49 49
50 For cases like this, the pin controller driv 50 For cases like this, the pin controller driver may use pinctrl-pin-array helper
51 binding with a hardware based index and a nu 51 binding with a hardware based index and a number of pin configuration values:
52 52
53 pincontroller { 53 pincontroller {
54 ... /* Standard DT properties for the devi 54 ... /* Standard DT properties for the device itself elided */
55 #pinctrl-cells = <2>; 55 #pinctrl-cells = <2>;
56 56
57 state_0_node_a { 57 state_0_node_a {
58 pinctrl-pin-array = < 58 pinctrl-pin-array = <
59 0 A_DELAY_PS(0) G_DELAY_PS(120) 59 0 A_DELAY_PS(0) G_DELAY_PS(120)
60 4 A_DELAY_PS(0) G_DELAY_PS(360) 60 4 A_DELAY_PS(0) G_DELAY_PS(360)
61 ... 61 ...
62 >; 62 >;
63 }; 63 };
64 ... 64 ...
65 }; 65 };
66 66
67 Above #pinctrl-cells specifies the number of 67 Above #pinctrl-cells specifies the number of value cells in addition to the
68 index of the registers. This is similar to t 68 index of the registers. This is similar to the interrupts-extended binding with
69 one exception. There is no need to specify t 69 one exception. There is no need to specify the phandle for each entry as that
70 is already known as the defined pins are alw 70 is already known as the defined pins are always children of the pin controller
71 node. Further having the phandle pointing to 71 node. Further having the phandle pointing to another pin controller would not
72 currently work as the pinctrl framework uses 72 currently work as the pinctrl framework uses named modes to group pins for each
73 pin control device. 73 pin control device.
74 74
75 The index for pinctrl-pin-array must relate 75 The index for pinctrl-pin-array must relate to the hardware for the pinctrl
76 registers, and must not be a virtual index o 76 registers, and must not be a virtual index of pin instances. The reason for
77 this is to avoid mapping of the index in the 77 this is to avoid mapping of the index in the dts files and the pin controller
78 driver as it can change. 78 driver as it can change.
79 79
80 For hardware where pin multiplexing configur 80 For hardware where pin multiplexing configurations have to be specified for
81 each single pin the number of required sub-n 81 each single pin the number of required sub-nodes containing "pin" and
82 "function" properties can quickly escalate a 82 "function" properties can quickly escalate and become hard to write and
83 maintain. 83 maintain.
84 84
85 For cases like this, the pin controller driv 85 For cases like this, the pin controller driver may use the pinmux helper
86 property, where the pin identifier is provid 86 property, where the pin identifier is provided with mux configuration settings
87 in a pinmux group. A pinmux group consists o 87 in a pinmux group. A pinmux group consists of the pin identifier and mux
88 settings represented as a single integer or 88 settings represented as a single integer or an array of integers.
89 89
90 The pinmux property accepts an array of pinm 90 The pinmux property accepts an array of pinmux groups, each of them describing
91 a single pin multiplexing configuration. 91 a single pin multiplexing configuration.
92 92
93 pincontroller { 93 pincontroller {
94 state_0_node_a { 94 state_0_node_a {
95 pinmux = <PINMUX_GROUP>, <PINMUX_GROUP>, 95 pinmux = <PINMUX_GROUP>, <PINMUX_GROUP>, ...;
96 }; 96 };
97 }; 97 };
98 98
99 Each individual pin controller driver bindin 99 Each individual pin controller driver bindings documentation shall specify
100 how pin IDs and pin multiplexing configurati 100 how pin IDs and pin multiplexing configuration are defined and assembled
101 together in a pinmux group. 101 together in a pinmux group.
102 102
103 properties: 103 properties:
104 function: 104 function:
105 $ref: /schemas/types.yaml#/definitions/str 105 $ref: /schemas/types.yaml#/definitions/string
106 description: The mux function to select 106 description: The mux function to select
107 107
108 pins: 108 pins:
109 oneOf: 109 oneOf:
110 - $ref: /schemas/types.yaml#/definitions 110 - $ref: /schemas/types.yaml#/definitions/uint32-array
111 - $ref: /schemas/types.yaml#/definitions 111 - $ref: /schemas/types.yaml#/definitions/string-array
112 description: 112 description:
113 The list of pin identifiers that propert 113 The list of pin identifiers that properties in the node apply to. The
114 specific binding for the hardware define 114 specific binding for the hardware defines whether the entries are integers
115 or strings, and their meaning. 115 or strings, and their meaning.
116 116
117 groups: 117 groups:
118 $ref: /schemas/types.yaml#/definitions/str 118 $ref: /schemas/types.yaml#/definitions/string-array
119 description: 119 description:
120 the group to apply the properties to, if 120 the group to apply the properties to, if the driver supports
121 configuration of whole groups rather tha 121 configuration of whole groups rather than individual pins (either
122 this, "pins" or "pinmux" has to be speci 122 this, "pins" or "pinmux" has to be specified)
123 123
124 pinmux: 124 pinmux:
125 description: 125 description:
126 The list of numeric pin ids and their mu 126 The list of numeric pin ids and their mux settings that properties in the
127 node apply to (either this, "pins" or "g 127 node apply to (either this, "pins" or "groups" have to be specified)
128 $ref: /schemas/types.yaml#/definitions/uin 128 $ref: /schemas/types.yaml#/definitions/uint32-array
129 129
130 pinctrl-pin-array: 130 pinctrl-pin-array:
131 $ref: /schemas/types.yaml#/definitions/uin 131 $ref: /schemas/types.yaml#/definitions/uint32-array
132 132
133 additionalProperties: true 133 additionalProperties: true
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.