.. SPDX-License-Identifier: GPL-2.0-only

========================================================================
Audio drivers for Cirrus Logic CS35L54/56/57/63 Boosted Smart Amplifiers
========================================================================
:Copyright: 2025 Cirrus Logic, Inc. and
                 Cirrus Logic International Semiconductor Ltd.

Contact: patches@opensource.cirrus.com

Summary
=======

The high-level summary of this document is:

**If you have a laptop that uses CS35L54/56/57/63 amplifiers but audio is not
working, DO NOT ATTEMPT TO USE FIRMWARE AND SETTINGS FROM ANOTHER LAPTOP,
EVEN IF THAT LAPTOP SEEMS SIMILAR.**

The CS35L54/56/57/63 amplifiers must be correctly configured for the power
supply voltage, speaker impedance, maximum speaker voltage/current, and
other external hardware connections.

The amplifiers feature advanced boost technology that increases the voltage
used to drive the speakers, while proprietary speaker protection algorithms
allow these boosted amplifiers to push the limits of the speakers without
causing damage. These **must** be configured correctly.

Supported Cirrus Logic amplifiers
---------------------------------

The cs35l56 drivers support:

* CS35L54
* CS35L56
* CS35L57
* CS35L63

There are two drivers in the kernel

*For systems using SoundWire*: sound/soc/codecs/cs35l56.c and associated files

*For systems using HDA*: sound/pci/hda/cs35l56_hda.c

/*(DEBLOBBED)*/

Early firmware for CS35L56 Rev B0 used the ALSA prefix (ampN) as the
filename qualifier. Support for the l?u? qualifier was added in kernel 6.16.

Sound Open Firmware and ALSA topology files
-------------------------------------------

All SoundWire systems will require a Sound Open Firmware (SOF) for the
host CPU audio DSP, together with an ALSA topology file (.tplg).

The SOF firmware will usually be provided by the manufacturer of the host
CPU (i.e. Intel or AMD). The .tplg file is normally part of the SOF firmware
release.

SOF binary builds are available from: /*(DEBLOBBED)*/

The main SOF source is here: https://github.com/thesofproject

ALSA-ucm configurations
-----------------------
Typically an appropriate ALSA-ucm configuration file is needed for
use-case managers and audio servers such as PipeWire.

Configuration files are available from the alsa-ucm-conf repository:
https://git.alsa-project.org/?p=alsa-ucm-conf.git

Kernel log messages
===================

SoundWire
---------
A successful initialization will look like this (this will be repeated for
each amplifier)::

  [ 7.568374] cs35l56 sdw:0:0:01fa:3556:01:0: supply VDD_P not found, using dummy regulator
  [ 7.605208] cs35l56 sdw:0:0:01fa:3556:01:0: supply VDD_IO not found, using dummy regulator
  [ 7.605313] cs35l56 sdw:0:0:01fa:3556:01:0: supply VDD_A not found, using dummy regulator
  [ 7.939279] cs35l56 sdw:0:0:01fa:3556:01:0: Cirrus Logic CS35L56 Rev B0 OTP3 fw:3.4.4 (patched=0)
  [ 7.947844] cs35l56 sdw:0:0:01fa:3556:01:0: Slave 4 state check1: UNATTACHED, status was 1
  [ 8.740280] cs35l56 sdw:0:0:01fa:3556:01:0: supply VDD_B not found, using dummy regulator
  [ 8.740552] cs35l56 sdw:0:0:01fa:3556:01:0: supply VDD_AMP not found, using dummy regulator
  [ 9.242164] cs35l56 sdw:0:0:01fa:3556:01:0: DSP1: /*(DEBLOBBED)*/: format 3 timestamp 0x66b2b872
  [ 9.242173] cs35l56 sdw:0:0:01fa:3556:01:0: DSP1: /*(DEBLOBBED)*/: Tue 05 Dec 2023 21:37:21 GMT Standard Time
  [ 9.991709] cs35l56 sdw:0:0:01fa:3556:01:0: DSP1: Firmware: 1a00d6 vendor: 0x2 v3.11.23, 41 algorithms
  [10.039098] cs35l56 sdw:0:0:01fa:3556:01:0: DSP1: /*(DEBLOBBED)*/: v3.11.23
  [10.879235] cs35l56 sdw:0:0:01fa:3556:01:0: Slave 4 state check1: UNATTACHED, status was 1
  [11.401536] cs35l56 sdw:0:0:01fa:3556:01:0: Calibration applied

