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