--- /dev/null
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/gpio-audio-amp.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Audio amplifier driven by GPIOs
+
+maintainers:
+ - Herve Codina <herve.codina@bootlin.com>
+
+description: |
+ Audio GPIO amplifiers are driven by GPIO in order to control the gain value
+ of the amplifier, its mute function and/or its bypass function.
+
+ Those amplifiers are based on discrete components (analog switches, op-amps
+ and more) where some of them, mostly analog switches, are controlled by GPIOs
+ to adjust the gain value of the whole amplifier and/or to control
+ the mute and/or bypass function.
+
+ For instance, the following piece of hardware is a GPIO amplifier
+
+ +5VA
+ ^
+ |\ |
+ | \
+ Vin >---------------------------|+ \
+ | +-------+-----> Vout
+ .--\/\/\/--+------------|- / |
+ | | | / |
+ v | |/ | |
+ GND o v |
+ \ GND |
+ gpio >-----------> \ |
+ o o |
+ | | |
+ | '--\/\/\/--. |
+ | +--\/\/\/--'
+ '---------------'
+
+properties:
+ compatible:
+ oneOf:
+ - const: gpio-audio-amp-mono
+ description:
+ A single channel amplifier. All features apply to this sole channel.
+
+ - const: gpio-audio-amp-stereo
+ description:
+ A dual channel amplifier (left and right). All features apply to both
+ channels producing the same effect on both channels at the same time.
+
+ vdd-supply:
+ description: Main power supply of the amplifier
+
+ vddio-supply:
+ description: Power supply related to the control path
+
+ vdda1-supply:
+ description: Analog power supply
+
+ vdda2-supply:
+ description: Additional analog power supply
+
+ mute-gpios:
+ description: GPIO to control the mute function
+ maxItems: 1
+
+ bypass-gpios:
+ description: GPIO to control the bypass function
+ maxItems: 1
+
+ gain-gpios:
+ description: |
+ GPIOs to control the amplifier gain
+
+ The gain value is computed from GPIOs value from 0 to 2^N-1 with N the
+ number of GPIO described. The first GPIO described is the lsb of the gain
+ value.
+
+ For instance assuming 2 gpios
+ gain-gpios = <&gpio1 GPIO_ACTIVE_HIGH> <&gpio2 GPIO_ACTIVE_HIGH>;
+ The gain value will be the following:
+
+ gpio1 | gpio2 | gain
+ ------+-------+-----
+ 0 | 0 | 0b00 -> 0
+ 1 | 0 | 0b01 -> 1
+ 0 | 1 | 0b10 -> 2
+ 1 | 1 | 0b11 -> 3
+ ------+-------+-----
+
+ Note: The gain value, bits set to 1 or 0, indicate the state active (bit
+ set) or the state inactive (bit unset) of the related GPIO. The
+ physical voltage corresponding to this active/inactive state is
+ given by the GPIO_ACTIVE_HIGH and GPIO_ACTIVE_LOW flags.
+
+ minItems: 1
+ maxItems: 16
+
+ gain-ranges:
+ $ref: /schemas/types.yaml#/definitions/int32-matrix
+ description: |
+ A list of one or more ranges of possible values. Each range is defined by
+ the first and last point in the range. Each point is defined by the pair
+ (GPIOs value, Gain in 0.01 dB unit).
+
+ Ranges can be contiguous or holes can be present between ranges if some
+ gpios value should not be used. Also in a range the first point and the
+ last point can be identical. In that case, the range contains only one
+ item, the given point.
+
+ items:
+ items:
+ - description: GPIOs value of the first point in the range
+ - description: Gain in 0.01 dB unit of the first point in the range
+ - description: GPIOs value of the last point in the range
+ - description: Gain in 0.01 dB unit of the last point in the range
+ description: |
+ A range defines a linear function (linear in dB) from the first point
+ to the last point, both included. The number of items in the range is
+ N = abs(first_point.gpio_value - last_point.gpio_value) + 1
+
+ It allows to define the gain range from the first_point.gain to
+ the last_point.gain, both points included.
+
+ Gain (0.01 dB unit)
+ ^
+ | last
+ +- - - - - - - - - - + point
+ | + .
+ | + .
+ | + .
+ +- - - - + .
+ | first . .
+ | point . .
+ | . .
+ +--------+-----------+---> gpios
+ value
+
+ Note: Even if first_point.gpio_value is lower than last_point.gpio_value
+ and first_point.gain is lower than last_point.gain in the above
+ graphic, all combination of values are supported leading to an
+ increasing or a decreasing linear segment.
+
+ minItems: 1
+ maxItems: 65536
+
+ gain-labels:
+ $ref: /schemas/types.yaml#/definitions/string-array
+ minItems: 2
+ maxItems: 65536
+ description: |
+ List of the gain labels attached to the combination of GPIOs controlling
+ the gain. The first label is related to the gain value 0, the second label
+ is related to the gain value 1 and so on.
+
+ With 2 GPIOs controlling the gain, GPIOs value can be 0, 1, 2 and 3.
+ Assuming that gain value set the hardware according to the following
+ table:
+
+ GPIOs | Hardware
+ value | amplification
+ ------+--------------
+ 0 | Low
+ 1 | Middle
+ 2 | High
+ 3 | Max
+ ------+--------------
+
+ The description using gain labels can be:
+ gain-labels = "Low", "Middle", "High", "Max";
+
+dependencies:
+ gain-ranges: [ gain-gpios ]
+ gain-labels: [ gain-gpios ]
+
+required:
+ - compatible
+ - vdd-supply
+
+anyOf:
+ - required:
+ - gain-gpios
+ - required:
+ - mute-gpios
+ - required:
+ - bypass-gpios
+
+allOf:
+ - $ref: component-common.yaml#
+ - if:
+ required:
+ - gain-ranges
+ then:
+ properties:
+ gain-labels: false
+ - if:
+ required:
+ - gain-labels
+ then:
+ properties:
+ gain-ranges: false
+
+unevaluatedProperties: false
+
+examples:
+ - |
+ #include <dt-bindings/gpio/gpio.h>
+
+ /* Gain controlled by gpios */
+ amplifier-0 {
+ compatible = "gpio-audio-amp-mono";
+ vdd-supply = <®ulator>;
+ gain-gpios = <&gpio 0 GPIO_ACTIVE_HIGH>, <&gpio 1 GPIO_ACTIVE_HIGH>;
+ };
+
+ /* Gain controlled by gpio using a simple range on a stereo amplifier */
+ amplifier-1 {
+ compatible = "gpio-audio-amp-stereo";
+ vdd-supply = <®ulator>;
+ gain-gpios = <&gpio 0 GPIO_ACTIVE_HIGH>, <&gpio 1 GPIO_ACTIVE_HIGH>;
+ gain-ranges = <0 (-300) 3 600>;
+ };
+
+ /* Gain controlled by gpio with labels */
+ amplifier-3 {
+ compatible = "gpio-audio-amp-mono";
+ vdd-supply = <®ulator>;
+ gain-gpios = <&gpio 0 GPIO_ACTIVE_HIGH>;
+ gain-labels = "Low", "High";
+ };
+
+ /* A mutable stereo amplifier without any gain control */
+ amplifier-4 {
+ compatible = "gpio-audio-amp-stereo";
+ vdd-supply = <®ulator>;
+ mute-gpios = <&gpio 0 GPIO_ACTIVE_HIGH>;
+ };
+
+ /*
+ * Several supplies, gain controlled using more complex ranges, mute and
+ * bypass.
+ *
+ * Assuming 3 gpios for controlling the gain with the following table
+ * gpios value Gain
+ * 0b000 Do not use (gpios value not allowed)
+ * 0b001 - 3dB
+ * 0b010 + 3dB
+ * 0b011 + 10dB
+ * 0b100 Do not use (gpios value not allowed)
+ * 0b101 + 6dB
+ * 0b110 + 7dB
+ * 0b111 + 8dB
+ */
+ amplifier-5 {
+ compatible = "gpio-audio-amp-mono";
+ vdd-supply = <®ulator>;
+ vddio-supply = <®ulator1>;
+ vdda1-supply = <®ulator2>;
+ gain-gpios = <&gpio 0 GPIO_ACTIVE_HIGH>,
+ <&gpio 1 GPIO_ACTIVE_HIGH>,
+ <&gpio 2 GPIO_ACTIVE_HIGH>;
+ gain-ranges = <1 (-300) 2 300>,
+ <3 1000 3 1000>,
+ <5 600 7 800>;
+ mute-gpios = <&gpio 3 GPIO_ACTIVE_HIGH>;
+ bypass-gpios = <&gpio 4 GPIO_ACTIVE_HIGH>;
+ };
+...
projects / thirdparty / kernel / linux.git / commitdiff
