1.. SPDX-License-Identifier: GPL-2.0-only 2 3======================================================================== 4Audio drivers for Cirrus Logic CS35L54/56/57/63 Boosted Smart Amplifiers 5======================================================================== 6:Copyright: 2025 Cirrus Logic, Inc. and 7 Cirrus Logic International Semiconductor Ltd. 8 9Contact: patches@opensource.cirrus.com 10 11Summary 12======= 13 14The high-level summary of this document is: 15 16**If you have a laptop that uses CS35L54/56/57/63 amplifiers but audio is not 17working, DO NOT ATTEMPT TO USE FIRMWARE AND SETTINGS FROM ANOTHER LAPTOP, 18EVEN IF THAT LAPTOP SEEMS SIMILAR.** 19 20The CS35L54/56/57/63 amplifiers must be correctly configured for the power 21supply voltage, speaker impedance, maximum speaker voltage/current, and 22other external hardware connections. 23 24The amplifiers feature advanced boost technology that increases the voltage 25used to drive the speakers, while proprietary speaker protection algorithms 26allow these boosted amplifiers to push the limits of the speakers without 27causing damage. These **must** be configured correctly. 28 29Supported Cirrus Logic amplifiers 30--------------------------------- 31 32The cs35l56 drivers support: 33 34* CS35L54 35* CS35L56 36* CS35L57 37* CS35L63 38 39There are two drivers in the kernel 40 41*For systems using SoundWire*: sound/soc/codecs/cs35l56.c and associated files 42 43*For systems using HDA*: sound/pci/hda/cs35l56_hda.c 44 45Firmware 46======== 47 48The amplifier is controlled and managed by firmware running on the internal 49DSP. Firmware files are essential to enable the full capabilities of the 50amplifier. 51 52Firmware is distributed in the linux-firmware repository: 53https://gitlab.com/kernel-firmware/linux-firmware.git 54 55On most SoundWire systems the amplifier has a default minimum capability to 56produce audio. However this will be 57 58* at low volume, to protect the speakers, since the speaker specifications 59 and power supply voltages are unknown. 60* a mono mix of left and right channels. 61 62On some SoundWire systems that have both CS42L43 and CS35L56/57 the CS35L56/57 63receive their audio from the CS42L43 instead of directly from the host 64SoundWire interface. These systems can be identified by the CS42L43 showing 65in dmesg as a SoundWire device, but the CS35L56/57 as SPI. On these systems 66the firmware is *mandatory* to enable receiving the audio from the CS42L43. 67 68On HDA systems the firmware is *mandatory* to enable HDA bridge mode. There 69will not be any audio from the amplifiers without firmware. 70 71Cirrus Logic firmware files 72--------------------------- 73 74Each amplifier requires two firmware files. One file has a .wmfw suffix, the 75other has a .bin suffix. 76 77The firmware is customized by the OEM to match the hardware of each laptop, 78and the firmware is specific to that laptop. Because of this, there are many 79firmware files in linux-firmware for these amplifiers. Firmware files are 80**not interchangeable between laptops**. 81 82Cirrus Logic submits files for known laptops to the upstream linux-firmware 83repository. Providing Cirrus Logic is aware of a particular laptop and has 84permission from the manufacturer to publish the firmware, it will be pushed 85to linux-firmware. You may need to upgrade to a newer release of 86linux-firmware to obtain the firmware for your laptop. 87 88**Important:** the Makefile for linux-firmware creates symlinks that are listed 89in the WHENCE file. These symlinks are required for the CS35L56 driver to be 90able to load the firmware. 91 92How do I know which firmware file I should have? 93~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 94All firmware file names are qualified with a unique "system ID". On normal 95x86 PCs with PCI audio this is the Vendor Subsystem ID (SSID) of the host 96PCI audio interface. 97 98The SSID can be viewed using the lspci tool:: 99 100 lspci -v -nn | grep -A2 -i audio 101 0000:00:1f.3 Audio device [0403]: Intel Corporation Meteor Lake-P HD Audio Controller [8086:7e28] 102 Subsystem: Dell Meteor Lake-P HD Audio Controller [1028:0c63] 103 104In this example the SSID is 10280c63. 105 106The format of the firmware file names is: 107 108SoundWire (except CS35L56 Rev B0): 109 cs35lxx-b0-dsp1-misc-SSID[-spkidX]-l?u? 110 111SoundWire CS35L56 Rev B0: 112 cs35lxx-b0-dsp1-misc-SSID[-spkidX]-ampN 113 114Non-SoundWire (HDA and I2S): 115 cs35lxx-b0-dsp1-misc-SSID[-spkidX]-ampN 116 117Where: 118 119 * cs35lxx-b0 is the amplifier model and silicon revision. This information 120 is logged by the driver during initialization. 121 * SSID is the 8-digit hexadecimal SSID value. 122 * l?u? is the physical address on the SoundWire bus of the amp this 123 file applies to. 124 * ampN is the amplifier number (for example amp1). This is the same as 125 the prefix on the ALSA control names except that it is always lower-case 126 in the file name. 127 * spkidX is an optional part, used for laptops that have firmware 128 configurations for different makes and models of internal speakers. 129 130The CS35L56 Rev B0 continues to use the old filename scheme because a 131large number of firmware files have already been published with these 132names. 133 134Sound Open Firmware and ALSA topology files 135------------------------------------------- 136 137All SoundWire systems will require a Sound Open Firmware (SOF) for the 138host CPU audio DSP, together with an ALSA topology file (.tplg). 139 140The SOF firmware will usually be provided by the manufacturer of the host 141CPU (i.e. Intel or AMD). The .tplg file is normally part of the SOF firmware 142release. 143 144SOF binary builds are available from: https://github.com/thesofproject/sof-bin/releases 145 146The main SOF source is here: https://github.com/thesofproject 147 148ALSA-ucm configurations 149----------------------- 150Typically an appropriate ALSA-ucm configuration file is needed for 151use-case managers and audio servers such as PipeWire. 152 153Configuration files are available from the alsa-ucm-conf repository: 154https://git.alsa-project.org/?p=alsa-ucm-conf.git 155 156Kernel log messages 157=================== 158 159SoundWire 160--------- 161A successful initialization will look like this (this will be repeated for 162each amplifier):: 163 164 [ 7.568374] cs35l56 sdw:0:0:01fa:3556:01:0: supply VDD_P not found, using dummy regulator 165 [ 7.605208] cs35l56 sdw:0:0:01fa:3556:01:0: supply VDD_IO not found, using dummy regulator 166 [ 7.605313] cs35l56 sdw:0:0:01fa:3556:01:0: supply VDD_A not found, using dummy regulator 167 [ 7.939279] cs35l56 sdw:0:0:01fa:3556:01:0: Cirrus Logic CS35L56 Rev B0 OTP3 fw:3.4.4 (patched=0) 168 [ 7.947844] cs35l56 sdw:0:0:01fa:3556:01:0: Slave 4 state check1: UNATTACHED, status was 1 169 [ 8.740280] cs35l56 sdw:0:0:01fa:3556:01:0: supply VDD_B not found, using dummy regulator 170 [ 8.740552] cs35l56 sdw:0:0:01fa:3556:01:0: supply VDD_AMP not found, using dummy regulator 171 [ 9.242164] cs35l56 sdw:0:0:01fa:3556:01:0: DSP1: cirrus/cs35l56-b0-dsp1-misc-xxxxxxxx.wmfw: format 3 timestamp 0x66b2b872 172 [ 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 173 [ 9.991709] cs35l56 sdw:0:0:01fa:3556:01:0: DSP1: Firmware: 1a00d6 vendor: 0x2 v3.11.23, 41 algorithms 174 [10.039098] cs35l56 sdw:0:0:01fa:3556:01:0: DSP1: cirrus/cs35l56-b0-dsp1-misc-xxxxxxxx-amp1.bin: v3.11.23 175 [10.879235] cs35l56 sdw:0:0:01fa:3556:01:0: Slave 4 state check1: UNATTACHED, status was 1 176 [11.401536] cs35l56 sdw:0:0:01fa:3556:01:0: Calibration applied 177 178HDA 179--- 180A successful initialization will look like this (this will be repeated for 181each amplifier):: 182 183 [ 6.306475] cs35l56-hda i2c-CSC3556:00-cs35l56-hda.0: Cirrus Logic CS35L56 Rev B0 OTP3 fw:3.4.4 (patched=0) 184 [ 6.613892] cs35l56-hda i2c-CSC3556:00-cs35l56-hda.0: DSP system name: 'xxxxxxxx', amp name: 'AMP1' 185 [ 8.266660] snd_hda_codec_cs8409 ehdaudio0D0: bound i2c-CSC3556:00-cs35l56-hda.0 (ops cs35l56_hda_comp_ops [snd_hda_scodec_cs35l56]) 186 [ 8.287525] cs35l56-hda i2c-CSC3556:00-cs35l56-hda.0: DSP1: cirrus/cs35l56-b0-dsp1-misc-xxxxxxxx.wmfw: format 3 timestamp 0x66b2b872 187 [ 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 188 [ 9.984335] cs35l56-hda i2c-CSC3556:00-cs35l56-hda.0: DSP1: Firmware: 1a00d6 vendor: 0x2 v3.11.23, 41 algorithms 189 [10.085797] cs35l56-hda i2c-CSC3556:00-cs35l56-hda.0: DSP1: cirrus/cs35l56-b0-dsp1-misc-xxxxxxxx-amp1.bin: v3.11.23 190 [10.655237] cs35l56-hda i2c-CSC3556:00-cs35l56-hda.0: Calibration applied 191 192Important messages 193~~~~~~~~~~~~~~~~~~ 194Cirrus Logic CS35L56 Rev B0 OTP3 fw:3.4.4 (patched=0) 195 Shows that the driver has been able to read device ID registers from the 196 amplifier. 197 198 * The actual amplifier type and silicon revision (CS35L56 B0 in this 199 example) is shown, as read from the amplifier identification registers. 200 * (patched=0) is normal, and indicates that the amplifier has been hard 201 reset and is running default ROM firmware. 202 * (patched=1) means that something has previously downloaded firmware 203 to the amplifier and the driver does not have control of the RESET 204 signal to be able to replace this preloaded firmware. This is normal 205 for systems where the BIOS downloads firmware to the amplifiers 206 before OS boot. 207 This status can also be seen if the cs35l56 kernel module is unloaded 208 and reloaded on a system where the driver does not have control of 209 RESET. SoundWire systems typically do not give the driver control of 210 RESET and only a BIOS (re)boot can reset the amplifiers. 211 212DSP1: cirrus/cs35l56-b0-dsp1-misc-xxxxxxxx.wmfw 213 Shows that a .wmfw firmware file was found and downloaded. 214 215DSP1: cirrus/cs35l56-b0-dsp1-misc-xxxxxxxx-amp1.bin 216 Shows that a .bin firmware file was found and downloaded. 217 218Calibration applied 219 Factory calibration data in EFI was written to the amplifier. 220 221Error messages 222============== 223This section explains some of the error messages that the driver can log. 224 225Algorithm coefficient version %d.%d.%d but expected %d.%d.%d 226 The version of the .bin file content does not match the loaded firmware. 227 Caused by mismatched .wmfw and .bin file, or .bin file was found but 228 .wmfw was not. 229 230No %s for algorithm %x 231 The version of the .bin file content does not match the loaded firmware. 232 Caused by mismatched .wmfw and .bin file, or .bin file was found but 233 .wmfw was not. 234 235.bin file required but not found 236 HDA driver did not find a .bin file that matches this hardware. 237 238Calibration disabled due to missing firmware controls 239 Driver was not able to write EFI calibration data to firmware registers. 240 This typically means that either: 241 242 * The driver did not find a suitable wmfw for this hardware, or 243 * The amplifier has already been patched with firmware by something 244 previously, and the driver does not have control of a hard RESET line 245 to be able to reset the amplifier and download the firmware files it 246 found. This situation is indicated by the device identification 247 string in the kernel log shows "(patched=1)" 248 249Failed to write calibration 250 Same meaning and cause as "Calibration disabled due to missing firmware 251 controls" 252 253Failed to read calibration data from EFI 254 Factory calibration data in EFI is missing, empty or corrupt. 255 This is most likely to be cause by accidentally deleting the file from 256 the EFI filesystem. 257 258No calibration for silicon ID 259 The factory calibration data in EFI does not match this hardware. 260 The most likely cause is that an amplifier has been replaced on the 261 motherboard without going through manufacturer calibration process to 262 generate calibration data for the new amplifier. 263 264Did not find any buses for CSCxxxx 265 Only on HDA systems. The HDA codec driver found an ACPI entry for 266 Cirrus Logic companion amps, but could not enumerate the ACPI entries for 267 the I2C/SPI buses. The most likely cause of this is that: 268 269 * The relevant bus driver (I2C or SPI) is not part of the kernel. 270 * The HDA codec driver was built-in to the kernel but the I2C/SPI 271 bus driver is a module and so the HDA codec driver cannot call the 272 bus driver functions. 273 274init_completion timed out 275 The SoundWire bus controller (host end) did not enumerate the amplifier. 276 In other words, the ACPI says there is an amplifier but for some reason 277 it was not detected on the bus. 278 279No AF01 node 280 Indicates an error in ACPI. A SoundWire system should have a Device() 281 node named "AF01" but it was not found. 282 283Failed to get spk-id-gpios 284 ACPI says that the driver should request a GPIO but the driver was not 285 able to get that GPIO. The most likely cause is that the kernel does not 286 include the correct GPIO or PINCTRL driver for this system. 287 288Failed to read spk-id 289 ACPI says that the driver should request a GPIO but the driver was not 290 able to read that GPIO. 291 292Unexpected spk-id element count 293 AF01 contains more speaker ID GPIO entries than the driver supports 294 295Overtemp error 296 Amplifier overheat protection was triggered and the amplifier shut down 297 to protect itself. 298 299Amp short error 300 Amplifier detected a short-circuit on the speaker output pins and shut 301 down for protection. This would normally indicate a damaged speaker. 302 303Hibernate wake failed 304 The driver tried to wake the amplifier from its power-saving state but 305 did not see the expected responses from the amplifier. This can be caused 306 by using firmware that does not match the hardware. 307