diff options
Diffstat (limited to 'Documentation/sound')
41 files changed, 3920 insertions, 1126 deletions
diff --git a/Documentation/sound/alsa-configuration.rst b/Documentation/sound/alsa-configuration.rst index 72f97d4b01a7..a45174d165eb 100644 --- a/Documentation/sound/alsa-configuration.rst +++ b/Documentation/sound/alsa-configuration.rst @@ -58,7 +58,7 @@ debug 2 = verbose debug messages); This option appears only when ``CONFIG_SND_DEBUG=y``. This option can be dynamically changed via sysfs - /sys/modules/snd/parameters/debug file. + /sys/module/snd/parameters/debug file. Module snd-pcm-oss ------------------ @@ -70,7 +70,7 @@ dsp_map PCM device number maps assigned to the 1st OSS device; Default: 0 adsp_map - PCM device number maps assigned to the 2st OSS device; + PCM device number maps assigned to the 2nd OSS device; Default: 1 nonblock_open Don't block opening busy PCM devices; @@ -97,9 +97,18 @@ midi_map MIDI device number maps assigned to the 1st OSS device; Default: 0 amidi_map - MIDI device number maps assigned to the 2st OSS device; + MIDI device number maps assigned to the 2nd OSS device; Default: 1 +Module snd-soc-core +------------------- + +The soc core module. It is used by all ALSA card drivers. +It takes the following options which have global effects. + +prealloc_buffer_size_kbytes + Specify prealloc buffer size in kbytes (default: 512). + Common parameters for top sound card modules -------------------------------------------- @@ -124,6 +133,19 @@ enable enable card; Default: enabled, for PCI and ISA PnP cards +These options are used for either specifying the order of instances or +controlling enabling and disabling of each one of the devices if there +are multiple devices bound with the same driver. For example, there are +many machines which have two HD-audio controllers (one for HDMI/DP +audio and another for onboard analog). In most cases, the second one is +in primary usage, and people would like to assign it as the first +appearing card. They can do it by specifying "index=1,0" module +parameter, which will swap the assignment slots. + +Today, with the sound backend like PulseAudio and PipeWire which +supports dynamic configuration, it's of little use, but that was a +help for static configuration in the past. + Module snd-adlib ---------------- @@ -309,7 +331,7 @@ pcifix This module supports all ADB PCM channels, ac97 mixer, SPDIF, hardware EQ, mpu401, gameport. A3D and wavetable support are still in development. Development and reverse engineering work is being coordinated at -http://savannah.nongnu.org/projects/openvortex/ +https://savannah.nongnu.org/projects/openvortex/ SPDIF output has a copy of the AC97 codec output, unless you use the ``spdif`` pcm device, which allows raw data passthru. The hardware EQ hardware and SPDIF is only present in the Vortex2 and @@ -714,13 +736,14 @@ Module for EMU10K1/EMU10k2 based PCI sound cards. * Sound Blaster Live! * Sound Blaster PCI 512 -* Emu APS (partially supported) * Sound Blaster Audigy - +* E-MU APS (partially supported) +* E-MU DAS + extin - bitmap of available external inputs for FX8010 (see bellow) + bitmap of available external inputs for FX8010 (see below) extout - bitmap of available external outputs for FX8010 (see bellow) + bitmap of available external outputs for FX8010 (see below) seq_ports allocated sequencer ports (4 by default) max_synth_voices @@ -1036,6 +1059,9 @@ power_save Automatic power-saving timeout (in second, 0 = disable) power_save_controller Reset HD-audio controller in power-saving mode (default = on) +pm_blacklist + Enable / disable power-management deny-list (default = look up PM + deny-list, 0 = skip PM deny-list, 1 = force to turn off runtime PM) align_buffer_size Force rounding of buffer/period sizes to multiples of 128 bytes. This is more efficient in terms of memory access but isn't @@ -1059,6 +1085,12 @@ The model name ``generic`` is treated as a special case. When this model is given, the driver uses the generic codec parser without "codec-patch". It's sometimes good for testing and debugging. +The model option can be used also for aliasing to another PCI or codec +SSID. When it's passed in the form of ``model=XXXX:YYYY`` where XXXX +and YYYY are the sub-vendor and sub-device IDs in hex numbers, +respectively, the driver will refer to that SSID as a reference to the +quirk table. + If the default configuration doesn't work and one of the above matches with your device, report it together with alsa-info.sh output (with ``--no-upload`` option) to kernel bugzilla or alsa-devel @@ -1501,7 +1533,7 @@ Module for Digigram miXart8 sound cards. This module supports multiple cards. Note: One miXart8 board will be represented as 4 alsa cards. -See MIXART.txt for details. +See Documentation/sound/cards/mixart.rst for details. When the driver is compiled as a module and the hotplug firmware is supported, the firmware data is loaded via hotplug automatically. @@ -1575,7 +1607,7 @@ See Documentation/sound/cards/multisound.sh for important information about this driver. Note that it has been discontinued, but the Voyetra Turtle Beach knowledge base entry for it is still available at -http://www.turtlebeach.com +https://www.turtlebeach.com Module snd-msnd-pinnacle ------------------------ @@ -2227,6 +2259,11 @@ quirk_alias Quirk alias list, pass strings like ``0123abcd:5678beef``, which applies the existing quirk for the device 5678:beef to a new device 0123:abcd. +implicit_fb + Apply the generic implicit feedback sync mode. When this is set + and the playback stream sync mode is ASYNC, the driver tries to + tie an adjacent ASYNC capture stream as the implicit feedback + source. This is equivalent with quirk_flags bit 17. use_vmalloc Use vmalloc() for allocations of the PCM buffers (default: yes). For architectures with non-coherent memory like ARM or MIPS, the @@ -2247,6 +2284,29 @@ delayed_register The driver prints a message like "Found post-registration device assignment: 1234abcd:04" for such a device, so that user can notice the need. +quirk_flags + Contains the bit flags for various device specific workarounds. + Applied to the corresponding card index. + + * bit 0: Skip reading sample rate for devices + * bit 1: Create Media Controller API entries + * bit 2: Allow alignment on audio sub-slot at transfer + * bit 3: Add length specifier to transfers + * bit 4: Start playback stream at first in implement feedback mode + * bit 5: Skip clock selector setup + * bit 6: Ignore errors from clock source search + * bit 7: Indicates ITF-USB DSD based DACs + * bit 8: Add a delay of 20ms at each control message handling + * bit 9: Add a delay of 1-2ms at each control message handling + * bit 10: Add a delay of 5-6ms at each control message handling + * bit 11: Add a delay of 50ms at each interface setup + * bit 12: Perform sample rate validations at probe + * bit 13: Disable runtime PM autosuspend + * bit 14: Ignore errors for mixer access + * bit 15: Support generic DSD raw U32_BE format + * bit 16: Set up the interface at first like UAC1 + * bit 17: Apply the generic implicit feedback sync mode + * bit 18: Don't apply implicit feedback sync mode This module supports multiple devices, autoprobe and hotplugging. @@ -2256,11 +2316,14 @@ check. NB: ``ignore_ctl_error=1`` may help when you get an error at accessing the mixer element such as URB error -22. This happens on some -buggy USB device or the controller. +buggy USB device or the controller. This workaround corresponds to +the ``quirk_flags`` bit 14, too. -NB: quirk_alias option is provided only for testing / development. +NB: ``quirk_alias`` option is provided only for testing / development. If you want to have a proper support, contact to upstream for adding the matching quirk in the driver code statically. +Ditto for ``quirk_flags``. If a device is known to require specific +workarounds, please report to the upstream. Module snd-usb-caiaq -------------------- @@ -2703,4 +2766,4 @@ Kernel Bugzilla ALSA Developers ML mailto:alsa-devel@alsa-project.org alsa-info.sh script - http://www.alsa-project.org/alsa-info.sh + https://www.alsa-project.org/alsa-info.sh diff --git a/Documentation/sound/cards/audigy-mixer.rst b/Documentation/sound/cards/audigy-mixer.rst index 86213234435f..7ebaacb6df3d 100644 --- a/Documentation/sound/cards/audigy-mixer.rst +++ b/Documentation/sound/cards/audigy-mixer.rst @@ -17,11 +17,11 @@ Digital mixer controls ====================== These controls are built using the DSP instructions. They offer extended -functionality. Only the default build-in code in the ALSA driver is described +functionality. Only the default built-in code in the ALSA driver is described here. Note that the controls work as attenuators: the maximum value is the -neutral position leaving the signal unchanged. Note that if the same destination -is mentioned in multiple controls, the signal is accumulated and can be wrapped -(set to maximal or minimal value without checking of overflow). +neutral position leaving the signal unchanged. Note that if the same destination +is mentioned in multiple controls, the signal is accumulated and can be clipped +(set to maximal or minimal value without checking for overflow). Explanation of used abbreviations: @@ -32,171 +32,172 @@ ADC analog to digital converter I2S one-way three wire serial bus for digital sound by Philips Semiconductors - (this standard is used for connecting standalone DAC and ADC converters) + (this standard is used for connecting standalone D/A and A/D converters) LFE - low frequency effects (subwoofer signal) + low frequency effects (used as subwoofer signal) AC97 - a chip containing an analog mixer, DAC and ADC converters + a chip containing an analog mixer, D/A and A/D converters IEC958 S/PDIF FX-bus the EMU10K2 chip has an effect bus containing 64 accumulators. - Each of the synthesizer voices can feed its output to these accumulators - and the DSP microcontroller can operate with the resulting sum. + Each of the synthesizer voices can feed its output to these accumulators + and the DSP microcontroller can operate with the resulting sum. name='PCM Front Playback Volume',index=0 ---------------------------------------- -This control is used to attenuate samples for left and right front PCM FX-bus +This control is used to attenuate samples from left and right front PCM FX-bus accumulators. ALSA uses accumulators 8 and 9 for left and right front PCM -samples for 5.1 playback. The result samples are forwarded to the front DAC PCM -slots of the Philips DAC. +samples for 5.1 playback. The result samples are forwarded to the front speakers. name='PCM Surround Playback Volume',index=0 ------------------------------------------- -This control is used to attenuate samples for left and right surround PCM FX-bus +This control is used to attenuate samples from left and right surround PCM FX-bus accumulators. ALSA uses accumulators 2 and 3 for left and right surround PCM -samples for 5.1 playback. The result samples are forwarded to the surround DAC PCM -slots of the Philips DAC. +samples for 5.1 playback. The result samples are forwarded to the surround (rear) +speakers. + +name='PCM Side Playback Volume',index=0 +--------------------------------------- +This control is used to attenuate samples from left and right side PCM FX-bus +accumulators. ALSA uses accumulators 14 and 15 for left and right side PCM +samples for 7.1 playback. The result samples are forwarded to the side speakers. name='PCM Center Playback Volume',index=0 ----------------------------------------- -This control is used to attenuate samples for center PCM FX-bus accumulator. -ALSA uses accumulator 6 for center PCM sample for 5.1 playback. The result sample -is forwarded to the center DAC PCM slot of the Philips DAC. +This control is used to attenuate samples from center PCM FX-bus accumulator. +ALSA uses accumulator 6 for center PCM samples for 5.1 playback. The result +samples are forwarded to the center speaker. name='PCM LFE Playback Volume',index=0 -------------------------------------- This control is used to attenuate sample for LFE PCM FX-bus accumulator. -ALSA uses accumulator 7 for LFE PCM sample for 5.1 playback. The result sample -is forwarded to the LFE DAC PCM slot of the Philips DAC. +ALSA uses accumulator 7 for LFE PCM samples for 5.1 playback. The result +samples are forwarded to the subwoofer. name='PCM Playback Volume',index=0 ---------------------------------- -This control is used to attenuate samples for left and right PCM FX-bus +This control is used to attenuate samples from left and right PCM FX-bus accumulators. ALSA uses accumulators 0 and 1 for left and right PCM samples for -stereo playback. The result samples are forwarded to the front DAC PCM slots -of the Philips DAC. +stereo playback. The result samples are forwarded to the front speakers. name='PCM Capture Volume',index=0 --------------------------------- -This control is used to attenuate samples for left and right PCM FX-bus -accumulator. ALSA uses accumulators 0 and 1 for left and right PCM. -The result is forwarded to the ADC capture FIFO (thus to the standard capture -PCM device). +This control is used to attenuate samples from left and right PCM FX-bus +accumulators. ALSA uses accumulators 0 and 1 for left and right PCM samples for +stereo playback. The result is forwarded to the standard capture PCM device. name='Music Playback Volume',index=0 ------------------------------------ -This control is used to attenuate samples for left and right MIDI FX-bus +This control is used to attenuate samples from left and right MIDI FX-bus accumulators. ALSA uses accumulators 4 and 5 for left and right MIDI samples. -The result samples are forwarded to the front DAC PCM slots of the AC97 codec. +The result samples are forwarded to the virtual stereo mixer. name='Music Capture Volume',index=0 ----------------------------------- -These controls are used to attenuate samples for left and right MIDI FX-bus -accumulator. ALSA uses accumulators 4 and 5 for left and right PCM. -The result is forwarded to the ADC capture FIFO (thus to the standard capture -PCM device). +These controls are used to attenuate samples from left and right MIDI FX-bus +accumulator. ALSA uses accumulators 4 and 5 for left and right MIDI samples. +The result is forwarded to the standard capture PCM device. name='Mic Playback Volume',index=0 ---------------------------------- -This control is used to attenuate samples for left and right Mic input. -For Mic input is used AC97 codec. The result samples are forwarded to -the front DAC PCM slots of the Philips DAC. Samples are forwarded to Mic -capture FIFO (device 1 - 16bit/8KHz mono) too without volume control. +This control is used to attenuate samples from left and right Mic input of +the AC97 codec. The result samples are forwarded to the virtual stereo mixer. name='Mic Capture Volume',index=0 --------------------------------- -This control is used to attenuate samples for left and right Mic input. -The result is forwarded to the ADC capture FIFO (thus to the standard capture -PCM device). +This control is used to attenuate samples from left and right Mic input of +the AC97 codec. The result is forwarded to the standard capture PCM device. + +The original samples are also forwarded to the Mic capture PCM device (device 1; +16bit/8KHz mono) without volume control. name='Audigy CD Playback Volume',index=0 ---------------------------------------- This control is used to attenuate samples from left and right IEC958 TTL digital inputs (usually used by a CDROM drive). The result samples are -forwarded to the front DAC PCM slots of the Philips DAC. +forwarded to the virtual stereo mixer. name='Audigy CD Capture Volume',index=0 --------------------------------------- This control is used to attenuate samples from left and right IEC958 TTL -digital inputs (usually used by a CDROM drive). The result samples are -forwarded to the ADC capture FIFO (thus to the standard capture PCM device). +digital inputs (usually used by a CDROM drive). The result is forwarded +to the standard capture PCM device. name='IEC958 Optical Playback Volume',index=0 --------------------------------------------- This control is used to attenuate samples from left and right IEC958 optical -digital input. The result samples are forwarded to the front DAC PCM slots -of the Philips DAC. +digital input. The result samples are forwarded to the virtual stereo mixer. name='IEC958 Optical Capture Volume',index=0 -------------------------------------------- This control is used to attenuate samples from left and right IEC958 optical -digital inputs. The result samples are forwarded to the ADC capture FIFO -(thus to the standard capture PCM device). +digital inputs. The result is forwarded to the standard capture PCM device. name='Line2 Playback Volume',index=0 ------------------------------------ This control is used to attenuate samples from left and right I2S ADC -inputs (on the AudigyDrive). The result samples are forwarded to the front -DAC PCM slots of the Philips DAC. +inputs (on the AudigyDrive). The result samples are forwarded to the virtual +stereo mixer. name='Line2 Capture Volume',index=1 ----------------------------------- This control is used to attenuate samples from left and right I2S ADC -inputs (on the AudigyDrive). The result samples are forwarded to the ADC -capture FIFO (thus to the standard capture PCM device). +inputs (on the AudigyDrive). The result is forwarded to the standard capture +PCM device. name='Analog Mix Playback Volume',index=0 ----------------------------------------- This control is used to attenuate samples from left and right I2S ADC -inputs from Philips ADC. The result samples are forwarded to the front -DAC PCM slots of the Philips DAC. This contains mix from analog sources -like CD, Line In, Aux, .... +inputs from Philips ADC. The result samples are forwarded to the virtual +stereo mixer. This contains mix from analog sources like CD, Line In, Aux, .... name='Analog Mix Capture Volume',index=1 ---------------------------------------- This control is used to attenuate samples from left and right I2S ADC -inputs Philips ADC. The result samples are forwarded to the ADC -capture FIFO (thus to the standard capture PCM device). +inputs Philips ADC. The result is forwarded to the standard capture PCM device. name='Aux2 Playback Volume',index=0 ----------------------------------- This control is used to attenuate samples from left and right I2S ADC -inputs (on the AudigyDrive). The result samples are forwarded to the front -DAC PCM slots of the Philips DAC. +inputs (on the AudigyDrive). The result samples are forwarded to the virtual +stereo mixer. name='Aux2 Capture Volume',index=1 ---------------------------------- This control is used to attenuate samples from left and right I2S ADC -inputs (on the AudigyDrive). The result samples are forwarded to the ADC -capture FIFO (thus to the standard capture PCM device). +inputs (on the AudigyDrive). The result is forwarded to the standard capture +PCM device. name='Front Playback Volume',index=0 ------------------------------------ -All stereo signals are mixed together and mirrored to surround, center and LFE. -This control is used to attenuate samples for left and right front speakers of -this mix. +This control is used to attenuate samples from the virtual stereo mixer. +The result samples are forwarded to the front speakers. name='Surround Playback Volume',index=0 --------------------------------------- -All stereo signals are mixed together and mirrored to surround, center and LFE. -This control is used to attenuate samples for left and right surround speakers of -this mix. +This control is used to attenuate samples from the virtual stereo mixer. +The result samples are forwarded to the surround (rear) speakers. + +name='Side Playback Volume',index=0 +----------------------------------- +This control is used to attenuate samples from the virtual stereo mixer. +The result samples are forwarded to the side speakers. name='Center Playback Volume',index=0 ------------------------------------- -All stereo signals are mixed together and mirrored to surround, center and LFE. -This control is used to attenuate sample for center speaker of this mix. +This control is used to attenuate samples from the virtual stereo mixer. +The result samples are forwarded to the center speaker. name='LFE Playback Volume',index=0 ---------------------------------- -All stereo signals are mixed together and mirrored to surround, center and LFE. -This control is used to attenuate sample for LFE speaker of this mix. +This control is used to attenuate samples from the virtual stereo mixer. +The result samples are forwarded to the subwoofer. name='Tone Control - Switch',index=0 ------------------------------------ -This control turns the tone control on or off. The samples for front, rear -and center / LFE outputs are affected. +This control turns the tone control on or off. The samples forwarded to +the speaker outputs are affected. name='Tone Control - Bass',index=0 ---------------------------------- @@ -212,14 +213,13 @@ The closest value to pure signal is 20. name='Master Playback Volume',index=0 ------------------------------------- -This control is used to attenuate samples for front, surround, center and -LFE outputs. +This control is used to attenuate samples forwarded to the speaker outputs. name='IEC958 Optical Raw Playback Switch',index=0 ------------------------------------------------- If this switch is on, then the samples for the IEC958 (S/PDIF) digital -output are taken only from the raw FX8010 PCM, otherwise standard front -PCM samples are taken. +output are taken only from the raw iec958 ALSA PCM device (which uses +accumulators 20 and 21 for left and right PCM by default). PCM stream related controls @@ -227,7 +227,7 @@ PCM stream related controls name='EMU10K1 PCM Volume',index 0-31 ------------------------------------ -Channel volume attenuation in range 0-0xffff. The maximum value (no +Channel volume attenuation in range 0-0x1fffd. The middle value (no attenuation) is default. The channel mapping for three values is as follows: @@ -237,33 +237,33 @@ as follows: name='EMU10K1 PCM Send Routing',index 0-31 ------------------------------------------ -This control specifies the destination - FX-bus accumulators. There 24 -values with this mapping: - -* 0 - mono, A destination (FX-bus 0-63), default 0 -* 1 - mono, B destination (FX-bus 0-63), default 1 -* 2 - mono, C destination (FX-bus 0-63), default 2 -* 3 - mono, D destination (FX-bus 0-63), default 3 -* 4 - mono, E destination (FX-bus 0-63), default 0 -* 5 - mono, F destination (FX-bus 0-63), default 0 -* 6 - mono, G destination (FX-bus 0-63), default 0 -* 7 - mono, H destination (FX-bus 0-63), default 0 -* 8 - left, A destination (FX-bus 0-63), default 0 -* 9 - left, B destination (FX-bus 0-63), default 1 +This control specifies the destination - FX-bus accumulators. There are 24 +values in this mapping: + +* 0 - mono, A destination (FX-bus 0-63), default 0 +* 1 - mono, B destination (FX-bus 0-63), default 1 +* 2 - mono, C destination (FX-bus 0-63), default 2 +* 3 - mono, D destination (FX-bus 0-63), default 3 +* 4 - mono, E destination (FX-bus 0-63), default 4 +* 5 - mono, F destination (FX-bus 0-63), default 5 +* 6 - mono, G destination (FX-bus 0-63), default 6 +* 7 - mono, H destination (FX-bus 0-63), default 7 +* 8 - left, A destination (FX-bus 0-63), default 0 +* 9 - left, B destination (FX-bus 0-63), default 1 * 10 - left, C destination (FX-bus 0-63), default 2 * 11 - left, D destination (FX-bus 0-63), default 3 -* 12 - left, E destination (FX-bus 0-63), default 0 -* 13 - left, F destination (FX-bus 0-63), default 0 -* 14 - left, G destination (FX-bus 0-63), default 0 -* 15 - left, H destination (FX-bus 0-63), default 0 +* 12 - left, E destination (FX-bus 0-63), default 4 +* 13 - left, F destination (FX-bus 0-63), default 5 +* 14 - left, G destination (FX-bus 0-63), default 6 +* 15 - left, H destination (FX-bus 0-63), default 7 * 16 - right, A destination (FX-bus 0-63), default 0 * 17 - right, B destination (FX-bus 0-63), default 1 * 18 - right, C destination (FX-bus 0-63), default 2 * 19 - right, D destination (FX-bus 0-63), default 3 -* 20 - right, E destination (FX-bus 0-63), default 0 -* 21 - right, F destination (FX-bus 0-63), default 0 -* 22 - right, G destination (FX-bus 0-63), default 0 -* 23 - right, H destination (FX-bus 0-63), default 0 +* 20 - right, E destination (FX-bus 0-63), default 4 +* 21 - right, F destination (FX-bus 0-63), default 5 +* 22 - right, G destination (FX-bus 0-63), default 6 +* 23 - right, H destination (FX-bus 0-63), default 7 Don't forget that it's illegal to assign a channel to the same FX-bus accumulator more than once (it means 0=0 && 1=0 is an invalid combination). @@ -303,66 +303,4 @@ The channel mapping is following: MANUALS/PATENTS =============== -ftp://opensource.creative.com/pub/doc -------------------------------------- - -LM4545.pdf - AC97 Codec - -m2049.pdf - The EMU10K1 Digital Audio Processor - -hog63.ps - FX8010 - A DSP Chip Architecture for Audio Effects - - -WIPO Patents ------------- - -WO 9901813 (A1) - Audio Effects Processor with multiple asynchronous streams - (Jan. 14, 1999) - -WO 9901814 (A1) - Processor with Instruction Set for Audio Effects (Jan. 14, 1999) - -WO 9901953 (A1) - Audio Effects Processor having Decoupled Instruction - Execution and Audio Data Sequencing (Jan. 14, 1999) - - -US Patents (http://www.uspto.gov/) ----------------------------------- - -US 5925841 - Digital Sampling Instrument employing cache memory (Jul. 20, 1999) - -US 5928342 - Audio Effects Processor integrated on a single chip - with a multiport memory onto which multiple asynchronous - digital sound samples can be concurrently loaded - (Jul. 27, 1999) - -US 5930158 - Processor with Instruction Set for Audio Effects (Jul. 27, 1999) - -US 6032235 - Memory initialization circuit (Tram) (Feb. 29, 2000) - -US 6138207 - Interpolation looping of audio samples in cache connected to - system bus with prioritization and modification of bus transfers - in accordance with loop ends and minimum block sizes - (Oct. 24, 2000) - -US 6151670 - Method for conserving memory storage using a - pool of short term memory registers - (Nov. 21, 2000) - -US 6195715 - Interrupt control for multiple programs communicating with - a common interrupt by associating programs to GP registers, - defining interrupt register, polling GP registers, and invoking - callback routine associated with defined interrupt register - (Feb. 27, 2001) +See sb-live-mixer.rst. diff --git a/Documentation/sound/cards/emu-mixer.rst b/Documentation/sound/cards/emu-mixer.rst new file mode 100644 index 000000000000..d87a6338d3d8 --- /dev/null +++ b/Documentation/sound/cards/emu-mixer.rst @@ -0,0 +1,226 @@ +================================================== +E-MU Digital Audio System mixer / default DSP code +================================================== + +This document covers the E-MU 0404/1010/1212/1616/1820 PCI/PCI-e/CardBus +cards. + +These cards use regular EMU10K2 (SoundBlaster Audigy) chips, but with an +alternative front-end geared towards semi-professional studio recording. + +This document is based on audigy-mixer.rst. + + +Hardware compatibility +====================== + +The EMU10K2 chips have a very short capture FIFO, which makes recording +unreliable if the card's PCI bus requests are not handled with the +appropriate priority. +This is the case on more modern motherboards, where the PCI bus is only a +secondary peripheral, rather than the actual arbiter of device access. +In particular, I got recording glitches during simultaneous playback on an +Intel DP55 board (memory controller in the CPU), but had success with an +Intel DP45 board (memory controller in the north bridge). + +The PCI Express variants of these cards (which have a PCI bridge on board, +but are otherwise identical) may be less problematic. + + +Driver capabilities +=================== + +This driver supports only 16-bit 44.1/48 kHz operation. The multi-channel +device (see emu10k1-jack.rst) additionally supports 24-bit capture. + +A patchset to enhance the driver is available from `a GitHub repository +<https://github.com/ossilator/linux/tree/ossis-emu10k1>`_. +Its multi-channel device supports 24-bit for both playback and capture, +and also supports full 88.2/96/176.4/192 kHz operation. +It is not going to be upstreamed due to a fundamental disagreement about +what constitutes a good user experience. + + +Digital mixer controls +====================== + +Note that the controls work as attenuators: the maximum value is the neutral +position leaving the signal unchanged. Note that if the same destination is +mentioned in multiple controls, the signal is accumulated and can be clipped +(set to maximal or minimal value without checking for overflow). + +Explanation of used abbreviations: + +DAC + digital to analog converter +ADC + analog to digital converter +LFE + low frequency effects (used as subwoofer signal) +IEC958 + S/PDIF +FX-bus + the EMU10K2 chip has an effect bus containing 64 accumulators. + Each of the synthesizer voices can feed its output to these accumulators + and the DSP microcontroller can operate with the resulting sum. + +name='Clock Source',index=0 +--------------------------- +This control allows switching the word clock between interally generated +44.1 or 48 kHz, or a number of external sources. + +Note: the sources for the 1616 CardBus card are unclear. Please report your +findings. + +name='Clock Fallback',index=0 +----------------------------- +This control determines the internal clock which the card switches to when +the selected external clock source is/becomes invalid. + +name='DAC1 0202 14dB PAD',index=0, etc. +--------------------------------------- +Output attenuation controls. Not available on 0404 cards. + +name='ADC1 14dB PAD 0202',index=0, etc. +--------------------------------------- +Input attenuation controls. Not available on 0404 cards. + +name='Optical Output Mode',index=0 +---------------------------------- +Switches the TOSLINK output port between S/PDIF and ADAT. +Not available on 0404 cards (fixed to S/PDIF). + +name='Optical Input Mode',index=0 +--------------------------------- +Switches the TOSLINK input port between S/PDIF and ADAT. +Not available on 0404 cards (fixed to S/PDIF). + +name='PCM Front Playback Volume',index=0 +---------------------------------------- +This control is used to attenuate samples from left and right front PCM FX-bus +accumulators. ALSA uses accumulators 8 and 9 for left and right front PCM +samples for 5.1 playback. The result samples are forwarded to the DSP 0 & 1 +playback channels. + +name='PCM Surround Playback Volume',index=0 +------------------------------------------- +This control is used to attenuate samples from left and right surround PCM FX-bus +accumulators. ALSA uses accumulators 2 and 3 for left and right surround PCM +samples for 5.1 playback. The result samples are forwarded to the DSP 2 & 3 +playback channels. + +name='PCM Side Playback Volume',index=0 +--------------------------------------- +This control is used to attenuate samples from left and right side PCM FX-bus +accumulators. ALSA uses accumulators 14 and 15 for left and right side PCM +samples for 7.1 playback. The result samples are forwarded to the DSP 6 & 7 +playback channels. + +name='PCM Center Playback Volume',index=0 +----------------------------------------- +This control is used to attenuate samples from the center PCM FX-bus accumulator. +ALSA uses accumulator 6 for center PCM samples for 5.1 playback. The result samples +are forwarded to the DSP 4 playback channel. + +name='PCM LFE Playback Volume',index=0 +-------------------------------------- +This control is used to attenuate samples from the LFE PCM FX-bus accumulator. +ALSA uses accumulator 7 for LFE PCM samples for 5.1 playback. The result samples +are forwarded to the DSP 5 playback channel. + +name='PCM Playback Volume',index=0 +---------------------------------- +This control is used to attenuate samples from left and right PCM FX-bus +accumulators. ALSA uses accumulators 0 and 1 for left and right PCM samples for +stereo playback. The result samples are forwarded to the virtual stereo mixer. + +name='PCM Capture Volume',index=0 +--------------------------------- +This control is used to attenuate samples from left and right PCM FX-bus +accumulators. ALSA uses accumulators 0 and 1 for left and right PCM. +The result is forwarded to the standard capture PCM device. + +name='Music Playback Volume',index=0 +------------------------------------ +This control is used to attenuate samples from left and right MIDI FX-bus +accumulators. ALSA uses accumulators 4 and 5 for left and right MIDI samples. +The result samples are forwarded to the virtual stereo mixer. + +name='Music Capture Volume',index=0 +----------------------------------- +These controls are used to attenuate samples from left and right MIDI FX-bus +accumulator. ALSA uses accumulators 4 and 5 for left and right MIDI samples. +The result is forwarded to the standard capture PCM device. + +name='Front Playback Volume',index=0 +------------------------------------ +This control is used to attenuate samples from the virtual stereo mixer. +The result samples are forwarded to the DSP 0 & 1 playback channels. + +name='Surround Playback Volume',index=0 +--------------------------------------- +This control is used to attenuate samples from the virtual stereo mixer. +The result samples are forwarded to the DSP 2 & 3 playback channels. + +name='Side Playback Volume',index=0 +----------------------------------- +This control is used to attenuate samples from the virtual stereo mixer. +The result samples are forwarded to the DSP 6 & 7 playback channels. + +name='Center Playback Volume',index=0 +------------------------------------- +This control is used to attenuate samples from the virtual stereo mixer. +The result samples are forwarded to the DSP 4 playback channel. + +name='LFE Playback Volume',index=0 +---------------------------------- +This control is used to attenuate samples from the virtual stereo mixer. +The result samples are forwarded to the DSP 5 playback channel. + +name='Tone Control - Switch',index=0 +------------------------------------ +This control turns the tone control on or off. The samples forwarded to +the DSP playback channels are affected. + +name='Tone Control - Bass',index=0 +---------------------------------- +This control sets the bass intensity. There is no neutral value!! +When the tone control code is activated, the samples are always modified. +The closest value to pure signal is 20. + +name='Tone Control - Treble',index=0 +------------------------------------ +This control sets the treble intensity. There is no neutral value!! +When the tone control code is activated, the samples are always modified. +The closest value to pure signal is 20. + +name='Master Playback Volume',index=0 +------------------------------------- +This control is used to attenuate samples for all DSP playback channels. + +name='EMU Capture Volume',index=0 +---------------------------------- +This control is used to attenuate samples from the DSP 0 & 1 capture channels. +The result is forwarded to the standard capture PCM device. + +name='DAC Left',index=0, etc. +----------------------------- +Select the source for the given physical audio output. These may be physical +inputs, playback channels (DSP xx, specified as a decimal number), or silence. + +name='DSP x',index=0 +-------------------- +Select the source for the given capture channel (specified as a hexadecimal +digit). Same options as for the physical audio outputs. + + +PCM stream related controls +=========================== + +These controls are described in audigy-mixer.rst. + + +MANUALS/PATENTS +=============== + +See sb-live-mixer.rst. diff --git a/Documentation/sound/cards/index.rst b/Documentation/sound/cards/index.rst index c016f8c3b88b..e68bbb13c384 100644 --- a/Documentation/sound/cards/index.rst +++ b/Documentation/sound/cards/index.rst @@ -8,6 +8,7 @@ Card-Specific Information cmipci sb-live-mixer audigy-mixer + emu-mixer emu10k1-jack via82xx-mixer audiophile-usb @@ -17,3 +18,4 @@ Card-Specific Information hdspm serial-u16550 img-spdif-in + pcmtest diff --git a/Documentation/sound/cards/maya44.rst b/Documentation/sound/cards/maya44.rst index bf09a584b443..ab973f66c973 100644 --- a/Documentation/sound/cards/maya44.rst +++ b/Documentation/sound/cards/maya44.rst @@ -156,7 +156,7 @@ IEC958 Output S/PDIF should output the same signal as channel 3+4. [untested!] -Digitial output selectors +Digital output selectors These switches allow a direct digital routing from the ADCs to the DACs. Each switch determines where the digital input data to one of the DACs comes from. They are not supported by the ESI windows driver. diff --git a/Documentation/sound/cards/pcmtest.rst b/Documentation/sound/cards/pcmtest.rst new file mode 100644 index 000000000000..e163522f3205 --- /dev/null +++ b/Documentation/sound/cards/pcmtest.rst @@ -0,0 +1,120 @@ +.. SPDX-License-Identifier: GPL-2.0 + +The Virtual PCM Test Driver +=========================== + +The Virtual PCM Test Driver emulates a generic PCM device, and can be used for +testing/fuzzing of the userspace ALSA applications, as well as for testing/fuzzing of +the PCM middle layer. Additionally, it can be used for simulating hard to reproduce +problems with PCM devices. + +What can this driver do? +~~~~~~~~~~~~~~~~~~~~~~~~ + +At this moment the driver can do the following things: + * Simulate both capture and playback processes + * Generate random or pattern-based capturing data + * Inject delays into the playback and capturing processes + * Inject errors during the PCM callbacks + +It supports up to 8 substreams and 4 channels. Also it supports both interleaved and +non-interleaved access modes. + +Also, this driver can check the playback stream for containing the predefined pattern, +which is used in the corresponding selftest (alsa/pcmtest-test.sh) to check the PCM middle +layer data transferring functionality. Additionally, this driver redefines the default +RESET ioctl, and the selftest covers this PCM API functionality as well. + +Configuration +------------- + +The driver has several parameters besides the common ALSA module parameters: + + * fill_mode (bool) - Buffer fill mode (see below) + * inject_delay (int) + * inject_hwpars_err (bool) + * inject_prepare_err (bool) + * inject_trigger_err (bool) + + +Capture Data Generation +----------------------- + +The driver has two modes of data generation: the first (0 in the fill_mode parameter) +means random data generation, the second (1 in the fill_mode) - pattern-based +data generation. Let's look at the second mode. + +First of all, you may want to specify the pattern for data generation. You can do it +by writing the pattern to the debugfs file. There are pattern buffer debugfs entries +for each channel, as well as entries which contain the pattern buffer length. + + * /sys/kernel/debug/pcmtest/fill_pattern[0-3] + * /sys/kernel/debug/pcmtest/fill_pattern[0-3]_len + +To set the pattern for the channel 0 you can execute the following command: + +.. code-block:: bash + + echo -n mycoolpattern > /sys/kernel/debug/pcmtest/fill_pattern0 + +Then, after every capture action performed on the 'pcmtest' device the buffer for the +channel 0 will contain 'mycoolpatternmycoolpatternmycoolpatternmy...'. + +The pattern itself can be up to 4096 bytes long. + +Delay injection +--------------- + +The driver has 'inject_delay' parameter, which has very self-descriptive name and +can be used for time delay/speedup simulations. The parameter has integer type, and +it means the delay added between module's internal timer ticks. + +If the 'inject_delay' value is positive, the buffer will be filled slower, if it is +negative - faster. You can try it yourself by starting a recording in any +audiorecording application (like Audacity) and selecting the 'pcmtest' device as a +source. + +This parameter can be also used for generating a huge amount of sound data in a very +short period of time (with the negative 'inject_delay' value). + +Errors injection +---------------- + +This module can be used for injecting errors into the PCM communication process. This +action can help you to figure out how the userspace ALSA program behaves under unusual +circumstances. + +For example, you can make all 'hw_params' PCM callback calls return EBUSY error by +writing '1' to the 'inject_hwpars_err' module parameter: + +.. code-block:: bash + + echo 1 > /sys/module/snd_pcmtest/parameters/inject_hwpars_err + +Errors can be injected into the following PCM callbacks: + + * hw_params (EBUSY) + * prepare (EINVAL) + * trigger (EINVAL) + +Playback test +------------- + +This driver can be also used for the playback functionality testing - every time you +write the playback data to the 'pcmtest' PCM device and close it, the driver checks the +buffer for containing the looped pattern (which is specified in the fill_pattern +debugfs file for each channel). If the playback buffer content represents the looped +pattern, 'pc_test' debugfs entry is set into '1'. Otherwise, the driver sets it to '0'. + +ioctl redefinition test +----------------------- + +The driver redefines the 'reset' ioctl, which is default for all PCM devices. To test +this functionality, we can trigger the reset ioctl and check the 'ioctl_test' debugfs +entry: + +.. code-block:: bash + + cat /sys/kernel/debug/pcmtest/ioctl_test + +If the ioctl is triggered successfully, this file will contain '1', and '0' otherwise. diff --git a/Documentation/sound/cards/sb-live-mixer.rst b/Documentation/sound/cards/sb-live-mixer.rst index bcb62fc99bbb..27667f58aae1 100644 --- a/Documentation/sound/cards/sb-live-mixer.rst +++ b/Documentation/sound/cards/sb-live-mixer.rst @@ -15,7 +15,7 @@ The ALSA driver programs this portion of chip by default code IEC958 (S/PDIF) raw PCM ======================= -This PCM device (it's the 4th PCM device (index 3!) and first subdevice +This PCM device (it's the 3rd PCM device (index 2!) and first subdevice (index 0) for a given card) allows to forward 48kHz, stereo, 16-bit little endian streams without any modifications to the digital output (coaxial or optical). The universal interface allows the creation of up @@ -31,11 +31,11 @@ Digital mixer controls ====================== These controls are built using the DSP instructions. They offer extended -functionality. Only the default build-in code in the ALSA driver is described +functionality. Only the default built-in code in the ALSA driver is described here. Note that the controls work as attenuators: the maximum value is the -neutral position leaving the signal unchanged. Note that if the same destination -is mentioned in multiple controls, the signal is accumulated and can be wrapped -(set to maximal or minimal value without checking of overflow). +neutral position leaving the signal unchanged. Note that if the same destination +is mentioned in multiple controls, the signal is accumulated and can be clipped +(set to maximal or minimal value without checking for overflow). Explanation of used abbreviations: @@ -46,11 +46,11 @@ ADC analog to digital converter I2S one-way three wire serial bus for digital sound by Philips Semiconductors - (this standard is used for connecting standalone DAC and ADC converters) + (this standard is used for connecting standalone D/A and A/D converters) LFE - low frequency effects (subwoofer signal) + low frequency effects (used as subwoofer signal) AC97 - a chip containing an analog mixer, DAC and ADC converters + a chip containing an analog mixer, D/A and A/D converters IEC958 S/PDIF FX-bus @@ -61,61 +61,61 @@ FX-bus ``name='Wave Playback Volume',index=0`` --------------------------------------- -This control is used to attenuate samples for left and right PCM FX-bus +This control is used to attenuate samples from left and right PCM FX-bus accumulators. ALSA uses accumulators 0 and 1 for left and right PCM samples. The result samples are forwarded to the front DAC PCM slots of the AC97 codec. ``name='Wave Surround Playback Volume',index=0`` ------------------------------------------------ -This control is used to attenuate samples for left and right PCM FX-bus +This control is used to attenuate samples from left and right PCM FX-bus accumulators. ALSA uses accumulators 0 and 1 for left and right PCM samples. The result samples are forwarded to the rear I2S DACs. These DACs operates separately (they are not inside the AC97 codec). ``name='Wave Center Playback Volume',index=0`` ---------------------------------------------- -This control is used to attenuate samples for left and right PCM FX-bus +This control is used to attenuate samples from left and right PCM FX-bus accumulators. ALSA uses accumulators 0 and 1 for left and right PCM samples. The result is mixed to mono signal (single channel) and forwarded to the ??rear?? right DAC PCM slot of the AC97 codec. ``name='Wave LFE Playback Volume',index=0`` ------------------------------------------- -This control is used to attenuate samples for left and right PCM FX-bus +This control is used to attenuate samples from left and right PCM FX-bus accumulators. ALSA uses accumulators 0 and 1 for left and right PCM. The result is mixed to mono signal (single channel) and forwarded to the ??rear?? left DAC PCM slot of the AC97 codec. ``name='Wave Capture Volume',index=0``, ``name='Wave Capture Switch',index=0`` ------------------------------------------------------------------------------ -These controls are used to attenuate samples for left and right PCM FX-bus +These controls are used to attenuate samples from left and right PCM FX-bus accumulator. ALSA uses accumulators 0 and 1 for left and right PCM. The result is forwarded to the ADC capture FIFO (thus to the standard capture PCM device). ``name='Synth Playback Volume',index=0`` ---------------------------------------- -This control is used to attenuate samples for left and right MIDI FX-bus +This control is used to attenuate samples from left and right MIDI FX-bus accumulators. ALSA uses accumulators 4 and 5 for left and right MIDI samples. The result samples are forwarded to the front DAC PCM slots of the AC97 codec. ``name='Synth Capture Volume',index=0``, ``name='Synth Capture Switch',index=0`` -------------------------------------------------------------------------------- -These controls are used to attenuate samples for left and right MIDI FX-bus -accumulator. ALSA uses accumulators 4 and 5 for left and right PCM. +These controls are used to attenuate samples from left and right MIDI FX-bus +accumulator. ALSA uses accumulators 4 and 5 for left and right MIDI samples. The result is forwarded to the ADC capture FIFO (thus to the standard capture PCM device). ``name='Surround Playback Volume',index=0`` ------------------------------------------- -This control is used to attenuate samples for left and right rear PCM FX-bus +This control is used to attenuate samples from left and right rear PCM FX-bus accumulators. ALSA uses accumulators 2 and 3 for left and right rear PCM samples. The result samples are forwarded to the rear I2S DACs. These DACs operate separately (they are not inside the AC97 codec). ``name='Surround Capture Volume',index=0``, ``name='Surround Capture Switch',index=0`` -------------------------------------------------------------------------------------- -These controls are used to attenuate samples for left and right rear PCM FX-bus +These controls are used to attenuate samples from left and right rear PCM FX-bus accumulators. ALSA uses accumulators 2 and 3 for left and right rear PCM samples. The result is forwarded to the ADC capture FIFO (thus to the standard capture PCM device). @@ -134,7 +134,7 @@ to the ??rear?? left DAC PCM slot of the AC97 codec. ``name='AC97 Playback Volume',index=0`` --------------------------------------- -This control is used to attenuate samples for left and right front ADC PCM slots +This control is used to attenuate samples from left and right front ADC PCM slots of the AC97 codec. The result samples are forwarded to the front DAC PCM slots of the AC97 codec. @@ -145,7 +145,7 @@ slots of the AC97 codec. ``name='AC97 Capture Volume',index=0`` -------------------------------------- -This control is used to attenuate samples for left and right front ADC PCM slots +This control is used to attenuate samples from left and right front ADC PCM slots of the AC97 codec. The result is forwarded to the ADC capture FIFO (thus to the standard capture PCM device). @@ -258,7 +258,7 @@ PCM stream related controls ``name='EMU10K1 PCM Volume',index 0-31`` ---------------------------------------- -Channel volume attenuation in range 0-0xffff. The maximum value (no +Channel volume attenuation in range 0-0x1fffd. The middle value (no attenuation) is default. The channel mapping for three values is as follows: @@ -313,6 +313,9 @@ MANUALS/PATENTS ftp://opensource.creative.com/pub/doc ------------------------------------- +Note that the site is defunct, but the documents are available +from various other locations. + LM4545.pdf AC97 Codec m2049.pdf @@ -336,8 +339,8 @@ WO 9901953 (A1) Execution and Audio Data Sequencing (Jan. 14, 1999) -US Patents (http://www.uspto.gov/) ----------------------------------- +US Patents (https://www.uspto.gov/) +----------------------------------- US 5925841 Digital Sampling Instrument employing cache memory (Jul. 20, 1999) diff --git a/Documentation/sound/codecs/cs35l56.rst b/Documentation/sound/codecs/cs35l56.rst new file mode 100644 index 000000000000..57d1964453e1 --- /dev/null +++ b/Documentation/sound/codecs/cs35l56.rst @@ -0,0 +1,306 @@ +.. 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. diff --git a/Documentation/sound/codecs/index.rst b/Documentation/sound/codecs/index.rst new file mode 100644 index 000000000000..2cb95d87bbef --- /dev/null +++ b/Documentation/sound/codecs/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Codec-Specific Information +========================== + +.. toctree:: + :maxdepth: 2 + + cs35l56 diff --git a/Documentation/sound/designs/compress-accel.rst b/Documentation/sound/designs/compress-accel.rst new file mode 100644 index 000000000000..c9c1744b94c2 --- /dev/null +++ b/Documentation/sound/designs/compress-accel.rst @@ -0,0 +1,134 @@ +================================== +ALSA Co-processor Acceleration API +================================== + +Jaroslav Kysela <perex@perex.cz> + + +Overview +======== + +There is a requirement to expose the audio hardware that accelerates various +tasks for user space such as sample rate converters, compressed +stream decoders, etc. + +This is description for the API extension for the compress ALSA API which +is able to handle "tasks" that are not bound to real-time operations +and allows for the serialization of operations. + +Requirements +============ + +The main requirements are: + +- serialization of multiple tasks for user space to allow multiple + operations without user space intervention + +- separate buffers (input + output) for each operation + +- expose buffers using mmap to user space + +- signal user space when the task is finished (standard poll mechanism) + +Design +====== + +A new direction SND_COMPRESS_ACCEL is introduced to identify +the passthrough API. + +The API extension shares device enumeration and parameters handling from +the main compressed API. All other realtime streaming ioctls are deactivated +and a new set of task related ioctls are introduced. The standard +read/write/mmap I/O operations are not supported in the passthrough device. + +Device ("stream") state handling is reduced to OPEN/SETUP. All other +states are not available for the passthrough mode. + +Data I/O mechanism is using standard dma-buf interface with all advantages +like mmap, standard I/O, buffer sharing etc. One buffer is used for the +input data and second (separate) buffer is used for the output data. Each task +have separate I/O buffers. + +For the buffering parameters, the fragments means a limit of allocated tasks +for given device. The fragment_size limits the input buffer size for the given +device. The output buffer size is determined by the driver (may be different +from the input buffer size). + +State Machine +============= + +The passthrough audio stream state machine is described below:: + + +----------+ + | | + | OPEN | + | | + +----------+ + | + | + | compr_set_params() + | + v + all passthrough task ops +----------+ + +------------------------------------| | + | | SETUP | + | | + | +----------+ + | | + +------------------------------------------+ + + +Passthrough operations (ioctls) +=============================== + +All operations are protected using stream->device->lock (mutex). + +CREATE +------ +Creates a set of input/output buffers. The input buffer size is +fragment_size. Allocates unique seqno. + +The hardware drivers allocate internal 'struct dma_buf' for both input and +output buffers (using 'dma_buf_export()' function). The anonymous +file descriptors for those buffers are passed to user space. + +FREE +---- +Free a set of input/output buffers. If a task is active, the stop +operation is executed before. If seqno is zero, operation is executed for all +tasks. + +START +----- +Starts (queues) a task. There are two cases of the task start - right after +the task is created. In this case, origin_seqno must be zero. +The second case is for reusing of already finished task. The origin_seqno +must identify the task to be reused. In both cases, a new seqno value +is allocated and returned to user space. + +The prerequisite is that application filled input dma buffer with +new source data and set input_size to pass the real data size to the driver. + +The order of data processing is preserved (first started job must be +finished at first). + +If the multiple tasks require a state handling (e.g. resampling operation), +the user space may set SND_COMPRESS_TFLG_NEW_STREAM flag to mark the +start of the new stream data. It is useful to keep the allocated buffers +for the new operation rather using open/close mechanism. + +STOP +---- +Stop (dequeues) a task. If seqno is zero, operation is executed for all +tasks. + +STATUS +------ +Obtain the task status (active, finished). Also, the driver will set +the real output data size (valid area in the output buffer). + +Credits +======= +- Shengjiu Wang <shengjiu.wang@gmail.com> +- Takashi Iwai <tiwai@suse.de> +- Vinod Koul <vkoul@kernel.org> diff --git a/Documentation/sound/designs/compress-offload.rst b/Documentation/sound/designs/compress-offload.rst index ad4bfbdacc83..655624f77092 100644 --- a/Documentation/sound/designs/compress-offload.rst +++ b/Documentation/sound/designs/compress-offload.rst @@ -151,6 +151,57 @@ Modifications include: - Addition of encoding options when required (derived from OpenMAX IL) - Addition of rateControlSupported (missing in OpenMAX AL) +State Machine +============= + +The compressed audio stream state machine is described below :: + + +----------+ + | | + | OPEN | + | | + +----------+ + | + | + | compr_set_params() + | + v + compr_free() +----------+ + +------------------------------------| | + | | SETUP | + | +-------------------------| |<-------------------------+ + | | compr_write() +----------+ | + | | ^ | + | | | compr_drain_notify() | + | | | or | + | | | compr_stop() | + | | | | + | | +----------+ | + | | | | | + | | | DRAIN | | + | | | | | + | | +----------+ | + | | ^ | + | | | | + | | | compr_drain() | + | | | | + | v | | + | +----------+ +----------+ | + | | | compr_start() | | compr_stop() | + | | PREPARE |------------------->| RUNNING |--------------------------+ + | | | | | | + | +----------+ +----------+ | + | | | ^ | + | |compr_free() | | | + | | compr_pause() | | compr_resume() | + | | | | | + | v v | | + | +----------+ +----------+ | + | | | | | compr_stop() | + +--->| FREE | | PAUSE |---------------------------+ + | | | | + +----------+ +----------+ + Gapless Playback ================ @@ -199,6 +250,39 @@ Sequence flow for gapless would be: (note: order for partial_drain and write for next track can be reversed as well) +Gapless Playback SM +=================== + +For Gapless, we move from running state to partial drain and back, along +with setting of meta_data and signalling for next track :: + + + +----------+ + compr_drain_notify() | | + +------------------------>| RUNNING | + | | | + | +----------+ + | | + | | + | | compr_next_track() + | | + | V + | +----------+ + | compr_set_params() | | + | +-----------|NEXT_TRACK| + | | | | + | | +--+-------+ + | | | | + | +--------------+ | + | | + | | compr_partial_drain() + | | + | V + | +----------+ + | | | + +------------------------ | PARTIAL_ | + | DRAIN | + +----------+ Not supported ============= diff --git a/Documentation/sound/designs/control-names.rst b/Documentation/sound/designs/control-names.rst index 7fedd0f33cd9..765ff9b5b7d9 100644 --- a/Documentation/sound/designs/control-names.rst +++ b/Documentation/sound/designs/control-names.rst @@ -34,7 +34,7 @@ CHANNEL Front front left/right channels Surround rear left/right in 4.0/5.1 surround CLFE C/LFE channels -Center center cannel +Center center channel LFE LFE channel Side side left/right for 7.1 surround ============ ================================================== diff --git a/Documentation/sound/designs/index.rst b/Documentation/sound/designs/index.rst index f0749943ccb2..6b825c5617fc 100644 --- a/Documentation/sound/designs/index.rst +++ b/Documentation/sound/designs/index.rst @@ -6,6 +6,7 @@ Designs and Implementations control-names channel-mapping-api + compress-accel compress-offload timestamping jack-controls @@ -14,3 +15,5 @@ Designs and Implementations powersave oss-emulation seq-oss + jack-injection + midi-2.0 diff --git a/Documentation/sound/designs/jack-controls.rst b/Documentation/sound/designs/jack-controls.rst index ae25b1531bb0..e8a18f126a63 100644 --- a/Documentation/sound/designs/jack-controls.rst +++ b/Documentation/sound/designs/jack-controls.rst @@ -8,7 +8,7 @@ Why we need Jack kcontrols ALSA uses kcontrols to export audio controls(switch, volume, Mux, ...) to user space. This means userspace applications like pulseaudio can switch off headphones and switch on speakers when no headphones are -pluged in. +plugged in. The old ALSA jack code only created input devices for each registered jack. These jack input devices are not readable by userspace devices diff --git a/Documentation/sound/designs/jack-injection.rst b/Documentation/sound/designs/jack-injection.rst new file mode 100644 index 000000000000..f9790521523e --- /dev/null +++ b/Documentation/sound/designs/jack-injection.rst @@ -0,0 +1,166 @@ +============================ +ALSA Jack Software Injection +============================ + +Simple Introduction On Jack Injection +===================================== + +Here jack injection means users could inject plugin or plugout events +to the audio jacks through debugfs interface, it is helpful to +validate ALSA userspace changes. For example, we change the audio +profile switching code in the pulseaudio, and we want to verify if the +change works as expected and if the change introduce the regression, +in this case, we could inject plugin or plugout events to an audio +jack or to some audio jacks, we don't need to physically access the +machine and plug/unplug physical devices to the audio jack. + +In this design, an audio jack doesn't equal to a physical audio jack. +Sometimes a physical audio jack contains multi functions, and the +ALSA driver creates multi ``jack_kctl`` for a ``snd_jack``, here the +``snd_jack`` represents a physical audio jack and the ``jack_kctl`` +represents a function, for example a physical jack has two functions: +headphone and mic_in, the ALSA ASoC driver will build 2 ``jack_kctl`` +for this jack. The jack injection is implemented based on the +``jack_kctl`` instead of ``snd_jack``. + +To inject events to audio jacks, we need to enable the jack injection +via ``sw_inject_enable`` first, once it is enabled, this jack will not +change the state by hardware events anymore, we could inject plugin or +plugout events via ``jackin_inject`` and check the jack state via +``status``, after we finish our test, we need to disable the jack +injection via ``sw_inject_enable`` too, once it is disabled, the jack +state will be restored according to the last reported hardware events +and will change by future hardware events. + +The Layout of Jack Injection Interface +====================================== + +If users enable the SND_JACK_INJECTION_DEBUG in the kernel, the audio +jack injection interface will be created as below: +:: + + $debugfs_mount_dir/sound + |-- card0 + |-- |-- HDMI_DP_pcm_10_Jack + |-- |-- |-- jackin_inject + |-- |-- |-- kctl_id + |-- |-- |-- mask_bits + |-- |-- |-- status + |-- |-- |-- sw_inject_enable + |-- |-- |-- type + ... + |-- |-- HDMI_DP_pcm_9_Jack + |-- |-- jackin_inject + |-- |-- kctl_id + |-- |-- mask_bits + |-- |-- status + |-- |-- sw_inject_enable + |-- |-- type + |-- card1 + |-- HDMI_DP_pcm_5_Jack + |-- |-- jackin_inject + |-- |-- kctl_id + |-- |-- mask_bits + |-- |-- status + |-- |-- sw_inject_enable + |-- |-- type + ... + |-- Headphone_Jack + |-- |-- jackin_inject + |-- |-- kctl_id + |-- |-- mask_bits + |-- |-- status + |-- |-- sw_inject_enable + |-- |-- type + |-- Headset_Mic_Jack + |-- jackin_inject + |-- kctl_id + |-- mask_bits + |-- status + |-- sw_inject_enable + |-- type + +The Explanation Of The Nodes +====================================== + +kctl_id + read-only, get jack_kctl->kctl's id + :: + + sound/card1/Headphone_Jack# cat kctl_id + Headphone Jack + +mask_bits + read-only, get jack_kctl's supported events mask_bits + :: + + sound/card1/Headphone_Jack# cat mask_bits + 0x0001 HEADPHONE(0x0001) + +status + read-only, get jack_kctl's current status + +- headphone unplugged: + + :: + + sound/card1/Headphone_Jack# cat status + Unplugged + +- headphone plugged: + + :: + + sound/card1/Headphone_Jack# cat status + Plugged + +type + read-only, get snd_jack's supported events from type (all supported events on the physical audio jack) + :: + + sound/card1/Headphone_Jack# cat type + 0x7803 HEADPHONE(0x0001) MICROPHONE(0x0002) BTN_3(0x0800) BTN_2(0x1000) BTN_1(0x2000) BTN_0(0x4000) + +sw_inject_enable + read-write, enable or disable injection + +- injection disabled: + + :: + + sound/card1/Headphone_Jack# cat sw_inject_enable + Jack: Headphone Jack Inject Enabled: 0 + +- injection enabled: + + :: + + sound/card1/Headphone_Jack# cat sw_inject_enable + Jack: Headphone Jack Inject Enabled: 1 + +- to enable jack injection: + + :: + + sound/card1/Headphone_Jack# echo 1 > sw_inject_enable + +- to disable jack injection: + + :: + + sound/card1/Headphone_Jack# echo 0 > sw_inject_enable + +jackin_inject + write-only, inject plugin or plugout + +- to inject plugin: + + :: + + sound/card1/Headphone_Jack# echo 1 > jackin_inject + +- to inject plugout: + + :: + + sound/card1/Headphone_Jack# echo 0 > jackin_inject diff --git a/Documentation/sound/designs/midi-2.0.rst b/Documentation/sound/designs/midi-2.0.rst new file mode 100644 index 000000000000..71a343c93fe7 --- /dev/null +++ b/Documentation/sound/designs/midi-2.0.rst @@ -0,0 +1,584 @@ +================= +MIDI 2.0 on Linux +================= + +General +======= + +MIDI 2.0 is an extended protocol for providing higher resolutions and +more fine controls over the legacy MIDI 1.0. The fundamental changes +introduced for supporting MIDI 2.0 are: + +- Support of Universal MIDI Packet (UMP) +- Support of MIDI 2.0 protocol messages +- Transparent conversions between UMP and legacy MIDI 1.0 byte stream +- MIDI-CI for property and profile configurations + +UMP is a new container format to hold all MIDI protocol 1.0 and MIDI +2.0 protocol messages. Unlike the former byte stream, it's 32bit +aligned, and each message can be put in a single packet. UMP can send +the events up to 16 "UMP Groups", where each UMP Group contain up to +16 MIDI channels. + +MIDI 2.0 protocol is an extended protocol to achieve the higher +resolution and more controls over the old MIDI 1.0 protocol. + +MIDI-CI is a high-level protocol that can talk with the MIDI device +for the flexible profiles and configurations. It's represented in the +form of special SysEx. + +For Linux implementations, the kernel supports the UMP transport and +the encoding/decoding of MIDI protocols on UMP, while MIDI-CI is +supported in user-space over the standard SysEx. + +As of this writing, only USB MIDI device supports the UMP and Linux +2.0 natively. The UMP support itself is pretty generic, hence it +could be used by other transport layers, although it could be +implemented differently (e.g. as a ALSA sequencer client), too. + +The access to UMP devices are provided in two ways: the access via +rawmidi device and the access via ALSA sequencer API. + +ALSA sequencer API was extended to allow the payload of UMP packets. +It's allowed to connect freely between MIDI 1.0 and MIDI 2.0 sequencer +clients, and the events are converted transparently. + + +Kernel Configuration +==================== + +The following new configs are added for supporting MIDI 2.0: +`CONFIG_SND_UMP`, `CONFIG_SND_UMP_LEGACY_RAWMIDI`, +`CONFIG_SND_SEQ_UMP`, `CONFIG_SND_SEQ_UMP_CLIENT`, and +`CONFIG_SND_USB_AUDIO_MIDI_V2`. The first visible one is +`CONFIG_SND_USB_AUDIO_MIDI_V2`, and when you choose it (to set `=y`), +the core support for UMP (`CONFIG_SND_UMP`) and the sequencer binding +(`CONFIG_SND_SEQ_UMP_CLIENT`) will be automatically selected. + +Additionally, `CONFIG_SND_UMP_LEGACY_RAWMIDI=y` will enable the +support for the legacy raw MIDI device for UMP Endpoints. + + +Rawmidi Device with USB MIDI 2.0 +================================ + +When a device supports MIDI 2.0, the USB-audio driver probes and uses +the MIDI 2.0 interface (that is found always at the altset 1) as +default instead of the MIDI 1.0 interface (at altset 0). You can +switch back to the binding with the old MIDI 1.0 interface by passing +`midi2_enable=0` option to snd-usb-audio driver module, too. + +The USB audio driver tries to query the UMP Endpoint and UMP Function +Block information that are provided since UMP v1.1, and builds up the +topology based on those information. When the device is older and +doesn't respond to the new UMP inquiries, the driver falls back and +builds the topology based on Group Terminal Block (GTB) information +from the USB descriptor. Some device might be screwed up by the +unexpected UMP command; in such a case, pass `midi2_ump_probe=0` +option to snd-usb-audio driver for skipping the UMP v1.1 inquiries. + +When the MIDI 2.0 device is probed, the kernel creates a rawmidi +device for each UMP Endpoint of the device. Its device name is +`/dev/snd/umpC*D*` and different from the standard rawmidi device name +`/dev/snd/midiC*D*` for MIDI 1.0, in order to avoid confusing the +legacy applications accessing mistakenly to UMP devices. + +You can read and write UMP packet data directly from/to this UMP +rawmidi device. For example, reading via `hexdump` like below will +show the incoming UMP packets of the card 0 device 0 in the hex +format:: + + % hexdump -C /dev/snd/umpC0D0 + 00000000 01 07 b0 20 00 07 b0 20 64 3c 90 20 64 3c 80 20 |... ... d<. d<. | + +Unlike the MIDI 1.0 byte stream, UMP is a 32bit packet, and the size +for reading or writing the device is also aligned to 32bit (which is 4 +bytes). + +The 32-bit words in the UMP packet payload are always in CPU native +endianness. Transport drivers are responsible to convert UMP words +from / to system endianness to required transport endianness / byte +order. + +When `CONFIG_SND_UMP_LEGACY_RAWMIDI` is set, the driver creates +another standard raw MIDI device additionally as `/dev/snd/midiC*D*`. +This contains 16 substreams, and each substream corresponds to a +(0-based) UMP Group. Legacy applications can access to the specified +group via each substream in MIDI 1.0 byte stream format. With the +ALSA rawmidi API, you can open the arbitrary substream, while just +opening `/dev/snd/midiC*D*` will end up with opening the first +substream. + +Each UMP Endpoint can provide the additional information, constructed +from the information inquired via UMP 1.1 Stream messages or USB MIDI +2.0 descriptors. And a UMP Endpoint may contain one or more UMP +Blocks, where UMP Block is an abstraction introduced in the ALSA UMP +implementations to represent the associations among UMP Groups. UMP +Block corresponds to Function Block in UMP 1.1 specification. When +UMP 1.1 Function Block information isn't available, it's filled +partially from Group Terminal Block (GTB) as defined in USB MIDI 2.0 +specifications. + +The information of UMP Endpoints and UMP Blocks are found in the proc +file `/proc/asound/card*/midi*`. For example:: + + % cat /proc/asound/card1/midi0 + ProtoZOA MIDI + + Type: UMP + EP Name: ProtoZOA + EP Product ID: ABCD12345678 + UMP Version: 0x0000 + Protocol Caps: 0x00000100 + Protocol: 0x00000100 + Num Blocks: 3 + + Block 0 (ProtoZOA Main) + Direction: bidirection + Active: Yes + Groups: 1-1 + Is MIDI1: No + + Block 1 (ProtoZOA Ext IN) + Direction: output + Active: Yes + Groups: 2-2 + Is MIDI1: Yes (Low Speed) + .... + +Note that `Groups` field shown in the proc file above indicates the +1-based UMP Group numbers (from-to). + +Those additional UMP Endpoint and UMP Block information can be +obtained via the new ioctls `SNDRV_UMP_IOCTL_ENDPOINT_INFO` and +`SNDRV_UMP_IOCTL_BLOCK_INFO`, respectively. + +The rawmidi name and the UMP Endpoint name are usually identical, and +in the case of USB MIDI, it's taken from `iInterface` of the +corresponding USB MIDI interface descriptor. If it's not provided, +it's copied from `iProduct` of the USB device descriptor as a +fallback. + +The Endpoint Product ID is a string field and supposed to be unique. +It's copied from `iSerialNumber` of the device for USB MIDI. + +The protocol capabilities and the actual protocol bits are defined in +`asound.h`. + + +ALSA Sequencer with USB MIDI 2.0 +================================ + +In addition to the rawmidi interfaces, ALSA sequencer interface +supports the new UMP MIDI 2.0 device, too. Now, each ALSA sequencer +client may set its MIDI version (0, 1 or 2) to declare itself being +either the legacy, UMP MIDI 1.0 or UMP MIDI 2.0 device, respectively. +The first, legacy client is the one that sends/receives the old +sequencer event as was. Meanwhile, UMP MIDI 1.0 and 2.0 clients send +and receive in the extended event record for UMP. The MIDI version is +seen in the new `midi_version` field of `snd_seq_client_info`. + +A UMP packet can be sent/received in a sequencer event embedded by +specifying the new event flag bit `SNDRV_SEQ_EVENT_UMP`. When this +flag is set, the event has 16 byte (128 bit) data payload for holding +the UMP packet. Without the `SNDRV_SEQ_EVENT_UMP` bit flag, the event +is treated as a legacy event as it was (with max 12 byte data +payload). + +With `SNDRV_SEQ_EVENT_UMP` flag set, the type field of a UMP sequencer +event is ignored (but it should be set to 0 as default). + +The type of each client can be seen in `/proc/asound/seq/clients`. +For example:: + + % cat /proc/asound/seq/clients + Client info + cur clients : 3 + .... + Client 14 : "Midi Through" [Kernel Legacy] + Port 0 : "Midi Through Port-0" (RWe-) + Client 20 : "ProtoZOA" [Kernel UMP MIDI1] + UMP Endpoint: ProtoZOA + UMP Block 0: ProtoZOA Main [Active] + Groups: 1-1 + UMP Block 1: ProtoZOA Ext IN [Active] + Groups: 2-2 + UMP Block 2: ProtoZOA Ext OUT [Active] + Groups: 3-3 + Port 0 : "MIDI 2.0" (RWeX) [In/Out] + Port 1 : "ProtoZOA Main" (RWeX) [In/Out] + Port 2 : "ProtoZOA Ext IN" (-We-) [Out] + Port 3 : "ProtoZOA Ext OUT" (R-e-) [In] + +Here you can find two types of kernel clients, "Legacy" for client 14, +and "UMP MIDI1" for client 20, which is a USB MIDI 2.0 device. +A USB MIDI 2.0 client gives always the port 0 as "MIDI 2.0" and the +rest ports from 1 for each UMP Group (e.g. port 1 for Group 1). +In this example, the device has three active groups (Main, Ext IN and +Ext OUT), and those are exposed as sequencer ports from 1 to 3. +The "MIDI 2.0" port is for a UMP Endpoint, and its difference from +other UMP Group ports is that UMP Endpoint port sends the events from +the all ports on the device ("catch-all"), while each UMP Group port +sends only the events from the given UMP Group. +Also, UMP groupless messages (such as the UMP message type 0x0f) are +sent only to the UMP Endpoint port. + +Note that, although each UMP sequencer client usually creates 16 +ports, those ports that don't belong to any UMP Blocks (or belonging +to inactive UMP Blocks) are marked as inactive, and they don't appear +in the proc outputs. In the example above, the sequencer ports from 4 +to 16 are present but not shown there. + +The proc file above shows the UMP Block information, too. The same +entry (but with more detailed information) is found in the rawmidi +proc output. + +When clients are connected between different MIDI versions, the events +are translated automatically depending on the client's version, not +only between the legacy and the UMP MIDI 1.0/2.0 types, but also +between UMP MIDI 1.0 and 2.0 types, too. For example, running +`aseqdump` program on the ProtoZOA Main port in the legacy mode will +give you the output like:: + + % aseqdump -p 20:1 + Waiting for data. Press Ctrl+C to end. + Source Event Ch Data + 20:1 Note on 0, note 60, velocity 100 + 20:1 Note off 0, note 60, velocity 100 + 20:1 Control change 0, controller 11, value 4 + +When you run `aseqdump` in MIDI 2.0 mode, it'll receive the high +precision data like:: + + % aseqdump -u 2 -p 20:1 + Waiting for data. Press Ctrl+C to end. + Source Event Ch Data + 20:1 Note on 0, note 60, velocity 0xc924, attr type = 0, data = 0x0 + 20:1 Note off 0, note 60, velocity 0xc924, attr type = 0, data = 0x0 + 20:1 Control change 0, controller 11, value 0x2000000 + +while the data is automatically converted by ALSA sequencer core. + + +Rawmidi API Extensions +====================== + +* The additional UMP Endpoint information can be obtained via the new + ioctl `SNDRV_UMP_IOCTL_ENDPOINT_INFO`. It contains the associated + card and device numbers, the bit flags, the protocols, the number of + UMP Blocks, the name string of the endpoint, etc. + + The protocols are specified in two field, the protocol capabilities + and the current protocol. Both contain the bit flags specifying the + MIDI protocol version (`SNDRV_UMP_EP_INFO_PROTO_MIDI1` or + `SNDRV_UMP_EP_INFO_PROTO_MIDI2`) in the upper byte and the jitter + reduction timestamp (`SNDRV_UMP_EP_INFO_PROTO_JRTS_TX` and + `SNDRV_UMP_EP_INFO_PROTO_JRTS_RX`) in the lower byte. + + A UMP Endpoint may contain up to 32 UMP Blocks, and the number of + the currently assigned blocks are shown in the Endpoint information. + +* Each UMP Block information can be obtained via another new ioctl + `SNDRV_UMP_IOCTL_BLOCK_INFO`. The block ID number (0-based) has to + be passed for the block to query. The received data contains the + associated the direction of the block, the first associated group ID + (0-based) and the number of groups, the name string of the block, + etc. + + The direction is either `SNDRV_UMP_DIR_INPUT`, + `SNDRV_UMP_DIR_OUTPUT` or `SNDRV_UMP_DIR_BIDIRECTION`. + +* For the device supports UMP v1.1, the UMP MIDI protocol can be + switched via "Stream Configuration Request" message (UMP type 0x0f, + status 0x05). When UMP core receives such a message, it updates the + UMP EP info and the corresponding sequencer clients as well. + +* The legacy rawmidi device number is found in the new `tied_device` + field of the rawmidi info. + On the other hand, the UMP rawmidi device number is found in + `tied_device` field of the legacy rawmidi info, too. + +* Each substream of the legacy rawmidi may be enabled / disabled + dynamically depending on the UMP FB state. + When the selected substream is inactive, it's indicated by the bit + 0x10 (`SNDRV_RAWMIDI_INFO_STREAM_INACTIVE`) in the `flags` field of + the legacy rawmidi info. + + +Control API Extensions +====================== + +* The new ioctl `SNDRV_CTL_IOCTL_UMP_NEXT_DEVICE` is introduced for + querying the next UMP rawmidi device, while the existing ioctl + `SNDRV_CTL_IOCTL_RAWMIDI_NEXT_DEVICE` queries only the legacy + rawmidi devices. + + For setting the subdevice (substream number) to be opened, use the + ioctl `SNDRV_CTL_IOCTL_RAWMIDI_PREFER_SUBDEVICE` like the normal + rawmidi. + +* Two new ioctls `SNDRV_CTL_IOCTL_UMP_ENDPOINT_INFO` and + `SNDRV_CTL_IOCTL_UMP_BLOCK_INFO` provide the UMP Endpoint and UMP + Block information of the specified UMP device via ALSA control API + without opening the actual (UMP) rawmidi device. + The `card` field is ignored upon inquiry, always tied with the card + of the control interface. + + +Sequencer API Extensions +======================== + +* `midi_version` field is added to `snd_seq_client_info` to indicate + the current MIDI version (either 0, 1 or 2) of each client. + When `midi_version` is 1 or 2, the alignment of read from a UMP + sequencer client is also changed from the former 28 bytes to 32 + bytes for the extended payload. The alignment size for the write + isn't changed, but each event size may differ depending on the new + bit flag below. + +* `SNDRV_SEQ_EVENT_UMP` flag bit is added for each sequencer event + flags. When this bit flag is set, the sequencer event is extended + to have a larger payload of 16 bytes instead of the legacy 12 + bytes, and the event contains the UMP packet in the payload. + +* The new sequencer port type bit (`SNDRV_SEQ_PORT_TYPE_MIDI_UMP`) + indicates the port being UMP-capable. + +* The sequencer ports have new capability bits to indicate the + inactive ports (`SNDRV_SEQ_PORT_CAP_INACTIVE`) and the UMP Endpoint + port (`SNDRV_SEQ_PORT_CAP_UMP_ENDPOINT`). + +* The event conversion of ALSA sequencer clients can be suppressed the + new filter bit `SNDRV_SEQ_FILTER_NO_CONVERT` set to the client info. + For example, the kernel pass-through client (`snd-seq-dummy`) sets + this flag internally. + +* The port information gained the new field `direction` to indicate + the direction of the port (either `SNDRV_SEQ_PORT_DIR_INPUT`, + `SNDRV_SEQ_PORT_DIR_OUTPUT` or `SNDRV_SEQ_PORT_DIR_BIDIRECTION`). + +* Another additional field for the port information is `ump_group` + which specifies the associated UMP Group Number (1-based). + When it's non-zero, the UMP group field in the UMP packet updated + upon delivery to the specified group (corrected to be 0-based). + Each sequencer port is supposed to set this field if it's a port to + specific to a certain UMP group. + +* Each client may set the additional event filter for UMP Groups in + `group_filter` bitmap. The filter consists of bitmap from 1-based + Group numbers. For example, when the bit 1 is set, messages from + Group 1 (i.e. the very first group) are filtered and not delivered. + The bit 0 is used for filtering UMP groupless messages. + +* Two new ioctls are added for UMP-capable clients: + `SNDRV_SEQ_IOCTL_GET_CLIENT_UMP_INFO` and + `SNDRV_SEQ_IOCTL_SET_CLIENT_UMP_INFO`. They are used to get and set + either `snd_ump_endpoint_info` or `snd_ump_block_info` data + associated with the sequencer client. The USB MIDI driver provides + those information from the underlying UMP rawmidi, while a + user-space client may provide its own data via `*_SET` ioctl. + For an Endpoint data, pass 0 to the `type` field, while for a Block + data, pass the block number + 1 to the `type` field. + Setting the data for a kernel client shall result in an error. + +* With UMP 1.1, Function Block information may be changed + dynamically. When the update of Function Block is received from the + device, ALSA sequencer core changes the corresponding sequencer port + name and attributes accordingly, and notifies the changes via the + announcement to the ALSA sequencer system port, similarly like the + normal port change notification. + +* There are two extended event types for notifying the UMP Endpoint and + Function Block changes via the system announcement port: + type 68 (`SNDRV_SEQ_EVENT_UMP_EP_CHANGE`) and type 69 + (`SNDRV_SEQ_EVENT_UMP_BLOCK_CHANGE`). They take the new type, + `snd_seq_ev_ump_notify` in the payload, indicating the client number + and the FB number that are changed. + + +MIDI2 USB Gadget Function Driver +================================ + +The latest kernel contains the support for USB MIDI 2.0 gadget +function driver, which can be used for prototyping and debugging MIDI +2.0 features. + +`CONFIG_USB_GADGET`, `CONFIG_USB_CONFIGFS` and +`CONFIG_USB_CONFIGFS_F_MIDI2` need to be enabled for the MIDI2 gadget +driver. + +In addition, for using a gadget driver, you need a working UDC driver. +In the example below, we use `dummy_hcd` driver (enabled via +`CONFIG_USB_DUMMY_HCD`) that is available on PC and VM for debugging +purpose. There are other UDC drivers depending on the platform, and +those can be used for a real device, instead, too. + +At first, on a system to run the gadget, load `libcomposite` module:: + + % modprobe libcomposite + +and you'll have `usb_gadget` subdirectory under configfs space +(typically `/sys/kernel/config` on modern OS). Then create a gadget +instance and add configurations there, for example:: + + % cd /sys/kernel/config + % mkdir usb_gadget/g1 + + % cd usb_gadget/g1 + % mkdir configs/c.1 + % mkdir functions/midi2.usb0 + + % echo 0x0004 > idProduct + % echo 0x17b3 > idVendor + % mkdir strings/0x409 + % echo "ACME Enterprises" > strings/0x409/manufacturer + % echo "ACMESynth" > strings/0x409/product + % echo "ABCD12345" > strings/0x409/serialnumber + + % mkdir configs/c.1/strings/0x409 + % echo "Monosynth" > configs/c.1/strings/0x409/configuration + % echo 120 > configs/c.1/MaxPower + +At this point, there must be a subdirectory `ep.0`, and that is the +configuration for a UMP Endpoint. You can fill the Endpoint +information like:: + + % echo "ACMESynth" > functions/midi2.usb0/iface_name + % echo "ACMESynth" > functions/midi2.usb0/ep.0/ep_name + % echo "ABCD12345" > functions/midi2.usb0/ep.0/product_id + % echo 0x0123 > functions/midi2.usb0/ep.0/family + % echo 0x4567 > functions/midi2.usb0/ep.0/model + % echo 0x123456 > functions/midi2.usb0/ep.0/manufacturer + % echo 0x12345678 > functions/midi2.usb0/ep.0/sw_revision + +The default MIDI protocol can be set either 1 or 2:: + + % echo 2 > functions/midi2.usb0/ep.0/protocol + +And, you can find a subdirectory `block.0` under this Endpoint +subdirectory. This defines the Function Block information:: + + % echo "Monosynth" > functions/midi2.usb0/ep.0/block.0/name + % echo 0 > functions/midi2.usb0/ep.0/block.0/first_group + % echo 1 > functions/midi2.usb0/ep.0/block.0/num_groups + +Finally, link the configuration and enable it:: + + % ln -s functions/midi2.usb0 configs/c.1 + % echo dummy_udc.0 > UDC + +where `dummy_udc.0` is an example case and it differs depending on the +system. You can find the UDC instances in `/sys/class/udc` and pass +the found name instead:: + + % ls /sys/class/udc + dummy_udc.0 + +Now, the MIDI 2.0 gadget device is enabled, and the gadget host +creates a new sound card instance containing a UMP rawmidi device by +`f_midi2` driver:: + + % cat /proc/asound/cards + .... + 1 [Gadget ]: f_midi2 - MIDI 2.0 Gadget + MIDI 2.0 Gadget + +And on the connected host, a similar card should appear, too, but with +the card and device names given in the configfs above:: + + % cat /proc/asound/cards + .... + 2 [ACMESynth ]: USB-Audio - ACMESynth + ACME Enterprises ACMESynth at usb-dummy_hcd.0-1, high speed + +You can play a MIDI file on the gadget side:: + + % aplaymidi -p 20:1 to_host.mid + +and this will appear as an input from a MIDI device on the connected +host:: + + % aseqdump -p 20:0 -u 2 + +Vice versa, a playback on the connected host will work as an input on +the gadget, too. + +Each Function Block may have different direction and UI-hint, +specified via `direction` and `ui_hint` attributes. +Passing `1` is for input-only, `2` for out-only and `3` for +bidirectional (the default value). For example:: + + % echo 2 > functions/midi2.usb0/ep.0/block.0/direction + % echo 2 > functions/midi2.usb0/ep.0/block.0/ui_hint + +When you need more than one Function Blocks, you can create +subdirectories `block.1`, `block.2`, etc dynamically, and configure +them in the configuration procedure above before linking. +For example, to create a second Function Block for a keyboard:: + + % mkdir functions/midi2.usb0/ep.0/block.1 + % echo "Keyboard" > functions/midi2.usb0/ep.0/block.1/name + % echo 1 > functions/midi2.usb0/ep.0/block.1/first_group + % echo 1 > functions/midi2.usb0/ep.0/block.1/num_groups + % echo 1 > functions/midi2.usb0/ep.0/block.1/direction + % echo 1 > functions/midi2.usb0/ep.0/block.1/ui_hint + +The `block.*` subdirectories can be removed dynamically, too (except +for `block.0` which is persistent). + +For assigning a Function Block for MIDI 1.0 I/O, set up in `is_midi1` +attribute. 1 is for MIDI 1.0, and 2 is for MIDI 1.0 with low speed +connection:: + + % echo 2 > functions/midi2.usb0/ep.0/block.1/is_midi1 + +For disabling the processing of UMP Stream messages in the gadget +driver, pass `0` to `process_ump` attribute in the top-level config:: + + % echo 0 > functions/midi2.usb0/process_ump + +The MIDI 1.0 interface at altset 0 is supported by the gadget driver, +too. When MIDI 1.0 interface is selected by the connected host, the +UMP I/O on the gadget is translated from/to USB MIDI 1.0 packets +accordingly while the gadget driver keeps communicating with the +user-space over UMP rawmidi. + +MIDI 1.0 ports are set up from the config in each Function Block. +For example:: + + % echo 0 > functions/midi2.usb0/ep.0/block.0/midi1_first_group + % echo 1 > functions/midi2.usb0/ep.0/block.0/midi1_num_groups + +The configuration above will enable the Group 1 (the index 0) for MIDI +1.0 interface. Note that those groups must be in the groups defined +for the Function Block itself. + +The gadget driver supports more than one UMP Endpoints, too. +Similarly like the Function Blocks, you can create a new subdirectory +`ep.1` (but under the card top-level config) to enable a new Endpoint:: + + % mkdir functions/midi2.usb0/ep.1 + +and create a new Function Block there. For example, to create 4 +Groups for the Function Block of this new Endpoint:: + + % mkdir functions/midi2.usb0/ep.1/block.0 + % echo 4 > functions/midi2.usb0/ep.1/block.0/num_groups + +Now, you'll have 4 rawmidi devices in total: the first two are UMP +rawmidi devices for Endpoint 0 and Endpoint 1, and other two for the +legacy MIDI 1.0 rawmidi devices corresponding to both EP 0 and EP 1. + +The current altsetting on the gadget can be informed via a control +element "Operation Mode" with `RAWMIDI` iface. e.g. you can read it +via `amixer` program running on the gadget host like:: + + % amixer -c1 cget iface=RAWMIDI,name='Operation Mode' + ; type=INTEGER,access=r--v----,values=1,min=0,max=2,step=0 + : values=2 + +The value (shown in the second returned line with `: values=`) +indicates 1 for MIDI 1.0 (altset 0), 2 for MIDI 2.0 (altset 1) and 0 +for unset. + +As of now, the configurations can't be changed after binding. diff --git a/Documentation/sound/designs/powersave.rst b/Documentation/sound/designs/powersave.rst index 138157452eb9..ca7d1e838b4d 100644 --- a/Documentation/sound/designs/powersave.rst +++ b/Documentation/sound/designs/powersave.rst @@ -25,15 +25,15 @@ operations. The ``power_save`` option is exported as writable. This means you can adjust the value via sysfs on the fly. For example, to turn on the automatic power-save mode with 10 seconds, write to -``/sys/modules/snd_ac97_codec/parameters/power_save`` (usually as root): +``/sys/module/snd_ac97_codec/parameters/power_save`` (usually as root): :: - # echo 10 > /sys/modules/snd_ac97_codec/parameters/power_save + # echo 10 > /sys/module/snd_ac97_codec/parameters/power_save Note that you might hear click noise/pop when changing the power state. Also, it often takes certain time to wake up from the -power-down to the active state. These are often hardly to fix, so +power-down to the active state. These are often hard to fix, so don't report extra bug reports unless you have a fix patch ;-) For HD-audio interface, there is another module option, diff --git a/Documentation/sound/designs/procfile.rst b/Documentation/sound/designs/procfile.rst index 29a466851fd2..e9f7e0cbdc5f 100644 --- a/Documentation/sound/designs/procfile.rst +++ b/Documentation/sound/designs/procfile.rst @@ -91,7 +91,7 @@ PCM Proc Files ``card*/pcm*/xrun_debug`` This file appears when ``CONFIG_SND_DEBUG=y`` and - ``CONFIG_PCM_XRUN_DEBUG=y``. + ``CONFIG_SND_PCM_XRUN_DEBUG=y``. This shows the status of xrun (= buffer overrun/xrun) and invalid PCM position debug/check of ALSA PCM middle layer. It takes an integer value, can be changed by writing to this diff --git a/Documentation/sound/designs/seq-oss.rst b/Documentation/sound/designs/seq-oss.rst index e82ffe0e7f43..ec6304a07441 100644 --- a/Documentation/sound/designs/seq-oss.rst +++ b/Documentation/sound/designs/seq-oss.rst @@ -96,7 +96,7 @@ if you use an AWE64 card, you'll see like the following: Number of synth devices: 1 synth 0: [EMU8000] type 0x1 : subtype 0x20 : voices 32 - capabilties : ioctl enabled / load_patch enabled + capabilities : ioctl enabled / load_patch enabled Number of MIDI devices: 3 midi 0: [Emu8000 Port-0] ALSA port 65:0 diff --git a/Documentation/sound/designs/timestamping.rst b/Documentation/sound/designs/timestamping.rst index 2b0fff503415..7c7ecf5dbc4b 100644 --- a/Documentation/sound/designs/timestamping.rst +++ b/Documentation/sound/designs/timestamping.rst @@ -143,7 +143,7 @@ timestamp shows when the information is put together by the driver before returning from the ``STATUS`` and ``STATUS_EXT`` ioctl. in most cases this driver_timestamp will be identical to the regular system tstamp. -Examples of typestamping with HDaudio: +Examples of timestamping with HDAudio: 1. DMA timestamp, no compensation for DMA+analog delay :: diff --git a/Documentation/sound/designs/tracepoints.rst b/Documentation/sound/designs/tracepoints.rst index 78bc5572f829..b0a7e3010187 100644 --- a/Documentation/sound/designs/tracepoints.rst +++ b/Documentation/sound/designs/tracepoints.rst @@ -34,20 +34,20 @@ substream. In this procedure, PCM hardware parameters are decided by interaction between applications and ALSA PCM core. Once decided, runtime of the PCM substream keeps the parameters. -The parameters are described in :c:type:`struct snd_pcm_hw_params`. This +The parameters are described in struct snd_pcm_hw_params. This structure includes several types of parameters. Applications set preferable value to these parameters, then execute ioctl(2) with SNDRV_PCM_IOCTL_HW_REFINE or SNDRV_PCM_IOCTL_HW_PARAMS. The former is used just for refining available set of parameters. The latter is used for an actual decision of the parameters. -The :c:type:`struct snd_pcm_hw_params` structure has below members: +The struct snd_pcm_hw_params structure has below members: ``flags`` Configurable. ALSA PCM core and some drivers handle this flag to select convenient parameters or change their behaviour. ``masks`` Configurable. This type of parameter is described in - :c:type:`struct snd_mask` and represent mask values. As of PCM protocol + struct snd_mask and represent mask values. As of PCM protocol v2.0.13, three types are defined. - SNDRV_PCM_HW_PARAM_ACCESS @@ -55,7 +55,7 @@ The :c:type:`struct snd_pcm_hw_params` structure has below members: - SNDRV_PCM_HW_PARAM_SUBFORMAT ``intervals`` Configurable. This type of parameter is described in - :c:type:`struct snd_interval` and represent values with a range. As of + struct snd_interval and represent values with a range. As of PCM protocol v2.0.13, twelve types are defined. - SNDRV_PCM_HW_PARAM_SAMPLE_BITS @@ -78,7 +78,7 @@ The :c:type:`struct snd_pcm_hw_params` structure has below members: are going to be changed. ``cmask`` Read-only. After returning from ioctl(2), buffer in user space for - :c:type:`struct snd_pcm_hw_params` includes result of each operation. + struct snd_pcm_hw_params includes result of each operation. This mask represents which mask/interval parameter is actually changed. ``info`` Read-only. This represents hardware/driver capabilities as bit flags @@ -110,10 +110,10 @@ The :c:type:`struct snd_pcm_hw_params` structure has below members: value to this parameter but some drivers intentionally set zero with a care of hardware design or data transmission protocol. -ALSA PCM core handles buffer of :c:type:`struct snd_pcm_hw_params` when +ALSA PCM core handles buffer of struct snd_pcm_hw_params when applications execute ioctl(2) with SNDRV_PCM_HW_REFINE or SNDRV_PCM_HW_PARAMS. Parameters in the buffer are changed according to -:c:type:`struct snd_pcm_hardware` and rules of constraints in the runtime. The +struct snd_pcm_hardware and rules of constraints in the runtime. The structure describes capabilities of handled hardware. The rules describes dependencies on which a parameter is decided according to several parameters. A rule has a callback function, and drivers can register arbitrary functions @@ -121,17 +121,17 @@ to compute the target parameter. ALSA PCM core registers some rules to the runtime as a default. Each driver can join in the interaction as long as it prepared for two stuffs -in a callback of :c:type:`struct snd_pcm_ops.open`. +in a callback of struct snd_pcm_ops.open. 1. In the callback, drivers are expected to change a member of - :c:type:`struct snd_pcm_hardware` type in the runtime, according to + struct snd_pcm_hardware type in the runtime, according to capacities of corresponding hardware. 2. In the same callback, drivers are also expected to register additional rules of constraints into the runtime when several parameters have dependencies due to hardware design. The driver can refers to result of the interaction in a callback of -:c:type:`struct snd_pcm_ops.hw_params`, however it should not change the +struct snd_pcm_ops.hw_params, however it should not change the content. Tracepoints in this category are designed to trace changes of the @@ -163,7 +163,7 @@ fields are different according to type of the parameter. For parameters of mask type, the fields represent hexadecimal dump of content of the parameter. For parameters of interval type, the fields represent values of each member of ``empty``, ``integer``, ``openmin``, ``min``, ``max``, ``openmax`` in -:c:type:`struct snd_interval` in this order. +struct snd_interval in this order. Tracepoints in drivers ====================== diff --git a/Documentation/sound/hd-audio/controls.rst b/Documentation/sound/hd-audio/controls.rst index f2ebc4f79b44..dbe6483f4ff4 100644 --- a/Documentation/sound/hd-audio/controls.rst +++ b/Documentation/sound/hd-audio/controls.rst @@ -102,7 +102,7 @@ Conexant codecs --------------- Auto-Mute Mode - See Reatek codecs. + See Realtek codecs. Analog codecs diff --git a/Documentation/sound/hd-audio/index.rst b/Documentation/sound/hd-audio/index.rst index 6e12de9fc34e..baefe4a5d165 100644 --- a/Documentation/sound/hd-audio/index.rst +++ b/Documentation/sound/hd-audio/index.rst @@ -9,3 +9,4 @@ HD-Audio controls dp-mst realtek-pc-beep + intel-multi-link diff --git a/Documentation/sound/hd-audio/intel-multi-link.rst b/Documentation/sound/hd-audio/intel-multi-link.rst new file mode 100644 index 000000000000..bf0bb78833e7 --- /dev/null +++ b/Documentation/sound/hd-audio/intel-multi-link.rst @@ -0,0 +1,312 @@ +.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-3-Clause) +.. include:: <isonum.txt> + +================================================ +HDAudio multi-link extensions on Intel platforms +================================================ + +:Copyright: |copy| 2023 Intel Corporation + +This file documents the 'multi-link structure' introduced in 2015 with +the Skylake processor and recently extended in newer Intel platforms + +HDaudio existing link mapping (2015 addition in SkyLake) +======================================================== + +External HDAudio codecs are handled with link #0, while iDISP codec +for HDMI/DisplayPort is handled with link #1. + +The only change to the 2015 definitions is the declaration of the +LCAP.ALT=0x0 - since the ALT bit was previously reserved, this is a +backwards-compatible change. + +LCTL.SPA and LCTL.CPA are automatically set when exiting reset. They +are only used in existing drivers when the SCF value needs to be +corrected. + +Basic structure for HDaudio codecs +---------------------------------- + +:: + + +-----------+ + | ML cap #0 | + +-----------+ + | ML cap #1 |---+ + +-----------+ | + | + +--> 0x0 +---------------+ LCAP + | ALT=0 | + +---------------+ + | S192 | + +---------------+ + | S96 | + +---------------+ + | S48 | + +---------------+ + | S24 | + +---------------+ + | S12 | + +---------------+ + | S6 | + +---------------+ + + 0x4 +---------------+ LCTL + | INTSTS | + +---------------+ + | CPA | + +---------------+ + | SPA | + +---------------+ + | SCF | + +---------------+ + + 0x8 +---------------+ LOSIDV + | L1OSIVD15 | + +---------------+ + | L1OSIDV.. | + +---------------+ + | L1OSIDV1 | + +---------------+ + + 0xC +---------------+ LSDIID + | SDIID14 | + +---------------+ + | SDIID... | + +---------------+ + | SDIID0 | + +---------------+ + +SoundWire HDaudio extended link mapping +======================================= + +A SoundWire extended link is identified when LCAP.ALT=1 and +LEPTR.ID=0. + +DMA control uses the existing LOSIDV register. + +Changes include additional descriptions for enumeration that were not +present in earlier generations. + +- multi-link synchronization: capabilities in LCAP.LSS and control in LSYNC +- number of sublinks (manager IP) in LCAP.LSCOUNT +- power management moved from SHIM to LCTL.SPA bits +- hand-over to the DSP for access to multi-link registers, SHIM/IP with LCTL.OFLEN +- mapping of SoundWire codecs to SDI ID bits +- move of SHIM and Cadence registers to different offsets, with no + change in functionality. The LEPTR.PTR value is an offset from the + ML address, with a default value of 0x30000. + +Extended structure for SoundWire (assuming 4 Manager IP) +-------------------------------------------------------- + +:: + + +-----------+ + | ML cap #0 | + +-----------+ + | ML cap #1 | + +-----------+ + | ML cap #2 |---+ + +-----------+ | + | + +--> 0x0 +---------------+ LCAP + | ALT=1 | + +---------------+ + | INTC | + +---------------+ + | OFLS | + +---------------+ + | LSS | + +---------------+ + | SLCOUNT=4 |-----------+ + +---------------+ | + | + 0x4 +---------------+ LCTL | + | INTSTS | | + +---------------+ | + | CPA (x bits) | | + +---------------+ | + | SPA (x bits) | | + +---------------+ for each sublink x + | INTEN | | + +---------------+ | + | OFLEN | | + +---------------+ | + | + 0x8 +---------------+ LOSIDV | + | L1OSIVD15 | | + +---------------+ | + | L1OSIDV.. | | + +---------------+ | + | L1OSIDV1 | +---+----------------------------------------------------------+ + +---------------+ | | + v | + 0xC + 0x2 * x +---------------+ LSDIIDx +---> 0x30000 +-----------------+ 0x00030000 | + | SDIID14 | | | SoundWire SHIM | | + +---------------+ | | generic | | + | SDIID... | | +-----------------+ 0x00030100 | + +---------------+ | | SoundWire IP | | + | SDIID0 | | +-----------------+ 0x00036000 | + +---------------+ | | SoundWire SHIM | | + | | vendor-specific | | + 0x1C +---------------+ LSYNC | +-----------------+ | + | CMDSYNC | | v + +---------------+ | +-----------------+ 0x00030000 + 0x8000 * x + | SYNCGO | | | SoundWire SHIM | + +---------------+ | | generic | + | SYNCPU | | +-----------------+ 0x00030100 + 0x8000 * x + +---------------+ | | SoundWire IP | + | SYNPRD | | +-----------------+ 0x00036000 + 0x8000 * x + +---------------+ | | SoundWire SHIM | + | | vendor-specific | + 0x20 +---------------+ LEPTR | +-----------------+ + | ID = 0 | | + +---------------+ | + | VER | | + +---------------+ | + | PTR |------------+ + +---------------+ + + +DMIC HDaudio extended link mapping +================================== + +A DMIC extended link is identified when LCAP.ALT=1 and +LEPTR.ID=0xC1 are set. + +DMA control uses the existing LOSIDV register + +Changes include additional descriptions for enumeration that were not +present in earlier generations. + +- multi-link synchronization: capabilities in LCAP.LSS and control in LSYNC +- power management with LCTL.SPA bits +- hand-over to the DSP for access to multi-link registers, SHIM/IP with LCTL.OFLEN + +- move of DMIC registers to different offsets, with no change in + functionality. The LEPTR.PTR value is an offset from the ML + address, with a default value of 0x10000. + +Extended structure for DMIC +--------------------------- + +:: + + +-----------+ + | ML cap #0 | + +-----------+ + | ML cap #1 | + +-----------+ + | ML cap #2 |---+ + +-----------+ | + | + +--> 0x0 +---------------+ LCAP + | ALT=1 | + +---------------+ + | INTC | + +---------------+ + | OFLS | + +---------------+ + | SLCOUNT=1 | + +---------------+ + + 0x4 +---------------+ LCTL + | INTSTS | + +---------------+ + | CPA | + +---------------+ + | SPA | + +---------------+ + | INTEN | + +---------------+ + | OFLEN | + +---------------+ +---> 0x10000 +-----------------+ 0x00010000 + | | DMIC SHIM | + 0x8 +---------------+ LOSIDV | | generic | + | L1OSIVD15 | | +-----------------+ 0x00010100 + +---------------+ | | DMIC IP | + | L1OSIDV.. | | +-----------------+ 0x00016000 + +---------------+ | | DMIC SHIM | + | L1OSIDV1 | | | vendor-specific | + +---------------+ | +-----------------+ + | + 0x20 +---------------+ LEPTR | + | ID = 0xC1 | | + +---------------+ | + | VER | | + +---------------+ | + | PTR |-----------+ + +---------------+ + + +SSP HDaudio extended link mapping +================================= + +A DMIC extended link is identified when LCAP.ALT=1 and +LEPTR.ID=0xC0 are set. + +DMA control uses the existing LOSIDV register + +Changes include additional descriptions for enumeration and control that were not +present in earlier generations: +- number of sublinks (SSP IP instances) in LCAP.LSCOUNT +- power management moved from SHIM to LCTL.SPA bits +- hand-over to the DSP for access to multi-link registers, SHIM/IP +with LCTL.OFLEN +- move of SHIM and SSP IP registers to different offsets, with no +change in functionality. The LEPTR.PTR value is an offset from the ML +address, with a default value of 0x28000. + +Extended structure for SSP (assuming 3 instances of the IP) +----------------------------------------------------------- + +:: + + +-----------+ + | ML cap #0 | + +-----------+ + | ML cap #1 | + +-----------+ + | ML cap #2 |---+ + +-----------+ | + | + +--> 0x0 +---------------+ LCAP + | ALT=1 | + +---------------+ + | INTC | + +---------------+ + | OFLS | + +---------------+ + | SLCOUNT=3 |-------------------------for each sublink x -------------------------+ + +---------------+ | + | + 0x4 +---------------+ LCTL | + | INTSTS | | + +---------------+ | + | CPA (x bits) | | + +---------------+ | + | SPA (x bits) | | + +---------------+ | + | INTEN | | + +---------------+ | + | OFLEN | | + +---------------+ +---> 0x28000 +-----------------+ 0x00028000 | + | | SSP SHIM | | + 0x8 +---------------+ LOSIDV | | generic | | + | L1OSIVD15 | | +-----------------+ 0x00028100 | + +---------------+ | | SSP IP | | + | L1OSIDV.. | | +-----------------+ 0x00028C00 | + +---------------+ | | SSP SHIM | | + | L1OSIDV1 | | | vendor-specific | | + +---------------+ | +-----------------+ | + | v + 0x20 +---------------+ LEPTR | +-----------------+ 0x00028000 + 0x1000 * x + | ID = 0xC0 | | | SSP SHIM | + +---------------+ | | generic | + | VER | | +-----------------+ 0x00028100 + 0x1000 * x + +---------------+ | | SSP IP | + | PTR |-----------+ +-----------------+ 0x00028C00 + 0x1000 * x + +---------------+ | SSP SHIM | + | vendor-specific | + +-----------------+ diff --git a/Documentation/sound/hd-audio/models.rst b/Documentation/sound/hd-audio/models.rst index 0ea967d34583..120430450014 100644 --- a/Documentation/sound/hd-audio/models.rst +++ b/Documentation/sound/hd-audio/models.rst @@ -261,6 +261,10 @@ alc-sense-combo huawei-mbx-stereo Enable initialization verbs for Huawei MBX stereo speakers; might be risky, try this at your own risk +alc298-samsung-headphone + Samsung laptops with ALC298 +alc256-samsung-headphone + Samsung laptops with ALC256 ALC66x/67x/892 ============== @@ -326,6 +330,8 @@ usi-headset Headset support on USI machines dual-codecs Lenovo laptops with dual codecs +alc285-hp-amp-init + HP laptops which require speaker amplifier initialization (ALC285) ALC680 ====== @@ -698,7 +704,7 @@ ref no-jd BIOS setup but without jack-detection intel - Intel DG45* mobos + Intel D*45* mobos dell-m6-amic Dell desktops/laptops with analog mics dell-m6-dmic diff --git a/Documentation/sound/hd-audio/notes.rst b/Documentation/sound/hd-audio/notes.rst index 0f3109d9abc8..f81e94d8f145 100644 --- a/Documentation/sound/hd-audio/notes.rst +++ b/Documentation/sound/hd-audio/notes.rst @@ -15,7 +15,7 @@ problem is broken BIOS, and the rest is the driver implementation. This document explains the brief trouble-shooting and debugging methods for the HD-audio hardware. -The HD-audio component consists of two parts: the controller chip and +The HD-audio component consists of two parts: the controller chip and the codec chips on the HD-audio bus. Linux provides a single driver for all controllers, snd-hda-intel. Although the driver name contains a word of a well-known hardware vendor, it's not specific to it but for @@ -42,7 +42,7 @@ If you are interested in the deep debugging of HD-audio, read the HD-audio specification at first. The specification is found on Intel's web page, for example: -* http://www.intel.com/standards/hdaudio/ +* https://www.intel.com/content/www/us/en/standards/high-definition-audio-specification.html HD-Audio Controller @@ -81,7 +81,7 @@ the wake-up timing. It wakes up a few samples before actually processing the data on the buffer. This caused a lot of problems, for example, with ALSA dmix or JACK. Since 2.6.27 kernel, the driver puts an artificial delay to the wake up timing. This delay is controlled -via ``bdl_pos_adj`` option. +via ``bdl_pos_adj`` option. When ``bdl_pos_adj`` is a negative value (as default), it's assigned to an appropriate value depending on the controller chip. For Intel @@ -144,7 +144,7 @@ see a regression wrt the sound quality (stuttering, etc) or a lock-up in the recent kernel, try to pass ``enable_msi=0`` option to disable MSI. If it works, you can add the known bad device to the blacklist defined in hda_intel.c. In such a case, please report and give the -patch back to the upstream developer. +patch back to the upstream developer. HD-Audio Codec @@ -215,6 +215,17 @@ There are a few special model option values: * when ``generic`` is passed, the codec-specific parser is skipped and only the generic parser is used. +A new style for the model option that was introduced since 5.15 kernel +is to pass the PCI or codec SSID in the form of ``model=XXXX:YYYY`` +where XXXX and YYYY are the sub-vendor and sub-device IDs in hex +numbers, respectively. This is a kind of aliasing to another device; +when this form is given, the driver will refer to that SSID as a +reference to the quirk table. It'd be useful especially when the +target quirk isn't listed in the model table. For example, passing +model=103c:8862 will apply the quirk for HP ProBook 445 G8 (which +isn't found in the model table as of writing) as long as the device is +handled equivalently by the same driver. + Speaker and Headphone Output ---------------------------- @@ -310,12 +321,6 @@ Kernel Configuration -------------------- In general, I recommend you to enable the sound debug option, ``CONFIG_SND_DEBUG=y``, no matter whether you are debugging or not. -This enables snd_printd() macro and others, and you'll get additional -kernel messages at probing. - -In addition, you can enable ``CONFIG_SND_DEBUG_VERBOSE=y``. But this -will give you far more messages. Thus turn this on only when you are -sure to want it. Don't forget to turn on the appropriate ``CONFIG_SND_HDA_CODEC_*`` options. Note that each of them corresponds to the codec chip, not @@ -364,7 +369,7 @@ HD-Audio Reconfiguration ------------------------ This is an experimental feature to allow you re-configure the HD-audio codec dynamically without reloading the driver. The following sysfs -files are available under each codec-hwdep device directory (e.g. +files are available under each codec-hwdep device directory (e.g. /sys/class/sound/hwC0D0): vendor_id @@ -422,7 +427,7 @@ re-configure based on that state, run like below: :: # echo 0x14 0x9993013f > /sys/class/sound/hwC0D0/user_pin_configs - # echo 1 > /sys/class/sound/hwC0D0/reconfig + # echo 1 > /sys/class/sound/hwC0D0/reconfig Hint Strings @@ -483,17 +488,17 @@ indep_hp (bool) mixer control, if available add_stereo_mix_input (bool) add the stereo mix (analog-loopback mix) to the input mux if - available + available add_jack_modes (bool) add "xxx Jack Mode" enum controls to each I/O jack for allowing to change the headphone amp and mic bias VREF capabilities power_save_node (bool) advanced power management for each widget, controlling the power - sate (D0/D3) of each widget node depending on the actual pin and + state (D0/D3) of each widget node depending on the actual pin and stream states power_down_unused (bool) power down the unused widgets, a subset of power_save_node, and - will be dropped in future + will be dropped in future add_hp_mic (bool) add the headphone to capture source if possible hp_mic_detect (bool) @@ -592,7 +597,7 @@ present. The patch module option is specific to each card instance, and you need to give one file name for each instance, separated by commas. -For example, if you have two cards, one for an on-board analog and one +For example, if you have two cards, one for an on-board analog and one for an HDMI video board, you may pass patch option like below: :: @@ -640,14 +645,14 @@ via power-saving behavior. Enabling all tracepoints can be done like :: - # echo 1 > /sys/kernel/debug/tracing/events/hda/enable + # echo 1 > /sys/kernel/tracing/events/hda/enable then after some commands, you can traces from -/sys/kernel/debug/tracing/trace file. For example, when you want to +/sys/kernel/tracing/trace file. For example, when you want to trace what codec command is sent, enable the tracepoint like: :: - # cat /sys/kernel/debug/tracing/trace + # cat /sys/kernel/tracing/trace # tracer: nop # # TASK-PID CPU# TIMESTAMP FUNCTION @@ -728,7 +733,7 @@ version can be found on git repository: The script can be fetched directly from the following URL, too: -* http://www.alsa-project.org/alsa-info.sh +* https://www.alsa-project.org/alsa-info.sh Run this script as root, and it will gather the important information such as the module lists, module parameters, proc file contents @@ -818,7 +823,7 @@ proc-compatible output. The hda-analyzer: -* http://git.alsa-project.org/?p=alsa.git;a=tree;f=hda-analyzer +* https://git.alsa-project.org/?p=alsa.git;a=tree;f=hda-analyzer is a part of alsa.git repository in alsa-project.org: diff --git a/Documentation/sound/index.rst b/Documentation/sound/index.rst index 4d7d42acf6df..51cd736f65b5 100644 --- a/Documentation/sound/index.rst +++ b/Documentation/sound/index.rst @@ -1,6 +1,8 @@ -=================================== -Linux Sound Subsystem Documentation -=================================== +.. SPDX-License-Identifier: GPL-2.0 + +============================= +Sound Subsystem Documentation +============================= .. toctree:: :maxdepth: 2 @@ -11,6 +13,8 @@ Linux Sound Subsystem Documentation alsa-configuration hd-audio/index cards/index + codecs/index + utimers .. only:: subproject and html diff --git a/Documentation/sound/kernel-api/alsa-driver-api.rst b/Documentation/sound/kernel-api/alsa-driver-api.rst index 14cd138989e3..d24c64df7069 100644 --- a/Documentation/sound/kernel-api/alsa-driver-api.rst +++ b/Documentation/sound/kernel-api/alsa-driver-api.rst @@ -99,7 +99,7 @@ ASoC Core API .. kernel-doc:: include/sound/soc.h .. kernel-doc:: sound/soc/soc-core.c .. kernel-doc:: sound/soc/soc-devres.c -.. kernel-doc:: sound/soc/soc-io.c +.. kernel-doc:: sound/soc/soc-component.c .. kernel-doc:: sound/soc/soc-pcm.c .. kernel-doc:: sound/soc/soc-ops.c .. kernel-doc:: sound/soc/soc-compress.c @@ -132,3 +132,4 @@ ISA DMA Helpers Other Helper Macros ------------------- .. kernel-doc:: include/sound/core.h +.. kernel-doc:: sound/sound_core.c diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst index fa4968817696..895752cbcedd 100644 --- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst +++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst @@ -19,18 +19,13 @@ explain the general topic of linux kernel coding and doesn't cover low-level driver implementation details. It only describes the standard way to write a PCI sound driver on ALSA. -This document is still a draft version. Any feedback and corrections, -please!! - File Tree Structure =================== General ------- -The file tree structure of ALSA driver is depicted below. - -:: +The file tree structure of ALSA driver is depicted below:: sound /core @@ -68,29 +63,29 @@ kernel config. core/oss ~~~~~~~~ -The codes for PCM and mixer OSS emulation modules are stored in this -directory. The rawmidi OSS emulation is included in the ALSA rawmidi +The code for OSS PCM and mixer emulation modules is stored in this +directory. The OSS rawmidi emulation is included in the ALSA rawmidi code since it's quite small. The sequencer code is stored in -``core/seq/oss`` directory (see `below <#core-seq-oss>`__). +``core/seq/oss`` directory (see `below <core/seq/oss_>`__). core/seq ~~~~~~~~ This directory and its sub-directories are for the ALSA sequencer. This directory contains the sequencer core and primary sequencer modules such -like snd-seq-midi, snd-seq-virmidi, etc. They are compiled only when +as snd-seq-midi, snd-seq-virmidi, etc. They are compiled only when ``CONFIG_SND_SEQUENCER`` is set in the kernel config. core/seq/oss ~~~~~~~~~~~~ -This contains the OSS sequencer emulation codes. +This contains the OSS sequencer emulation code. include directory ----------------- This is the place for the public header files of ALSA drivers, which are -to be exported to user-space, or included by several files at different +to be exported to user-space, or included by several files in different directories. Basically, the private header files should not be placed in this directory, but you may still find files there, due to historical reasons :) @@ -100,7 +95,7 @@ drivers directory This directory contains code shared among different drivers on different architectures. They are hence supposed not to be architecture-specific. -For example, the dummy pcm driver and the serial MIDI driver are found +For example, the dummy PCM driver and the serial MIDI driver are found in this directory. In the sub-directories, there is code for components which are independent from bus and cpu architectures. @@ -156,8 +151,8 @@ these architectures. usb directory ------------- -This directory contains the USB-audio driver. In the latest version, the -USB MIDI driver is integrated in the usb-audio driver. +This directory contains the USB-audio driver. +The USB MIDI driver is integrated in the usb-audio driver. pcmcia directory ---------------- @@ -175,9 +170,9 @@ layer including ASoC core, codec and machine drivers. oss directory ------------- -Here contains OSS/Lite codes. -All codes have been deprecated except for dmasound on m68k as of -writing this. +This contains OSS/Lite code. +At the time of writing, all code has been removed except for dmasound +on m68k. Basic Flow for PCI Drivers @@ -194,7 +189,7 @@ The minimum flow for PCI soundcards is as follows: - create ``remove`` callback. -- create a :c:type:`struct pci_driver <pci_driver>` structure +- create a struct pci_driver structure containing the three pointers above. - create an ``init`` function just calling the @@ -341,7 +336,7 @@ to details explained in the following section. error: snd_card_free(card); - return err; + return err; } /* destructor -- see the "Destructor" sub-section */ @@ -381,8 +376,8 @@ where ``enable[dev]`` is the module option. Each time the ``probe`` callback is called, check the availability of the device. If not available, simply increment the device index and -returns. dev will be incremented also later (`step 7 -<#set-the-pci-driver-data-and-return-zero>`__). +return. dev will be incremented also later (`step 7 +<7) Set the PCI driver data and return zero._>`__). 2) Create a card instance ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -402,9 +397,7 @@ Components`_. 3) Create a main component ~~~~~~~~~~~~~~~~~~~~~~~~~~ -In this part, the PCI resources are allocated. - -:: +In this part, the PCI resources are allocated:: struct mychip *chip; .... @@ -417,13 +410,11 @@ Management`_. When something goes wrong, the probe function needs to deal with the error. In this example, we have a single error handling path placed -at the end of the function. - -:: +at the end of the function:: error: snd_card_free(card); - return err; + return err; Since each component can be properly freed, the single :c:func:`snd_card_free()` call should suffice in most cases. @@ -450,10 +441,10 @@ field contains the information shown in ``/proc/asound/cards``. 5) Create other components, such as mixer, MIDI, etc. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Here you define the basic components such as `PCM <#PCM-Interface>`__, -mixer (e.g. `AC97 <#API-for-AC97-Codec>`__), MIDI (e.g. -`MPU-401 <#MIDI-MPU401-UART-Interface>`__), and other interfaces. -Also, if you want a `proc file <#Proc-Interface>`__, define it here, +Here you define the basic components such as `PCM <PCM Interface_>`__, +mixer (e.g. `AC97 <API for AC97 Codec_>`__), MIDI (e.g. +`MPU-401 <MIDI (MPU401-UART) Interface_>`__), and other interfaces. +Also, if you want a `proc file <Proc Interface_>`__, define it here, too. 6) Register the card instance. @@ -483,13 +474,11 @@ remove callback and power-management callbacks, too. Destructor ---------- -The destructor, remove callback, simply releases the card instance. Then -the ALSA middle layer will release all the attached components +The destructor, the remove callback, simply releases the card instance. +Then the ALSA middle layer will release all the attached components automatically. -It would be typically just :c:func:`calling snd_card_free()`: - -:: +It would be typically just calling :c:func:`snd_card_free()`:: static void snd_mychip_remove(struct pci_dev *pci) { @@ -504,9 +493,7 @@ Header Files ------------ For the above example, at least the following include files are -necessary. - -:: +necessary:: #include <linux/init.h> #include <linux/pci.h> @@ -544,9 +531,7 @@ list on the card record is used to manage the correct release of resources at destruction. As mentioned above, to create a card instance, call -:c:func:`snd_card_new()`. - -:: +:c:func:`snd_card_new()`:: struct snd_card *card; int err; @@ -560,23 +545,20 @@ return the card instance. The extra_size argument is used to allocate card->private_data for the chip-specific data. Note that these data are allocated by :c:func:`snd_card_new()`. -The first argument, the pointer of struct :c:type:`struct device -<device>`, specifies the parent device. For PCI devices, typically -``&pci->`` is passed there. +The first argument, the pointer of struct device, specifies the parent +device. For PCI devices, typically ``&pci->`` is passed there. Components ---------- After the card is created, you can attach the components (devices) to the card instance. In an ALSA driver, a component is represented as a -:c:type:`struct snd_device <snd_device>` object. A component +struct snd_device object. A component can be a PCM instance, a control interface, a raw MIDI interface, etc. Each such instance has one component entry. -A component can be created via :c:func:`snd_device_new()` -function. - -:: +A component can be created via the :c:func:`snd_device_new()` +function:: snd_device_new(card, SNDRV_DEV_XXX, chip, &ops); @@ -592,7 +574,7 @@ allocated manually beforehand, and its pointer is passed as the argument. This pointer (``chip`` in the above example) is used as the identifier for the instance. -Each pre-defined ALSA component such as ac97 and pcm calls +Each pre-defined ALSA component such as AC97 and PCM calls :c:func:`snd_device_new()` inside its constructor. The destructor for each component is defined in the callback pointers. Hence, you don't need to take care of calling a destructor for such a component. @@ -606,9 +588,7 @@ Chip-Specific Data ------------------ Chip-specific information, e.g. the I/O port address, its resource -pointer, or the irq number, is stored in the chip-specific record. - -:: +pointer, or the irq number, is stored in the chip-specific record:: struct mychip { .... @@ -621,14 +601,12 @@ In general, there are two ways of allocating the chip record. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ As mentioned above, you can pass the extra-data-length to the 5th -argument of :c:func:`snd_card_new()`, i.e. - -:: +argument of :c:func:`snd_card_new()`, e.g.:: err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, sizeof(struct mychip), &card); -:c:type:`struct mychip <mychip>` is the type of the chip record. +struct mychip is the type of the chip record. In return, the allocated record can be accessed as @@ -643,9 +621,7 @@ released together with the card instance. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ After allocating a card instance via :c:func:`snd_card_new()` -(with ``0`` on the 4th arg), call :c:func:`kzalloc()`. - -:: +(with ``0`` on the 4th arg), call :c:func:`kzalloc()`:: struct snd_card *card; struct mychip *chip; @@ -664,16 +640,12 @@ The chip record should have the field to hold the card pointer at least, }; -Then, set the card pointer in the returned chip instance. - -:: +Then, set the card pointer in the returned chip instance:: chip->card = card; Next, initialize the fields, and register this chip record as a -low-level device with a specified ``ops``, - -:: +low-level device with a specified ``ops``:: static const struct snd_device_ops ops = { .dev_free = snd_mychip_dev_free, @@ -682,9 +654,7 @@ low-level device with a specified ``ops``, snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops); :c:func:`snd_mychip_dev_free()` is the device-destructor -function, which will call the real destructor. - -:: +function, which will call the real destructor:: static int snd_mychip_dev_free(struct snd_device *device) { @@ -693,10 +663,10 @@ function, which will call the real destructor. where :c:func:`snd_mychip_free()` is the real destructor. -The demerit of this method is the obviously more amount of codes. -The merit is, however, you can trigger the own callback at registering -and disconnecting the card via setting in snd_device_ops. -About the registering and disconnecting the card, see the subsections +The demerit of this method is the obviously larger amount of code. +The merit is, however, that you can trigger your own callback at +registering and disconnecting the card via a setting in snd_device_ops. +About registering and disconnecting the card, see the subsections below. @@ -725,9 +695,7 @@ Full Code Example ----------------- In this section, we'll complete the chip-specific constructor, -destructor and PCI entries. Example code is shown first, below. - -:: +destructor and PCI entries. Example code is shown first, below:: struct mychip { struct snd_card *card; @@ -867,9 +835,7 @@ resources. Also, you need to set the proper PCI DMA mask to limit the accessed I/O range. In some cases, you might need to call :c:func:`pci_set_master()` function, too. -Suppose the 28bit mask, and the code to be added would be like: - -:: +Suppose a 28bit mask, the code to be added would look like:: err = pci_enable_device(pci); if (err < 0) @@ -890,10 +856,8 @@ functions. These resources must be released in the destructor function (see below). Now assume that the PCI device has an I/O port with 8 bytes and an -interrupt. Then :c:type:`struct mychip <mychip>` will have the -following fields: - -:: +interrupt. Then struct mychip will have the +following fields:: struct mychip { struct snd_card *card; @@ -906,14 +870,12 @@ following fields: For an I/O port (and also a memory region), you need to have the resource pointer for the standard resource management. For an irq, you have to keep only the irq number (integer). But you need to initialize -this number as -1 before actual allocation, since irq 0 is valid. The +this number to -1 before actual allocation, since irq 0 is valid. The port address and its resource pointer can be initialized as null by :c:func:`kzalloc()` automatically, so you don't have to take care of resetting them. -The allocation of an I/O port is done like this: - -:: +The allocation of an I/O port is done like this:: err = pci_request_regions(pci, "My Chip"); if (err < 0) { @@ -929,9 +891,7 @@ The returned value, ``chip->res_port``, is allocated via must be released via :c:func:`kfree()`, but there is a problem with this. This issue will be explained later. -The allocation of an interrupt source is done like this: - -:: +The allocation of an interrupt source is done like this:: if (request_irq(pci->irq, snd_mychip_interrupt, IRQF_SHARED, KBUILD_MODNAME, chip)) { @@ -942,7 +902,7 @@ The allocation of an interrupt source is done like this: chip->irq = pci->irq; where :c:func:`snd_mychip_interrupt()` is the interrupt handler -defined `later <#pcm-interface-interrupt-handler>`__. Note that +defined `later <PCM Interrupt Handler_>`__. Note that ``chip->irq`` should be defined only when :c:func:`request_irq()` succeeded. @@ -955,9 +915,7 @@ used for that, but you can use what you like, too. I won't give details about the interrupt handler at this point, but at least its appearance can be explained now. The interrupt handler looks -usually like the following: - -:: +usually as follows:: static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id) { @@ -967,13 +925,12 @@ usually like the following: } After requesting the IRQ, you can passed it to ``card->sync_irq`` -field: -:: +field:: card->irq = chip->irq; -This allows PCM core automatically performing -:c:func:`synchronize_irq()` at the necessary timing like ``hw_free``. +This allows the PCM core to automatically call +:c:func:`synchronize_irq()` at the right time, like before ``hw_free``. See the later section `sync_stop callback`_ for details. Now let's write the corresponding destructor for the resources above. @@ -982,9 +939,7 @@ activated) and release the resources. So far, we have no hardware part, so the disabling code is not written here. To release the resources, the “check-and-release” method is a safer way. -For the interrupt, do like this: - -:: +For the interrupt, do like this:: if (chip->irq >= 0) free_irq(chip->irq, chip); @@ -998,9 +953,7 @@ When you requested I/O ports or memory regions via :c:func:`pci_request_regions()` like in this example, release the resource(s) using the corresponding function, :c:func:`pci_release_region()` or -:c:func:`pci_release_regions()`. - -:: +:c:func:`pci_release_regions()`:: pci_release_regions(chip->pci); @@ -1008,39 +961,32 @@ When you requested manually via :c:func:`request_region()` or :c:func:`request_mem_region()`, you can release it via :c:func:`release_resource()`. Suppose that you keep the resource pointer returned from :c:func:`request_region()` in -chip->res_port, the release procedure looks like: - -:: +chip->res_port, the release procedure looks like:: release_and_free_resource(chip->res_port); Don't forget to call :c:func:`pci_disable_device()` before the end. -And finally, release the chip-specific record. - -:: +And finally, release the chip-specific record:: kfree(chip); -We didn't implement the hardware disabling part in the above. If you +We didn't implement the hardware disabling part above. If you need to do this, please note that the destructor may be called even before the initialization of the chip is completed. It would be better to have a flag to skip hardware disabling if the hardware was not initialized yet. When the chip-data is assigned to the card using -:c:func:`snd_device_new()` with ``SNDRV_DEV_LOWLELVEL`` , its -destructor is called at the last. That is, it is assured that all other +:c:func:`snd_device_new()` with ``SNDRV_DEV_LOWLELVEL``, its +destructor is called last. That is, it is assured that all other components like PCMs and controls have already been released. You don't have to stop PCMs, etc. explicitly, but just call low-level hardware stopping. The management of a memory-mapped region is almost as same as the -management of an I/O port. You'll need three fields like the -following: - -:: +management of an I/O port. You'll need two fields as follows:: struct mychip { .... @@ -1048,9 +994,7 @@ following: void __iomem *iobase_virt; }; -and the allocation would be like below: - -:: +and the allocation would look like below:: err = pci_request_regions(pci, "My Chip"); if (err < 0) { @@ -1061,9 +1005,7 @@ and the allocation would be like below: chip->iobase_virt = ioremap(chip->iobase_phys, pci_resource_len(pci, 0)); -and the corresponding destructor would be: - -:: +and the corresponding destructor would be:: static int snd_mychip_free(struct mychip *chip) { @@ -1076,9 +1018,7 @@ and the corresponding destructor would be: } Of course, a modern way with :c:func:`pci_iomap()` will make things a -bit easier, too. - -:: +bit easier, too:: err = pci_request_regions(pci, "My Chip"); if (err < 0) { @@ -1094,13 +1034,11 @@ PCI Entries ----------- So far, so good. Let's finish the missing PCI stuff. At first, we need a -:c:type:`struct pci_device_id <pci_device_id>` table for +struct pci_device_id table for this chipset. It's a table of PCI vendor/device ID number, and some masks. -For example, - -:: +For example:: static struct pci_device_id snd_mychip_ids[] = { { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR, @@ -1110,22 +1048,18 @@ For example, }; MODULE_DEVICE_TABLE(pci, snd_mychip_ids); -The first and second fields of the :c:type:`struct pci_device_id -<pci_device_id>` structure are the vendor and device IDs. If you -have no reason to filter the matching devices, you can leave the -remaining fields as above. The last field of the :c:type:`struct -pci_device_id <pci_device_id>` struct contains private data -for this entry. You can specify any value here, for example, to define -specific operations for supported device IDs. Such an example is found -in the intel8x0 driver. +The first and second fields of the struct pci_device_id are the vendor +and device IDs. If you have no reason to filter the matching devices, you can +leave the remaining fields as above. The last field of the +struct pci_device_id contains private data for this entry. You can specify +any value here, for example, to define specific operations for supported +device IDs. Such an example is found in the intel8x0 driver. The last entry of this list is the terminator. You must specify this all-zero entry. -Then, prepare the :c:type:`struct pci_driver <pci_driver>` -record: - -:: +Then, prepare the struct pci_driver +record:: static struct pci_driver driver = { .name = KBUILD_MODNAME, @@ -1136,11 +1070,9 @@ record: The ``probe`` and ``remove`` functions have already been defined in the previous sections. The ``name`` field is the name string of this -device. Note that you must not use a slash “/” in this string. +device. Note that you must not use slashes (“/”) in this string. -And at last, the module entries: - -:: +And at last, the module entries:: static int __init alsa_card_mychip_init(void) { @@ -1170,22 +1102,22 @@ The PCM middle layer of ALSA is quite powerful and it is only necessary for each driver to implement the low-level functions to access its hardware. -For accessing to the PCM layer, you need to include ``<sound/pcm.h>`` +To access the PCM layer, you need to include ``<sound/pcm.h>`` first. In addition, ``<sound/pcm_params.h>`` might be needed if you -access to some functions related with hw_param. +access some functions related with hw_param. -Each card device can have up to four pcm instances. A pcm instance -corresponds to a pcm device file. The limitation of number of instances -comes only from the available bit size of the Linux's device numbers. -Once when 64bit device number is used, we'll have more pcm instances +Each card device can have up to four PCM instances. A PCM instance +corresponds to a PCM device file. The limitation of number of instances +comes only from the available bit size of Linux' device numbers. +Once 64bit device numbers are used, we'll have more PCM instances available. -A pcm instance consists of pcm playback and capture streams, and each -pcm stream consists of one or more pcm substreams. Some soundcards +A PCM instance consists of PCM playback and capture streams, and each +PCM stream consists of one or more PCM substreams. Some soundcards support multiple playback functions. For example, emu10k1 has a PCM playback of 32 stereo substreams. In this case, at each open, a free substream is (usually) automatically chosen and opened. Meanwhile, when -only one substream exists and it was already opened, the successful open +only one substream exists and it was already opened, a subsequent open will either block or error with ``EAGAIN`` according to the file open mode. But you don't have to care about such details in your driver. The PCM middle layer will take care of such work. @@ -1194,9 +1126,7 @@ Full Code Example ----------------- The example code below does not include any hardware access routines but -shows only the skeleton, how to build up the PCM interfaces. - -:: +shows only the skeleton, how to build up the PCM interfaces:: #include <sound/pcm.h> .... @@ -1402,10 +1332,8 @@ shows only the skeleton, how to build up the PCM interfaces. PCM Constructor --------------- -A pcm instance is allocated by the :c:func:`snd_pcm_new()` -function. It would be better to create a constructor for pcm, namely, - -:: +A PCM instance is allocated by the :c:func:`snd_pcm_new()` +function. It would be better to create a constructor for the PCM, namely:: static int snd_mychip_new_pcm(struct mychip *chip) { @@ -1418,16 +1346,16 @@ function. It would be better to create a constructor for pcm, namely, pcm->private_data = chip; strcpy(pcm->name, "My Chip"); chip->pcm = pcm; - .... + ... return 0; } -The :c:func:`snd_pcm_new()` function takes four arguments. The -first argument is the card pointer to which this pcm is assigned, and +The :c:func:`snd_pcm_new()` function takes six arguments. The +first argument is the card pointer to which this PCM is assigned, and the second is the ID string. The third argument (``index``, 0 in the above) is the index of this new -pcm. It begins from zero. If you create more than one pcm instances, +PCM. It begins from zero. If you create more than one PCM instances, specify the different numbers in this argument. For example, ``index = 1`` for the second PCM device. @@ -1439,27 +1367,21 @@ corresponding argument. If a chip supports multiple playbacks or captures, you can specify more numbers, but they must be handled properly in open/close, etc. callbacks. When you need to know which substream you are referring to, -then it can be obtained from :c:type:`struct snd_pcm_substream -<snd_pcm_substream>` data passed to each callback as follows: - -:: +then it can be obtained from struct snd_pcm_substream data passed to each +callback as follows:: struct snd_pcm_substream *substream; int index = substream->number; -After the pcm is created, you need to set operators for each pcm stream. - -:: +After the PCM is created, you need to set operators for each PCM stream:: snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK, &snd_mychip_playback_ops); snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE, &snd_mychip_capture_ops); -The operators are defined typically like this: - -:: +The operators are defined typically like this:: static struct snd_pcm_ops snd_mychip_playback_ops = { .open = snd_mychip_pcm_open, @@ -1475,25 +1397,21 @@ All the callbacks are described in the Operators_ subsection. After setting the operators, you probably will want to pre-allocate the buffer and set up the managed allocation mode. -For that, simply call the following: - -:: +For that, simply call the following:: snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV, &chip->pci->dev, 64*1024, 64*1024); -It will allocate a buffer up to 64kB as default. Buffer management +It will allocate a buffer up to 64kB by default. Buffer management details will be described in the later section `Buffer and Memory Management`_. -Additionally, you can set some extra information for this pcm in +Additionally, you can set some extra information for this PCM in ``pcm->info_flags``. The available values are defined as ``SNDRV_PCM_INFO_XXX`` in ``<sound/asound.h>``, which is used for the hardware definition (described later). When your soundchip supports only -half-duplex, specify like this: - -:: +half-duplex, specify it like this:: pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX; @@ -1501,15 +1419,13 @@ half-duplex, specify like this: ... And the Destructor? ----------------------- -The destructor for a pcm instance is not always necessary. Since the pcm +The destructor for a PCM instance is not always necessary. Since the PCM device will be released by the middle layer code automatically, you don't have to call the destructor explicitly. The destructor would be necessary if you created special records internally and needed to release them. In such a case, set the -destructor function to ``pcm->private_free``: - -:: +destructor function to ``pcm->private_free``:: static void mychip_pcm_free(struct snd_pcm *pcm) { @@ -1540,13 +1456,11 @@ Runtime Pointer - The Chest of PCM Information When the PCM substream is opened, a PCM runtime instance is allocated and assigned to the substream. This pointer is accessible via ``substream->runtime``. This runtime pointer holds most information you -need to control the PCM: the copy of hw_params and sw_params +need to control the PCM: a copy of hw_params and sw_params configurations, the buffer pointers, mmap records, spinlocks, etc. The definition of runtime instance is found in ``<sound/pcm.h>``. Here -are the contents of this file: - -:: +is the relevant part of this file:: struct _snd_pcm_runtime { /* -- Status -- */ @@ -1580,14 +1494,19 @@ are the contents of this file: unsigned int period_step; unsigned int sleep_min; /* min ticks to sleep */ snd_pcm_uframes_t start_threshold; - snd_pcm_uframes_t stop_threshold; - snd_pcm_uframes_t silence_threshold; /* Silence filling happens when - noise is nearest than this */ - snd_pcm_uframes_t silence_size; /* Silence filling size */ + /* + * The following two thresholds alleviate playback buffer underruns; when + * hw_avail drops below the threshold, the respective action is triggered: + */ + snd_pcm_uframes_t stop_threshold; /* - stop playback */ + snd_pcm_uframes_t silence_threshold; /* - pre-fill buffer with silence */ + snd_pcm_uframes_t silence_size; /* max size of silence pre-fill; when >= boundary, + * fill played area with silence immediately */ snd_pcm_uframes_t boundary; /* pointers wrap point */ - snd_pcm_uframes_t silenced_start; - snd_pcm_uframes_t silenced_size; + /* internal data of auto-silencer */ + snd_pcm_uframes_t silence_start; /* starting pointer to silence area */ + snd_pcm_uframes_t silence_filled; /* size filled with silence */ snd_pcm_sync_id_t sync; /* hardware synchronization ID */ @@ -1639,17 +1558,14 @@ In the sections below, important records are explained. Hardware Description ~~~~~~~~~~~~~~~~~~~~ -The hardware descriptor (:c:type:`struct snd_pcm_hardware -<snd_pcm_hardware>`) contains the definitions of the fundamental -hardware configuration. Above all, you'll need to define this in the -`PCM open callback`_. Note that the runtime instance holds the copy of -the descriptor, not the pointer to the existing descriptor. That is, +The hardware descriptor (struct snd_pcm_hardware) contains the definitions of +the fundamental hardware configuration. Above all, you'll need to define this +in the `PCM open callback`_. Note that the runtime instance holds a copy of +the descriptor, not a pointer to the existing descriptor. That is, in the open callback, you can modify the copied descriptor (``runtime->hw``) as you need. For example, if the maximum number of channels is 1 only on some chip models, you can still use the same -hardware descriptor and change the channels_max later: - -:: +hardware descriptor and change the channels_max later:: struct snd_pcm_runtime *runtime = substream->runtime; ... @@ -1657,9 +1573,7 @@ hardware descriptor and change the channels_max later: if (chip->model == VERY_OLD_ONE) runtime->hw.channels_max = 1; -Typically, you'll have a hardware descriptor as below: - -:: +Typically, you'll have a hardware descriptor as below:: static struct snd_pcm_hardware snd_mychip_playback_hw = { .info = (SNDRV_PCM_INFO_MMAP | @@ -1680,71 +1594,72 @@ Typically, you'll have a hardware descriptor as below: }; - The ``info`` field contains the type and capabilities of this - pcm. The bit flags are defined in ``<sound/asound.h>`` as + PCM. The bit flags are defined in ``<sound/asound.h>`` as ``SNDRV_PCM_INFO_XXX``. Here, at least, you have to specify whether - the mmap is supported and which interleaved format is + mmap is supported and which interleaving formats are supported. When the hardware supports mmap, add the ``SNDRV_PCM_INFO_MMAP`` flag here. When the hardware supports the - interleaved or the non-interleaved formats, + interleaved or the non-interleaved formats, the ``SNDRV_PCM_INFO_INTERLEAVED`` or ``SNDRV_PCM_INFO_NONINTERLEAVED`` flag must be set, respectively. If both are supported, you can set both, too. In the above example, ``MMAP_VALID`` and ``BLOCK_TRANSFER`` are specified for the OSS mmap mode. Usually both are set. Of course, - ``MMAP_VALID`` is set only if the mmap is really supported. + ``MMAP_VALID`` is set only if mmap is really supported. The other possible flags are ``SNDRV_PCM_INFO_PAUSE`` and - ``SNDRV_PCM_INFO_RESUME``. The ``PAUSE`` bit means that the pcm + ``SNDRV_PCM_INFO_RESUME``. The ``PAUSE`` bit means that the PCM supports the “pause” operation, while the ``RESUME`` bit means that - the pcm supports the full “suspend/resume” operation. If the + the PCM supports the full “suspend/resume” operation. If the ``PAUSE`` flag is set, the ``trigger`` callback below must handle the corresponding (pause push/release) commands. The suspend/resume trigger commands can be defined even without the ``RESUME`` - flag. See `Power Management`_ section for details. + flag. See the `Power Management`_ section for details. When the PCM substreams can be synchronized (typically, - synchronized start/stop of a playback and a capture streams), you + synchronized start/stop of a playback and a capture stream), you can give ``SNDRV_PCM_INFO_SYNC_START``, too. In this case, you'll need to check the linked-list of PCM substreams in the trigger - callback. This will be described in the later section. + callback. This will be described in a later section. -- ``formats`` field contains the bit-flags of supported formats +- The ``formats`` field contains the bit-flags of supported formats (``SNDRV_PCM_FMTBIT_XXX``). If the hardware supports more than one format, give all or'ed bits. In the example above, the signed 16bit little-endian format is specified. -- ``rates`` field contains the bit-flags of supported rates +- The ``rates`` field contains the bit-flags of supported rates (``SNDRV_PCM_RATE_XXX``). When the chip supports continuous rates, - pass ``CONTINUOUS`` bit additionally. The pre-defined rate bits are - provided only for typical rates. If your chip supports + pass the ``CONTINUOUS`` bit additionally. The pre-defined rate bits + are provided only for typical rates. If your chip supports unconventional rates, you need to add the ``KNOT`` bit and set up the hardware constraint manually (explained later). - ``rate_min`` and ``rate_max`` define the minimum and maximum sample rate. This should correspond somehow to ``rates`` bits. -- ``channel_min`` and ``channel_max`` define, as you might already +- ``channels_min`` and ``channels_max`` define, as you might have already expected, the minimum and maximum number of channels. - ``buffer_bytes_max`` defines the maximum buffer size in bytes. There is no ``buffer_bytes_min`` field, since it can be calculated from the minimum period size and the minimum number of - periods. Meanwhile, ``period_bytes_min`` and define the minimum and - maximum size of the period in bytes. ``periods_max`` and - ``periods_min`` define the maximum and minimum number of periods in - the buffer. + periods. Meanwhile, ``period_bytes_min`` and ``period_bytes_max`` + define the minimum and maximum size of the period in bytes. + ``periods_max`` and ``periods_min`` define the maximum and minimum + number of periods in the buffer. The “period” is a term that corresponds to a fragment in the OSS - world. The period defines the size at which a PCM interrupt is - generated. This size strongly depends on the hardware. Generally, - the smaller period size will give you more interrupts, that is, - more controls. In the case of capture, this size defines the input - latency. On the other hand, the whole buffer size defines the - output latency for the playback direction. + world. The period defines the point at which a PCM interrupt is + generated. This point strongly depends on the hardware. Generally, + a smaller period size will give you more interrupts, which results + in being able to fill/drain the buffer more timely. In the case of + capture, this size defines the input latency. On the other hand, + the whole buffer size defines the output latency for the playback + direction. - There is also a field ``fifo_size``. This specifies the size of the - hardware FIFO, but currently it is neither used in the driver nor + hardware FIFO, but currently it is neither used by the drivers nor in the alsa-lib. So, you can ignore this field. PCM Configurations @@ -1763,34 +1678,32 @@ One thing to be noted is that the configured buffer and period sizes are stored in “frames” in the runtime. In the ALSA world, ``1 frame = channels \* samples-size``. For conversion between frames and bytes, you can use the :c:func:`frames_to_bytes()` and -:c:func:`bytes_to_frames()` helper functions. - -:: +:c:func:`bytes_to_frames()` helper functions:: period_bytes = frames_to_bytes(runtime, runtime->period_size); Also, many software parameters (sw_params) are stored in frames, too. -Please check the type of the field. ``snd_pcm_uframes_t`` is for the -frames as unsigned integer while ``snd_pcm_sframes_t`` is for the +Please check the type of the field. ``snd_pcm_uframes_t`` is for +frames as unsigned integer while ``snd_pcm_sframes_t`` is for frames as signed integer. DMA Buffer Information ~~~~~~~~~~~~~~~~~~~~~~ -The DMA buffer is defined by the following four fields, ``dma_area``, -``dma_addr``, ``dma_bytes`` and ``dma_private``. The ``dma_area`` +The DMA buffer is defined by the following four fields: ``dma_area``, +``dma_addr``, ``dma_bytes`` and ``dma_private``. ``dma_area`` holds the buffer pointer (the logical address). You can call :c:func:`memcpy()` from/to this pointer. Meanwhile, ``dma_addr`` holds the physical address of the buffer. This field is specified only when -the buffer is a linear buffer. ``dma_bytes`` holds the size of buffer -in bytes. ``dma_private`` is used for the ALSA DMA allocator. +the buffer is a linear buffer. ``dma_bytes`` holds the size of the +buffer in bytes. ``dma_private`` is used for the ALSA DMA allocator. If you use either the managed buffer allocation mode or the standard API function :c:func:`snd_pcm_lib_malloc_pages()` for allocating the buffer, these fields are set by the ALSA middle layer, and you should *not* change them by yourself. You can read them but not write them. On the other hand, if you want to allocate the buffer by yourself, you'll -need to manage it in hw_params callback. At least, ``dma_bytes`` is +need to manage it in the hw_params callback. At least, ``dma_bytes`` is mandatory. ``dma_area`` is necessary when the buffer is mmapped. If your driver doesn't support mmap, this field is not necessary. ``dma_addr`` is also optional. You can use dma_private as @@ -1800,14 +1713,13 @@ Running Status ~~~~~~~~~~~~~~ The running status can be referred via ``runtime->status``. This is -the pointer to the :c:type:`struct snd_pcm_mmap_status -<snd_pcm_mmap_status>` record. For example, you can get the current +a pointer to a struct snd_pcm_mmap_status record. +For example, you can get the current DMA hardware pointer via ``runtime->status->hw_ptr``. The DMA application pointer can be referred via ``runtime->control``, -which points to the :c:type:`struct snd_pcm_mmap_control -<snd_pcm_mmap_control>` record. However, accessing directly to -this value is not recommended. +which points to a struct snd_pcm_mmap_control record. +However, accessing this value directly is not recommended. Private Data ~~~~~~~~~~~~ @@ -1816,11 +1728,10 @@ You can allocate a record for the substream and store it in ``runtime->private_data``. Usually, this is done in the `PCM open callback`_. Don't mix this with ``pcm->private_data``. The ``pcm->private_data`` usually points to the chip instance assigned -statically at the creation of PCM, while the ``runtime->private_data`` -points to a dynamic data structure created at the PCM open -callback. - -:: +statically at creation time of the PCM device, while +``runtime->private_data`` +points to a dynamic data structure created in the PCM open +callback:: static int snd_xxx_open(struct snd_pcm_substream *substream) { @@ -1837,20 +1748,18 @@ The allocated object must be released in the `close callback`_. Operators --------- -OK, now let me give details about each pcm callback (``ops``). In +OK, now let me give details about each PCM callback (``ops``). In general, every callback must return 0 if successful, or a negative error number such as ``-EINVAL``. To choose an appropriate error number, it is advised to check what value other parts of the kernel return when the same kind of request fails. -The callback function takes at least the argument with :c:type:`struct -snd_pcm_substream <snd_pcm_substream>` pointer. To retrieve the chip +Each callback function takes at least one argument containing a +struct snd_pcm_substream pointer. To retrieve the chip record from the given substream instance, you can use the following -macro. - -:: +macro:: - int xxx() { + int xxx(...) { struct mychip *chip = snd_pcm_substream_chip(substream); .... } @@ -1869,12 +1778,10 @@ PCM open callback static int snd_xxx_open(struct snd_pcm_substream *substream); -This is called when a pcm substream is opened. +This is called when a PCM substream is opened. At least, here you have to initialize the ``runtime->hw`` -record. Typically, this is done by like this: - -:: +record. Typically, this is done like this:: static int snd_xxx_open(struct snd_pcm_substream *substream) { @@ -1888,7 +1795,7 @@ record. Typically, this is done by like this: where ``snd_mychip_playback_hw`` is the pre-defined hardware description. -You can allocate a private data in this callback, as described in +You can allocate private data in this callback, as described in the `Private Data`_ section. If the hardware configuration needs more constraints, set the hardware @@ -1902,12 +1809,10 @@ close callback static int snd_xxx_close(struct snd_pcm_substream *substream); -Obviously, this is called when a pcm substream is closed. +Obviously, this is called when a PCM substream is closed. -Any private instance for a pcm substream allocated in the ``open`` -callback will be released here. - -:: +Any private instance for a PCM substream allocated in the ``open`` +callback will be released here:: static int snd_xxx_close(struct snd_pcm_substream *substream) { @@ -1919,9 +1824,9 @@ callback will be released here. ioctl callback ~~~~~~~~~~~~~~ -This is used for any special call to pcm ioctls. But usually you can -leave it as NULL, then PCM core calls the generic ioctl callback -function :c:func:`snd_pcm_lib_ioctl()`. If you need to deal with the +This is used for any special call to PCM ioctls. But usually you can +leave it NULL, then the PCM core calls the generic ioctl callback +function :c:func:`snd_pcm_lib_ioctl()`. If you need to deal with a unique setup of channel info or reset procedure, you can pass your own callback function here. @@ -1933,22 +1838,20 @@ hw_params callback static int snd_xxx_hw_params(struct snd_pcm_substream *substream, struct snd_pcm_hw_params *hw_params); -This is called when the hardware parameter (``hw_params``) is set up +This is called when the hardware parameters (``hw_params``) are set up by the application, that is, once when the buffer size, the period -size, the format, etc. are defined for the pcm substream. +size, the format, etc. are defined for the PCM substream. Many hardware setups should be done in this callback, including the allocation of buffers. -Parameters to be initialized are retrieved by +Parameters to be initialized are retrieved by the :c:func:`params_xxx()` macros. -When you set up the managed buffer allocation mode for the substream, +When you choose managed buffer allocation mode for the substream, a buffer is already allocated before this callback gets called. Alternatively, you can call a helper function below for -allocating the buffer, too. - -:: +allocating the buffer:: snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params)); @@ -1956,8 +1859,8 @@ allocating the buffer, too. DMA buffers have been pre-allocated. See the section `Buffer Types`_ for more details. -Note that this and ``prepare`` callbacks may be called multiple times -per initialization. For example, the OSS emulation may call these +Note that this one and the ``prepare`` callback may be called multiple +times per initialization. For example, the OSS emulation may call these callbacks at each change via its ioctl. Thus, you need to be careful not to allocate the same buffers many @@ -1965,10 +1868,10 @@ times, which will lead to memory leaks! Calling the helper function above many times is OK. It will release the previous buffer automatically when it was already allocated. -Another note is that this callback is non-atomic (schedulable) as +Another note is that this callback is non-atomic (schedulable) by default, i.e. when no ``nonatomic`` flag set. This is important, because the ``trigger`` callback is atomic (non-schedulable). That is, -mutexes or any schedule-related functions are not available in +mutexes or any schedule-related functions are not available in the ``trigger`` callback. Please see the subsection Atomicity_ for details. @@ -1984,16 +1887,14 @@ This is called to release the resources allocated via This function is always called before the close callback is called. Also, the callback may be called multiple times, too. Keep track -whether the resource was already released. +whether each resource was already released. -When you have set up the managed buffer allocation mode for the PCM +When you have chosen managed buffer allocation mode for the PCM substream, the allocated PCM buffer will be automatically released after this callback gets called. Otherwise you'll have to release the buffer manually. Typically, when the buffer was allocated from the pre-allocated pool, you can use the standard API function -:c:func:`snd_pcm_lib_malloc_pages()` like: - -:: +:c:func:`snd_pcm_lib_malloc_pages()` like:: snd_pcm_lib_free_pages(substream); @@ -2004,13 +1905,13 @@ prepare callback static int snd_xxx_prepare(struct snd_pcm_substream *substream); -This callback is called when the pcm is “prepared”. You can set the +This callback is called when the PCM is “prepared”. You can set the format type, sample rate, etc. here. The difference from ``hw_params`` is that the ``prepare`` callback will be called each time :c:func:`snd_pcm_prepare()` is called, i.e. when recovering after underruns, etc. -Note that this callback is now non-atomic. You can use +Note that this callback is non-atomic. You can use schedule-related functions safely in this callback. In this and the following callbacks, you can refer to the values via @@ -2031,13 +1932,11 @@ trigger callback static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd); -This is called when the pcm is started, stopped or paused. - -Which action is specified in the second argument, -``SNDRV_PCM_TRIGGER_XXX`` in ``<sound/pcm.h>``. At least, the ``START`` -and ``STOP`` commands must be defined in this callback. +This is called when the PCM is started, stopped or paused. -:: +The action is specified in the second argument, ``SNDRV_PCM_TRIGGER_XXX`` +defined in ``<sound/pcm.h>``. At least, the ``START`` +and ``STOP`` commands must be defined in this callback:: switch (cmd) { case SNDRV_PCM_TRIGGER_START: @@ -2050,23 +1949,23 @@ and ``STOP`` commands must be defined in this callback. return -EINVAL; } -When the pcm supports the pause operation (given in the info field of +When the PCM supports the pause operation (given in the info field of the hardware table), the ``PAUSE_PUSH`` and ``PAUSE_RELEASE`` commands -must be handled here, too. The former is the command to pause the pcm, -and the latter to restart the pcm again. +must be handled here, too. The former is the command to pause the PCM, +and the latter to restart the PCM again. -When the pcm supports the suspend/resume operation, regardless of full +When the PCM supports the suspend/resume operation, regardless of full or partial suspend/resume support, the ``SUSPEND`` and ``RESUME`` commands must be handled, too. These commands are issued when the power-management status is changed. Obviously, the ``SUSPEND`` and -``RESUME`` commands suspend and resume the pcm substream, and usually, +``RESUME`` commands suspend and resume the PCM substream, and usually, they are identical to the ``STOP`` and ``START`` commands, respectively. See the `Power Management`_ section for details. -As mentioned, this callback is atomic as default unless ``nonatomic`` +As mentioned, this callback is atomic by default unless the ``nonatomic`` flag set, and you cannot call functions which may sleep. The ``trigger`` callback should be as minimal as possible, just really -triggering the DMA. The other stuff should be initialized +triggering the DMA. The other stuff should be initialized in ``hw_params`` and ``prepare`` callbacks properly beforehand. sync_stop callback @@ -2077,22 +1976,22 @@ sync_stop callback static int snd_xxx_sync_stop(struct snd_pcm_substream *substream); This callback is optional, and NULL can be passed. It's called after -the PCM core stops the stream and changes the stream state +the PCM core stops the stream, before it changes the stream state via ``prepare``, ``hw_params`` or ``hw_free``. Since the IRQ handler might be still pending, we need to wait until the pending task finishes before moving to the next step; otherwise it -might lead to a crash due to resource conflicts or access to the freed +might lead to a crash due to resource conflicts or access to freed resources. A typical behavior is to call a synchronization function like :c:func:`synchronize_irq()` here. -For majority of drivers that need only a call of +For the majority of drivers that need only a call of :c:func:`synchronize_irq()`, there is a simpler setup, too. -While keeping NULL to ``sync_stop`` PCM callback, the driver can set -``card->sync_irq`` field to store the valid interrupt number after -requesting an IRQ, instead. Then PCM core will look call +While keeping the ``sync_stop`` PCM callback NULL, the driver can set +the ``card->sync_irq`` field to the returned interrupt number after +requesting an IRQ, instead. Then PCM core will call :c:func:`synchronize_irq()` with the given IRQ appropriately. -If the IRQ handler is released at the card destructor, you don't need +If the IRQ handler is released by the card destructor, you don't need to clear ``card->sync_irq``, as the card itself is being released. So, usually you'll need to add just a single line for assigning ``card->sync_irq`` in the driver code unless the driver re-acquires @@ -2108,30 +2007,30 @@ pointer callback static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream) This callback is called when the PCM middle layer inquires the current -hardware position on the buffer. The position must be returned in +hardware position in the buffer. The position must be returned in frames, ranging from 0 to ``buffer_size - 1``. -This is called usually from the buffer-update routine in the pcm +This is usually called from the buffer-update routine in the PCM middle layer, which is invoked when :c:func:`snd_pcm_period_elapsed()` -is called in the interrupt routine. Then the pcm middle layer updates +is called by the interrupt routine. Then the PCM middle layer updates the position and calculates the available space, and wakes up the sleeping poll threads, etc. -This callback is also atomic as default. +This callback is also atomic by default. -copy_user, copy_kernel and fill_silence ops -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +copy and fill_silence ops +~~~~~~~~~~~~~~~~~~~~~~~~~ These callbacks are not mandatory, and can be omitted in most cases. These callbacks are used when the hardware buffer cannot be in the -normal memory space. Some chips have their own buffer on the hardware +normal memory space. Some chips have their own buffer in the hardware which is not mappable. In such a case, you have to transfer the data manually from the memory buffer to the hardware buffer. Or, if the buffer is non-contiguous on both physical and virtual memory spaces, these callbacks must be defined, too. If these two callbacks are defined, copy and set-silence operations -are done by them. The detailed will be described in the later section +are done by them. The details will be described in the later section `Buffer and Memory Management`_. ack callback @@ -2142,7 +2041,11 @@ This callback is also not mandatory. This callback is called when the emu10k1-fx and cs46xx need to track the current ``appl_ptr`` for the internal buffer, and this callback is useful only for such a purpose. -This callback is atomic as default. +The callback function may return 0 or a negative error. When the +return value is ``-EPIPE``, PCM core treats that as a buffer XRUN, +and changes the state to ``SNDRV_PCM_STATE_XRUN`` automatically. + +This callback is atomic by default. page callback ~~~~~~~~~~~~~ @@ -2150,16 +2053,15 @@ page callback This callback is optional too. The mmap calls this callback to get the page fault address. -Since the recent changes, you need no special callback any longer for -the standard SG-buffer or vmalloc-buffer. Hence this callback should -be rarely used. +You need no special callback for the standard SG-buffer or vmalloc- +buffer. Hence this callback should be rarely used. -mmap calllback -~~~~~~~~~~~~~~ +mmap callback +~~~~~~~~~~~~~ This is another optional callback for controlling mmap behavior. -Once when defined, PCM core calls this callback when a page is -memory-mapped instead of dealing via the standard helper. +When defined, the PCM core calls this callback when a page is +memory-mapped, instead of using the standard helper. If you need special handling (due to some architecture or device-specific issues), implement everything here as you like. @@ -2167,13 +2069,14 @@ device-specific issues), implement everything here as you like. PCM Interrupt Handler --------------------- -The rest of pcm stuff is the PCM interrupt handler. The role of PCM +The remainder of the PCM stuff is the PCM interrupt handler. The role +of the PCM interrupt handler in the sound driver is to update the buffer position and to tell the PCM middle layer when the buffer position goes across -the prescribed period size. To inform this, call the +the specified period boundary. To inform about this, call the :c:func:`snd_pcm_period_elapsed()` function. -There are several types of sound chips to generate the interrupts. +There are several ways sound chips can generate interrupts. Interrupts at the period (fragment) boundary ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2189,14 +2092,12 @@ chip record to hold the current running substream pointer, and set the pointer value at ``open`` callback (and reset at ``close`` callback). If you acquire a spinlock in the interrupt handler, and the lock is used -in other pcm callbacks, too, then you have to release the lock before +in other PCM callbacks, too, then you have to release the lock before calling :c:func:`snd_pcm_period_elapsed()`, because -:c:func:`snd_pcm_period_elapsed()` calls other pcm callbacks +:c:func:`snd_pcm_period_elapsed()` calls other PCM callbacks inside. -Typical code would be like: - -:: +Typical code would look like:: static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id) @@ -2216,6 +2117,12 @@ Typical code would be like: return IRQ_HANDLED; } +Also, when the device can detect a buffer underrun/overrun, the driver +can notify the XRUN status to the PCM core by calling +:c:func:`snd_pcm_stop_xrun()`. This function stops the stream and sets +the PCM state to ``SNDRV_PCM_STATE_XRUN``. Note that it must be called +outside the PCM stream lock, hence it can't be called from the atomic +callback. High frequency timer interrupts @@ -2228,9 +2135,7 @@ position and accumulate the processed sample length at each interrupt. When the accumulated size exceeds the period size, call :c:func:`snd_pcm_period_elapsed()` and reset the accumulator. -Typical code would be like the following. - -:: +Typical code would look as follows:: static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id) @@ -2275,9 +2180,9 @@ Typical code would be like the following. On calling :c:func:`snd_pcm_period_elapsed()` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In both cases, even if more than one period are elapsed, you don't have +In both cases, even if more than one period has elapsed, you don't have to call :c:func:`snd_pcm_period_elapsed()` many times. Call only -once. And the pcm layer will check the current hardware pointer and +once. And the PCM layer will check the current hardware pointer and update to the latest status. Atomicity @@ -2288,15 +2193,16 @@ kernel programming are race conditions. In the Linux kernel, they are usually avoided via spin-locks, mutexes or semaphores. In general, if a race condition can happen in an interrupt handler, it has to be managed atomically, and you have to use a spinlock to protect the critical -session. If the critical section is not in interrupt handler code and if +section. If the critical section is not in interrupt handler code and if taking a relatively long time to execute is acceptable, you should use mutexes or semaphores instead. -As already seen, some pcm callbacks are atomic and some are not. For -example, the ``hw_params`` callback is non-atomic, while ``trigger`` +As already seen, some PCM callbacks are atomic and some are not. For +example, the ``hw_params`` callback is non-atomic, while the ``trigger`` callback is atomic. This means, the latter is called already in a -spinlock held by the PCM middle layer. Please take this atomicity into -account when you choose a locking scheme in the callbacks. +spinlock held by the PCM middle layer, the PCM stream lock. Please +take this atomicity into account when you choose a locking scheme in +the callbacks. In the atomic callbacks, you cannot use functions which may call :c:func:`schedule()` or go to :c:func:`sleep()`. Semaphores and @@ -2307,29 +2213,34 @@ callback, please use :c:func:`udelay()` or :c:func:`mdelay()`. All three atomic callbacks (trigger, pointer, and ack) are called with local interrupts disabled. -The recent changes in PCM core code, however, allow all PCM operations -to be non-atomic. This assumes that the all caller sides are in +However, it is possible to request all PCM operations to be non-atomic. +This assumes that all call sites are in non-atomic contexts. For example, the function :c:func:`snd_pcm_period_elapsed()` is called typically from the interrupt handler. But, if you set up the driver to use a threaded interrupt handler, this call can be in non-atomic context, too. In such -a case, you can set ``nonatomic`` filed of :c:type:`struct snd_pcm -<snd_pcm>` object after creating it. When this flag is set, mutex -and rwsem are used internally in the PCM core instead of spin and -rwlocks, so that you can call all PCM functions safely in a non-atomic +a case, you can set the ``nonatomic`` field of the struct snd_pcm object +after creating it. When this flag is set, mutex and rwsem are used internally +in the PCM core instead of spin and rwlocks, so that you can call all PCM +functions safely in a non-atomic context. +Also, in some cases, you might need to call +:c:func:`snd_pcm_period_elapsed()` in the atomic context (e.g. the +period gets elapsed during ``ack`` or other callback). There is a +variant that can be called inside the PCM stream lock +:c:func:`snd_pcm_period_elapsed_under_stream_lock()` for that purpose, +too. + Constraints ----------- -If your chip supports unconventional sample rates, or only the limited -samples, you need to set a constraint for the condition. +Due to physical limitations, hardware is not infinitely configurable. +These limitations are expressed by setting constraints. -For example, in order to restrict the sample rates in the some supported +For example, in order to restrict the sample rates to some supported values, use :c:func:`snd_pcm_hw_constraint_list()`. You need to -call this function in the open callback. - -:: +call this function in the open callback:: static unsigned int rates[] = {4000, 10000, 22050, 44100}; @@ -2351,17 +2262,12 @@ call this function in the open callback. .... } - - There are many different constraints. Look at ``sound/pcm.h`` for a complete list. You can even define your own constraint rules. For example, let's suppose my_chip can manage a substream of 1 channel if and only if the format is ``S16_LE``, otherwise it supports any format -specified in the :c:type:`struct snd_pcm_hardware -<snd_pcm_hardware>` structure (or in any other -constraint_list). You can build a rule like this: - -:: +specified in struct snd_pcm_hardware (or in any other +constraint_list). You can build a rule like this:: static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params, struct snd_pcm_hw_rule *rule) @@ -2381,9 +2287,7 @@ constraint_list). You can build a rule like this: } -Then you need to call this function to add your rule: - -:: +Then you need to call this function to add your rule:: snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS, hw_rule_channels_by_format, NULL, @@ -2392,9 +2296,7 @@ Then you need to call this function to add your rule: The rule function is called when an application sets the PCM format, and it refines the number of channels accordingly. But an application may set the number of channels before setting the format. Thus you also need -to define the inverse rule: - -:: +to define the inverse rule:: static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params, struct snd_pcm_hw_rule *rule) @@ -2413,16 +2315,14 @@ to define the inverse rule: } -... and in the open callback: - -:: +... and in the open callback:: snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT, hw_rule_format_by_channels, NULL, SNDRV_PCM_HW_PARAM_CHANNELS, -1); One typical usage of the hw constraints is to align the buffer size -with the period size. As default, ALSA PCM core doesn't enforce the +with the period size. By default, ALSA PCM core doesn't enforce the buffer size to be aligned with the period size. For example, it'd be possible to have a combination like 256 period bytes with 999 buffer bytes. @@ -2430,9 +2330,7 @@ bytes. Many device chips, however, require the buffer to be a multiple of periods. In such a case, call :c:func:`snd_pcm_hw_constraint_integer()` for -``SNDRV_PCM_HW_PARAM_PERIODS``. - -:: +``SNDRV_PCM_HW_PARAM_PERIODS``:: snd_pcm_hw_constraint_integer(substream->runtime, SNDRV_PCM_HW_PARAM_PERIODS); @@ -2440,7 +2338,7 @@ periods. In such a case, call This assures that the number of periods is integer, hence the buffer size is aligned with the period size. -The hw constraint is a very much powerful mechanism to define the +The hw constraint is a very powerful mechanism to define the preferred PCM configuration, and there are relevant helpers. I won't give more details here, rather I would like to say, “Luke, use the source.” @@ -2467,9 +2365,7 @@ Definition of Controls To create a new control, you need to define the following three callbacks: ``info``, ``get`` and ``put``. Then, define a -:c:type:`struct snd_kcontrol_new <snd_kcontrol_new>` record, such as: - -:: +struct snd_kcontrol_new record, such as:: static struct snd_kcontrol_new my_control = { @@ -2512,7 +2408,7 @@ The ``private_value`` field contains an arbitrary long integer value for this record. When using the generic ``info``, ``get`` and ``put`` callbacks, you can pass a value through this field. If several small numbers are necessary, you can combine them in bitwise. Or, it's -possible to give a pointer (casted to unsigned long) of some record to +possible to store a pointer (casted to unsigned long) of some record in this field, too. The ``tlv`` field can be used to provide metadata about the control; @@ -2579,7 +2475,7 @@ The access flag is the bitmask which specifies the access type of the given control. The default access type is ``SNDRV_CTL_ELEM_ACCESS_READWRITE``, which means both read and write are allowed to this control. When the access flag is omitted (i.e. = 0), it -is considered as ``READWRITE`` access as default. +is considered as ``READWRITE`` access by default. When the control is read-only, pass ``SNDRV_CTL_ELEM_ACCESS_READ`` instead. In this case, you don't have to define the ``put`` callback. @@ -2592,8 +2488,11 @@ If the control value changes frequently (e.g. the VU meter), changed without `Change notification`_. Applications should poll such a control constantly. -When the control is inactive, set the ``INACTIVE`` flag, too. There are -``LOCK`` and ``OWNER`` flags to change the write permissions. +When the control may be updated, but currently has no effect on anything, +setting the ``INACTIVE`` flag may be appropriate. For example, PCM +controls should be inactive while no PCM device is open. + +There are ``LOCK`` and ``OWNER`` flags to change the write permissions. Control Callbacks ----------------- @@ -2602,11 +2501,9 @@ info callback ~~~~~~~~~~~~~ The ``info`` callback is used to get detailed information on this -control. This must store the values of the given :c:type:`struct -snd_ctl_elem_info <snd_ctl_elem_info>` object. For example, -for a boolean control with a single element: - -:: +control. This must store the values of the given +struct snd_ctl_elem_info object. For example, +for a boolean control with a single element:: static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol, @@ -2625,13 +2522,11 @@ The ``type`` field specifies the type of the control. There are ``BOOLEAN``, ``INTEGER``, ``ENUMERATED``, ``BYTES``, ``IEC958`` and ``INTEGER64``. The ``count`` field specifies the number of elements in this control. For example, a stereo volume would have count = 2. The -``value`` field is a union, and the values stored are depending on the +``value`` field is a union, and the values stored depend on the type. The boolean and integer types are identical. -The enumerated type is a bit different from others. You'll need to set -the string for the currently given item index. - -:: +The enumerated type is a bit different from the others. You'll need to +set the string for the selectec item index:: static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol, struct snd_ctl_elem_info *uinfo) @@ -2676,13 +2571,10 @@ stereo channel boolean item. get callback ~~~~~~~~~~~~ -This callback is used to read the current value of the control and to -return to user-space. - -For example, - -:: +This callback is used to read the current value of the control, so it +can be returned to user-space. +For example:: static int snd_myctl_get(struct snd_kcontrol *kcontrol, struct snd_ctl_elem_value *ucontrol) @@ -2697,15 +2589,11 @@ For example, The ``value`` field depends on the type of control as well as on the info callback. For example, the sb driver uses this field to store the register offset, the bit-shift and the bit-mask. The ``private_value`` -field is set as follows: - -:: +field is set as follows:: .private_value = reg | (shift << 16) | (mask << 24) -and is retrieved in callbacks like - -:: +and is retrieved in callbacks like:: static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol, struct snd_ctl_elem_value *ucontrol) @@ -2717,19 +2605,16 @@ and is retrieved in callbacks like } In the ``get`` callback, you have to fill all the elements if the -control has more than one elements, i.e. ``count > 1``. In the example +control has more than one element, i.e. ``count > 1``. In the example above, we filled only one element (``value.integer.value[0]``) since -it's assumed as ``count = 1``. +``count = 1`` is assumed. put callback ~~~~~~~~~~~~ -This callback is used to write a value from user-space. - -For example, - -:: +This callback is used to write a value coming from user-space. +For example:: static int snd_myctl_put(struct snd_kcontrol *kcontrol, struct snd_ctl_elem_value *ucontrol) @@ -2752,12 +2637,12 @@ value is not changed, return 0 instead. If any fatal error happens, return a negative error code as usual. As in the ``get`` callback, when the control has more than one -elements, all elements must be evaluated in this callback, too. +element, all elements must be evaluated in this callback, too. Callbacks are not atomic ~~~~~~~~~~~~~~~~~~~~~~~~ -All these three callbacks are basically not atomic. +All these three callbacks are not-atomic. Control Constructor ------------------- @@ -2766,21 +2651,17 @@ When everything is ready, finally we can create a new control. To create a control, there are two functions to be called, :c:func:`snd_ctl_new1()` and :c:func:`snd_ctl_add()`. -In the simplest way, you can do like this: - -:: +In the simplest way, you can do it like this:: err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip)); if (err < 0) return err; -where ``my_control`` is the :c:type:`struct snd_kcontrol_new -<snd_kcontrol_new>` object defined above, and chip is the object -pointer to be passed to kcontrol->private_data which can be referred -to in callbacks. +where ``my_control`` is the struct snd_kcontrol_new object defined above, +and chip is the object pointer to be passed to kcontrol->private_data which +can be referred to in callbacks. -:c:func:`snd_ctl_new1()` allocates a new :c:type:`struct -snd_kcontrol <snd_kcontrol>` instance, and +:c:func:`snd_ctl_new1()` allocates a new struct snd_kcontrol instance, and :c:func:`snd_ctl_add()` assigns the given control component to the card. @@ -2788,30 +2669,25 @@ Change Notification ------------------- If you need to change and update a control in the interrupt routine, you -can call :c:func:`snd_ctl_notify()`. For example, - -:: +can call :c:func:`snd_ctl_notify()`. For example:: snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer); This function takes the card pointer, the event-mask, and the control id pointer for the notification. The event-mask specifies the types of notification, for example, in the above example, the change of control -values is notified. The id pointer is the pointer of :c:type:`struct -snd_ctl_elem_id <snd_ctl_elem_id>` to be notified. You can -find some examples in ``es1938.c`` or ``es1968.c`` for hardware volume -interrupts. +values is notified. The id pointer is the pointer of struct snd_ctl_elem_id +to be notified. You can find some examples in ``es1938.c`` or ``es1968.c`` +for hardware volume interrupts. Metadata -------- -To provide information about the dB values of a mixer control, use on of +To provide information about the dB values of a mixer control, use one of the ``DECLARE_TLV_xxx`` macros from ``<sound/tlv.h>`` to define a variable containing this information, set the ``tlv.p`` field to point to this variable, and include the ``SNDRV_CTL_ELEM_ACCESS_TLV_READ`` flag -in the ``access`` field; like this: - -:: +in the ``access`` field; like this:: static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0); @@ -2901,9 +2777,7 @@ AC97 Constructor ---------------- To create an ac97 instance, first call :c:func:`snd_ac97_bus()` -with an ``ac97_bus_ops_t`` record with callback functions. - -:: +with an ``ac97_bus_ops_t`` record with callback functions:: struct snd_ac97_bus *bus; static struct snd_ac97_bus_ops ops = { @@ -2915,11 +2789,8 @@ with an ``ac97_bus_ops_t`` record with callback functions. The bus record is shared among all belonging ac97 instances. -And then call :c:func:`snd_ac97_mixer()` with an :c:type:`struct -snd_ac97_template <snd_ac97_template>` record together with -the bus pointer created above. - -:: +And then call :c:func:`snd_ac97_mixer()` with a struct snd_ac97_template +record together with the bus pointer created above:: struct snd_ac97_template ac97; int err; @@ -2944,9 +2815,7 @@ correspond to the functions for read and write accesses to the hardware low-level codes. The ``read`` callback returns the register value specified in the -argument. - -:: +argument:: static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97, unsigned short reg) @@ -2959,9 +2828,7 @@ argument. Here, the chip can be cast from ``ac97->private_data``. Meanwhile, the ``write`` callback is used to set the register -value - -:: +value:: static void snd_mychip_ac97_write(struct snd_ac97 *ac97, unsigned short reg, unsigned short val) @@ -2994,32 +2861,24 @@ Both :c:func:`snd_ac97_write()` and the given register (``AC97_XXX``). The difference between them is that :c:func:`snd_ac97_update()` doesn't write a value if the given value has been already set, while :c:func:`snd_ac97_write()` -always rewrites the value. - -:: +always rewrites the value:: snd_ac97_write(ac97, AC97_MASTER, 0x8080); snd_ac97_update(ac97, AC97_MASTER, 0x8080); :c:func:`snd_ac97_read()` is used to read the value of the given -register. For example, - -:: +register. For example:: value = snd_ac97_read(ac97, AC97_MASTER); :c:func:`snd_ac97_update_bits()` is used to update some bits in -the given register. - -:: +the given register:: snd_ac97_update_bits(ac97, reg, mask, value); Also, there is a function to change the sample rate (of a given register such as ``AC97_PCM_FRONT_DAC_RATE``) when VRA or DRA is supported by the -codec: :c:func:`snd_ac97_set_rate()`. - -:: +codec: :c:func:`snd_ac97_set_rate()`:: snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100); @@ -3074,9 +2933,7 @@ mpu401 stuff. For example, emu10k1 has its own mpu401 routines. MIDI Constructor ---------------- -To create a rawmidi object, call :c:func:`snd_mpu401_uart_new()`. - -:: +To create a rawmidi object, call :c:func:`snd_mpu401_uart_new()`:: struct snd_rawmidi *rmidi; snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags, @@ -3114,24 +2971,19 @@ processing the output stream in the irq handler. If the MPU-401 interface shares its interrupt with the other logical devices on the card, set ``MPU401_INFO_IRQ_HOOK`` (see -`below <#MIDI-Interrupt-Handler>`__). +`below <MIDI Interrupt Handler_>`__). Usually, the port address corresponds to the command port and port + 1 corresponds to the data port. If not, you may change the ``cport`` -field of :c:type:`struct snd_mpu401 <snd_mpu401>` manually afterward. -However, :c:type:`struct snd_mpu401 <snd_mpu401>` pointer is +field of struct snd_mpu401 manually afterward. +However, struct snd_mpu401 pointer is not returned explicitly by :c:func:`snd_mpu401_uart_new()`. You -need to cast ``rmidi->private_data`` to :c:type:`struct snd_mpu401 -<snd_mpu401>` explicitly, - -:: +need to cast ``rmidi->private_data`` to struct snd_mpu401 explicitly:: struct snd_mpu401 *mpu; mpu = rmidi->private_data; -and reset the ``cport`` as you like: - -:: +and reset the ``cport`` as you like:: mpu->cport = my_own_control_port; @@ -3155,9 +3007,7 @@ occurred. In this case, you need to pass the private_data of the returned rawmidi object from :c:func:`snd_mpu401_uart_new()` as the second -argument of :c:func:`snd_mpu401_uart_interrupt()`. - -:: +argument of :c:func:`snd_mpu401_uart_interrupt()`:: snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs); @@ -3181,9 +3031,7 @@ RawMIDI Constructor ------------------- To create a rawmidi device, call the :c:func:`snd_rawmidi_new()` -function: - -:: +function:: struct snd_rawmidi *rmidi; err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi); @@ -3213,16 +3061,12 @@ output and input at the same time. After the rawmidi device is created, you need to set the operators (callbacks) for each substream. There are helper functions to set the -operators for all the substreams of a device: - -:: +operators for all the substreams of a device:: snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops); snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops); -The operators are usually defined like this: - -:: +The operators are usually defined like this:: static struct snd_rawmidi_ops snd_mymidi_output_ops = { .open = snd_mymidi_output_open, @@ -3233,9 +3077,7 @@ The operators are usually defined like this: These callbacks are explained in the `RawMIDI Callbacks`_ section. If there are more than one substream, you should give a unique name to -each of them: - -:: +each of them:: struct snd_rawmidi_substream *substream; list_for_each_entry(substream, @@ -3253,9 +3095,7 @@ device can be accessed as ``substream->rmidi->private_data``. If there is more than one port, your callbacks can determine the port index from the struct snd_rawmidi_substream data passed to each -callback: - -:: +callback:: struct snd_rawmidi_substream *substream; int index = substream->number; @@ -3300,9 +3140,7 @@ of bytes that have been read; this will be less than the number of bytes requested when there are no more data in the buffer. After the data have been transmitted successfully, call :c:func:`snd_rawmidi_transmit_ack()` to remove the data from the -substream buffer: - -:: +substream buffer:: unsigned char data; while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) { @@ -3314,9 +3152,7 @@ substream buffer: If you know beforehand that the hardware will accept data, you can use the :c:func:`snd_rawmidi_transmit()` function which reads some -data and removes them from the buffer at once: - -:: +data and removes them from the buffer at once:: while (snd_mychip_transmit_possible()) { unsigned char data; @@ -3326,8 +3162,7 @@ data and removes them from the buffer at once: } If you know beforehand how many bytes you can accept, you can use a -buffer size greater than one with the -:c:func:`snd_rawmidi_transmit\*()` functions. +buffer size greater than one with the ``snd_rawmidi_transmit*()`` functions. The ``trigger`` callback must not sleep. If the hardware FIFO is full before the substream buffer has been emptied, you have to continue @@ -3352,9 +3187,7 @@ The ``trigger`` callback must not sleep; the actual reading of data from the device is usually done in an interrupt handler. When data reception is enabled, your interrupt handler should call -:c:func:`snd_rawmidi_receive()` for all received data: - -:: +:c:func:`snd_rawmidi_receive()` for all received data:: void snd_mychip_midi_interrupt(...) { @@ -3380,7 +3213,7 @@ This ensures that the device can be closed and the driver unloaded without losing data. This callback is optional. If you do not set ``drain`` in the struct -snd_rawmidi_ops structure, ALSA will simply wait for 50 milliseconds +snd_rawmidi_ops structure, ALSA will simply wait for 50 milliseconds instead. Miscellaneous Devices @@ -3400,9 +3233,7 @@ whereas in OSS compatible mode, FM registers can be accessed with the OSS direct-FM compatible API in ``/dev/dmfmX`` device. To create the OPL3 component, you have two functions to call. The first -one is a constructor for the ``opl3_t`` instance. - -:: +one is a constructor for the ``opl3_t`` instance:: struct snd_opl3 *opl3; snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX, @@ -3420,9 +3251,7 @@ the opl3 module will allocate the specified ports by itself. When the accessing the hardware requires special method instead of the standard I/O access, you can create opl3 instance separately with -:c:func:`snd_opl3_new()`. - -:: +:c:func:`snd_opl3_new()`:: struct snd_opl3 *opl3; snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3); @@ -3439,9 +3268,7 @@ proper state. Note that :c:func:`snd_opl3_create()` always calls it internally. If the opl3 instance is created successfully, then create a hwdep device -for this opl3. - -:: +for this opl3:: struct snd_hwdep *opl3hwdep; snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep); @@ -3463,9 +3290,7 @@ the micro code. In such a case, you can create a hwdep ``isa/sb/sb16_csp.c``. The creation of the ``hwdep`` instance is done via -:c:func:`snd_hwdep_new()`. - -:: +:c:func:`snd_hwdep_new()`:: struct snd_hwdep *hw; snd_hwdep_new(card, "My HWDEP", 0, &hw); @@ -3473,18 +3298,14 @@ The creation of the ``hwdep`` instance is done via where the third argument is the index number. You can then pass any pointer value to the ``private_data``. If you -assign a private data, you should define the destructor, too. The -destructor function is set in the ``private_free`` field. - -:: +assign private data, you should define a destructor, too. The +destructor function is set in the ``private_free`` field:: struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL); hw->private_data = p; hw->private_free = mydata_free; -and the implementation of the destructor would be: - -:: +and the implementation of the destructor would be:: static void mydata_free(struct snd_hwdep *hw) { @@ -3494,9 +3315,7 @@ and the implementation of the destructor would be: The arbitrary file operations can be defined for this instance. The file operators are defined in the ``ops`` table. For example, assume that -this chip needs an ioctl. - -:: +this chip needs an ioctl:: hw->ops.open = mydata_open; hw->ops.ioctl = mydata_ioctl; @@ -3520,14 +3339,15 @@ field must be set, though). “IEC958 Playback Con Mask” is used to return the bit-mask for the IEC958 status bits of consumer mode. Similarly, “IEC958 Playback Pro Mask” -returns the bitmask for professional mode. They are read-only controls, -and are defined as MIXER controls (iface = -``SNDRV_CTL_ELEM_IFACE_MIXER``). +returns the bitmask for professional mode. They are read-only controls. Meanwhile, “IEC958 Playback Default” control is defined for getting and -setting the current default IEC958 bits. Note that this one is usually -defined as a PCM control (iface = ``SNDRV_CTL_ELEM_IFACE_PCM``), -although in some places it's defined as a MIXER control. +setting the current default IEC958 bits. + +Due to historical reasons, both variants of the Playback Mask and the +Playback Default controls can be implemented on either a +``SNDRV_CTL_ELEM_IFACE_PCM`` or a ``SNDRV_CTL_ELEM_IFACE_MIXER`` iface. +Drivers should expose the mask and default on the same iface though. In addition, you can define the control switches to enable/disable or to set the raw bit mode. The implementation will depend on the chip, but @@ -3545,79 +3365,78 @@ Buffer Types ALSA provides several different buffer allocation functions depending on the bus and the architecture. All these have a consistent API. The -allocation of physically-contiguous pages is done via +allocation of physically-contiguous pages is done via the :c:func:`snd_malloc_xxx_pages()` function, where xxx is the bus type. -The allocation of pages with fallback is -:c:func:`snd_malloc_xxx_pages_fallback()`. This function tries -to allocate the specified pages but if the pages are not available, it -tries to reduce the page sizes until enough space is found. +The allocation of pages with fallback is done via +:c:func:`snd_dma_alloc_pages_fallback()`. This function tries +to allocate the specified number of pages, but if not enough pages are +available, it tries to reduce the request size until enough space +is found, down to one page. -The release the pages, call :c:func:`snd_free_xxx_pages()` +To release the pages, call the :c:func:`snd_dma_free_pages()` function. Usually, ALSA drivers try to allocate and reserve a large contiguous -physical space at the time the module is loaded for the later use. This +physical space at the time the module is loaded for later use. This is called “pre-allocation”. As already written, you can call the -following function at pcm instance construction time (in the case of PCI -bus). - -:: +following function at PCM instance construction time (in the case of PCI +bus):: snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV, &pci->dev, size, max); -where ``size`` is the byte size to be pre-allocated and the ``max`` is -the maximum size to be changed via the ``prealloc`` proc file. The +where ``size`` is the byte size to be pre-allocated and ``max`` is +the maximum size settable via the ``prealloc`` proc file. The allocator will try to get an area as large as possible within the given size. The second argument (type) and the third argument (device pointer) are dependent on the bus. For normal devices, pass the device pointer (typically identical as ``card->dev``) to the third argument with -``SNDRV_DMA_TYPE_DEV`` type. For the continuous buffer unrelated to the +``SNDRV_DMA_TYPE_DEV`` type. + +A continuous buffer unrelated to the bus can be pre-allocated with ``SNDRV_DMA_TYPE_CONTINUOUS`` type. You can pass NULL to the device pointer in that case, which is the -default mode implying to allocate with ``GFP_KRENEL`` flag. -If you need a different GFP flag, you can pass it by encoding the flag -into the device pointer via a special macro -:c:func:`snd_dma_continuous_data()`. +default mode implying to allocate with the ``GFP_KERNEL`` flag. +If you need a restricted (lower) address, set up the coherent DMA mask +bits for the device, and pass the device pointer, like the normal +device memory allocations. For this type, it's still allowed to pass +NULL to the device pointer, too, if no address restriction is needed. + For the scatter-gather buffers, use ``SNDRV_DMA_TYPE_DEV_SG`` with the device pointer (see the `Non-Contiguous Buffers`_ section). Once the buffer is pre-allocated, you can use the allocator in the -``hw_params`` callback: - -:: +``hw_params`` callback:: snd_pcm_lib_malloc_pages(substream, size); Note that you have to pre-allocate to use this function. -Most of drivers use, though, rather the newly introduced "managed -buffer allocation mode" instead of the manual allocation or release. +But most drivers use the "managed buffer allocation mode" instead +of manual allocation and release. This is done by calling :c:func:`snd_pcm_set_managed_buffer_all()` -instead of :c:func:`snd_pcm_lib_preallocate_pages_for_all()`. - -:: +instead of :c:func:`snd_pcm_lib_preallocate_pages_for_all()`:: snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV, &pci->dev, size, max); -where passed arguments are identical in both functions. +where the passed arguments are identical for both functions. The difference in the managed mode is that PCM core will call :c:func:`snd_pcm_lib_malloc_pages()` internally already before calling the PCM ``hw_params`` callback, and call :c:func:`snd_pcm_lib_free_pages()` after the PCM ``hw_free`` callback automatically. So the driver doesn't have to call these functions explicitly in its callback any -longer. This made many driver code having NULL ``hw_params`` and +longer. This allows many drivers to have NULL ``hw_params`` and ``hw_free`` entries. External Hardware Buffers ------------------------- -Some chips have their own hardware buffers and the DMA transfer from the +Some chips have their own hardware buffers and DMA transfer from the host memory is not available. In such a case, you need to either 1) copy/set the audio data directly to the external hardware buffer, or 2) make an intermediate buffer and copy/set the data from it to the @@ -3625,8 +3444,8 @@ external hardware buffer in interrupts (or in tasklets, preferably). The first case works fine if the external hardware buffer is large enough. This method doesn't need any extra buffers and thus is more -effective. You need to define the ``copy_user`` and ``copy_kernel`` -callbacks for the data transfer, in addition to ``fill_silence`` +efficient. You need to define the ``copy`` callback +for the data transfer, in addition to the ``fill_silence`` callback for playback. However, there is a drawback: it cannot be mmapped. The examples are GUS's GF1 PCM or emu8000's wavetable PCM. @@ -3639,28 +3458,25 @@ Another case is when the chip uses a PCI memory-map region for the buffer instead of the host memory. In this case, mmap is available only on certain architectures like the Intel one. In non-mmap mode, the data cannot be transferred as in the normal way. Thus you need to define the -``copy_user``, ``copy_kernel`` and ``fill_silence`` callbacks as well, -as in the cases above. The examples are found in ``rme32.c`` and +``copy`` and ``fill_silence`` callbacks as well, +as in the cases above. Examples are found in ``rme32.c`` and ``rme96.c``. -The implementation of the ``copy_user``, ``copy_kernel`` and +The implementation of the ``copy`` and ``silence`` callbacks depends upon whether the hardware supports -interleaved or non-interleaved samples. The ``copy_user`` callback is -defined like below, a bit differently depending whether the direction -is playback or capture: +interleaved or non-interleaved samples. The ``copy`` callback is +defined like below, a bit differently depending on whether the direction +is playback or capture:: -:: - - static int playback_copy_user(struct snd_pcm_substream *substream, + static int playback_copy(struct snd_pcm_substream *substream, int channel, unsigned long pos, - void __user *src, unsigned long count); - static int capture_copy_user(struct snd_pcm_substream *substream, + struct iov_iter *src, unsigned long count); + static int capture_copy(struct snd_pcm_substream *substream, int channel, unsigned long pos, - void __user *dst, unsigned long count); + struct iov_iter *dst, unsigned long count); In the case of interleaved samples, the second argument (``channel``) is -not used. The third argument (``pos``) points the current position -offset in bytes. +not used. The third argument (``pos``) specifies the position in bytes. The meaning of the fourth argument is different between playback and capture. For playback, it holds the source data pointer, and for @@ -3671,126 +3487,88 @@ The last argument is the number of bytes to be copied. What you have to do in this callback is again different between playback and capture directions. In the playback case, you copy the given amount of data (``count``) at the specified pointer (``src``) to the specified -offset (``pos``) on the hardware buffer. When coded like memcpy-like -way, the copy would be like: +offset (``pos``) in the hardware buffer. When coded like memcpy-like +way, the copy would look like:: -:: - - my_memcpy_from_user(my_buffer + pos, src, count); + my_memcpy_from_iter(my_buffer + pos, src, count); For the capture direction, you copy the given amount of data (``count``) -at the specified offset (``pos``) on the hardware buffer to the -specified pointer (``dst``). - -:: +at the specified offset (``pos``) in the hardware buffer to the +specified pointer (``dst``):: - my_memcpy_to_user(dst, my_buffer + pos, count); + my_memcpy_to_iter(dst, my_buffer + pos, count); -Here the functions are named as ``from_user`` and ``to_user`` because -it's the user-space buffer that is passed to these callbacks. That -is, the callback is supposed to copy from/to the user-space data -directly to/from the hardware buffer. +The given ``src`` or ``dst`` a struct iov_iter pointer containing the +pointer and the size. Use the existing helpers to copy or access the +data as defined in ``linux/uio.h``. Careful readers might notice that these callbacks receive the arguments in bytes, not in frames like other callbacks. It's because -it would make coding easier like the examples above, and also it makes -easier to unify both the interleaved and non-interleaved cases, as -explained in the following. +this makes coding easier like in the examples above, and also it makes +it easier to unify both the interleaved and non-interleaved cases, as +explained below. In the case of non-interleaved samples, the implementation will be a bit -more complicated. The callback is called for each channel, passed by -the second argument, so totally it's called for N-channels times per -transfer. - -The meaning of other arguments are almost same as the interleaved -case. The callback is supposed to copy the data from/to the given -user-space buffer, but only for the given channel. For the detailed -implementations, please check ``isa/gus/gus_pcm.c`` or -"pci/rme9652/rme9652.c" as examples. +more complicated. The callback is called for each channel, passed in +the second argument, so in total it's called N times per transfer. -The above callbacks are the copy from/to the user-space buffer. There -are some cases where we want copy from/to the kernel-space buffer -instead. In such a case, ``copy_kernel`` callback is called. It'd -look like: - -:: - - static int playback_copy_kernel(struct snd_pcm_substream *substream, - int channel, unsigned long pos, - void *src, unsigned long count); - static int capture_copy_kernel(struct snd_pcm_substream *substream, - int channel, unsigned long pos, - void *dst, unsigned long count); - -As found easily, the only difference is that the buffer pointer is -without ``__user`` prefix; that is, a kernel-buffer pointer is passed -in the fourth argument. Correspondingly, the implementation would be -a version without the user-copy, such as: - -:: - - my_memcpy(my_buffer + pos, src, count); +The meaning of the other arguments are almost the same as in the +interleaved case. The callback is supposed to copy the data from/to +the given user-space buffer, but only for the given channel. For +details, please check ``isa/gus/gus_pcm.c`` or ``pci/rme9652/rme9652.c`` +as examples. Usually for the playback, another callback ``fill_silence`` is defined. It's implemented in a similar way as the copy callbacks -above: - -:: +above:: static int silence(struct snd_pcm_substream *substream, int channel, unsigned long pos, unsigned long count); -The meanings of arguments are the same as in the ``copy_user`` and -``copy_kernel`` callbacks, although there is no buffer pointer +The meanings of arguments are the same as in the ``copy`` callback, +although there is no buffer pointer argument. In the case of interleaved samples, the channel argument has -no meaning, as well as on ``copy_*`` callbacks. +no meaning, as for the ``copy`` callback. -The role of ``fill_silence`` callback is to set the given amount -(``count``) of silence data at the specified offset (``pos``) on the +The role of the ``fill_silence`` callback is to set the given amount +(``count``) of silence data at the specified offset (``pos``) in the hardware buffer. Suppose that the data format is signed (that is, the silent-data is 0), and the implementation using a memset-like function -would be like: - -:: +would look like:: my_memset(my_buffer + pos, 0, count); In the case of non-interleaved samples, again, the implementation -becomes a bit more complicated, as it's called N-times per transfer +becomes a bit more complicated, as it's called N times per transfer for each channel. See, for example, ``isa/gus/gus_pcm.c``. Non-Contiguous Buffers ---------------------- -If your hardware supports the page table as in emu10k1 or the buffer -descriptors as in via82xx, you can use the scatter-gather (SG) DMA. ALSA +If your hardware supports a page table as in emu10k1 or buffer +descriptors as in via82xx, you can use scatter-gather (SG) DMA. ALSA provides an interface for handling SG-buffers. The API is provided in ``<sound/pcm.h>``. For creating the SG-buffer handler, call :c:func:`snd_pcm_set_managed_buffer()` or :c:func:`snd_pcm_set_managed_buffer_all()` with -``SNDRV_DMA_TYPE_DEV_SG`` in the PCM constructor like other PCI -pre-allocator. You need to pass ``&pci->dev``, where pci is -the :c:type:`struct pci_dev <pci_dev>` pointer of the chip as -well. - -:: +``SNDRV_DMA_TYPE_DEV_SG`` in the PCM constructor like for other PCI +pre-allocations. You need to pass ``&pci->dev``, where pci is +the struct pci_dev pointer of the chip as well:: snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV_SG, &pci->dev, size, max); The ``struct snd_sg_buf`` instance is created as -``substream->dma_private`` in turn. You can cast the pointer like: - -:: +``substream->dma_private`` in turn. You can cast the pointer like:: struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private; -Then in :c:func:`snd_pcm_lib_malloc_pages()` call, the common SG-buffer +Then in the :c:func:`snd_pcm_lib_malloc_pages()` call, the common SG-buffer handler will allocate the non-contiguous kernel pages of the given size -and map them onto the virtually contiguous memory. The virtual pointer -is addressed in runtime->dma_area. The physical address +and map them as virtually contiguous memory. The virtual pointer +is addressed via runtime->dma_area. The physical address (``runtime->dma_addr``) is set to zero, because the buffer is physically non-contiguous. The physical address table is set up in ``sgbuf->table``. You can get the physical address at a certain offset @@ -3803,34 +3581,23 @@ Vmalloc'ed Buffers ------------------ It's possible to use a buffer allocated via :c:func:`vmalloc()`, for -example, for an intermediate buffer. In the recent version of kernel, -you can simply allocate it via standard -:c:func:`snd_pcm_lib_malloc_pages()` and co after setting up the -buffer preallocation with ``SNDRV_DMA_TYPE_VMALLOC`` type. - -:: +example, for an intermediate buffer. +You can simply allocate it via the standard +:c:func:`snd_pcm_lib_malloc_pages()` and co. after setting up the +buffer preallocation with ``SNDRV_DMA_TYPE_VMALLOC`` type:: snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_VMALLOC, NULL, 0, 0); -The NULL is passed to the device pointer argument, which indicates -that the default pages (GFP_KERNEL and GFP_HIGHMEM) will be +NULL is passed as the device pointer argument, which indicates +that default pages (GFP_KERNEL and GFP_HIGHMEM) will be allocated. -Also, note that zero is passed to both the size and the max size -arguments here. Since each vmalloc call should succeed at any time, +Also, note that zero is passed as both the size and the max size +argument here. Since each vmalloc call should succeed at any time, we don't need to pre-allocate the buffers like other continuous pages. -If you need the 32bit DMA allocation, pass the device pointer encoded -by :c:func:`snd_dma_continuous_data()` with ``GFP_KERNEL|__GFP_DMA32`` -argument. - -:: - - snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_VMALLOC, - snd_dma_continuous_data(GFP_KERNEL | __GFP_DMA32), 0, 0); - Proc Interface ============== @@ -3839,9 +3606,7 @@ useful for debugging. I recommend you set up proc files if you write a driver and want to get a running status or register dumps. The API is found in ``<sound/info.h>``. -To create a proc file, call :c:func:`snd_card_proc_new()`. - -:: +To create a proc file, call :c:func:`snd_card_proc_new()`:: struct snd_info_entry *entry; int err = snd_card_proc_new(card, "my-file", &entry); @@ -3857,28 +3622,22 @@ automatically in the card registration and release functions. When the creation is successful, the function stores a new instance in the pointer given in the third argument. It is initialized as a text proc file for read only. To use this proc file as a read-only text file -as it is, set the read callback with a private data via -:c:func:`snd_info_set_text_ops()`. - -:: +as-is, set the read callback with private data via +:c:func:`snd_info_set_text_ops()`:: snd_info_set_text_ops(entry, chip, my_proc_read); where the second argument (``chip``) is the private data to be used in -the callbacks. The third parameter specifies the read buffer size and +the callback. The third parameter specifies the read buffer size and the fourth (``my_proc_read``) is the callback function, which is -defined like - -:: +defined like:: static void my_proc_read(struct snd_info_entry *entry, struct snd_info_buffer *buffer); In the read callback, use :c:func:`snd_iprintf()` for output strings, which works just like normal :c:func:`printf()`. For -example, - -:: +example:: static void my_proc_read(struct snd_info_entry *entry, struct snd_info_buffer *buffer) @@ -3889,28 +3648,22 @@ example, snd_iprintf(buffer, "Port = %ld\n", chip->port); } -The file permissions can be changed afterwards. As default, it's set as +The file permissions can be changed afterwards. By default, they are read only for all users. If you want to add write permission for the -user (root as default), do as follows: - -:: +user (root by default), do as follows:: entry->mode = S_IFREG | S_IRUGO | S_IWUSR; -and set the write buffer size and the callback - -:: +and set the write buffer size and the callback:: entry->c.text.write = my_proc_write; -For the write callback, you can use :c:func:`snd_info_get_line()` +In the write callback, you can use :c:func:`snd_info_get_line()` to get a text line, and :c:func:`snd_info_get_str()` to retrieve a string from the line. Some examples are found in ``core/oss/mixer_oss.c``, core/oss/and ``pcm_oss.c``. -For a raw-data proc-file, set the attributes as follows: - -:: +For a raw-data proc-file, set the attributes as follows:: static const struct snd_info_entry_ops my_file_io_ops = { .read = my_file_io_read, @@ -3922,14 +3675,13 @@ For a raw-data proc-file, set the attributes as follows: entry->size = 4096; entry->mode = S_IFREG | S_IRUGO; -For the raw data, ``size`` field must be set properly. This specifies +For raw data, ``size`` field must be set properly. This specifies the maximum size of the proc file access. The read/write callbacks of raw mode are more direct than the text mode. You need to use a low-level I/O functions such as -:c:func:`copy_from/to_user()` to transfer the data. - -:: +:c:func:`copy_from_user()` and :c:func:`copy_to_user()` to transfer the +data:: static ssize_t my_file_io_read(struct snd_info_entry *entry, void *file_private_data, @@ -3954,12 +3706,11 @@ Power Management If the chip is supposed to work with suspend/resume functions, you need to add power-management code to the driver. The additional code for power-management should be ifdef-ed with ``CONFIG_PM``, or annotated -with __maybe_unused attribute; otherwise the compiler will complain -you. +with __maybe_unused attribute; otherwise the compiler will complain. If the driver *fully* supports suspend/resume that is, the device can be properly resumed to its state when suspend was called, you can set the -``SNDRV_PCM_INFO_RESUME`` flag in the pcm info field. Usually, this is +``SNDRV_PCM_INFO_RESUME`` flag in the PCM info field. Usually, this is possible when the registers of the chip can be safely saved and restored to RAM. If this is set, the trigger callback is called with ``SNDRV_PCM_TRIGGER_RESUME`` after the resume callback completes. @@ -3969,7 +3720,7 @@ is still possible, it's still worthy to implement suspend/resume callbacks. In such a case, applications would reset the status by calling :c:func:`snd_pcm_prepare()` and restart the stream appropriately. Hence, you can define suspend/resume callbacks below but -don't set ``SNDRV_PCM_INFO_RESUME`` info flag to the PCM. +don't set the ``SNDRV_PCM_INFO_RESUME`` info flag to the PCM. Note that the trigger with SUSPEND can always be called when :c:func:`snd_pcm_suspend_all()` is called, regardless of the @@ -3979,12 +3730,9 @@ behavior of :c:func:`snd_pcm_resume()`. (Thus, in theory, callback when no ``SNDRV_PCM_INFO_RESUME`` flag is set. But, it's better to keep it for compatibility reasons.) -In the earlier version of ALSA drivers, a common power-management layer -was provided, but it has been removed. The driver needs to define the +The driver needs to define the suspend/resume hooks according to the bus the device is connected to. In -the case of PCI drivers, the callbacks look like below: - -:: +the case of PCI drivers, the callbacks look like below:: static int __maybe_unused snd_my_suspend(struct device *dev) { @@ -3997,7 +3745,7 @@ the case of PCI drivers, the callbacks look like below: return 0; } -The scheme of the real suspend job is as follows. +The scheme of the real suspend job is as follows: 1. Retrieve the card and the chip data. @@ -4011,9 +3759,7 @@ The scheme of the real suspend job is as follows. 5. Stop the hardware if necessary. -A typical code would be like: - -:: +Typical code would look like:: static int __maybe_unused mychip_suspend(struct device *dev) { @@ -4032,7 +3778,7 @@ A typical code would be like: } -The scheme of the real resume job is as follows. +The scheme of the real resume job is as follows: 1. Retrieve the card and the chip data. @@ -4040,16 +3786,14 @@ The scheme of the real resume job is as follows. 3. Restore the saved registers if necessary. -4. Resume the mixer, e.g. calling :c:func:`snd_ac97_resume()`. +4. Resume the mixer, e.g. by calling :c:func:`snd_ac97_resume()`. 5. Restart the hardware (if any). 6. Call :c:func:`snd_power_change_state()` with ``SNDRV_CTL_POWER_D0`` to notify the processes. -A typical code would be like: - -:: +Typical code would look like:: static int __maybe_unused mychip_resume(struct pci_dev *pci) { @@ -4076,9 +3820,7 @@ been already suspended via its own PM ops calling OK, we have all callbacks now. Let's set them up. In the initialization of the card, make sure that you can get the chip data from the card instance, typically via ``private_data`` field, in case you created the -chip data individually. - -:: +chip data individually:: static int snd_mychip_probe(struct pci_dev *pci, const struct pci_device_id *pci_id) @@ -4098,9 +3840,7 @@ chip data individually. } When you created the chip data with :c:func:`snd_card_new()`, it's -anyway accessible via ``private_data`` field. - -:: +anyway accessible via ``private_data`` field:: static int snd_mychip_probe(struct pci_dev *pci, const struct pci_device_id *pci_id) @@ -4117,23 +3857,23 @@ anyway accessible via ``private_data`` field. .... } -If you need a space to save the registers, allocate the buffer for it +If you need space to save the registers, allocate the buffer for it here, too, since it would be fatal if you cannot allocate a memory in the suspend phase. The allocated buffer should be released in the corresponding destructor. -And next, set suspend/resume callbacks to the pci_driver. - -:: +And next, set suspend/resume callbacks to the pci_driver:: - static SIMPLE_DEV_PM_OPS(snd_my_pm_ops, mychip_suspend, mychip_resume); + static DEFINE_SIMPLE_DEV_PM_OPS(snd_my_pm_ops, mychip_suspend, mychip_resume); static struct pci_driver driver = { .name = KBUILD_MODNAME, .id_table = snd_my_ids, .probe = snd_my_probe, .remove = snd_my_remove, - .driver.pm = &snd_my_pm_ops, + .driver = { + .pm = &snd_my_pm_ops, + }, }; Module Parameters @@ -4144,9 +3884,7 @@ have the ``index``, ``id`` and ``enable`` options. If the module supports multiple cards (usually up to 8 = ``SNDRV_CARDS`` cards), they should be arrays. The default initial values are defined -already as constants for easier programming: - -:: +already as constants for easier programming:: static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX; static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR; @@ -4160,9 +3898,7 @@ The module parameters must be declared with the standard ``module_param()``, ``module_param_array()`` and :c:func:`MODULE_PARM_DESC()` macros. -The typical coding would be like below: - -:: +Typical code would look as below:: #define CARD_NAME "My Chip" @@ -4175,14 +3911,45 @@ The typical coding would be like below: Also, don't forget to define the module description and the license. Especially, the recent modprobe requires to define the -module license as GPL, etc., otherwise the system is shown as “tainted”. - -:: +module license as GPL, etc., otherwise the system is shown as “tainted”:: MODULE_DESCRIPTION("Sound driver for My Chip"); MODULE_LICENSE("GPL"); +Device-Managed Resources +======================== + +In the examples above, all resources are allocated and released +manually. But human beings are lazy in nature, especially developers +are lazier. So there are some ways to automate the release part; it's +the (device-)managed resources aka devres or devm family. For +example, an object allocated via :c:func:`devm_kmalloc()` will be +freed automatically at unbinding the device. + +ALSA core provides also the device-managed helper, namely, +:c:func:`snd_devm_card_new()` for creating a card object. +Call this functions instead of the normal :c:func:`snd_card_new()`, +and you can forget the explicit :c:func:`snd_card_free()` call, as +it's called automagically at error and removal paths. + +One caveat is that the call of :c:func:`snd_card_free()` would be put +at the beginning of the call chain only after you call +:c:func:`snd_card_register()`. + +Also, the ``private_free`` callback is always called at the card free, +so be careful to put the hardware clean-up procedure in +``private_free`` callback. It might be called even before you +actually set up at an earlier error path. For avoiding such an +invalid initialization, you can set ``private_free`` callback after +:c:func:`snd_card_register()` call succeeds. + +Another thing to be remarked is that you should use device-managed +helpers for each component as much as possible once when you manage +the card in that way. Mixing up with the normal and the managed +resources may screw up the release order. + + How To Put Your Driver Into ALSA Tree ===================================== @@ -4207,32 +3974,36 @@ Driver with A Single Source File 1. Modify sound/pci/Makefile - Suppose you have a file xyz.c. Add the following two lines + Suppose you have a file xyz.c. Add the following two lines:: -:: - - snd-xyz-objs := xyz.o - obj-$(CONFIG_SND_XYZ) += snd-xyz.o + snd-xyz-y := xyz.o + obj-$(CONFIG_SND_XYZ) += snd-xyz.o 2. Create the Kconfig entry - Add the new entry of Kconfig for your xyz driver. config SND_XYZ - tristate "Foobar XYZ" depends on SND select SND_PCM help Say Y here - to include support for Foobar XYZ soundcard. To compile this driver - as a module, choose M here: the module will be called snd-xyz. the - line, select SND_PCM, specifies that the driver xyz supports PCM. In - addition to SND_PCM, the following components are supported for - select command: SND_RAWMIDI, SND_TIMER, SND_HWDEP, - SND_MPU401_UART, SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, - SND_AC97_CODEC. Add the select command for each supported - component. + Add the new entry of Kconfig for your xyz driver:: + + config SND_XYZ + tristate "Foobar XYZ" + depends on SND + select SND_PCM + help + Say Y here to include support for Foobar XYZ soundcard. + To compile this driver as a module, choose M here: + the module will be called snd-xyz. - Note that some selections imply the lowlevel selections. For example, - PCM includes TIMER, MPU401_UART includes RAWMIDI, AC97_CODEC - includes PCM, and OPL3_LIB includes HWDEP. You don't need to give - the lowlevel selections again. +The line ``select SND_PCM`` specifies that the driver xyz supports PCM. +In addition to SND_PCM, the following components are supported for +select command: SND_RAWMIDI, SND_TIMER, SND_HWDEP, SND_MPU401_UART, +SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, SND_AC97_CODEC. +Add the select command for each supported component. - For the details of Kconfig script, refer to the kbuild documentation. +Note that some selections imply the lowlevel selections. For example, +PCM includes TIMER, MPU401_UART includes RAWMIDI, AC97_CODEC +includes PCM, and OPL3_LIB includes HWDEP. You don't need to give +the lowlevel selections again. + +For the details of Kconfig script, refer to the kbuild documentation. Drivers with Several Source Files --------------------------------- @@ -4241,18 +4012,14 @@ Suppose that the driver snd-xyz have several source files. They are located in the new subdirectory, sound/pci/xyz. 1. Add a new directory (``sound/pci/xyz``) in ``sound/pci/Makefile`` - as below + as below:: -:: + obj-$(CONFIG_SND) += sound/pci/xyz/ - obj-$(CONFIG_SND) += sound/pci/xyz/ +2. Under the directory ``sound/pci/xyz``, create a Makefile:: -2. Under the directory ``sound/pci/xyz``, create a Makefile - -:: - - snd-xyz-objs := xyz.o abc.o def.o + snd-xyz-y := xyz.o abc.o def.o obj-$(CONFIG_SND_XYZ) += snd-xyz.o 3. Create the Kconfig entry @@ -4263,31 +4030,6 @@ located in the new subdirectory, sound/pci/xyz. Useful Functions ================ -:c:func:`snd_printk()` and friends ----------------------------------- - -.. note:: This subsection describes a few helper functions for - decorating a bit more on the standard :c:func:`printk()` & co. - However, in general, the use of such helpers is no longer recommended. - If possible, try to stick with the standard functions like - :c:func:`dev_err()` or :c:func:`pr_err()`. - -ALSA provides a verbose version of the :c:func:`printk()` function. -If a kernel config ``CONFIG_SND_VERBOSE_PRINTK`` is set, this function -prints the given message together with the file name and the line of the -caller. The ``KERN_XXX`` prefix is processed as well as the original -:c:func:`printk()` does, so it's recommended to add this prefix, -e.g. snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\\n"); - -There are also :c:func:`printk()`'s for debugging. -:c:func:`snd_printd()` can be used for general debugging purposes. -If ``CONFIG_SND_DEBUG`` is set, this function is compiled, and works -just like :c:func:`snd_printk()`. If the ALSA is compiled without -the debugging flag, it's ignored. - -:c:func:`snd_printdd()` is compiled in only when -``CONFIG_SND_DEBUG_VERBOSE`` is set. - :c:func:`snd_BUG()` ------------------- diff --git a/Documentation/sound/soc/clocking.rst b/Documentation/sound/soc/clocking.rst index 32122d6877a3..25d016ea8b65 100644 --- a/Documentation/sound/soc/clocking.rst +++ b/Documentation/sound/soc/clocking.rst @@ -42,5 +42,17 @@ rate, number of channels and word size) to save on power. It is also desirable to use the codec (if possible) to drive (or master) the audio clocks as it usually gives more accurate sample rates than the CPU. +ASoC provided clock APIs +------------------------ +.. kernel-doc:: sound/soc/soc-dai.c + :identifiers: snd_soc_dai_set_sysclk +.. kernel-doc:: sound/soc/soc-dai.c + :identifiers: snd_soc_dai_set_clkdiv + +.. kernel-doc:: sound/soc/soc-dai.c + :identifiers: snd_soc_dai_set_pll + +.. kernel-doc:: sound/soc/soc-dai.c + :identifiers: snd_soc_dai_set_bclk_ratio diff --git a/Documentation/sound/soc/codec-to-codec.rst b/Documentation/sound/soc/codec-to-codec.rst index 4eaa9a0c41fc..973c147d9d82 100644 --- a/Documentation/sound/soc/codec-to-codec.rst +++ b/Documentation/sound/soc/codec-to-codec.rst @@ -68,9 +68,10 @@ file: .codec_dai_name = "codec-2-dai_name", .platform_name = "samsung-i2s.0", .dai_fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_NB_NF - | SND_SOC_DAIFMT_CBM_CFM, + | SND_SOC_DAIFMT_CBP_CFP, .ignore_suspend = 1, - .params = &dsp_codec_params, + .c2c_params = &dsp_codec_params, + .num_c2c_params = 1, }, { .name = "DSP-CODEC", @@ -79,14 +80,15 @@ file: .codec_name = "codec-3, .codec_dai_name = "codec-3-dai_name", .dai_fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_NB_NF - | SND_SOC_DAIFMT_CBM_CFM, + | SND_SOC_DAIFMT_CBP_CFP, .ignore_suspend = 1, - .params = &dsp_codec_params, + .c2c_params = &dsp_codec_params, + .num_c2c_params = 1, }, Above code snippet is motivated from sound/soc/samsung/speyside.c. -Note the "params" callback which lets the dapm know that this +Note the "c2c_params" callback which lets the dapm know that this dai_link is a codec to codec connection. In dapm core a route is created between cpu_dai playback widget diff --git a/Documentation/sound/soc/codec.rst b/Documentation/sound/soc/codec.rst index 8a9737eb7597..af973c4cac93 100644 --- a/Documentation/sound/soc/codec.rst +++ b/Documentation/sound/soc/codec.rst @@ -40,7 +40,7 @@ e.g. .prepare = wm8731_pcm_prepare, .hw_params = wm8731_hw_params, .shutdown = wm8731_shutdown, - .digital_mute = wm8731_mute, + .mute_stream = wm8731_mute, .set_sysclk = wm8731_set_dai_sysclk, .set_fmt = wm8731_set_dai_fmt, }; @@ -60,7 +60,7 @@ e.g. .rates = WM8731_RATES, .formats = WM8731_FORMATS,}, .ops = &wm8731_dai_ops, - .symmetric_rates = 1, + .symmetric_rate = 1, }; @@ -132,7 +132,7 @@ The codec driver also supports the following ALSA PCM operations:- }; Please refer to the ALSA driver PCM documentation for details. -http://www.alsa-project.org/~iwai/writing-an-alsa-driver/ +https://www.kernel.org/doc/html/latest/sound/kernel-api/writing-an-alsa-driver.html DAPM description @@ -177,10 +177,10 @@ when the mute is applied or freed. i.e. :: - static int wm8974_mute(struct snd_soc_dai *dai, int mute) + static int wm8974_mute(struct snd_soc_dai *dai, int mute, int direction) { struct snd_soc_component *component = dai->component; - u16 mute_reg = snd_soc_component_read32(component, WM8974_DAC) & 0xffbf; + u16 mute_reg = snd_soc_component_read(component, WM8974_DAC) & 0xffbf; if (mute) snd_soc_component_write(component, WM8974_DAC, mute_reg | 0x40); diff --git a/Documentation/sound/soc/dai.rst b/Documentation/sound/soc/dai.rst index 2e99183a7a47..bf8431386d26 100644 --- a/Documentation/sound/soc/dai.rst +++ b/Documentation/sound/soc/dai.rst @@ -10,14 +10,14 @@ AC97 ==== AC97 is a five wire interface commonly found on many PC sound cards. It is -now also popular in many portable devices. This DAI has a reset line and time +now also popular in many portable devices. This DAI has a RESET line and time multiplexes its data on its SDATA_OUT (playback) and SDATA_IN (capture) lines. The bit clock (BCLK) is always driven by the CODEC (usually 12.288MHz) and the frame (FRAME) (usually 48kHz) is always driven by the controller. Each AC97 frame is 21uS long and is divided into 13 time slots. The AC97 specification can be found at : -http://www.intel.com/p/en_US/business/design +https://www.intel.com/p/en_US/business/design I2S diff --git a/Documentation/sound/soc/dapm-graph.svg b/Documentation/sound/soc/dapm-graph.svg new file mode 100644 index 000000000000..d783672db815 --- /dev/null +++ b/Documentation/sound/soc/dapm-graph.svg @@ -0,0 +1,375 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<!-- Generated by graphviz version 2.43.0 (0) + --> +<!-- Title: G Pages: 1 --> +<svg width="900pt" height="630pt" + viewBox="0.00 0.00 900.00 630.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> +<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 626)"> +<title>G</title> +<polygon fill="white" stroke="transparent" points="-4,4 -4,-626 896,-626 896,4 -4,4"/> +<g id="clust1" class="cluster"> +<title>ROOT</title> +<polygon fill="none" stroke="dodgerblue" points="8,-537 8,-614 102,-614 102,-537 8,-537"/> +<text text-anchor="middle" x="55" y="-598.8" font-family="sans-serif" font-size="14.00">ROOT</text> +</g> +<g id="clust2" class="cluster"> +<title>4000b000.audio-controller</title> +<polygon fill="none" stroke="dodgerblue" points="120,-378 120,-455 312,-455 312,-378 120,-378"/> +<text text-anchor="middle" x="216" y="-439.8" font-family="sans-serif" font-size="14.00">4000b000.audio-controller</text> +</g> +<g id="clust5" class="cluster"> +<title>cs42l51.0-004a</title> +<polygon fill="none" stroke="dodgerblue" points="330,-8 330,-614 884,-614 884,-8 330,-8"/> +<text text-anchor="middle" x="607" y="-598.8" font-family="sans-serif" font-size="14.00">cs42l51.0-004a</text> +</g> +<g id="clust9" class="cluster"> +<title>hdmi-audio-codec.1.auto</title> +<polygon fill="none" stroke="dodgerblue" points="110,-463 110,-614 314,-614 314,-463 110,-463"/> +<text text-anchor="middle" x="212" y="-598.8" font-family="sans-serif" font-size="14.00">hdmi-audio-codec.1.auto</text> +</g> +<!-- ROOT_Amplifier --> +<g id="node1" class="node"> +<title>ROOT_Amplifier</title> +<polygon fill="#f2f2f2" stroke="#4d4d4d" points="93.5,-583 16.5,-583 16.5,-545 93.5,-545 93.5,-583"/> +<text text-anchor="middle" x="55" y="-567.8" font-family="sans-serif" font-size="14.00">Amplifier</text> +<text text-anchor="middle" x="55" y="-552.8" font-family="sans-serif" font-size="14.00">[out_drv]</text> +</g> +<!-- 4000b000.audio-controller_capture --> +<g id="node2" class="node"> +<title>4000b000.audio-controller_capture</title> +<polygon fill="#f2f2f2" stroke="#4d4d4d" points="202,-424 128,-424 128,-386 202,-386 202,-424"/> +<text text-anchor="middle" x="165" y="-408.8" font-family="sans-serif" font-size="14.00">capture</text> +<text text-anchor="middle" x="165" y="-393.8" font-family="sans-serif" font-size="14.00">[dai_out]</text> +</g> +<!-- 4000b000.audio-controller_playback --> +<g id="node3" class="node"> +<title>4000b000.audio-controller_playback</title> +<polygon fill="#f2f2f2" stroke="#4d4d4d" points="304,-424 230,-424 230,-386 304,-386 304,-424"/> +<text text-anchor="middle" x="267" y="-408.8" font-family="sans-serif" font-size="14.00">playback</text> +<text text-anchor="middle" x="267" y="-393.8" font-family="sans-serif" font-size="14.00">[dai_in]</text> +</g> +<!-- hdmi-audio-codec.1.auto_I2S Playback --> +<g id="node28" class="node"> +<title>hdmi-audio-codec.1.auto_I2S Playback</title> +<polygon fill="#f2f2f2" stroke="#4d4d4d" points="306,-583 208,-583 208,-545 306,-545 306,-583"/> +<text text-anchor="middle" x="257" y="-567.8" font-family="sans-serif" font-size="14.00">I2S Playback</text> +<text text-anchor="middle" x="257" y="-552.8" font-family="sans-serif" font-size="14.00">[dai_in]</text> +</g> +<!-- 4000b000.audio-controller_playback->hdmi-audio-codec.1.auto_I2S Playback --> +<g id="edge21" class="edge"> +<title>4000b000.audio-controller_playback->hdmi-audio-codec.1.auto_I2S Playback</title> +<path fill="none" stroke="black" d="M276.84,-424.14C282.19,-435.06 288.26,-449.42 291,-463 295.05,-483.04 296.67,-489.36 291,-509 288.25,-518.54 283.26,-528.01 277.93,-536.3"/> +<polygon fill="black" stroke="black" points="274.89,-534.55 272.11,-544.78 280.66,-538.51 274.89,-534.55"/> +</g> +<!-- hdmi-audio-codec.1.auto_Capture --> +<g id="node4" class="node"> +<title>hdmi-audio-codec.1.auto_Capture</title> +<polygon fill="#f2f2f2" stroke="#4d4d4d" points="192,-509 118,-509 118,-471 192,-471 192,-509"/> +<text text-anchor="middle" x="155" y="-493.8" font-family="sans-serif" font-size="14.00">Capture</text> +<text text-anchor="middle" x="155" y="-478.8" font-family="sans-serif" font-size="14.00">[dai_out]</text> +</g> +<!-- hdmi-audio-codec.1.auto_Capture->4000b000.audio-controller_capture --> +<g id="edge1" class="edge"> +<title>hdmi-audio-codec.1.auto_Capture->4000b000.audio-controller_capture</title> +<path fill="none" stroke="black" d="M157.17,-470.99C158.46,-460.3 160.12,-446.5 161.58,-434.37"/> +<polygon fill="black" stroke="black" points="165.08,-434.61 162.8,-424.26 158.13,-433.77 165.08,-434.61"/> +</g> +<!-- cs42l51.0-004a_AIN1L --> +<g id="node5" class="node"> +<title>cs42l51.0-004a_AIN1L</title> +<polygon fill="#f2f2f2" stroke="#4d4d4d" points="836.5,-583 775.5,-583 775.5,-545 836.5,-545 836.5,-583"/> +<text text-anchor="middle" x="806" y="-567.8" font-family="sans-serif" font-size="14.00">AIN1L</text> +<text text-anchor="middle" x="806" y="-552.8" font-family="sans-serif" font-size="14.00">[input]</text> +</g> +<!-- cs42l51.0-004a_PGA-ADC Mux Left --> +<g id="node22" class="node"> +<title>cs42l51.0-004a_PGA-ADC Mux Left</title> +<polygon fill="#f2f2f2" stroke="#4d4d4d" points="876,-509 736,-509 736,-471 876,-471 876,-509"/> +<text text-anchor="middle" x="806" y="-493.8" font-family="sans-serif" font-size="14.00">PGA-ADC Mux Left</text> +<text text-anchor="middle" x="806" y="-478.8" font-family="sans-serif" font-size="14.00">[mux]</text> +</g> +<!-- cs42l51.0-004a_AIN1L->cs42l51.0-004a_PGA-ADC Mux Left --> +<g id="edge14" class="edge"> +<title>cs42l51.0-004a_AIN1L->cs42l51.0-004a_PGA-ADC Mux Left</title> +<path fill="none" stroke="black" d="M806,-544.83C806,-537.13 806,-527.97 806,-519.42"/> +<polygon fill="black" stroke="black" points="809.5,-519.41 806,-509.41 802.5,-519.41 809.5,-519.41"/> +</g> +<!-- cs42l51.0-004a_AIN1R --> +<g id="node6" class="node"> +<title>cs42l51.0-004a_AIN1R</title> +<polygon fill="#f2f2f2" stroke="#4d4d4d" points="738.5,-583 677.5,-583 677.5,-545 738.5,-545 738.5,-583"/> +<text text-anchor="middle" x="708" y="-567.8" font-family="sans-serif" font-size="14.00">AIN1R</text> +<text text-anchor="middle" x="708" y="-552.8" font-family="sans-serif" font-size="14.00">[input]</text> +</g> +<!-- cs42l51.0-004a_PGA-ADC Mux Right --> +<g id="node23" class="node"> +<title>cs42l51.0-004a_PGA-ADC Mux Right</title> +<polygon fill="#f2f2f2" stroke="#4d4d4d" points="717.5,-509 568.5,-509 568.5,-471 717.5,-471 717.5,-509"/> +<text text-anchor="middle" x="643" y="-493.8" font-family="sans-serif" font-size="14.00">PGA-ADC Mux Right</text> +<text text-anchor="middle" x="643" y="-478.8" font-family="sans-serif" font-size="14.00">[mux]</text> +</g> +<!-- cs42l51.0-004a_AIN1R->cs42l51.0-004a_PGA-ADC Mux Right --> +<g id="edge15" class="edge"> +<title>cs42l51.0-004a_AIN1R->cs42l51.0-004a_PGA-ADC Mux Right</title> +<path fill="none" stroke="black" d="M691.6,-544.83C683.96,-536.37 674.73,-526.15 666.38,-516.9"/> +<polygon fill="black" stroke="black" points="668.92,-514.49 659.62,-509.41 663.73,-519.18 668.92,-514.49"/> +</g> +<!-- cs42l51.0-004a_AIN2L --> +<g id="node7" class="node"> +<title>cs42l51.0-004a_AIN2L</title> +<polygon fill="#f2f2f2" stroke="#4d4d4d" points="659.5,-583 598.5,-583 598.5,-545 659.5,-545 659.5,-583"/> +<text text-anchor="middle" x="629" y="-567.8" font-family="sans-serif" font-size="14.00">AIN2L</text> +<text text-anchor="middle" x="629" y="-552.8" font-family="sans-serif" font-size="14.00">[input]</text> +</g> +<!-- cs42l51.0-004a_AIN2R --> +<g id="node8" class="node"> +<title>cs42l51.0-004a_AIN2R</title> +<polygon fill="#f2f2f2" stroke="#4d4d4d" points="580.5,-583 519.5,-583 519.5,-545 580.5,-545 580.5,-583"/> +<text text-anchor="middle" x="550" y="-567.8" font-family="sans-serif" font-size="14.00">AIN2R</text> +<text text-anchor="middle" x="550" y="-552.8" font-family="sans-serif" font-size="14.00">[input]</text> +</g> +<!-- cs42l51.0-004a_Capture --> +<g id="node9" class="node"> +<title>cs42l51.0-004a_Capture</title> +<polygon fill="#f2f2f2" stroke="#4d4d4d" points="692,-276 618,-276 618,-238 692,-238 692,-276"/> +<text text-anchor="middle" x="655" y="-260.8" font-family="sans-serif" font-size="14.00">Capture</text> +<text text-anchor="middle" x="655" y="-245.8" font-family="sans-serif" font-size="14.00">[dai_out]</text> +</g> +<!-- cs42l51.0-004a_DAC Mux --> +<g id="node10" class="node"> +<title>cs42l51.0-004a_DAC Mux</title> +<polygon fill="none" stroke="#008b00" stroke-width="2" points="598.5,-202 521.5,-202 521.5,-164 598.5,-164 598.5,-202"/> +<text text-anchor="middle" x="560" y="-186.8" font-family="sans-serif" font-size="14.00">DAC Mux</text> +<text text-anchor="middle" x="560" y="-171.8" font-family="sans-serif" font-size="14.00">[mux]</text> +</g> +<!-- cs42l51.0-004a_Left DAC --> +<g id="node14" class="node"> +<title>cs42l51.0-004a_Left DAC</title> +<polygon fill="none" stroke="#008b00" stroke-width="2" points="548,-128 474,-128 474,-90 548,-90 548,-128"/> +<text text-anchor="middle" x="511" y="-112.8" font-family="sans-serif" font-size="14.00">Left DAC</text> +<text text-anchor="middle" x="511" y="-97.8" font-family="sans-serif" font-size="14.00">[dac]</text> +</g> +<!-- cs42l51.0-004a_DAC Mux->cs42l51.0-004a_Left DAC --> +<g id="edge9" class="edge"> +<title>cs42l51.0-004a_DAC Mux->cs42l51.0-004a_Left DAC</title> +<path fill="none" stroke="black" d="M547.64,-163.83C542.05,-155.62 535.34,-145.76 529.19,-136.73"/> +<polygon fill="black" stroke="black" points="532.05,-134.71 523.53,-128.41 526.26,-138.65 532.05,-134.71"/> +</g> +<!-- cs42l51.0-004a_Right DAC --> +<g id="node26" class="node"> +<title>cs42l51.0-004a_Right DAC</title> +<polygon fill="none" stroke="#008b00" stroke-width="2" points="649.5,-128 566.5,-128 566.5,-90 649.5,-90 649.5,-128"/> +<text text-anchor="middle" x="608" y="-112.8" font-family="sans-serif" font-size="14.00">Right DAC</text> +<text text-anchor="middle" x="608" y="-97.8" font-family="sans-serif" font-size="14.00">[dac]</text> +</g> +<!-- cs42l51.0-004a_DAC Mux->cs42l51.0-004a_Right DAC --> +<g id="edge18" class="edge"> +<title>cs42l51.0-004a_DAC Mux->cs42l51.0-004a_Right DAC</title> +<path fill="none" stroke="black" d="M572.11,-163.83C577.53,-155.71 584.02,-145.96 589.99,-137.01"/> +<polygon fill="black" stroke="black" points="593.09,-138.68 595.72,-128.41 587.27,-134.79 593.09,-138.68"/> +</g> +<!-- cs42l51.0-004a_HPL --> +<g id="node11" class="node"> +<title>cs42l51.0-004a_HPL</title> +<polygon fill="none" stroke="#008b00" stroke-width="2" points="546.5,-54 475.5,-54 475.5,-16 546.5,-16 546.5,-54"/> +<text text-anchor="middle" x="511" y="-38.8" font-family="sans-serif" font-size="14.00">HPL</text> +<text text-anchor="middle" x="511" y="-23.8" font-family="sans-serif" font-size="14.00">[output]</text> +</g> +<!-- cs42l51.0-004a_HPR --> +<g id="node12" class="node"> +<title>cs42l51.0-004a_HPR</title> +<polygon fill="none" stroke="#008b00" stroke-width="2" points="643.5,-54 572.5,-54 572.5,-16 643.5,-16 643.5,-54"/> +<text text-anchor="middle" x="608" y="-38.8" font-family="sans-serif" font-size="14.00">HPR</text> +<text text-anchor="middle" x="608" y="-23.8" font-family="sans-serif" font-size="14.00">[output]</text> +</g> +<!-- cs42l51.0-004a_Left ADC --> +<g id="node13" class="node"> +<title>cs42l51.0-004a_Left ADC</title> +<polygon fill="#f2f2f2" stroke="#4d4d4d" points="822,-350 748,-350 748,-312 822,-312 822,-350"/> +<text text-anchor="middle" x="785" y="-334.8" font-family="sans-serif" font-size="14.00">Left ADC</text> +<text text-anchor="middle" x="785" y="-319.8" font-family="sans-serif" font-size="14.00">[adc]</text> +</g> +<!-- cs42l51.0-004a_Left ADC->cs42l51.0-004a_Capture --> +<g id="edge4" class="edge"> +<title>cs42l51.0-004a_Left ADC->cs42l51.0-004a_Capture</title> +<path fill="none" stroke="black" d="M752.2,-311.83C735.41,-302.54 714.8,-291.12 696.88,-281.2"/> +<polygon fill="black" stroke="black" points="698.24,-277.95 687.79,-276.16 694.85,-284.07 698.24,-277.95"/> +</g> +<!-- cs42l51.0-004a_Left DAC->cs42l51.0-004a_HPL --> +<g id="edge6" class="edge"> +<title>cs42l51.0-004a_Left DAC->cs42l51.0-004a_HPL</title> +<path fill="none" stroke="black" d="M511,-89.83C511,-82.13 511,-72.97 511,-64.42"/> +<polygon fill="black" stroke="black" points="514.5,-64.41 511,-54.41 507.5,-64.41 514.5,-64.41"/> +</g> +<!-- cs42l51.0-004a_Left PGA --> +<g id="node15" class="node"> +<title>cs42l51.0-004a_Left PGA</title> +<polygon fill="#f2f2f2" stroke="#4d4d4d" points="838,-424 764,-424 764,-386 838,-386 838,-424"/> +<text text-anchor="middle" x="801" y="-408.8" font-family="sans-serif" font-size="14.00">Left PGA</text> +<text text-anchor="middle" x="801" y="-393.8" font-family="sans-serif" font-size="14.00">[pga]</text> +</g> +<!-- cs42l51.0-004a_Left PGA->cs42l51.0-004a_Left ADC --> +<g id="edge8" class="edge"> +<title>cs42l51.0-004a_Left PGA->cs42l51.0-004a_Left ADC</title> +<path fill="none" stroke="black" d="M796.96,-385.83C795.25,-378.13 793.22,-368.97 791.31,-360.42"/> +<polygon fill="black" stroke="black" points="794.68,-359.42 789.09,-350.41 787.84,-360.93 794.68,-359.42"/> +</g> +<!-- cs42l51.0-004a_MCLK --> +<g id="node16" class="node"> +<title>cs42l51.0-004a_MCLK</title> +<polygon fill="none" stroke="#008b00" stroke-width="2" points="594.5,-350 525.5,-350 525.5,-312 594.5,-312 594.5,-350"/> +<text text-anchor="middle" x="560" y="-334.8" font-family="sans-serif" font-size="14.00">MCLK</text> +<text text-anchor="middle" x="560" y="-319.8" font-family="sans-serif" font-size="14.00">[supply]</text> +</g> +<!-- cs42l51.0-004a_MCLK->cs42l51.0-004a_Capture --> +<g id="edge2" class="edge"> +<title>cs42l51.0-004a_MCLK->cs42l51.0-004a_Capture</title> +<path fill="none" stroke="black" d="M583.97,-311.83C595.79,-302.88 610.2,-291.96 622.94,-282.3"/> +<polygon fill="black" stroke="black" points="625.18,-284.99 631.04,-276.16 620.95,-279.41 625.18,-284.99"/> +</g> +<!-- cs42l51.0-004a_Playback --> +<g id="node24" class="node"> +<title>cs42l51.0-004a_Playback</title> +<polygon fill="none" stroke="#008b00" stroke-width="2" points="597,-276 523,-276 523,-238 597,-238 597,-276"/> +<text text-anchor="middle" x="560" y="-260.8" font-family="sans-serif" font-size="14.00">Playback</text> +<text text-anchor="middle" x="560" y="-245.8" font-family="sans-serif" font-size="14.00">[dai_in]</text> +</g> +<!-- cs42l51.0-004a_MCLK->cs42l51.0-004a_Playback --> +<g id="edge16" class="edge"> +<title>cs42l51.0-004a_MCLK->cs42l51.0-004a_Playback</title> +<path fill="none" stroke="black" d="M560,-311.83C560,-304.13 560,-294.97 560,-286.42"/> +<polygon fill="black" stroke="black" points="563.5,-286.41 560,-276.41 556.5,-286.41 563.5,-286.41"/> +</g> +<!-- cs42l51.0-004a_MICL --> +<g id="node17" class="node"> +<title>cs42l51.0-004a_MICL</title> +<polygon fill="#f2f2f2" stroke="#4d4d4d" points="399.5,-509 338.5,-509 338.5,-471 399.5,-471 399.5,-509"/> +<text text-anchor="middle" x="369" y="-493.8" font-family="sans-serif" font-size="14.00">MICL</text> +<text text-anchor="middle" x="369" y="-478.8" font-family="sans-serif" font-size="14.00">[input]</text> +</g> +<!-- cs42l51.0-004a_Mic Preamp Left --> +<g id="node20" class="node"> +<title>cs42l51.0-004a_Mic Preamp Left</title> +<polygon fill="#f2f2f2" stroke="#4d4d4d" points="461.5,-424 338.5,-424 338.5,-386 461.5,-386 461.5,-424"/> +<text text-anchor="middle" x="400" y="-408.8" font-family="sans-serif" font-size="14.00">Mic Preamp Left</text> +<text text-anchor="middle" x="400" y="-393.8" font-family="sans-serif" font-size="14.00">[mixer]</text> +</g> +<!-- cs42l51.0-004a_MICL->cs42l51.0-004a_Mic Preamp Left --> +<g id="edge12" class="edge"> +<title>cs42l51.0-004a_MICL->cs42l51.0-004a_Mic Preamp Left</title> +<path fill="none" stroke="black" d="M375.73,-470.99C379.8,-460.08 385.08,-445.94 389.68,-433.64"/> +<polygon fill="black" stroke="black" points="392.96,-434.85 393.18,-424.26 386.4,-432.4 392.96,-434.85"/> +</g> +<!-- cs42l51.0-004a_MICR --> +<g id="node18" class="node"> +<title>cs42l51.0-004a_MICR</title> +<polygon fill="#f2f2f2" stroke="#4d4d4d" points="501.5,-583 440.5,-583 440.5,-545 501.5,-545 501.5,-583"/> +<text text-anchor="middle" x="471" y="-567.8" font-family="sans-serif" font-size="14.00">MICR</text> +<text text-anchor="middle" x="471" y="-552.8" font-family="sans-serif" font-size="14.00">[input]</text> +</g> +<!-- cs42l51.0-004a_Mic Preamp Right --> +<g id="node21" class="node"> +<title>cs42l51.0-004a_Mic Preamp Right</title> +<polygon fill="#f2f2f2" stroke="#4d4d4d" points="550.5,-509 417.5,-509 417.5,-471 550.5,-471 550.5,-509"/> +<text text-anchor="middle" x="484" y="-493.8" font-family="sans-serif" font-size="14.00">Mic Preamp Right</text> +<text text-anchor="middle" x="484" y="-478.8" font-family="sans-serif" font-size="14.00">[mixer]</text> +</g> +<!-- cs42l51.0-004a_MICR->cs42l51.0-004a_Mic Preamp Right --> +<g id="edge13" class="edge"> +<title>cs42l51.0-004a_MICR->cs42l51.0-004a_Mic Preamp Right</title> +<path fill="none" stroke="black" d="M474.28,-544.83C475.67,-537.13 477.32,-527.97 478.87,-519.42"/> +<polygon fill="black" stroke="black" points="482.34,-519.88 480.68,-509.41 475.45,-518.63 482.34,-519.88"/> +</g> +<!-- cs42l51.0-004a_Mic Bias --> +<g id="node19" class="node"> +<title>cs42l51.0-004a_Mic Bias</title> +<polygon fill="#f2f2f2" stroke="#4d4d4d" points="409.5,-583 338.5,-583 338.5,-545 409.5,-545 409.5,-583"/> +<text text-anchor="middle" x="374" y="-567.8" font-family="sans-serif" font-size="14.00">Mic Bias</text> +<text text-anchor="middle" x="374" y="-552.8" font-family="sans-serif" font-size="14.00">[supply]</text> +</g> +<!-- cs42l51.0-004a_Mic Bias->cs42l51.0-004a_MICL --> +<g id="edge11" class="edge"> +<title>cs42l51.0-004a_Mic Bias->cs42l51.0-004a_MICL</title> +<path fill="none" stroke="black" d="M372.74,-544.83C372.2,-537.13 371.57,-527.97 370.97,-519.42"/> +<polygon fill="black" stroke="black" points="374.46,-519.15 370.28,-509.41 367.48,-519.63 374.46,-519.15"/> +</g> +<!-- cs42l51.0-004a_PGA-ADC Mux Left->cs42l51.0-004a_Left PGA --> +<g id="edge10" class="edge"> +<title>cs42l51.0-004a_PGA-ADC Mux Left->cs42l51.0-004a_Left PGA</title> +<path fill="none" stroke="black" d="M804.92,-470.99C804.27,-460.3 803.44,-446.5 802.71,-434.37"/> +<polygon fill="black" stroke="black" points="806.2,-434.03 802.1,-424.26 799.21,-434.45 806.2,-434.03"/> +</g> +<!-- cs42l51.0-004a_Right PGA --> +<g id="node27" class="node"> +<title>cs42l51.0-004a_Right PGA</title> +<polygon fill="#f2f2f2" stroke="#4d4d4d" points="688.5,-424 605.5,-424 605.5,-386 688.5,-386 688.5,-424"/> +<text text-anchor="middle" x="647" y="-408.8" font-family="sans-serif" font-size="14.00">Right PGA</text> +<text text-anchor="middle" x="647" y="-393.8" font-family="sans-serif" font-size="14.00">[pga]</text> +</g> +<!-- cs42l51.0-004a_PGA-ADC Mux Right->cs42l51.0-004a_Right PGA --> +<g id="edge19" class="edge"> +<title>cs42l51.0-004a_PGA-ADC Mux Right->cs42l51.0-004a_Right PGA</title> +<path fill="none" stroke="black" d="M643.87,-470.99C644.38,-460.3 645.05,-446.5 645.63,-434.37"/> +<polygon fill="black" stroke="black" points="649.13,-434.42 646.12,-424.26 642.14,-434.08 649.13,-434.42"/> +</g> +<!-- cs42l51.0-004a_Playback->cs42l51.0-004a_DAC Mux --> +<g id="edge5" class="edge"> +<title>cs42l51.0-004a_Playback->cs42l51.0-004a_DAC Mux</title> +<path fill="none" stroke="black" d="M560,-237.83C560,-230.13 560,-220.97 560,-212.42"/> +<polygon fill="black" stroke="black" points="563.5,-212.41 560,-202.41 556.5,-212.41 563.5,-212.41"/> +</g> +<!-- cs42l51.0-004a_Right ADC --> +<g id="node25" class="node"> +<title>cs42l51.0-004a_Right ADC</title> +<polygon fill="#f2f2f2" stroke="#4d4d4d" points="697,-350 613,-350 613,-312 697,-312 697,-350"/> +<text text-anchor="middle" x="655" y="-334.8" font-family="sans-serif" font-size="14.00">Right ADC</text> +<text text-anchor="middle" x="655" y="-319.8" font-family="sans-serif" font-size="14.00">[adc]</text> +</g> +<!-- cs42l51.0-004a_Right ADC->cs42l51.0-004a_Capture --> +<g id="edge3" class="edge"> +<title>cs42l51.0-004a_Right ADC->cs42l51.0-004a_Capture</title> +<path fill="none" stroke="black" d="M655,-311.83C655,-304.13 655,-294.97 655,-286.42"/> +<polygon fill="black" stroke="black" points="658.5,-286.41 655,-276.41 651.5,-286.41 658.5,-286.41"/> +</g> +<!-- cs42l51.0-004a_Right DAC->cs42l51.0-004a_HPR --> +<g id="edge7" class="edge"> +<title>cs42l51.0-004a_Right DAC->cs42l51.0-004a_HPR</title> +<path fill="none" stroke="black" d="M608,-89.83C608,-82.13 608,-72.97 608,-64.42"/> +<polygon fill="black" stroke="black" points="611.5,-64.41 608,-54.41 604.5,-64.41 611.5,-64.41"/> +</g> +<!-- cs42l51.0-004a_Right PGA->cs42l51.0-004a_Right ADC --> +<g id="edge17" class="edge"> +<title>cs42l51.0-004a_Right PGA->cs42l51.0-004a_Right ADC</title> +<path fill="none" stroke="black" d="M649.02,-385.83C649.87,-378.13 650.89,-368.97 651.84,-360.42"/> +<polygon fill="black" stroke="black" points="655.33,-360.74 652.95,-350.41 648.37,-359.97 655.33,-360.74"/> +</g> +<!-- hdmi-audio-codec.1.auto_TX --> +<g id="node30" class="node"> +<title>hdmi-audio-codec.1.auto_TX</title> +<polygon fill="#f2f2f2" stroke="#4d4d4d" points="281.5,-509 210.5,-509 210.5,-471 281.5,-471 281.5,-509"/> +<text text-anchor="middle" x="246" y="-493.8" font-family="sans-serif" font-size="14.00">TX</text> +<text text-anchor="middle" x="246" y="-478.8" font-family="sans-serif" font-size="14.00">[output]</text> +</g> +<!-- hdmi-audio-codec.1.auto_I2S Playback->hdmi-audio-codec.1.auto_TX --> +<g id="edge22" class="edge"> +<title>hdmi-audio-codec.1.auto_I2S Playback->hdmi-audio-codec.1.auto_TX</title> +<path fill="none" stroke="black" d="M254.22,-544.83C253.05,-537.13 251.65,-527.97 250.34,-519.42"/> +<polygon fill="black" stroke="black" points="253.78,-518.77 248.81,-509.41 246.86,-519.83 253.78,-518.77"/> +</g> +<!-- hdmi-audio-codec.1.auto_RX --> +<g id="node29" class="node"> +<title>hdmi-audio-codec.1.auto_RX</title> +<polygon fill="#f2f2f2" stroke="#4d4d4d" points="189.5,-583 118.5,-583 118.5,-545 189.5,-545 189.5,-583"/> +<text text-anchor="middle" x="154" y="-567.8" font-family="sans-serif" font-size="14.00">RX</text> +<text text-anchor="middle" x="154" y="-552.8" font-family="sans-serif" font-size="14.00">[output]</text> +</g> +<!-- hdmi-audio-codec.1.auto_RX->hdmi-audio-codec.1.auto_Capture --> +<g id="edge20" class="edge"> +<title>hdmi-audio-codec.1.auto_RX->hdmi-audio-codec.1.auto_Capture</title> +<path fill="none" stroke="black" d="M154.25,-544.83C154.36,-537.13 154.49,-527.97 154.61,-519.42"/> +<polygon fill="black" stroke="black" points="158.1,-519.46 154.74,-509.41 151.11,-519.36 158.1,-519.46"/> +</g> +</g> +</svg> diff --git a/Documentation/sound/soc/dapm.rst b/Documentation/sound/soc/dapm.rst index 8e44107933ab..73a42d5a9f30 100644 --- a/Documentation/sound/soc/dapm.rst +++ b/Documentation/sound/soc/dapm.rst @@ -7,8 +7,8 @@ Description Dynamic Audio Power Management (DAPM) is designed to allow portable Linux devices to use the minimum amount of power within the audio -subsystem at all times. It is independent of other kernel PM and as -such, can easily co-exist with the other PM systems. +subsystem at all times. It is independent of other kernel power +management frameworks and, as such, can easily co-exist with them. DAPM is also completely transparent to all user space applications as all power switching is done within the ASoC core. No code changes or @@ -16,11 +16,32 @@ recompiling are required for user space applications. DAPM makes power switching decisions based upon any audio stream (capture/playback) activity and audio mixer settings within the device. -DAPM spans the whole machine. It covers power control within the entire -audio subsystem, this includes internal codec power blocks and machine -level power systems. +DAPM is based on two basic elements, called widgets and routes: -There are 4 power domains within DAPM + * a **widget** is every part of the audio hardware that can be enabled by + software when in use and disabled to save power when not in use + * a **route** is an interconnection between widgets that exists when sound + can flow from one widget to the other + +All DAPM power switching decisions are made automatically by consulting an +audio routing graph. This graph is specific to each sound card and spans +the whole sound card, so some DAPM routes connect two widgets belonging to +different components (e.g. the LINE OUT pin of a CODEC and the input pin of +an amplifier). + +The graph for the STM32MP1-DK1 sound card is shown in picture: + +.. kernel-figure:: dapm-graph.svg + :alt: Example DAPM graph + :align: center + +You can also generate compatible graph for your sound card using +`tools/sound/dapm-graph` utility. + +DAPM power domains +================== + +There are 4 power domains within DAPM: Codec bias domain VREF, VMID (core codec and audio power) @@ -47,17 +68,11 @@ Stream domain Enabled and disabled when stream playback/capture is started and stopped respectively. e.g. aplay, arecord. -All DAPM power switching decisions are made automatically by consulting an audio -routing map of the whole machine. This map is specific to each machine and -consists of the interconnections between every audio component (including -internal codec components). All audio components that effect power are called -widgets hereafter. - DAPM Widgets ============ -Audio DAPM widgets fall into a number of types:- +Audio DAPM widgets fall into a number of types: Mixer Mixes several analog signals into a single analog signal. @@ -141,14 +156,14 @@ Stream Widgets relate to the stream power domain and only consist of ADCs (analog to digital converters), DACs (digital to analog converters), AIF IN and AIF OUT. -Stream widgets have the following format:- +Stream widgets have the following format: :: SND_SOC_DAPM_DAC(name, stream name, reg, shift, invert), SND_SOC_DAPM_AIF_IN(name, stream, slot, reg, shift, invert) NOTE: the stream name must match the corresponding stream name in your codec -snd_soc_codec_dai. +snd_soc_dai_driver. e.g. stream widgets for HiFi playback and capture :: @@ -167,7 +182,7 @@ Path Domain Widgets ------------------- Path domain widgets have a ability to control or affect the audio signal or -audio paths within the audio subsystem. They have the following form:- +audio paths within the audio subsystem. They have the following form: :: SND_SOC_DAPM_PGA(name, reg, shift, invert, controls, num_controls) @@ -207,7 +222,7 @@ powered. e.g. A machine widget can have an optional call back. e.g. Jack connector widget for an external Mic that enables Mic Bias -when the Mic is inserted:-:: +when the Mic is inserted:: static int spitz_mic_bias(struct snd_soc_dapm_widget* w, int event) { @@ -221,7 +236,7 @@ when the Mic is inserted:-:: Codec (BIAS) Domain ------------------- -The codec bias power domain has no widgets and is handled by the codecs DAPM +The codec bias power domain has no widgets and is handled by the codec DAPM event handler. This handler is called when the codec powerstate is changed wrt to any stream event or by kernel PM events. @@ -229,17 +244,58 @@ to any stream event or by kernel PM events. Virtual Widgets --------------- -Sometimes widgets exist in the codec or machine audio map that don't have any +Sometimes widgets exist in the codec or machine audio graph that don't have any corresponding soft power control. In this case it is necessary to create a virtual widget - a widget with no control bits e.g. :: - SND_SOC_DAPM_MIXER("AC97 Mixer", SND_SOC_DAPM_NOPM, 0, 0, NULL, 0), + SND_SOC_DAPM_MIXER("AC97 Mixer", SND_SOC_NOPM, 0, 0, NULL, 0), + +This can be used to merge two signal paths together in software. + +Registering DAPM controls +========================= + +In many cases the DAPM widgets are implemented statically in a ``static +const struct snd_soc_dapm_widget`` array in a codec driver, and simply +declared via the ``dapm_widgets`` and ``num_dapm_widgets`` fields of the +``struct snd_soc_component_driver``. + +Similarly, routes connecting them are implemented statically in a ``static +const struct snd_soc_dapm_route`` array and declared via the +``dapm_routes`` and ``num_dapm_routes`` fields of the same struct. + +With the above declared, the driver registration will take care of +populating them:: -This can be used to merge to signal paths together in software. + static const struct snd_soc_dapm_widget wm2000_dapm_widgets[] = { + SND_SOC_DAPM_OUTPUT("SPKN"), + SND_SOC_DAPM_OUTPUT("SPKP"), + ... + }; + + /* Target, Path, Source */ + static const struct snd_soc_dapm_route wm2000_audio_map[] = { + { "SPKN", NULL, "ANC Engine" }, + { "SPKP", NULL, "ANC Engine" }, + ... + }; -After all the widgets have been defined, they can then be added to the DAPM -subsystem individually with a call to snd_soc_dapm_new_control(). + static const struct snd_soc_component_driver soc_component_dev_wm2000 = { + ... + .dapm_widgets = wm2000_dapm_widgets, + .num_dapm_widgets = ARRAY_SIZE(wm2000_dapm_widgets), + .dapm_routes = wm2000_audio_map, + .num_dapm_routes = ARRAY_SIZE(wm2000_audio_map), + ... + }; + +In more complex cases the list of DAPM widgets and/or routes can be only +known at probe time. This happens for example when a driver supports +different models having a different set of features. In those cases +separate widgets and routes arrays implementing the case-specific features +can be registered programmatically by calling snd_soc_dapm_new_controls() +and snd_soc_dapm_add_routes(). Codec/DSP Widget Interconnections @@ -247,31 +303,29 @@ Codec/DSP Widget Interconnections Widgets are connected to each other within the codec, platform and machine by audio paths (called interconnections). Each interconnection must be defined in -order to create a map of all audio paths between widgets. +order to create a graph of all audio paths between widgets. This is easiest with a diagram of the codec or DSP (and schematic of the machine audio system), as it requires joining widgets together via their audio signal paths. -e.g., from the WM8731 output mixer (wm8731.c) - -The WM8731 output mixer has 3 inputs (sources) +For example the WM8731 output mixer (wm8731.c) has 3 inputs (sources): 1. Line Bypass Input 2. DAC (HiFi playback) 3. Mic Sidetone Input -Each input in this example has a kcontrol associated with it (defined in example -above) and is connected to the output mixer via its kcontrol name. We can now -connect the destination widget (wrt audio signal) with its source widgets. -:: +Each input in this example has a kcontrol associated with it (defined in +the example above) and is connected to the output mixer via its kcontrol +name. We can now connect the destination widget (wrt audio signal) with its +source widgets. :: /* output mixer */ {"Output Mixer", "Line Bypass Switch", "Line Input"}, {"Output Mixer", "HiFi Playback Switch", "DAC"}, {"Output Mixer", "Mic Sidetone Switch", "Mic Bias"}, -So we have :- +So we have: * Destination Widget <=== Path Name <=== Source Widget, or * Sink, Path, Source, or @@ -280,12 +334,11 @@ So we have :- When there is no path name connecting widgets (e.g. a direct connection) we pass NULL for the path name. -Interconnections are created with a call to:- -:: +Interconnections are created with a call to:: snd_soc_dapm_connect_input(codec, sink, path, source); -Finally, snd_soc_dapm_new_widgets(codec) must be called after all widgets and +Finally, snd_soc_dapm_new_widgets() must be called after all widgets and interconnections have been registered with the core. This causes the core to scan the codec and machine so that the internal DAPM state matches the physical state of the machine. @@ -326,35 +379,44 @@ jacks can also be switched OFF. DAPM Widget Events ================== -Some widgets can register their interest with the DAPM core in PM events. -e.g. A Speaker with an amplifier registers a widget so the amplifier can be -powered only when the spk is in use. -:: +Widgets needing to implement a more complex behaviour than what DAPM can do +can set a custom "event handler" by setting a function pointer. An example +is a power supply needing to enable a GPIO:: - /* turn speaker amplifier on/off depending on use */ - static int corgi_amp_event(struct snd_soc_dapm_widget *w, int event) + static int sof_es8316_speaker_power_event(struct snd_soc_dapm_widget *w, + struct snd_kcontrol *kcontrol, int event) { - gpio_set_value(CORGI_GPIO_APM_ON, SND_SOC_DAPM_EVENT_ON(event)); - return 0; + if (SND_SOC_DAPM_EVENT_ON(event)) + gpiod_set_value_cansleep(gpio_pa, true); + else + gpiod_set_value_cansleep(gpio_pa, false); + + return 0; } - /* corgi machine dapm widgets */ - static const struct snd_soc_dapm_widget wm8731_dapm_widgets = - SND_SOC_DAPM_SPK("Ext Spk", corgi_amp_event); + static const struct snd_soc_dapm_widget st_widgets[] = { + ... + SND_SOC_DAPM_SUPPLY("Speaker Power", SND_SOC_NOPM, 0, 0, + sof_es8316_speaker_power_event, + SND_SOC_DAPM_PRE_PMD | SND_SOC_DAPM_POST_PMU), + }; -Please see soc-dapm.h for all other widgets that support events. +See soc-dapm.h for all other widgets that support events. Event types ----------- -The following event types are supported by event widgets. -:: +The following event types are supported by event widgets:: /* dapm event types */ - #define SND_SOC_DAPM_PRE_PMU 0x1 /* before widget power up */ - #define SND_SOC_DAPM_POST_PMU 0x2 /* after widget power up */ - #define SND_SOC_DAPM_PRE_PMD 0x4 /* before widget power down */ - #define SND_SOC_DAPM_POST_PMD 0x8 /* after widget power down */ - #define SND_SOC_DAPM_PRE_REG 0x10 /* before audio path setup */ - #define SND_SOC_DAPM_POST_REG 0x20 /* after audio path setup */ + #define SND_SOC_DAPM_PRE_PMU 0x1 /* before widget power up */ + #define SND_SOC_DAPM_POST_PMU 0x2 /* after widget power up */ + #define SND_SOC_DAPM_PRE_PMD 0x4 /* before widget power down */ + #define SND_SOC_DAPM_POST_PMD 0x8 /* after widget power down */ + #define SND_SOC_DAPM_PRE_REG 0x10 /* before audio path setup */ + #define SND_SOC_DAPM_POST_REG 0x20 /* after audio path setup */ + #define SND_SOC_DAPM_WILL_PMU 0x40 /* called at start of sequence */ + #define SND_SOC_DAPM_WILL_PMD 0x80 /* called at start of sequence */ + #define SND_SOC_DAPM_PRE_POST_PMD (SND_SOC_DAPM_PRE_PMD | SND_SOC_DAPM_POST_PMD) + #define SND_SOC_DAPM_PRE_POST_PMU (SND_SOC_DAPM_PRE_PMU | SND_SOC_DAPM_POST_PMU) diff --git a/Documentation/sound/soc/dpcm.rst b/Documentation/sound/soc/dpcm.rst index 77f67ded53de..7b6aeab3c207 100644 --- a/Documentation/sound/soc/dpcm.rst +++ b/Documentation/sound/soc/dpcm.rst @@ -147,25 +147,25 @@ For the example above we have to define 4 FE DAI links and 6 BE DAI links. The FE DAI links are defined as follows :- :: + SND_SOC_DAILINK_DEFS(pcm0, + DAILINK_COMP_ARRAY(COMP_CPU("System Pin")), + DAILINK_COMP_ARRAY(COMP_DUMMY()), + DAILINK_COMP_ARRAY(COMP_PLATFORM("dsp-audio"))); + static struct snd_soc_dai_link machine_dais[] = { { .name = "PCM0 System", .stream_name = "System Playback", - .cpu_dai_name = "System Pin", - .platform_name = "dsp-audio", - .codec_name = "snd-soc-dummy", - .codec_dai_name = "snd-soc-dummy-dai", + SND_SOC_DAILINK_REG(pcm0), .dynamic = 1, .trigger = {SND_SOC_DPCM_TRIGGER_POST, SND_SOC_DPCM_TRIGGER_POST}, - .dpcm_playback = 1, }, .....< other FE and BE DAI links here > }; This FE DAI link is pretty similar to a regular DAI link except that we also -set the DAI link to a DPCM FE with the ``dynamic = 1``. The supported FE stream -directions should also be set with the ``dpcm_playback`` and ``dpcm_capture`` -flags. There is also an option to specify the ordering of the trigger call for +set the DAI link to a DPCM FE with the ``dynamic = 1``. +There is also an option to specify the ordering of the trigger call for each FE. This allows the ASoC core to trigger the DSP before or after the other components (as some DSPs have strong requirements for the ordering DAI/DSP start and stop sequences). @@ -176,28 +176,26 @@ dynamic and will change depending on runtime config. The BE DAIs are configured as follows :- :: + SND_SOC_DAILINK_DEFS(headset, + DAILINK_COMP_ARRAY(COMP_CPU("ssp-dai.0")), + DAILINK_COMP_ARRAY(COMP_CODEC("rt5640.0-001c", "rt5640-aif1"))); + static struct snd_soc_dai_link machine_dais[] = { .....< FE DAI links here > { .name = "Codec Headset", - .cpu_dai_name = "ssp-dai.0", - .platform_name = "snd-soc-dummy", + SND_SOC_DAILINK_REG(headset), .no_pcm = 1, - .codec_name = "rt5640.0-001c", - .codec_dai_name = "rt5640-aif1", .ignore_suspend = 1, .ignore_pmdown_time = 1, .be_hw_params_fixup = hswult_ssp0_fixup, .ops = &haswell_ops, - .dpcm_playback = 1, - .dpcm_capture = 1, }, .....< other BE DAI links here > }; This BE DAI link connects DAI0 to the codec (in this case RT5460 AIF1). It sets -the ``no_pcm`` flag to mark it has a BE and sets flags for supported stream -directions using ``dpcm_playback`` and ``dpcm_capture`` above. +the ``no_pcm`` flag to mark it has a BE. The BE has also flags set for ignoring suspend and PM down time. This allows the BE to work in a hostless mode where the host CPU is not transferring data @@ -367,8 +365,9 @@ The machine driver sets some additional parameters to the DAI link i.e. .codec_dai_name = "modem-aif1", .codec_name = "modem", .dai_fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_NB_NF - | SND_SOC_DAIFMT_CBM_CFM, - .params = &dai_params, + | SND_SOC_DAIFMT_CBP_CFP, + .c2c_params = &dai_params, + .num_c2c_params = 1, } < ... more DAI links here ... > diff --git a/Documentation/sound/soc/index.rst b/Documentation/sound/soc/index.rst index e57df2dab2fd..8bed8f8f48da 100644 --- a/Documentation/sound/soc/index.rst +++ b/Documentation/sound/soc/index.rst @@ -18,3 +18,4 @@ The documentation is spilt into the following sections:- jack dpcm codec-to-codec + usb diff --git a/Documentation/sound/soc/machine.rst b/Documentation/sound/soc/machine.rst index 515c9444deaf..1828f5edca3e 100644 --- a/Documentation/sound/soc/machine.rst +++ b/Documentation/sound/soc/machine.rst @@ -71,6 +71,18 @@ struct snd_soc_dai_link is used to set up each DAI in your machine. e.g. .ops = &corgi_ops, }; +In the above struct, dai’s are registered using names but you can pass +either dai name or device tree node but not both. Also, names used here +for cpu/codec/platform dais should be globally unique. + +Additionally below example macro can be used to register cpu, codec and +platform dai:: + + SND_SOC_DAILINK_DEFS(wm2200_cpu_dsp, + DAILINK_COMP_ARRAY(COMP_CPU("samsung-i2s.0")), + DAILINK_COMP_ARRAY(COMP_CODEC("spi0.0", "wm0010-sdi1")), + DAILINK_COMP_ARRAY(COMP_PLATFORM("samsung-i2s.0"))); + struct snd_soc_card then sets up the machine with its DAIs. e.g. :: @@ -81,6 +93,10 @@ struct snd_soc_card then sets up the machine with its DAIs. e.g. .num_links = 1, }; +Following this, ``devm_snd_soc_register_card`` can be used to register +the sound card. During the registration, the individual components +such as the codec, CPU, and platform are probed. If all these components +are successfully probed, the sound card gets registered. Machine Power Map ----------------- @@ -95,3 +111,13 @@ Machine Controls ---------------- Machine specific audio mixer controls can be added in the DAI init function. + + +Clocking Controls +----------------- + +As previously noted, clock configuration is handled within the machine driver. +For details on the clock APIs that the machine driver can utilize for +setup, please refer to Documentation/sound/soc/clocking.rst. However, the +callback needs to be registered by the CPU/Codec/Platform drivers to configure +the clocks that is needed for the corresponding device operation. diff --git a/Documentation/sound/soc/platform.rst b/Documentation/sound/soc/platform.rst index c1badea53d3d..7036630eaf01 100644 --- a/Documentation/sound/soc/platform.rst +++ b/Documentation/sound/soc/platform.rst @@ -46,7 +46,7 @@ snd_soc_component_driver:- }; Please refer to the ALSA driver documentation for details of audio DMA. -http://www.alsa-project.org/~iwai/writing-an-alsa-driver/ +https://www.kernel.org/doc/html/latest/sound/kernel-api/writing-an-alsa-driver.html An example DMA driver is soc/pxa/pxa2xx-pcm.c diff --git a/Documentation/sound/soc/usb.rst b/Documentation/sound/soc/usb.rst new file mode 100644 index 000000000000..94c12f9d9dd1 --- /dev/null +++ b/Documentation/sound/soc/usb.rst @@ -0,0 +1,482 @@ +================ +ASoC USB support +================ + +Overview +======== +In order to leverage the existing USB sound device support in ALSA, the +ASoC USB APIs are introduced to allow the subsystems to exchange +configuration information. + +One potential use case would be to support USB audio offloading, which is +an implementation that allows for an alternate power-optimized path in the audio +subsystem to handle the transfer of audio data over the USB bus. This would +let the main processor to stay in lower power modes for longer duration. The +following is an example design of how the ASoC and ALSA pieces can be connected +together to achieve this: + +:: + + USB | ASoC + | _________________________ + | | ASoC Platform card | + | |_________________________| + | | | + | ___V____ ____V____ + | |ASoC BE | |ASoC FE | + | |DAI LNK | |DAI LNK | + | |________| |_________| + | ^ ^ ^ + | | |________| + | ___V____ | + | |SoC-USB | | + ________ ________ | | | + |USB SND |<--->|USBSND |<------------>|________| | + |(card.c)| |offld |<---------- | + |________| |________|___ | | | + ^ ^ | | | ____________V_________ + | | | | | |IPC | + __ V_______________V_____ | | | |______________________| + |USB SND (endpoint.c) | | | | ^ + |_________________________| | | | | + ^ | | | ___________V___________ + | | | |->|audio DSP | + ___________V_____________ | | |_______________________| + |XHCI HCD |<- | + |_________________________| | + + +SoC USB driver +============== +Structures +---------- +``struct snd_soc_usb`` + + - ``list``: list head for SND SoC struct list + - ``component``: reference to ASoC component + - ``connection_status_cb``: callback to notify connection events + - ``update_offload_route_info``: callback to fetch selected USB sound card/PCM + device + - ``priv_data``: driver data + +The snd_soc_usb structure can be referenced using the ASoC platform card +device, or a USB device (udev->dev). This is created by the ASoC BE DAI +link, and the USB sound entity will be able to pass information to the +ASoC BE DAI link using this structure. + +``struct snd_soc_usb_device`` + + - ``card_idx``: sound card index associated with USB sound device + - ``chip_idx``: USB sound chip array index + - ``cpcm_idx``: capture pcm device indexes associated with the USB sound device + - ``ppcm_idx``: playback pcm device indexes associated with the USB sound device + - ``num_playback``: number of playback streams + - ``num_capture``: number of capture streams + - ``list``: list head for the USB sound device list + +The struct snd_soc_usb_device is created by the USB sound offload driver. +This will carry basic parameters/limitations that will be used to +determine the possible offloading paths for this USB audio device. + +Functions +--------- +.. code-block:: rst + + int snd_soc_usb_find_supported_format(int card_idx, + struct snd_pcm_hw_params *params, int direction) +.. + + - ``card_idx``: the index into the USB sound chip array. + - ``params``: Requested PCM parameters from the USB DPCM BE DAI link + - ``direction``: capture or playback + +**snd_soc_usb_find_supported_format()** ensures that the requested audio profile +being requested by the external DSP is supported by the USB device. + +Returns 0 on success, and -EOPNOTSUPP on failure. + +.. code-block:: rst + + int snd_soc_usb_connect(struct device *usbdev, struct snd_soc_usb_device *sdev) +.. + + - ``usbdev``: the usb device that was discovered + - ``sdev``: capabilities of the device + +**snd_soc_usb_connect()** notifies the ASoC USB DCPM BE DAI link of a USB +audio device detection. This can be utilized in the BE DAI +driver to keep track of available USB audio devices. This is intended +to be called by the USB offload driver residing in USB SND. + +Returns 0 on success, negative error code on failure. + +.. code-block:: rst + + int snd_soc_usb_disconnect(struct device *usbdev, struct snd_soc_usb_device *sdev) +.. + + - ``usbdev``: the usb device that was removed + - ``sdev``: capabilities to free + +**snd_soc_usb_disconnect()** notifies the ASoC USB DCPM BE DAI link of a USB +audio device removal. This is intended to be called by the USB offload +driver that resides in USB SND. + +.. code-block:: rst + + void *snd_soc_usb_find_priv_data(struct device *usbdev) +.. + + - ``usbdev``: the usb device to reference to find private data + +**snd_soc_usb_find_priv_data()** fetches the private data saved to the SoC USB +device. + +Returns pointer to priv_data on success, NULL on failure. + +.. code-block:: rst + + int snd_soc_usb_setup_offload_jack(struct snd_soc_component *component, + struct snd_soc_jack *jack) +.. + + - ``component``: ASoC component to add the jack + - ``jack``: jack component to populate + +**snd_soc_usb_setup_offload_jack()** is a helper to add a sound jack control to +the platform sound card. This will allow for consistent naming to be used on +designs that support USB audio offloading. Additionally, this will enable the +jack to notify of changes. + +Returns 0 on success, negative otherwise. + +.. code-block:: rst + + int snd_soc_usb_update_offload_route(struct device *dev, int card, int pcm, + int direction, enum snd_soc_usb_kctl path, + long *route) +.. + + - ``dev``: USB device to look up offload path mapping + - ``card``: USB sound card index + - ``pcm``: USB sound PCM device index + - ``direction``: direction to fetch offload routing information + - ``path``: kcontrol selector - pcm device or card index + - ``route``: mapping of sound card and pcm indexes for the offload path. This is + an array of two integers that will carry the card and pcm device indexes + in that specific order. This can be used as the array for the kcontrol + output. + +**snd_soc_usb_update_offload_route()** calls a registered callback to the USB BE DAI +link to fetch the information about the mapped ASoC devices for executing USB audio +offload for the device. ``route`` may be a pointer to a kcontrol value output array, +which carries values when the kcontrol is read. + +Returns 0 on success, negative otherwise. + +.. code-block:: rst + + struct snd_soc_usb *snd_soc_usb_allocate_port(struct snd_soc_component *component, + void *data); +.. + + - ``component``: DPCM BE DAI link component + - ``data``: private data + +**snd_soc_usb_allocate_port()** allocates a SoC USB device and populates standard +parameters that is used for further operations. + +Returns a pointer to struct soc_usb on success, negative on error. + +.. code-block:: rst + + void snd_soc_usb_free_port(struct snd_soc_usb *usb); +.. + + - ``usb``: SoC USB device to free + +**snd_soc_usb_free_port()** frees a SoC USB device. + +.. code-block:: rst + + void snd_soc_usb_add_port(struct snd_soc_usb *usb); +.. + + - ``usb``: SoC USB device to add + +**snd_soc_usb_add_port()** add an allocated SoC USB device to the SOC USB framework. +Once added, this device can be referenced by further operations. + +.. code-block:: rst + + void snd_soc_usb_remove_port(struct snd_soc_usb *usb); +.. + + - ``usb``: SoC USB device to remove + +**snd_soc_usb_remove_port()** removes a SoC USB device from the SoC USB framework. +After removing a device, any SOC USB operations would not be able to reference the +device removed. + +How to Register to SoC USB +-------------------------- +The ASoC DPCM USB BE DAI link is the entity responsible for allocating and +registering the SoC USB device on the component bind. Likewise, it will +also be responsible for freeing the allocated resources. An example can +be shown below: + +.. code-block:: rst + + static int q6usb_component_probe(struct snd_soc_component *component) + { + ... + data->usb = snd_soc_usb_allocate_port(component, 1, &data->priv); + if (!data->usb) + return -ENOMEM; + + usb->connection_status_cb = q6usb_alsa_connection_cb; + + ret = snd_soc_usb_add_port(usb); + if (ret < 0) { + dev_err(component->dev, "failed to add usb port\n"); + goto free_usb; + } + ... + } + + static void q6usb_component_remove(struct snd_soc_component *component) + { + ... + snd_soc_usb_remove_port(data->usb); + snd_soc_usb_free_port(data->usb); + } + + static const struct snd_soc_component_driver q6usb_dai_component = { + .probe = q6usb_component_probe, + .remove = q6usb_component_remove, + .name = "q6usb-dai-component", + ... + }; +.. + +BE DAI links can pass along vendor specific information as part of the +call to allocate the SoC USB device. This will allow any BE DAI link +parameters or settings to be accessed by the USB offload driver that +resides in USB SND. + +USB Audio Device Connection Flow +-------------------------------- +USB devices can be hotplugged into the USB ports at any point in time. +The BE DAI link should be aware of the current state of the physical USB +port, i.e. if there are any USB devices with audio interface(s) connected. +connection_status_cb() can be used to notify the BE DAI link of any change. + +This is called whenever there is a USB SND interface bind or remove event, +using snd_soc_usb_connect() or snd_soc_usb_disconnect(): + +.. code-block:: rst + + static void qc_usb_audio_offload_probe(struct snd_usb_audio *chip) + { + ... + snd_soc_usb_connect(usb_get_usb_backend(udev), sdev); + ... + } + + static void qc_usb_audio_offload_disconnect(struct snd_usb_audio *chip) + { + ... + snd_soc_usb_disconnect(usb_get_usb_backend(chip->dev), dev->sdev); + ... + } +.. + +In order to account for conditions where driver or device existence is +not guaranteed, USB SND exposes snd_usb_rediscover_devices() to resend the +connect events for any identified USB audio interfaces. Consider the +the following situation: + + **usb_audio_probe()** + | --> USB audio streams allocated and saved to usb_chip[] + | --> Propagate connect event to USB offload driver in USB SND + | --> **snd_soc_usb_connect()** exits as USB BE DAI link is not ready + + BE DAI link component probe + | --> DAI link is probed and SoC USB port is allocated + | --> The USB audio device connect event is missed + +To ensure connection events are not missed, **snd_usb_rediscover_devices()** +is executed when the SoC USB device is registered. Now, when the BE DAI +link component probe occurs, the following highlights the sequence: + + BE DAI link component probe + | --> DAI link is probed and SoC USB port is allocated + | --> SoC USB device added, and **snd_usb_rediscover_devices()** runs + + **snd_usb_rediscover_devices()** + | --> Traverses through usb_chip[] and for non-NULL entries issue + | **connection_status_cb()** + +In the case where the USB offload driver is unbound, while USB SND is ready, +the **snd_usb_rediscover_devices()** is called during module init. This allows +for the offloading path to also be enabled with the following flow: + + **usb_audio_probe()** + | --> USB audio streams allocated and saved to usb_chip[] + | --> Propagate connect event to USB offload driver in USB SND + | --> USB offload driver **NOT** ready! + + BE DAI link component probe + | --> DAI link is probed and SoC USB port is allocated + | --> No USB connect event due to missing USB offload driver + + USB offload driver probe + | --> **qc_usb_audio_offload_init()** + | --> Calls **snd_usb_rediscover_devices()** to notify of devices + +USB Offload Related Kcontrols +============================= +Details +------- +A set of kcontrols can be utilized by applications to help select the proper sound +devices to enable USB audio offloading. SoC USB exposes the get_offload_dev() +callback that designs can use to ensure that the proper indices are returned to the +application. + +Implementation +-------------- + +**Example:** + + **Sound Cards**: + + :: + + 0 [SM8250MTPWCD938]: sm8250 - SM8250-MTP-WCD9380-WSA8810-VA-D + SM8250-MTP-WCD9380-WSA8810-VA-DMIC + 1 [Seri ]: USB-Audio - Plantronics Blackwire 3225 Seri + Plantronics Plantronics Blackwire + 3225 Seri at usb-xhci-hcd.1.auto-1.1, + full sp + 2 [C320M ]: USB-Audio - Plantronics C320-M + Plantronics Plantronics C320-M at usb-xhci-hcd.1.auto-1.2, full speed + + **PCM Devices**: + + :: + + card 0: SM8250MTPWCD938 [SM8250-MTP-WCD9380-WSA8810-VA-D], device 0: MultiMedia1 (*) [] + Subdevices: 1/1 + Subdevice #0: subdevice #0 + card 0: SM8250MTPWCD938 [SM8250-MTP-WCD9380-WSA8810-VA-D], device 1: MultiMedia2 (*) [] + Subdevices: 1/1 + Subdevice #0: subdevice #0 + card 1: Seri [Plantronics Blackwire 3225 Seri], device 0: USB Audio [USB Audio] + Subdevices: 1/1 + Subdevice #0: subdevice #0 + card 2: C320M [Plantronics C320-M], device 0: USB Audio [USB Audio] + Subdevices: 1/1 + Subdevice #0: subdevice #0 + + **USB Sound Card** - card#1: + + :: + + USB Offload Playback Card Route PCM#0 -1 (range -1->32) + USB Offload Playback PCM Route PCM#0 -1 (range -1->255) + + **USB Sound Card** - card#2: + + :: + + USB Offload Playback Card Route PCM#0 0 (range -1->32) + USB Offload Playback PCM Route PCM#0 1 (range -1->255) + +The above example shows a scenario where the system has one ASoC platform card +(card#0) and two USB sound devices connected (card#1 and card#2). When reading +the available kcontrols for each USB audio device, the following kcontrols lists +the mapped offload card and pcm device indexes for the specific USB device: + + ``USB Offload Playback Card Route PCM#*`` + + ``USB Offload Playback PCM Route PCM#*`` + +The kcontrol is indexed, because a USB audio device could potentially have +several PCM devices. The above kcontrols are defined as: + + - ``USB Offload Playback Card Route PCM#`` **(R)**: Returns the ASoC platform sound + card index for a mapped offload path. The output **"0"** (card index) signifies + that there is an available offload path for the USB SND device through card#0. + If **"-1"** is seen, then no offload path is available for the USB SND device. + This kcontrol exists for each USB audio device that exists in the system, and + its expected to derive the current status of offload based on the output value + for the kcontrol along with the PCM route kcontrol. + + - ``USB Offload Playback PCM Route PCM#`` **(R)**: Returns the ASoC platform sound + PCM device index for a mapped offload path. The output **"1"** (PCM device index) + signifies that there is an available offload path for the USB SND device through + PCM device#0. If **"-1"** is seen, then no offload path is available for the USB\ + SND device. This kcontrol exists for each USB audio device that exists in the + system, and its expected to derive the current status of offload based on the + output value for this kcontrol, in addition to the card route kcontrol. + +USB Offload Playback Route Kcontrol +----------------------------------- +In order to allow for vendor specific implementations on audio offloading device +selection, the SoC USB layer exposes the following: + +.. code-block:: rst + + int (*update_offload_route_info)(struct snd_soc_component *component, + int card, int pcm, int direction, + enum snd_soc_usb_kctl path, + long *route) +.. + +These are specific for the **USB Offload Playback Card Route PCM#** and **USB +Offload PCM Route PCM#** kcontrols. + +When users issue get calls to the kcontrol, the registered SoC USB callbacks will +execute the registered function calls to the DPCM BE DAI link. + +**Callback Registration:** + +.. code-block:: rst + + static int q6usb_component_probe(struct snd_soc_component *component) + { + ... + usb = snd_soc_usb_allocate_port(component, 1, &data->priv); + if (IS_ERR(usb)) + return -ENOMEM; + + usb->connection_status_cb = q6usb_alsa_connection_cb; + usb->update_offload_route_info = q6usb_get_offload_dev; + + ret = snd_soc_usb_add_port(usb); +.. + +Existing USB Sound Kcontrol +--------------------------- +With the introduction of USB offload support, the above USB offload kcontrol +will be added to the pre existing list of kcontrols identified by the USB sound +framework. These kcontrols are still the main controls that are used to +modify characteristics pertaining to the USB audio device. + + :: + + Number of controls: 9 + ctl type num name value + 0 INT 2 Capture Channel Map 0, 0 (range 0->36) + 1 INT 2 Playback Channel Map 0, 0 (range 0->36) + 2 BOOL 1 Headset Capture Switch On + 3 INT 1 Headset Capture Volume 10 (range 0->13) + 4 BOOL 1 Sidetone Playback Switch On + 5 INT 1 Sidetone Playback Volume 4096 (range 0->8192) + 6 BOOL 1 Headset Playback Switch On + 7 INT 2 Headset Playback Volume 20, 20 (range 0->24) + 8 INT 1 USB Offload Playback Card Route PCM#0 0 (range -1->32) + 9 INT 1 USB Offload Playback PCM Route PCM#0 1 (range -1->255) + +Since USB audio device controls are handled over the USB control endpoint, use the +existing mechanisms present in the USB mixer to set parameters, such as volume. diff --git a/Documentation/sound/utimers.rst b/Documentation/sound/utimers.rst new file mode 100644 index 000000000000..ec21567d3f72 --- /dev/null +++ b/Documentation/sound/utimers.rst @@ -0,0 +1,126 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================= +Userspace-driven timers +======================= + +:Author: Ivan Orlov <ivan.orlov0322@gmail.com> + +Preface +======= + +This document describes the userspace-driven timers: virtual ALSA timers +which could be created and controlled by userspace applications using +IOCTL calls. Such timers could be useful when synchronizing audio +stream with timer sources which we don't have ALSA timers exported for +(e.g. PTP clocks), and when synchronizing the audio stream going through +two virtual sound devices using ``snd-aloop`` (for instance, when +we have a network application sending frames to one snd-aloop device, +and another sound application listening on the other end of snd-aloop). + +Enabling userspace-driven timers +================================ + +The userspace-driven timers could be enabled in the kernel using the +``CONFIG_SND_UTIMER`` configuration option. It depends on the +``CONFIG_SND_TIMER`` option, so it also should be enabled. + +Userspace-driven timers API +=========================== + +Userspace application can create a userspace-driven ALSA timer by +executing the ``SNDRV_TIMER_IOCTL_CREATE`` ioctl call on the +``/dev/snd/timer`` device file descriptor. The ``snd_timer_uinfo`` +structure should be passed as an ioctl argument: + +:: + + struct snd_timer_uinfo { + __u64 resolution; + int fd; + unsigned int id; + unsigned char reserved[16]; + } + +The ``resolution`` field sets the desired resolution in nanoseconds for +the virtual timer. ``resolution`` field simply provides an information +about the virtual timer, but does not affect the timing itself. ``id`` +field gets overwritten by the ioctl, and the identifier you get in this +field after the call can be used as a timer subdevice number when +passing the timer to ``snd-aloop`` kernel module or other userspace +applications. There could be up to 128 userspace-driven timers in the +system at one moment of time, thus the id value ranges from 0 to 127. + +Besides from overwriting the ``snd_timer_uinfo`` struct, ioctl stores +a timer file descriptor, which can be used to trigger the timer, in the +``fd`` field of the ``snd_timer_uinfo`` struct. Allocation of a file +descriptor for the timer guarantees that the timer can only be triggered +by the process which created it. The timer then can be triggered with +``SNDRV_TIMER_IOCTL_TRIGGER`` ioctl call on the timer file descriptor. + +So, the example code for creating and triggering the timer would be: + +:: + + static struct snd_timer_uinfo utimer_info = { + /* Timer is going to tick (presumably) every 1000000 ns */ + .resolution = 1000000ULL, + .id = -1, + }; + + int timer_device_fd = open("/dev/snd/timer", O_RDWR | O_CLOEXEC); + + if (ioctl(timer_device_fd, SNDRV_TIMER_IOCTL_CREATE, &utimer_info)) { + perror("Failed to create the timer"); + return -1; + } + + ... + + /* + * Now we want to trigger the timer. Callbacks of all of the + * timer instances binded to this timer will be executed after + * this call. + */ + ioctl(utimer_info.fd, SNDRV_TIMER_IOCTL_TRIGGER, NULL); + + ... + + /* Now, destroy the timer */ + close(timer_info.fd); + + +More detailed example of creating and ticking the timer could be found +in the utimer ALSA selftest. + +Userspace-driven timers and snd-aloop +------------------------------------- + +Userspace-driven timers could be easily used with ``snd-aloop`` module +when synchronizing two sound applications on both ends of the virtual +sound loopback. For instance, if one of the applications receives sound +frames from network and sends them to snd-aloop pcm device, and another +application listens for frames on the other snd-aloop pcm device, it +makes sense that the ALSA middle layer should initiate a data +transaction when the new period of data is received through network, but +not when the certain amount of jiffies elapses. Userspace-driven ALSA +timers could be used to achieve this. + +To use userspace-driven ALSA timer as a timer source of snd-aloop, pass +the following string as the snd-aloop ``timer_source`` parameter: + +:: + + # modprobe snd-aloop timer_source="-1.4.<utimer_id>" + +Where ``utimer_id`` is the id of the timer you created with +``SNDRV_TIMER_IOCTL_CREATE``, and ``4`` is the number of +userspace-driven timers device (``SNDRV_TIMER_GLOBAL_UDRIVEN``). + +``resolution`` for the userspace-driven ALSA timer used with snd-aloop +should be calculated as ``1000000000ULL / frame_rate * period_size`` as +the timer is going to tick every time a new period of frames is ready. + +After that, each time you trigger the timer with +``SNDRV_TIMER_IOCTL_TRIGGER`` the new period of data will be transferred +from one snd-aloop device to another. |
