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 bindings
   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' 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
  63 select:
  64   anyOf:
  65     - properties:
  66         $nodename:
  67           pattern: '^mux-controller'
  68     - required:
  69         - '#mux-control-cells'
  70
  71 properties:
  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
 103 additionalProperties: true
 104
 105 examples:
 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 ...