[PATCH 2/2] ASoC: cs35l36: Add device tree documentation for CS35L36

[PATCH 2/2] ASoC: cs35l36: Add device tree documentation for CS35L36

[James Schulman]

Add device tree documentation for Cirrus Logic CS35L36
speaker amplifier

Signed-off-by: James Schulman <james.schulman@cirrus.com>
Reviewed-by: Charles Keepax <ckeepax@opensource.cirrus.com>
Acked-by: Brian Austin <brian.austin@cirrus.com>
---
 .../devicetree/bindings/sound/cs35l36.txt          | 168 +++++++++++++++++++++
 1 file changed, 168 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/sound/cs35l36.txt

diff --git a/Documentation/devicetree/bindings/sound/cs35l36.txt b/Documentation/devicetree/bindings/sound/cs35l36.txt
new file mode 100644
index 0000000..ccfeaf6
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/cs35l36.txt
@@ -0,0 +1,168 @@
+CS35L36 Speaker Amplifier
+
+Required properties:
+
+  - compatible : "cirrus,cs35l36"
+
+  - reg : the I2C address of the device for I2C
+
+  - VA-supply, VP-supply : power supplies for the device,
+    as covered in
+    Documentation/devicetree/bindings/regulator/regulator.txt.
+
+Optional properties:
+  - cirrus,multi-amp-mode : Boolean to determine if there are more than
+  one amplifier in the system. If more than one it is best to Hi-Z the ASP
+  port to prevent bus contention on the output signal
+
+  - cirrus,boost-ctl-millivolt : Boost Voltage Value.  Configures the boost
+  converter's output voltage in mV. The range is from 2550mV to 12000mV with
+  increments of 50mV.
+  (Default) VP
+
+  - cirrus,boost-ctl-select : Boost conerter control source selection.
+  Selects the source of the BST_CTL target VBST voltage for the boost
+  converter to generate.
+  0x00 - Control Port Value
+  0x01 - Class H Tracking (Default)
+  0x10 - MultiDevice Sync Value
+
+  - cirrus,boost-peak-milliamp : Boost-converter peak current limit in mA.
+  Configures the peak current by monitoring the current through the boost FET.
+  Range starts at 1600mA and goes to a maximum of 4500mA with increments of
+  50mA.
+  (Default) 4.50 Amps
+
+  - cirrus,boost-ind-nanohenry : Inductor estimation LBST reference value.
+  Seeds the digital boost converter's inductor estimation block with the initial
+  inductance value to reference.
+
+  1000 = 1uH (Default)
+  1200 = 1.2uH
+
+  - cirrus,amp-pcm-inv : Boolean to determine Amplifier will invert incoming
+  PCM data
+
+  - cirrus,imon-pol-inv : Boolean to determine Amplifier will invert the
+  polarity of outbound IMON feedback data
+
+  - cirrus,vmon-pol-inv : Boolean to determine Amplifier will invert the
+  polarity of outbound VMON feedback data
+
+  - cirrus,dcm-mode-enable : Boost converter automatic DCM Mode enable.
+  This enables the digital boost converter to operate in a low power
+  (Discontinuous Conduction) mode during low loading conditions.
+
+  - cirrus,weak-fet-disable : Boolean : The strength of the output drivers is
+  reduced when operating in a Weak-FET Drive Mode and must not be used to drive
+  a large load.
+
+  - cirrus,classh-wk-fet-delay :  Weak-FET entry delay. Controls the delay
+  (in ms) before the Class H algorithm switches to the weak-FET voltage
+  (after the audio falls and remains below the value specified in WKFET_AMP_THLD).
+
+  0 = 0ms
+  1 = 5ms
+  2 = 10ms
+  3 = 50ms
+  4 = 100ms (Default)
+  5 = 200ms
+  6 = 500ms
+  7 = 1000ms
+
+  - cirrus,classh-weak-fet-thld-millivolt : Weak-FET amplifier drive threshold.
+  Configures the signal threshold at which the PWM output stage enters
+  weak-FET operation. The range is 50mV to 700mV in 50mV increments.
+
+  - cirrus,temp-warn-threshold :  Amplifier overtemperature warning threshold.
+  Configures the threshold at which the overtemperature warning condition occurs.
+  When the threshold is met, the overtemperature warning attenuation is applied
+  and the TEMP_WARN_EINT interrupt status bit is set.
+  If TEMP_WARN_MASK = 0, INTb is asserted.
+
+  0 = 105C
+  1 = 115C
+  2 = 125C (Default)
+  3 = 135C
+
+  - cirrus,irq-drive-select : Selects the driver type of the selected interrupt
+  output.
+
+  0 = Open-drain
+  1 = Push-pull (Default)
+
+  - cirrus,irq-gpio-select : Selects the pin to serve as the programmable
+  interrupt output.
+
+  0 = PDM_DATA / SWIRE_SD / INT (Default)
+  1 = GPIO
+
+Optional properties for the "cirrus,vpbr-config" Sub-node
+
+  - cirrus,vpbr-en : VBST brownout prevention enable. Configures whether the
+  VBST brownout prevention algorithm is enabled or disabled.
+
+  0 = VBST brownout prevention disabled (default)
+  1 = VBST brownout prevention enabled
+
+  See Section 7.31.1 VPBR Config for configuration options & further details
+
+  - cirrus,vpbr-thld : Initial VPBR threshold. Configures the VP brownout
+  threshold voltage
+
+  - cirrus,cirrus,vpbr-atk-rate : Attenuation attack step rate. Configures the
+  amount delay between consecutive volume attenuation steps when a brownout
+  condition is present and the VP brownout condition is in an attacking state.
+
+  - cirrus,vpbr-atk-vol : VP brownout prevention step size. Configures the VP
+  brownout prevention attacking attenuation step size when operating in either
+  digital volume or analog gain modes.
+
+  - cirrus,vpbr-max-attn : Maximum attenuation that the VP brownout prevention
+  can apply to the audio signal.
+
+  - cirrus,vpbr-wait : Configures the delay time between a brownout condition
+  no longer being present and the VP brownout prevention entering an attenuation
+  release state.
+
+  - cirrus,vpbr-rel-rate : Attenuation release step rate. Configures the delay
+  between consecutive volume attenuation release steps when a brownout condition
+  is not longer present and the VP brownout is in an attenuation release state.
+
+  - cirrus,vpbr-mute-en : During the attack state, if the vpbr-max-attn value
+  is reached, the error condition still remains, and this bit is set, the audio
+  is muted.
+
+Example:
+
+cs35l36: cs35l36@40 {
+	compatible = "cirrus,cs35l36";
+	reg = <0x40>;
+	VA-supply = <&dummy_vreg>;
+	VP-supply = <&dummy_vreg>;
+	reset-gpios = <&gpio0 54 0>;
+	interrupt-parent = <&gpio8>;
+	interrupts = <3 IRQ_TYPE_LEVEL_LOW>;
+
+	cirrus,boost-ind-nanohenry = <1000>;
+	cirrus,boost-ctl-millivolt = <10000>;
+	cirrus,boost-ctl-select = <0x00>;
+	cirrus,boost-peak-milliamp = <4500>;
+	cirrus,weak-fet-delay = <0x04>;
+	cirrus,weak-fet-thld = <0x01>;
+	cirrus,temp-warn-threshold = <0x01>;
+	cirrus,multi-amp-mode;
+	cirrus,irq-drive-select = <0x01>;
+	cirrus,irq-gpio-select = <0x01>;
+
+	cirrus,vpbr-config {
+		cirrus,vpbr-en = <0x00>;
+		cirrus,vpbr-thld = <0x05>;
+		cirrus,vpbr-atk-rate = <0x02>;
+		cirrus,vpbr-atk-vol = <0x01>;
+		cirrus,vpbr-max-attn = <0x09>;
+		cirrus,vpbr-wait = <0x01>;
+		cirrus,vpbr-rel-rate = <0x05>;
+		cirrus,vpbr-mute-en = <0x00>;
+	};
+};
-- 
1.9.1

