| .. 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 |
| |
| Firmware |
| ======== |
| |
| The amplifier is controlled and managed by firmware running on the internal |
| DSP. Firmware files are essential to enable the full capabilities of the |
| amplifier. |
| |
| Firmware is distributed in the linux-firmware repository: |
| https://gitlab.com/kernel-firmware/linux-firmware.git |
| |
| On most SoundWire systems the amplifier has a default minimum capability to |
| produce audio. However this will be |
| |
| * at low volume, to protect the speakers, since the speaker specifications |
| and power supply voltages are unknown. |
| * a mono mix of left and right channels. |
| |
| On some SoundWire systems that have both CS42L43 and CS35L56/57 the CS35L56/57 |
| receive their audio from the CS42L43 instead of directly from the host |
| SoundWire interface. These systems can be identified by the CS42L43 showing |
| in dmesg as a SoundWire device, but the CS35L56/57 as SPI. On these systems |
| the firmware is *mandatory* to enable receiving the audio from the CS42L43. |
| |
| On HDA systems the firmware is *mandatory* to enable HDA bridge mode. There |
| will not be any audio from the amplifiers without firmware. |
| |
| Cirrus Logic firmware files |
| --------------------------- |
| |
| Each amplifier requires two firmware files. One file has a .wmfw suffix, the |
| other has a .bin suffix. |
| |
| The firmware is customized by the OEM to match the hardware of each laptop, |
| and the firmware is specific to that laptop. Because of this, there are many |
| firmware files in linux-firmware for these amplifiers. Firmware files are |
| **not interchangeable between laptops**. |
| |
| Cirrus Logic submits files for known laptops to the upstream linux-firmware |
| repository. Providing Cirrus Logic is aware of a particular laptop and has |
| permission from the manufacturer to publish the firmware, it will be pushed |
| to linux-firmware. You may need to upgrade to a newer release of |
| linux-firmware to obtain the firmware for your laptop. |
| |
| **Important:** the Makefile for linux-firmware creates symlinks that are listed |
| in the WHENCE file. These symlinks are required for the CS35L56 driver to be |
| able to load the firmware. |
| |
| How do I know which firmware file I should have? |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| All firmware file names are qualified with a unique "system ID". On normal |
| x86 PCs with PCI audio this is the Vendor Subsystem ID (SSID) of the host |
| PCI audio interface. |
| |
| The SSID can be viewed using the lspci tool:: |
| |
| lspci -v -nn | grep -A2 -i audio |
| 0000:00:1f.3 Audio device [0403]: Intel Corporation Meteor Lake-P HD Audio Controller [8086:7e28] |
| Subsystem: Dell Meteor Lake-P HD Audio Controller [1028:0c63] |
| |
| In this example the SSID is 10280c63. |
| |
| The format of the firmware file names is: |
| |
| SoundWire (except CS35L56 Rev B0): |
| cs35lxx-b0-dsp1-misc-SSID[-spkidX]-l?u? |
| |
| SoundWire CS35L56 Rev B0: |
| cs35lxx-b0-dsp1-misc-SSID[-spkidX]-ampN |
| |
| Non-SoundWire (HDA and I2S): |
| cs35lxx-b0-dsp1-misc-SSID[-spkidX]-ampN |
| |
| Where: |
| |
| * cs35lxx-b0 is the amplifier model and silicon revision. This information |
| is logged by the driver during initialization. |
| * SSID is the 8-digit hexadecimal SSID value. |
| * l?u? is the physical address on the SoundWire bus of the amp this |
| file applies to. |
| * ampN is the amplifier number (for example amp1). This is the same as |
| the prefix on the ALSA control names except that it is always lower-case |
| in the file name. |
| * spkidX is an optional part, used for laptops that have firmware |
| configurations for different makes and models of internal speakers. |
| |
| The CS35L56 Rev B0 continues to use the old filename scheme because a |
| large number of firmware files have already been published with these |
| names. |
| |
| 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: https://github.com/thesofproject/sof-bin/releases |
| |
| 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: cirrus/cs35l56-b0-dsp1-misc-xxxxxxxx.wmfw: format 3 timestamp 0x66b2b872 |
| [ 9.242173] cs35l56 sdw:0:0:01fa:3556:01:0: DSP1: cirrus/cs35l56-b0-dsp1-misc-xxxxxxxx.wmfw: 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: cirrus/cs35l56-b0-dsp1-misc-xxxxxxxx-amp1.bin: 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: cirrus/cs35l56-b0-dsp1-misc-xxxxxxxx.wmfw: format 3 timestamp 0x66b2b872 |
| [ 8.287528] cs35l56-hda i2c-CSC3556:00-cs35l56-hda.0: DSP1: cirrus/cs35l56-b0-dsp1-misc-xxxxxxxx.wmfw: 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: cirrus/cs35l56-b0-dsp1-misc-xxxxxxxx-amp1.bin: 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: cirrus/cs35l56-b0-dsp1-misc-xxxxxxxx.wmfw |
| Shows that a .wmfw firmware file was found and downloaded. |
| |
| DSP1: cirrus/cs35l56-b0-dsp1-misc-xxxxxxxx-amp1.bin |
| 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. |
