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