1# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) 2%YAML 1.2 3--- 4$id: http://devicetree.org/schemas/sound/gpio-audio-amp.yaml# 5$schema: http://devicetree.org/meta-schemas/core.yaml# 6 7title: Audio amplifier driven by GPIOs 8 9maintainers: 10 - Herve Codina <herve.codina@bootlin.com> 11 12description: | 13 Audio GPIO amplifiers are driven by GPIO in order to control the gain value 14 of the amplifier, its mute function and/or its bypass function. 15 16 Those amplifiers are based on discrete components (analog switches, op-amps 17 and more) where some of them, mostly analog switches, are controlled by GPIOs 18 to adjust the gain value of the whole amplifier and/or to control 19 the mute and/or bypass function. 20 21 For instance, the following piece of hardware is a GPIO amplifier 22 23 +5VA 24 ^ 25 |\ | 26 | \ 27 Vin >---------------------------|+ \ 28 | +-------+-----> Vout 29 .--\/\/\/--+------------|- / | 30 | | | / | 31 v | |/ | | 32 GND o v | 33 \ GND | 34 gpio >-----------> \ | 35 o o | 36 | | | 37 | '--\/\/\/--. | 38 | +--\/\/\/--' 39 '---------------' 40 41properties: 42 compatible: 43 oneOf: 44 - const: gpio-audio-amp-mono 45 description: 46 A single channel amplifier. All features apply to this sole channel. 47 48 - const: gpio-audio-amp-stereo 49 description: 50 A dual channel amplifier (left and right). All features apply to both 51 channels producing the same effect on both channels at the same time. 52 53 vdd-supply: 54 description: Main power supply of the amplifier 55 56 vddio-supply: 57 description: Power supply related to the control path 58 59 vdda1-supply: 60 description: Analog power supply 61 62 vdda2-supply: 63 description: Additional analog power supply 64 65 mute-gpios: 66 description: GPIO to control the mute function 67 maxItems: 1 68 69 bypass-gpios: 70 description: GPIO to control the bypass function 71 maxItems: 1 72 73 gain-gpios: 74 description: | 75 GPIOs to control the amplifier gain 76 77 The gain value is computed from GPIOs value from 0 to 2^N-1 with N the 78 number of GPIO described. The first GPIO described is the lsb of the gain 79 value. 80 81 For instance assuming 2 gpios 82 gain-gpios = <&gpio1 GPIO_ACTIVE_HIGH> <&gpio2 GPIO_ACTIVE_HIGH>; 83 The gain value will be the following: 84 85 gpio1 | gpio2 | gain 86 ------+-------+----- 87 0 | 0 | 0b00 -> 0 88 1 | 0 | 0b01 -> 1 89 0 | 1 | 0b10 -> 2 90 1 | 1 | 0b11 -> 3 91 ------+-------+----- 92 93 Note: The gain value, bits set to 1 or 0, indicate the state active (bit 94 set) or the state inactive (bit unset) of the related GPIO. The 95 physical voltage corresponding to this active/inactive state is 96 given by the GPIO_ACTIVE_HIGH and GPIO_ACTIVE_LOW flags. 97 98 minItems: 1 99 maxItems: 16 100 101 gain-ranges: 102 $ref: /schemas/types.yaml#/definitions/int32-matrix 103 description: | 104 A list of one or more ranges of possible values. Each range is defined by 105 the first and last point in the range. Each point is defined by the pair 106 (GPIOs value, Gain in 0.01 dB unit). 107 108 Ranges can be contiguous or holes can be present between ranges if some 109 gpios value should not be used. Also in a range the first point and the 110 last point can be identical. In that case, the range contains only one 111 item, the given point. 112 113 items: 114 items: 115 - description: GPIOs value of the first point in the range 116 - description: Gain in 0.01 dB unit of the first point in the range 117 - description: GPIOs value of the last point in the range 118 - description: Gain in 0.01 dB unit of the last point in the range 119 description: | 120 A range defines a linear function (linear in dB) from the first point 121 to the last point, both included. The number of items in the range is 122 N = abs(first_point.gpio_value - last_point.gpio_value) + 1 123 124 It allows to define the gain range from the first_point.gain to 125 the last_point.gain, both points included. 126 127 Gain (0.01 dB unit) 128 ^ 129 | last 130 +- - - - - - - - - - + point 131 | + . 132 | + . 133 | + . 134 +- - - - + . 135 | first . . 136 | point . . 137 | . . 138 +--------+-----------+---> gpios 139 value 140 141 Note: Even if first_point.gpio_value is lower than last_point.gpio_value 142 and first_point.gain is lower than last_point.gain in the above 143 graphic, all combination of values are supported leading to an 144 increasing or a decreasing linear segment. 145 146 minItems: 1 147 maxItems: 65536 148 149 gain-labels: 150 $ref: /schemas/types.yaml#/definitions/string-array 151 minItems: 2 152 maxItems: 65536 153 description: | 154 List of the gain labels attached to the combination of GPIOs controlling 155 the gain. The first label is related to the gain value 0, the second label 156 is related to the gain value 1 and so on. 157 158 With 2 GPIOs controlling the gain, GPIOs value can be 0, 1, 2 and 3. 159 Assuming that gain value set the hardware according to the following 160 table: 161 162 GPIOs | Hardware 163 value | amplification 164 ------+-------------- 165 0 | Low 166 1 | Middle 167 2 | High 168 3 | Max 169 ------+-------------- 170 171 The description using gain labels can be: 172 gain-labels = "Low", "Middle", "High", "Max"; 173 174dependencies: 175 gain-ranges: [ gain-gpios ] 176 gain-labels: [ gain-gpios ] 177 178required: 179 - compatible 180 - vdd-supply 181 182anyOf: 183 - required: 184 - gain-gpios 185 - required: 186 - mute-gpios 187 - required: 188 - bypass-gpios 189 190allOf: 191 - $ref: component-common.yaml# 192 - if: 193 required: 194 - gain-ranges 195 then: 196 properties: 197 gain-labels: false 198 - if: 199 required: 200 - gain-labels 201 then: 202 properties: 203 gain-ranges: false 204 205unevaluatedProperties: false 206 207examples: 208 - | 209 #include <dt-bindings/gpio/gpio.h> 210 211 /* Gain controlled by gpios */ 212 amplifier-0 { 213 compatible = "gpio-audio-amp-mono"; 214 vdd-supply = <®ulator>; 215 gain-gpios = <&gpio 0 GPIO_ACTIVE_HIGH>, <&gpio 1 GPIO_ACTIVE_HIGH>; 216 }; 217 218 /* Gain controlled by gpio using a simple range on a stereo amplifier */ 219 amplifier-1 { 220 compatible = "gpio-audio-amp-stereo"; 221 vdd-supply = <®ulator>; 222 gain-gpios = <&gpio 0 GPIO_ACTIVE_HIGH>, <&gpio 1 GPIO_ACTIVE_HIGH>; 223 gain-ranges = <0 (-300) 3 600>; 224 }; 225 226 /* Gain controlled by gpio with labels */ 227 amplifier-3 { 228 compatible = "gpio-audio-amp-mono"; 229 vdd-supply = <®ulator>; 230 gain-gpios = <&gpio 0 GPIO_ACTIVE_HIGH>; 231 gain-labels = "Low", "High"; 232 }; 233 234 /* A mutable stereo amplifier without any gain control */ 235 amplifier-4 { 236 compatible = "gpio-audio-amp-stereo"; 237 vdd-supply = <®ulator>; 238 mute-gpios = <&gpio 0 GPIO_ACTIVE_HIGH>; 239 }; 240 241 /* 242 * Several supplies, gain controlled using more complex ranges, mute and 243 * bypass. 244 * 245 * Assuming 3 gpios for controlling the gain with the following table 246 * gpios value Gain 247 * 0b000 Do not use (gpios value not allowed) 248 * 0b001 - 3dB 249 * 0b010 + 3dB 250 * 0b011 + 10dB 251 * 0b100 Do not use (gpios value not allowed) 252 * 0b101 + 6dB 253 * 0b110 + 7dB 254 * 0b111 + 8dB 255 */ 256 amplifier-5 { 257 compatible = "gpio-audio-amp-mono"; 258 vdd-supply = <®ulator>; 259 vddio-supply = <®ulator1>; 260 vdda1-supply = <®ulator2>; 261 gain-gpios = <&gpio 0 GPIO_ACTIVE_HIGH>, 262 <&gpio 1 GPIO_ACTIVE_HIGH>, 263 <&gpio 2 GPIO_ACTIVE_HIGH>; 264 gain-ranges = <1 (-300) 2 300>, 265 <3 1000 3 1000>, 266 <5 600 7 800>; 267 mute-gpios = <&gpio 3 GPIO_ACTIVE_HIGH>; 268 bypass-gpios = <&gpio 4 GPIO_ACTIVE_HIGH>; 269 }; 270... 271