Documentation/devicetree/bindings/mux/mux-controller.yaml

   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
   7 title: Common multiplexer controller provider
   8
   9 maintainers:
  10   - Peter Rosin <peda@axentia.se>
  11
  12 description: |
  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
  65 select:
  66   anyOf:
  67     - properties:
  68         $nodename:
  69           pattern: '^mux-controller'
  70     - required:
  71         - '#mux-control-cells'
  72     - required:
  73         - '#mux-state-cells'
  74
  75 properties:
  76   $nodename:
  77     pattern: '^mux-controller(@.*|-([0-9]|[1-9][0-9]+))?$'
  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
 110 additionalProperties: true
 111
 112 examples:
 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 ...