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 bindings
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' property.
29
30  Optionally, mux controller nodes can also specify the state the mux should
31  have when it is idle. The idle-state property is used for this. If the
32  idle-state is not present, the mux controller is typically left as is when
33  it is idle. For multiplexer chips that expose several mux controllers, the
34  idle-state property is an array with one idle state for each mux controller.
35
36  The special value (-1) may be used to indicate that the mux should be left
37  as is when it is idle. This is the default, but can still be useful for
38  mux controller chips with more than one mux controller, particularly when
39  there is a need to "step past" a mux controller and set some other idle
40  state for a mux controller with a higher index.
41
42  Some mux controllers have the ability to disconnect the input/output of the
43  multiplexer. Using this disconnected high-impedance state as the idle state
44  is indicated with idle state (-2).
45
46  These constants are available in
47
48        #include <dt-bindings/mux/mux.h>
49
50  as MUX_IDLE_AS_IS (-1) and MUX_IDLE_DISCONNECT (-2).
51
52  An example mux controller node look like this (the adg972a chip is a triple
53  4-way multiplexer):
54
55    mux: mux-controller@50 {
56      compatible = "adi,adg792a";
57      reg = <0x50>;
58      #mux-control-cells = <1>;
59
60      idle-state = <MUX_IDLE_DISCONNECT MUX_IDLE_AS_IS 2>;
61    };
62
63select:
64  anyOf:
65    - properties:
66        $nodename:
67          pattern: '^mux-controller'
68    - required:
69        - '#mux-control-cells'
70
71properties:
72  $nodename:
73    pattern: '^mux-controller(@.*|-[0-9a-f]+)?$'
74
75  '#mux-control-cells':
76    enum: [ 0, 1 ]
77
78  idle-state:
79    $ref: /schemas/types.yaml#/definitions/int32
80    minimum: -2
81
82  idle-states:
83    description: |
84      Mux controller nodes can specify the state the mux should have when it is
85      idle. If the idle-state is not present, the mux controller is typically
86      left as is when it is idle. For multiplexer chips that expose several mux
87      controllers, the idle-state property is an array with one idle state for
88      each mux controller.
89
90      The special value (-1) may be used to indicate that the mux should be left
91      as is when it is idle. This is the default, but can still be useful for
92      mux controller chips with more than one mux controller, particularly when
93      there is a need to "step past" a mux controller and set some other idle
94      state for a mux controller with a higher index.
95
96      Some mux controllers have the ability to disconnect the input/output of the
97      multiplexer. Using this disconnected high-impedance state as the idle state
98      is indicated with idle state (-2).
99    $ref: /schemas/types.yaml#/definitions/int32-array
100    items:
101      minimum: -2
102
103additionalProperties: true
104
105examples:
106  - |
107    #include <dt-bindings/gpio/gpio.h>
108
109    /* One consumer of a 2-way mux controller (one GPIO-line) */
110    mux: mux-controller {
111        compatible = "gpio-mux";
112        #mux-control-cells = <0>;
113
114        mux-gpios = <&pioA 0 GPIO_ACTIVE_HIGH>;
115    };
116
117    adc-mux {
118        compatible = "io-channel-mux";
119        io-channels = <&adc 0>;
120        io-channel-names = "parent";
121
122        mux-controls = <&mux>;
123        mux-control-names = "adc";
124
125        channels = "sync", "in";
126    };
127
128  - |
129    #include <dt-bindings/gpio/gpio.h>
130
131    /*
132     * Two consumers (one for an ADC line and one for an i2c bus) of
133     * parallel 4-way multiplexers controlled by the same two GPIO-lines.
134     */
135    mux2: mux-controller {
136        compatible = "gpio-mux";
137        #mux-control-cells = <0>;
138
139        mux-gpios = <&pioA 0 GPIO_ACTIVE_HIGH>,
140              <&pioA 1 GPIO_ACTIVE_HIGH>;
141    };
142
143    adc-mux {
144        compatible = "io-channel-mux";
145        io-channels = <&adc 0>;
146        io-channel-names = "parent";
147
148        mux-controls = <&mux2>;
149
150        channels = "sync-1", "in", "out", "sync-2";
151    };
152
153    i2c-mux {
154        compatible = "i2c-mux";
155        i2c-parent = <&i2c1>;
156
157        mux-controls = <&mux2>;
158
159        #address-cells = <1>;
160        #size-cells = <0>;
161
162        i2c@0 {
163            reg = <0>;
164            #address-cells = <1>;
165            #size-cells = <0>;
166
167            ssd1307: oled@3c {
168                reg = <0x3c>;
169            };
170        };
171
172        i2c@3 {
173            reg = <3>;
174            #address-cells = <1>;
175            #size-cells = <0>;
176
177            pca9555: pca9555@20 {
178                reg = <0x20>;
179            };
180        };
181    };
182...
183