1# SPDX-License-Identifier: GPL-2.0
2%YAML 1.2
3---
4$id: http://devicetree.org/schemas/mux/mux-controller.yaml#
5$schema: http://devicetree.org/meta-schemas/core.yaml#
6
7title: Common multiplexer controller provider
8
9maintainers:
10  - Peter Rosin <peda@axentia.se>
11
12description: |
13  A multiplexer (or mux) controller will have one, or several, consumer devices
14  that uses the mux controller. Thus, a mux controller can possibly control
15  several parallel multiplexers. Presumably there will be at least one
16  multiplexer needed by each consumer, but a single mux controller can of course
17  control several multiplexers for a single consumer.
18
19  A mux controller provides a number of states to its consumers, and the state
20  space is a simple zero-based enumeration. I.e. 0-1 for a 2-way multiplexer,
21  0-7 for an 8-way multiplexer, etc.
22
23
24  Mux controller nodes
25  --------------------
26
27  Mux controller nodes must specify the number of cells used for the
28  specifier using the '#mux-control-cells' or '#mux-state-cells' property.
29  The value of '#mux-state-cells' will always be one greater than the value
30  of '#mux-control-cells'.
31
32  Optionally, mux controller nodes can also specify the state the mux should
33  have when it is idle. The idle-state property is used for this. If the
34  idle-state is not present, the mux controller is typically left as is when
35  it is idle. For multiplexer chips that expose several mux controllers, the
36  idle-state property is an array with one idle state for each mux controller.
37
38  The special value (-1) may be used to indicate that the mux should be left
39  as is when it is idle. This is the default, but can still be useful for
40  mux controller chips with more than one mux controller, particularly when
41  there is a need to "step past" a mux controller and set some other idle
42  state for a mux controller with a higher index.
43
44  Some mux controllers have the ability to disconnect the input/output of the
45  multiplexer. Using this disconnected high-impedance state as the idle state
46  is indicated with idle state (-2).
47
48  These constants are available in
49
50        #include <dt-bindings/mux/mux.h>
51
52  as MUX_IDLE_AS_IS (-1) and MUX_IDLE_DISCONNECT (-2).
53
54  An example mux controller node look like this (the adg972a chip is a triple
55  4-way multiplexer):
56
57    mux: mux-controller@50 {
58      compatible = "adi,adg792a";
59      reg = <0x50>;
60      #mux-control-cells = <1>;
61
62      idle-state = <MUX_IDLE_DISCONNECT MUX_IDLE_AS_IS 2>;
63    };
64
65select:
66  anyOf:
67    - properties:
68        $nodename:
69          pattern: '^mux-controller'
70    - required:
71        - '#mux-control-cells'
72    - required:
73        - '#mux-state-cells'
74
75properties:
76  $nodename:
77    pattern: '^mux-controller(@.*|-[0-9a-f]+)?$'
78
79  '#mux-control-cells':
80    enum: [ 0, 1 ]
81
82  '#mux-state-cells':
83    enum: [ 1, 2 ]
84
85  idle-state:
86    $ref: /schemas/types.yaml#/definitions/int32
87    minimum: -2
88
89  idle-states:
90    description: |
91      Mux controller nodes can specify the state the mux should have when it is
92      idle. If the idle-state is not present, the mux controller is typically
93      left as is when it is idle. For multiplexer chips that expose several mux
94      controllers, the idle-state property is an array with one idle state for
95      each mux controller.
96
97      The special value (-1) may be used to indicate that the mux should be left
98      as is when it is idle. This is the default, but can still be useful for
99      mux controller chips with more than one mux controller, particularly when
100      there is a need to "step past" a mux controller and set some other idle
101      state for a mux controller with a higher index.
102
103      Some mux controllers have the ability to disconnect the input/output of the
104      multiplexer. Using this disconnected high-impedance state as the idle state
105      is indicated with idle state (-2).
106    $ref: /schemas/types.yaml#/definitions/int32-array
107    items:
108      minimum: -2
109
110additionalProperties: true
111
112examples:
113  - |
114    #include <dt-bindings/gpio/gpio.h>
115
116    /* One consumer of a 2-way mux controller (one GPIO-line) */
117    mux: mux-controller {
118        compatible = "gpio-mux";
119        #mux-control-cells = <0>;
120
121        mux-gpios = <&pioA 0 GPIO_ACTIVE_HIGH>;
122    };
123
124    adc-mux {
125        compatible = "io-channel-mux";
126        io-channels = <&adc 0>;
127        io-channel-names = "parent";
128
129        mux-controls = <&mux>;
130        mux-control-names = "adc";
131
132        channels = "sync", "in";
133    };
134
135  - |
136    #include <dt-bindings/gpio/gpio.h>
137
138    /*
139     * Two consumers (one for an ADC line and one for an i2c bus) of
140     * parallel 4-way multiplexers controlled by the same two GPIO-lines.
141     */
142    mux2: mux-controller {
143        compatible = "gpio-mux";
144        #mux-control-cells = <0>;
145
146        mux-gpios = <&pioA 0 GPIO_ACTIVE_HIGH>,
147              <&pioA 1 GPIO_ACTIVE_HIGH>;
148    };
149
150    adc-mux {
151        compatible = "io-channel-mux";
152        io-channels = <&adc 0>;
153        io-channel-names = "parent";
154
155        mux-controls = <&mux2>;
156
157        channels = "sync-1", "in", "out", "sync-2";
158    };
159
160    i2c-mux {
161        compatible = "i2c-mux";
162        i2c-parent = <&i2c1>;
163
164        mux-controls = <&mux2>;
165
166        #address-cells = <1>;
167        #size-cells = <0>;
168
169        i2c@0 {
170            reg = <0>;
171            #address-cells = <1>;
172            #size-cells = <0>;
173
174            ssd1307: oled@3c {
175                reg = <0x3c>;
176            };
177        };
178
179        i2c@3 {
180            reg = <3>;
181            #address-cells = <1>;
182            #size-cells = <0>;
183
184            pca9555: pca9555@20 {
185                reg = <0x20>;
186            };
187        };
188    };
189
190  - |
191    #include <dt-bindings/gpio/gpio.h>
192
193    mux1: mux-controller {
194        compatible = "gpio-mux";
195        #mux-state-cells = <1>;
196        mux-gpios = <&exp_som 2 GPIO_ACTIVE_HIGH>;
197    };
198
199    transceiver4: can-phy4 {
200        compatible = "ti,tcan1042";
201        #phy-cells = <0>;
202        max-bitrate = <5000000>;
203        standby-gpios = <&exp_som 7 GPIO_ACTIVE_HIGH>;
204        mux-states = <&mux1 1>;
205    };
206...
207