Re: [PATCH 2/2] ASoC: cs35l36: Add device tree documentation for CS35L36

[Mark Brown]

[-- Attachment #1.1: Type: text/plain, Size: 440 bytes --]

On Fri, Feb 01, 2019 at 01:33:21PM -0600, James Schulman wrote:

> +  - cirrus,boost-peak-milliamp : Boost-converter peak current limit in mA.
> +  Configures the peak current by monitoring the current through the boost FET.
> +  Range starts at 1600mA and goes to a maximum of 4500mA with increments of
> +  50mA.
> +  (Default) 4.50 Amps

This is a required property according to the code, either the binding or
the code needs an update.

[-- Attachment #1.2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

[-- Attachment #2: Type: text/plain, Size: 0 bytes --]

Re: [PATCH 2/2] ASoC: cs35l36: Add device tree documentation for CS35L36

[Charles Keepax]

On Wed, Nov 14, 2018 at 09:31:11AM +0000, Charles Keepax wrote:
> On Tue, Nov 13, 2018 at 12:49:17PM -0600, James Schulman wrote:
> > Add device tree documentation for Cirrus Logic CS35L36
> > speaker amplifier
> > 
> > Signed-off-by: James Schulman <james.schulman@cirrus.com>
> > ---
> > +	cirrus,irq-config {
> > +		cirrus,irq-drive-select = <0x01>;
> > +		cirrus,irq-polarity = <0x00>;
> > +		cirrus,irq-gpio-select = <0x01>;
> > +		cirrus,irq-output-enable = <0x01>;
> > +		cirrus,irq-src-select = <0x01>;
> > +	};
> 
> This block is not documented in the rest of the document and
> looks like things that should really be controlled through other
> means. Presuming this is legacy and just needs removed?

Seems they are used by the driver so I guess best to document
them as a first step and we can review them from there.

Also looks like documentation is also missing for:

dcm-mode-enable
boost-ind-nanohenry

Thanks,
Charles

Re: [PATCH 2/2] ASoC: cs35l36: Add device tree documentation for CS35L36

[Charles Keepax]

On Tue, Nov 13, 2018 at 12:49:17PM -0600, James Schulman wrote:
> Add device tree documentation for Cirrus Logic CS35L36
> speaker amplifier
> 
> Signed-off-by: James Schulman <james.schulman@cirrus.com>
> ---
> +Optional properties:
> +  - cirrus,sclk-force-output : Audio serial port SCLK force
> +  output control. Forces the SCLK to continue to drive even
> +  if no ASP_TXn channels are enabled.
> +
> +  - cirrus,lrclk-force-output : Audio serial port LRCLK force
> +  output control. Forces the LRCLK to continue to drive even
> +  if no ASP_TXn channels are enabled.
> +

Would it be best to use SND_SOC_DAIFMT_CONT/GATED for these?
Unless I have misunderstood their purpose, although presently that
doesn't give you individual control over sclk and lrclk.

> +Example:
> +
> +cs35l36: cs35l36@40 {
> +	compatible = "cirrus,cs35l36";
> +	reg = <0x40>;
> +	VA-supply = <&dummy_vreg>;
> +	VP-supply = <&dummy_vreg>;
> +	reset-gpios = <&gpio0 54 0>;
> +	interrupt-parent = <&gpio8>;
> +	interrupts = <3 IRQ_TYPE_LEVEL_LOW>;
> +
> +	cirrus,boost-ind-nanohenry = <1000>;
> +	cirrus,boost-ctl-millivolt = <10000>;
> +	cirrus,boost-ctl-select = <0x00>;
> +	cirrus,boost-peak-milliamp = <4500>;
> +	cirrus,amp-gain-zc;
> +	cirrus,ldm-mode-select = <0x01>;
> +	cirrus,pdm-ldm-exit;
> +	cirrus,pdm-ldm-enter;
> +	cirrus,weak-fet-delay = <0x04>;
> +	cirrus,weak-fet-thld = <0x01>;
> +	cirrus,temp-warn-threshold = <0x01>;
> +	cirrus,multi-amp-mode;
> +
> +	cirrus,vpbr-config {
> +		cirrus,vpbr-en = <0x00>;
> +		cirrus,vpbr-thld = <0x05>;
> +		cirrus,vpbr-atk-rate = <0x02>;
> +		cirrus,vpbr-atk-vol = <0x01>;
> +		cirrus,vpbr-max-attn = <0x09>;
> +		cirrus,vpbr-wait = <0x01>;
> +		cirrus,vpbr-rel-rate = <0x05>;
> +		cirrus,vpbr-mute-en = <0x00>;
> +	};
> +
> +	cirrus,irq-config {
> +		cirrus,irq-drive-select = <0x01>;
> +		cirrus,irq-polarity = <0x00>;
> +		cirrus,irq-gpio-select = <0x01>;
> +		cirrus,irq-output-enable = <0x01>;
> +		cirrus,irq-src-select = <0x01>;
> +	};

This block is not documented in the rest of the document and
looks like things that should really be controlled through other
means. Presuming this is legacy and just needs removed?

Thanks,
Charles

Re: [PATCH 2/2] ASoC: cs35l36: Add device tree documentation for CS35L36

[Mark Brown]

[-- Attachment #1.1: Type: text/plain, Size: 1698 bytes --]

On Tue, Nov 13, 2018 at 12:49:17PM -0600, James Schulman wrote:

> +  - cirrus,amp-gain-zc : Boolean to determine if to use Amplifier gain-change
> +  zero-cross

Why is this a DT setting and not either enabled unconditionally or set
from userspace (many devices do the latter)?  It seems like more of a
use case dependent setting than a feature of the board.

> +  - cirrus,ldm-mode-select : Amplifier level-dependent muting enable mode selection.
> +  Configures whether the amplifier level-dependent muting is enabled for the various
> +  blocks when the selected audio source has been below the AMP_LDM_THLD for a period
> +  of time configured by AMP_LDM_DELAY. Any and all bits can be set.

Might the user not want to set these at runtime?

> +  - cirrus,pdm-ldm-exit : Boolean : Amplifier PDM mode digital volume ramp enable.
> +  When AMP_PDM_MODE = 1 controls whether the digital volume soft ramp is enabled
> +  or disabled when exiting a level-dependent muted condition. The AMP_RAMP_PDM_DN
> +  control is used to control desired ramp rate.

This also seems like a use case dependent thing.

> +  - cirrus,imon-pol-inv : Boolean to determine Amplifier will invert the
> +  polarity of outbound IMON feedback data
> +
> +  - cirrus,vmon-pol-inv : Boolean to determine Amplifier will invert the
> +  polarity of outbound VMON feedback data

Why might anyone ever want to set these?

> +  - cirrus,pdm-channel-select : PDM Channel select.
> +  0x00 (Default) : Selects Channel A data when the PDM audio input is selected.
> +  0x01 : Selects Channel B data when the PDM audio input is selected

This looks like routing control, shouldn't it be in DAPM?

[-- Attachment #1.2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

[-- Attachment #2: Type: text/plain, Size: 0 bytes --]

[PATCH 2/2] ASoC: cs35l36: Add device tree documentation for CS35L36

[James Schulman]

Add device tree documentation for Cirrus Logic CS35L36
speaker amplifier

Signed-off-by: James Schulman <james.schulman@cirrus.com>
---
 .../devicetree/bindings/sound/cs35l36.txt          | 192 +++++++++++++++++++++
 1 file changed, 192 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/sound/cs35l36.txt

diff --git a/Documentation/devicetree/bindings/sound/cs35l36.txt b/Documentation/devicetree/bindings/sound/cs35l36.txt
new file mode 100644
index 0000000..f3c2088
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/cs35l36.txt
@@ -0,0 +1,192 @@
+CS35L36 Speaker Amplifier
+
+Required properties:
+
+  - compatible : "cirrus,cs35l36"
+
+  - reg : the I2C address of the device for I2C
+
+  - VA-supply, VP-supply : power supplies for the device,
+    as covered in
+    Documentation/devicetree/bindings/regulator/regulator.txt.
+
+Optional properties:
+  - cirrus,sclk-force-output : Audio serial port SCLK force
+  output control. Forces the SCLK to continue to drive even
+  if no ASP_TXn channels are enabled.
+
+  - cirrus,lrclk-force-output : Audio serial port LRCLK force
+  output control. Forces the LRCLK to continue to drive even
+  if no ASP_TXn channels are enabled.
+
+  - cirrus,multi-amp-mode : Boolean to determine if there are more than
+  one amplifier in the system. If more than one it is best to Hi-Z the ASP
+  port to prevent bus contention on the output signal
+
+  - cirrus,boost-ctl-millivolt : Boost Voltage Value.  Configures the boost
+  converter's output voltage in mV. The range is from 2550mV to 12000mV with
+  increments of 50mV.
+  (Default) VP
+
+  - cirrus,boost-ctl-select : Boost conerter control source selection.
+  Selects the source of the BST_CTL target VBST voltage for the boost
+  converter to generate.
+  0x00 - Control Port Value
+  0x01 - Class H Tracking (Default)
+  0x10 - MultiDevice Sync Value
+
+  - cirrus,boost-peak-milliamp : Boost-converter peak current limit in mA.
+  Configures the peak current by monitoring the current through the boost FET.
+  Range starts at 1600mA and goes to a maximum of 4500mA with increments of
+  50mA.
+  (Default) 4.50 Amps
+
+  - cirrus,amp-gain-zc : Boolean to determine if to use Amplifier gain-change
+  zero-cross
+
+  - cirrus,amp-pcm-inv : Boolean to determine Amplifier will invert incoming
+  PCM data
+
+  - cirrus,ldm-mode-select : Amplifier level-dependent muting enable mode selection.
+  Configures whether the amplifier level-dependent muting is enabled for the various
+  blocks when the selected audio source has been below the AMP_LDM_THLD for a period
+  of time configured by AMP_LDM_DELAY. Any and all bits can be set.
+
+  00000 - All level-dependent muting functionality disabled (Default)
+  xxxx1 - Amplifier level-dependent muting detection enabled (OUT+/-; switching)
+  xxx1x - Boost converter DCM detection enabled
+  xx1xx - VMON low power mode detection enabled
+  x1xxx - IMON low power mode detection enabled
+  1xxxx - VP brownout prevention detection enabled
+
+  - cirrus,pdm-ldm-exit : Boolean : Amplifier PDM mode digital volume ramp enable.
+  When AMP_PDM_MODE = 1 controls whether the digital volume soft ramp is enabled
+  or disabled when exiting a level-dependent muted condition. The AMP_RAMP_PDM_DN
+  control is used to control desired ramp rate.
+
+  - cirrus,pdm-ldm-enter : Boolean: Amplifier PDM mode digital volume ramp enable.
+  When AMP_PDM_MODE = 1 controls whether the digital volume soft ramp is enabled
+  or disabled when entering a level-dependent muted condition. The AMP_RAMP_PDM_UP
+  control is used to control desired ramp rate.
+
+  - cirrus,imon-pol-inv : Boolean to determine Amplifier will invert the
+  polarity of outbound IMON feedback data
+
+  - cirrus,vmon-pol-inv : Boolean to determine Amplifier will invert the
+  polarity of outbound VMON feedback data
+
+  - cirrus,pdm-channel-select : PDM Channel select.
+  0x00 (Default) : Selects Channel A data when the PDM audio input is selected.
+  0x01 : Selects Channel B data when the PDM audio input is selected
+
+  - cirrus,weak-fet-disable : Boolean : The strength of the output drivers is
+  reduced when operating in a Weak-FET Drive Mode and must not be used to drive
+  a large load.
+
+  - cirrus,classh-wk-fet-delay :  Weak-FET entry delay. Controls the delay
+  (in ms) before the Class H algorithm switches to the weak-FET voltage
+  (after the audio falls and remains below the value specified in WKFET_AMP_THLD).
+
+  0 = 0ms
+  1 = 5ms
+  2 = 10ms
+  3 = 50ms
+  4 = 100ms (Default)
+  5 = 200ms
+  6 = 500ms
+  7 = 1000ms
+
+  - cirrus,classh-weak-fet-thld-millivolt : Weak-FET amplifier drive threshold.
+  Configures the signal threshold at which the PWM output stage enters
+  weak-FET operation. The range is 50mV to 700mV in 50mV increments.
+
+  - cirrus,temp-warn-threshold :  Amplifier overtemperature warning threshold.
+  Configures the threshold at which the overtemperature warning condition occurs.
+  When the threshold is met, the overtemperature warning attenuation is applied
+  and the TEMP_WARN_EINT interrupt status bit is set.
+  If TEMP_WARN_MASK = 0, INTb is asserted.
+
+  0 = 105C
+  1 = 115C
+  2 = 125C (Default)
+  3 = 135C
+
+Optional properties for the "cirrus,vpbr-config" Sub-node
+
+  - cirrus,vpbr-en : VBST brownout prevention enable. Configures whether the
+  VBST brownout prevention algorithm is enabled or disabled.
+
+  0 = VBST brownout prevention disabled (default)
+  1 = VBST brownout prevention enabled
+
+  See Section 7.31.1 VPBR Config for configuration options & further details
+
+  - cirrus,vpbr-thld : Initial VPBR threshold. Configures the VP brownout
+  threshold voltage
+
+  - cirrus,cirrus,vpbr-atk-rate : Attenuation attack step rate. Configures the
+  amount delay between consecutive volume attenuation steps when a brownout
+  condition is present and the VP brownout condition is in an attacking state.
+
+  - cirrus,vpbr-atk-vol : VP brownout prevention step size. Configures the VP
+  brownout prevention attacking attenuation step size when operating in either
+  digital volume or analog gain modes.
+
+  - cirrus,vpbr-max-attn : Maximum attenuation that the VP brownout prevention
+  can apply to the audio signal.
+
+  - cirrus,vpbr-wait : Configures the delay time between a brownout condition
+  no longer being present and the VP brownout prevention entering an attenuation
+  release state.
+
+  - cirrus,vpbr-rel-rate : Attenuation release step rate. Configures the delay
+  between consecutive volume attenuation release steps when a brownout condition
+  is not longer present and the VP brownout is in an attenuation release state.
+
+  - cirrus,vpbr-mute-en : During the attack state, if the vpbr-max-attn value
+  is reached, the error condition still remains, and this bit is set, the audio
+  is muted.
+
+Example:
+
+cs35l36: cs35l36@40 {
+	compatible = "cirrus,cs35l36";
+	reg = <0x40>;
+	VA-supply = <&dummy_vreg>;
+	VP-supply = <&dummy_vreg>;
+	reset-gpios = <&gpio0 54 0>;
+	interrupt-parent = <&gpio8>;
+	interrupts = <3 IRQ_TYPE_LEVEL_LOW>;
+
+	cirrus,boost-ind-nanohenry = <1000>;
+	cirrus,boost-ctl-millivolt = <10000>;
+	cirrus,boost-ctl-select = <0x00>;
+	cirrus,boost-peak-milliamp = <4500>;
+	cirrus,amp-gain-zc;
+	cirrus,ldm-mode-select = <0x01>;
+	cirrus,pdm-ldm-exit;
+	cirrus,pdm-ldm-enter;
+	cirrus,weak-fet-delay = <0x04>;
+	cirrus,weak-fet-thld = <0x01>;
+	cirrus,temp-warn-threshold = <0x01>;
+	cirrus,multi-amp-mode;
+
+	cirrus,vpbr-config {
+		cirrus,vpbr-en = <0x00>;
+		cirrus,vpbr-thld = <0x05>;
+		cirrus,vpbr-atk-rate = <0x02>;
+		cirrus,vpbr-atk-vol = <0x01>;
+		cirrus,vpbr-max-attn = <0x09>;
+		cirrus,vpbr-wait = <0x01>;
+		cirrus,vpbr-rel-rate = <0x05>;
+		cirrus,vpbr-mute-en = <0x00>;
+	};
+
+	cirrus,irq-config {
+		cirrus,irq-drive-select = <0x01>;
+		cirrus,irq-polarity = <0x00>;
+		cirrus,irq-gpio-select = <0x01>;
+		cirrus,irq-output-enable = <0x01>;
+		cirrus,irq-src-select = <0x01>;
+	};
+};
-- 
1.9.1