1Common multiplexer controller bindings
2======================================
3
4A multiplexer (or mux) controller will have one, or several, consumer devices
5that uses the mux controller. Thus, a mux controller can possibly control
6several parallel multiplexers. Presumably there will be at least one
7multiplexer needed by each consumer, but a single mux controller can of course
8control several multiplexers for a single consumer.
9
10A mux controller provides a number of states to its consumers, and the state
11space is a simple zero-based enumeration. I.e. 0-1 for a 2-way multiplexer,
120-7 for an 8-way multiplexer, etc.
13
14
15Consumers
16---------
17
18Mux controller consumers should specify a list of mux controllers that they
19want to use with a property containing a 'mux-ctrl-list':
20
21	mux-ctrl-list ::= <single-mux-ctrl> [mux-ctrl-list]
22	single-mux-ctrl ::= <mux-ctrl-phandle> [mux-ctrl-specifier]
23	mux-ctrl-phandle : phandle to mux controller node
24	mux-ctrl-specifier : array of #mux-control-cells specifying the
25			     given mux controller (controller specific)
26
27Mux controller properties should be named "mux-controls". The exact meaning of
28each mux controller property must be documented in the device tree binding for
29each consumer. An optional property "mux-control-names" may contain a list of
30strings to label each of the mux controllers listed in the "mux-controls"
31property.
32
33Drivers for devices that use more than a single mux controller can use the
34"mux-control-names" property to map the name of the requested mux controller
35to an index into the list given by the "mux-controls" property.
36
37mux-ctrl-specifier typically encodes the chip-relative mux controller number.
38If the mux controller chip only provides a single mux controller, the
39mux-ctrl-specifier can typically be left out.
40
41Example:
42
43	/* One consumer of a 2-way mux controller (one GPIO-line) */
44	mux: mux-controller {
45		compatible = "gpio-mux";
46		#mux-control-cells = <0>;
47
48		mux-gpios = <&pioA 0 GPIO_ACTIVE_HIGH>;
49	};
50
51	adc-mux {
52		compatible = "io-channel-mux";
53		io-channels = <&adc 0>;
54		io-channel-names = "parent";
55
56		mux-controls = <&mux>;
57		mux-control-names = "adc";
58
59		channels = "sync", "in";
60	};
61
62Note that in the example above, specifying the "mux-control-names" is redundant
63because there is only one mux controller in the list. However, if the driver
64for the consumer node in fact asks for a named mux controller, that name is of
65course still required.
66
67	/*
68	 * Two consumers (one for an ADC line and one for an i2c bus) of
69	 * parallel 4-way multiplexers controlled by the same two GPIO-lines.
70	 */
71	mux: mux-controller {
72		compatible = "gpio-mux";
73		#mux-control-cells = <0>;
74
75		mux-gpios = <&pioA 0 GPIO_ACTIVE_HIGH>,
76			    <&pioA 1 GPIO_ACTIVE_HIGH>;
77	};
78
79	adc-mux {
80		compatible = "io-channel-mux";
81		io-channels = <&adc 0>;
82		io-channel-names = "parent";
83
84		mux-controls = <&mux>;
85
86		channels = "sync-1", "in", "out", "sync-2";
87	};
88
89	i2c-mux {
90		compatible = "i2c-mux";
91		i2c-parent = <&i2c1>;
92
93		mux-controls = <&mux>;
94
95		#address-cells = <1>;
96		#size-cells = <0>;
97
98		i2c@0 {
99			reg = <0>;
100			#address-cells = <1>;
101			#size-cells = <0>;
102
103			ssd1307: oled@3c {
104				/* ... */
105			};
106		};
107
108		i2c@3 {
109			reg = <3>;
110			#address-cells = <1>;
111			#size-cells = <0>;
112
113			pca9555: pca9555@20 {
114				/* ... */
115			};
116		};
117	};
118
119
120Mux controller nodes
121--------------------
122
123Mux controller nodes must specify the number of cells used for the
124specifier using the '#mux-control-cells' property.
125
126Optionally, mux controller nodes can also specify the state the mux should
127have when it is idle. The idle-state property is used for this. If the
128idle-state is not present, the mux controller is typically left as is when
129it is idle. For multiplexer chips that expose several mux controllers, the
130idle-state property is an array with one idle state for each mux controller.
131
132The special value (-1) may be used to indicate that the mux should be left
133as is when it is idle. This is the default, but can still be useful for
134mux controller chips with more than one mux controller, particularly when
135there is a need to "step past" a mux controller and set some other idle
136state for a mux controller with a higher index.
137
138Some mux controllers have the ability to disconnect the input/output of the
139multiplexer. Using this disconnected high-impedance state as the idle state
140is indicated with idle state (-2).
141
142These constants are available in
143
144      #include <dt-bindings/mux/mux.h>
145
146as MUX_IDLE_AS_IS (-1) and MUX_IDLE_DISCONNECT (-2).
147
148An example mux controller node look like this (the adg972a chip is a triple
1494-way multiplexer):
150
151	mux: mux-controller@50 {
152		compatible = "adi,adg792a";
153		reg = <0x50>;
154		#mux-control-cells = <1>;
155
156		idle-state = <MUX_IDLE_DISCONNECT MUX_IDLE_AS_IS 2>;
157	};
158