HDA
---
A successful initialization will look like this (this will be repeated for
each amplifier)::

  [ 6.306475] cs35l56-hda i2c-CSC3556:00-cs35l56-hda.0: Cirrus Logic CS35L56 Rev B0 OTP3 fw:3.4.4 (patched=0)
  [ 6.613892] cs35l56-hda i2c-CSC3556:00-cs35l56-hda.0: DSP system name: 'xxxxxxxx', amp name: 'AMP1'
  [ 8.266660] snd_hda_codec_cs8409 ehdaudio0D0: bound i2c-CSC3556:00-cs35l56-hda.0 (ops cs35l56_hda_comp_ops [snd_hda_scodec_cs35l56])
  [ 8.287525] cs35l56-hda i2c-CSC3556:00-cs35l56-hda.0: DSP1: /*(DEBLOBBED)*/: format 3 timestamp 0x66b2b872
  [ 8.287528] cs35l56-hda i2c-CSC3556:00-cs35l56-hda.0: DSP1: /*(DEBLOBBED)*/: Tue 05 Dec 2023 21:37:21 GMT Standard Time
  [ 9.984335] cs35l56-hda i2c-CSC3556:00-cs35l56-hda.0: DSP1: Firmware: 1a00d6 vendor: 0x2 v3.11.23, 41 algorithms
  [10.085797] cs35l56-hda i2c-CSC3556:00-cs35l56-hda.0: DSP1: /*(DEBLOBBED)*/: v3.11.23
  [10.655237] cs35l56-hda i2c-CSC3556:00-cs35l56-hda.0: Calibration applied

Important messages
~~~~~~~~~~~~~~~~~~
Cirrus Logic CS35L56 Rev B0 OTP3 fw:3.4.4 (patched=0)
  Shows that the driver has been able to read device ID registers from the
  amplifier.

    * The actual amplifier type and silicon revision (CS35L56 B0 in this
      example) is shown, as read from the amplifier identification registers.
    * (patched=0) is normal, and indicates that the amplifier has been hard
      reset and is running default ROM firmware.
    * (patched=1) means that something has previously downloaded firmware
      to the amplifier and the driver does not have control of the RESET
      signal to be able to replace this preloaded firmware. This is normal
      for systems where the BIOS downloads firmware to the amplifiers
      before OS boot.
      This status can also be seen if the cs35l56 kernel module is unloaded
      and reloaded on a system where the driver does not have control of
      RESET. SoundWire systems typically do not give the driver control of
      RESET and only a BIOS (re)boot can reset the amplifiers.

DSP1: /*(DEBLOBBED)*/
  Shows that a .wmfw firmware file was found and downloaded.

DSP1: /*(DEBLOBBED)*/
  Shows that a .bin firmware file was found and downloaded.

Calibration applied
  Factory calibration data in EFI was written to the amplifier.

Error messages
==============
This section explains some of the error messages that the driver can log.

Algorithm coefficient version %d.%d.%d but expected %d.%d.%d
  The version of the .bin file content does not match the loaded firmware.
  Caused by mismatched .wmfw and .bin file, or .bin file was found but
  .wmfw was not.

No %s for algorithm %x
  The version of the .bin file content does not match the loaded firmware.
  Caused by mismatched .wmfw and .bin file, or .bin file was found but
  .wmfw was not.

.bin file required but not found
  HDA driver did not find a .bin file that matches this hardware.

Calibration disabled due to missing firmware controls
  Driver was not able to write EFI calibration data to firmware registers.
  This typically means that either:

    * The driver did not find a suitable wmfw for this hardware, or
    * The amplifier has already been patched with firmware by something
      previously, and the driver does not have control of a hard RESET line
      to be able to reset the amplifier and download the firmware files it
      found. This situation is indicated by the device identification
      string in the kernel log shows "(patched=1)"

Failed to write calibration
  Same meaning and cause as "Calibration disabled due to missing firmware
  controls"

Failed to read calibration data from EFI
  Factory calibration data in EFI is missing, empty or corrupt.
  This is most likely to be cause by accidentally deleting the file from
  the EFI filesystem.

No calibration for silicon ID
  The factory calibration data in EFI does not match this hardware.
  The most likely cause is that an amplifier has been replaced on the
  motherboard without going through manufacturer calibration process to
  generate calibration data for the new amplifier.

Did not find any buses for CSCxxxx
  Only on HDA systems. The HDA codec driver found an ACPI entry for
  Cirrus Logic companion amps, but could not enumerate the ACPI entries for
  the I2C/SPI buses. The most likely cause of this is that:

    * The relevant bus driver (I2C or SPI) is not part of the kernel.
    * The HDA codec driver was built-in to the kernel but the I2C/SPI
      bus driver is a module and so the HDA codec driver cannot call the
      bus driver functions.

init_completion timed out
  The SoundWire bus controller (host end) did not enumerate the amplifier.
  In other words, the ACPI says there is an amplifier but for some reason
  it was not detected on the bus.

No AF01 node
  Indicates an error in ACPI. A SoundWire system should have a Device()
  node named "AF01" but it was not found.

Failed to get spk-id-gpios
  ACPI says that the driver should request a GPIO but the driver was not
  able to get that GPIO. The most likely cause is that the kernel does not
  include the correct GPIO or PINCTRL driver for this system.

Failed to read spk-id
  ACPI says that the driver should request a GPIO but the driver was not
  able to read that GPIO.

Unexpected spk-id element count
  AF01 contains more speaker ID GPIO entries than the driver supports

Overtemp error
  Amplifier overheat protection was triggered and the amplifier shut down
  to protect itself.

Amp short error
  Amplifier detected a short-circuit on the speaker output pins and shut
  down for protection. This would normally indicate a damaged speaker.

Hibernate wake failed
  The driver tried to wake the amplifier from its power-saving state but
  did not see the expected responses from the amplifier. This can be caused
  by using firmware that does not match the hardware.
