diff options
Diffstat (limited to 'Documentation/sound/alsa')
26 files changed, 678 insertions, 1583 deletions
diff --git a/Documentation/sound/alsa/ALSA-Configuration.txt b/Documentation/sound/alsa/ALSA-Configuration.txt index fc53ccd9a629..89757012c7ff 100644 --- a/Documentation/sound/alsa/ALSA-Configuration.txt +++ b/Documentation/sound/alsa/ALSA-Configuration.txt @@ -616,7 +616,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. As default, snd-dummy drivers doesn't allocate the real buffers but either ignores read/write or mmap a single dummy page to all - buffer pages, in order to save the resources. If your apps need + buffer pages, in order to save the resouces. If your apps need the read/ written buffer data to be consistent, pass fake_buffer=0 option. @@ -860,14 +860,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. [Multiple options for each card instance] model - force the model name - position_fix - Fix DMA pointer - -1 = system default: choose appropriate one per controller - hardware - 0 = auto: falls back to LPIB when POSBUF doesn't work - 1 = use LPIB - 2 = POSBUF: use position buffer - 3 = VIACOMBO: VIA-specific workaround for capture - 4 = COMBO: use LPIB for playback, auto for capture stream + position_fix - Fix DMA pointer (0 = auto, 1 = use LPIB, 2 = POSBUF) probe_mask - Bitmask to probe codecs (default = -1, meaning all slots) When the bit 8 (0x100) is set, the lower 8 bits are used as the "fixed" codec slots; i.e. the driver probes the @@ -881,7 +874,8 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. setup before initializing the codecs. This option is available only when CONFIG_SND_HDA_PATCH_LOADER=y is set. See HD-Audio.txt for details. - beep_mode - Selects the beep registration mode (0=off, 1=on); default + beep_mode - Selects the beep registration mode (0=off, 1=on, 2= + dynamic registration via mute switch on/off); the default value is set via CONFIG_SND_HDA_INPUT_BEEP_MODE kconfig. [Single (global) options] @@ -892,12 +886,6 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. disable) power_save_controller - Reset HD-audio controller in power-saving mode (default = on) - 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 required by the HDA spec and prevents - users from specifying exact period/buffer sizes. - (default = on) - snoop - Enable/disable snooping (default = on) This module supports multiple cards and autoprobe. @@ -911,7 +899,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. models depending on the codec chip. The list of available models is found in HD-Audio-Models.txt - The model name "generic" is treated as a special case. When this + The model name "genric" 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. @@ -931,11 +919,6 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. (Usually SD_LPIB register is more accurate than the position buffer.) - position_fix=3 is specific to VIA devices. The position - of the capture stream is checked from both LPIB and POSBUF - values. position_fix=4 is a combination mode, using LPIB - for playback and POSBUF for capture. - NB: If you get many "azx_get_response timeout" messages at loading, it's likely a problem of interrupts (e.g. ACPI irq routing). Try to boot with options like "pci=noacpi". Also, you @@ -948,7 +931,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. avoided as much as possible... MORE NOTES ON "azx_get_response timeout" PROBLEMS: - On some hardware, you may need to add a proper probe_mask option + On some hardwares, you may need to add a proper probe_mask option to avoid the "azx_get_response timeout" problem above, instead. This occurs when the access to non-existing or non-working codec slot (likely a modem one) causes a stall of the communication via HD-audio @@ -1124,7 +1107,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. buggy_irq - Enable workaround for buggy interrupts on some motherboards (default yes on nForce chips, otherwise off) - buggy_semaphore - Enable workaround for hardware with buggy + buggy_semaphore - Enable workaround for hardwares with buggy semaphores (e.g. on some ASUS laptops) (default off) spdif_aclink - Use S/PDIF over AC-link instead of direct connection @@ -1550,7 +1533,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module for sound cards based on the C-Media CMI8786/8787/8788 chip: * Asound A-8788 - * Asus Xonar DG/DGX + * Asus Xonar DG * AuzenTech X-Meridian * AuzenTech X-Meridian 2G * Bgears b-Enspirer @@ -1599,7 +1582,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module supports autoprobe a chip. - Note: the driver may have problems regarding endianness. + Note: the driver may have problems regarding endianess. The power-management is supported. @@ -1905,29 +1888,23 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. vid - Vendor ID for the device (optional) pid - Product ID for the device (optional) nrpacks - Max. number of packets per URB (default: 8) + async_unlink - Use async unlink mode (default: yes) device_setup - Device specific magic number (optional) - Influence depends on the device - Default: 0x0000 ignore_ctl_error - Ignore any USB-controller regarding mixer interface (default: no) - autoclock - Enable auto-clock selection for UAC2 devices - (default: yes) - 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. This module supports multiple devices, autoprobe and hotplugging. NB: nrpacks parameter can be modified dynamically via sysfs. Don't put the value over 20. Changing via sysfs has no sanity check. + NB: async_unlink=0 would cause Oops. It remains just for + debugging purpose (if any). 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. - 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. Module snd-usb-caiaq -------------------- @@ -2035,8 +2012,8 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. ------------------- Module for sound cards based on the Asus AV66/AV100/AV200 chips, - i.e., Xonar D1, DX, D2, D2X, DS, DSX, Essence ST (Deluxe), - Essence STX (II), HDAV1.3 (Deluxe), and HDAV1.3 Slim. + i.e., Xonar D1, DX, D2, D2X, DS, Essence ST (Deluxe), Essence STX, + HDAV1.3 (Deluxe), and HDAV1.3 Slim. This module supports autoprobe and multiple cards. @@ -2055,7 +2032,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Install the necessary firmware files in alsa-firmware package. When no hotplug fw loader is available, you need to load the firmware via vxloader utility in alsa-tools package. To invoke - vxloader automatically, add the following to /etc/modprobe.d/alsa.conf + vxloader automatically, add the following to /etc/modprobe.conf install snd-vx222 /sbin/modprobe --first-time -i snd-vx222 && /usr/bin/vxloader @@ -2179,10 +2156,10 @@ corresponds to the card index of ALSA. Usually, define this as the same card module. An example configuration for a single emu10k1 card is like below: ------ /etc/modprobe.d/alsa.conf +----- /etc/modprobe.conf alias snd-card-0 snd-emu10k1 alias sound-slot-0 snd-emu10k1 ------ /etc/modprobe.d/alsa.conf +----- /etc/modprobe.conf The available number of auto-loaded sound cards depends on the module option "cards_limit" of snd module. As default it's set to 1. @@ -2195,7 +2172,7 @@ cards is kept consistent. An example configuration for two sound cards is like below: ------ /etc/modprobe.d/alsa.conf +----- /etc/modprobe.conf # ALSA portion options snd cards_limit=2 alias snd-card-0 snd-interwave @@ -2205,7 +2182,7 @@ options snd-ens1371 index=1 # OSS/Free portion alias sound-slot-0 snd-interwave alias sound-slot-1 snd-ens1371 ------ /etc/modprobe.d/alsa.conf +----- /etc/modprobe.conf In this example, the interwave card is always loaded as the first card (index 0) and ens1371 as the second (index 1). diff --git a/Documentation/sound/alsa/Audiophile-Usb.txt b/Documentation/sound/alsa/Audiophile-Usb.txt index e7a5ed4dcae8..a4c53d8961e1 100644 --- a/Documentation/sound/alsa/Audiophile-Usb.txt +++ b/Documentation/sound/alsa/Audiophile-Usb.txt @@ -232,7 +232,7 @@ The parameter can be given: # modprobe snd-usb-audio index=1 device_setup=0x09 * Or while configuring the modules options in your modules configuration file - (typically a .conf file in /etc/modprobe.d/ directory: + - For Fedora distributions, edit the /etc/modprobe.conf file: alias snd-card-1 snd-usb-audio options snd-usb-audio index=1 device_setup=0x09 @@ -253,7 +253,7 @@ CAUTION when initializing the device - first turn off the device - de-register the snd-usb-audio module (modprobe -r) - change the device_setup parameter by changing the device_setup - option in /etc/modprobe.d/*.conf + option in /etc/modprobe.conf - turn on the device * A workaround for this last issue has been applied to kernel 2.6.23, but it may not be enough to ensure the 'stability' of the device initialization. diff --git a/Documentation/sound/alsa/CMIPCI.txt b/Documentation/sound/alsa/CMIPCI.txt index 4e36e6e809ca..16935c8561f7 100644 --- a/Documentation/sound/alsa/CMIPCI.txt +++ b/Documentation/sound/alsa/CMIPCI.txt @@ -87,7 +87,7 @@ with 4 channels, and use the interleaved 4 channel data. -There are some control switches affecting to the speaker connections: +There are some control switchs affecting to the speaker connections: "Line-In Mode" - an enum control to change the behavior of line-in jack. Either "Line-In", "Rear Output" or "Bass Output" can diff --git a/Documentation/sound/alsa/Channel-Mapping-API.txt b/Documentation/sound/alsa/Channel-Mapping-API.txt deleted file mode 100644 index 3c43d1a4ca0e..000000000000 --- a/Documentation/sound/alsa/Channel-Mapping-API.txt +++ /dev/null @@ -1,153 +0,0 @@ -ALSA PCM channel-mapping API -============================ - Takashi Iwai <tiwai@suse.de> - -GENERAL -------- - -The channel mapping API allows user to query the possible channel maps -and the current channel map, also optionally to modify the channel map -of the current stream. - -A channel map is an array of position for each PCM channel. -Typically, a stereo PCM stream has a channel map of - { front_left, front_right } -while a 4.0 surround PCM stream has a channel map of - { front left, front right, rear left, rear right }. - -The problem, so far, was that we had no standard channel map -explicitly, and applications had no way to know which channel -corresponds to which (speaker) position. Thus, applications applied -wrong channels for 5.1 outputs, and you hear suddenly strange sound -from rear. Or, some devices secretly assume that center/LFE is the -third/fourth channels while others that C/LFE as 5th/6th channels. - -Also, some devices such as HDMI are configurable for different speaker -positions even with the same number of total channels. However, there -was no way to specify this because of lack of channel map -specification. These are the main motivations for the new channel -mapping API. - - -DESIGN ------- - -Actually, "the channel mapping API" doesn't introduce anything new in -the kernel/user-space ABI perspective. It uses only the existing -control element features. - -As a ground design, each PCM substream may contain a control element -providing the channel mapping information and configuration. This -element is specified by: - iface = SNDRV_CTL_ELEM_IFACE_PCM - name = "Playback Channel Map" or "Capture Channel Map" - device = the same device number for the assigned PCM substream - index = the same index number for the assigned PCM substream - -Note the name is different depending on the PCM substream direction. - -Each control element provides at least the TLV read operation and the -read operation. Optionally, the write operation can be provided to -allow user to change the channel map dynamically. - -* TLV - -The TLV operation gives the list of available channel -maps. A list item of a channel map is usually a TLV of - type data-bytes ch0 ch1 ch2... -where type is the TLV type value, the second argument is the total -bytes (not the numbers) of channel values, and the rest are the -position value for each channel. - -As a TLV type, either SNDRV_CTL_TLVT_CHMAP_FIXED, -SNDRV_CTL_TLV_CHMAP_VAR or SNDRV_CTL_TLVT_CHMAP_PAIRED can be used. -The _FIXED type is for a channel map with the fixed channel position -while the latter two are for flexible channel positions. _VAR type is -for a channel map where all channels are freely swappable and _PAIRED -type is where pair-wise channels are swappable. For example, when you -have {FL/FR/RL/RR} channel map, _PAIRED type would allow you to swap -only {RL/RR/FL/FR} while _VAR type would allow even swapping FL and -RR. - -These new TLV types are defined in sound/tlv.h. - -The available channel position values are defined in sound/asound.h, -here is a cut: - -/* channel positions */ -enum { - SNDRV_CHMAP_UNKNOWN = 0, - SNDRV_CHMAP_NA, /* N/A, silent */ - SNDRV_CHMAP_MONO, /* mono stream */ - /* this follows the alsa-lib mixer channel value + 3 */ - SNDRV_CHMAP_FL, /* front left */ - SNDRV_CHMAP_FR, /* front right */ - SNDRV_CHMAP_RL, /* rear left */ - SNDRV_CHMAP_RR, /* rear right */ - SNDRV_CHMAP_FC, /* front center */ - SNDRV_CHMAP_LFE, /* LFE */ - SNDRV_CHMAP_SL, /* side left */ - SNDRV_CHMAP_SR, /* side right */ - SNDRV_CHMAP_RC, /* rear center */ - /* new definitions */ - SNDRV_CHMAP_FLC, /* front left center */ - SNDRV_CHMAP_FRC, /* front right center */ - SNDRV_CHMAP_RLC, /* rear left center */ - SNDRV_CHMAP_RRC, /* rear right center */ - SNDRV_CHMAP_FLW, /* front left wide */ - SNDRV_CHMAP_FRW, /* front right wide */ - SNDRV_CHMAP_FLH, /* front left high */ - SNDRV_CHMAP_FCH, /* front center high */ - SNDRV_CHMAP_FRH, /* front right high */ - SNDRV_CHMAP_TC, /* top center */ - SNDRV_CHMAP_TFL, /* top front left */ - SNDRV_CHMAP_TFR, /* top front right */ - SNDRV_CHMAP_TFC, /* top front center */ - SNDRV_CHMAP_TRL, /* top rear left */ - SNDRV_CHMAP_TRR, /* top rear right */ - SNDRV_CHMAP_TRC, /* top rear center */ - SNDRV_CHMAP_LAST = SNDRV_CHMAP_TRC, -}; - -When a PCM stream can provide more than one channel map, you can -provide multiple channel maps in a TLV container type. The TLV data -to be returned will contain such as: - SNDRV_CTL_TLVT_CONTAINER 96 - SNDRV_CTL_TLVT_CHMAP_FIXED 4 SNDRV_CHMAP_FC - SNDRV_CTL_TLVT_CHMAP_FIXED 8 SNDRV_CHMAP_FL SNDRV_CHMAP_FR - SNDRV_CTL_TLVT_CHMAP_FIXED 16 NDRV_CHMAP_FL SNDRV_CHMAP_FR \ - SNDRV_CHMAP_RL SNDRV_CHMAP_RR - -The channel position is provided in LSB 16bits. The upper bits are -used for bit flags. - -#define SNDRV_CHMAP_POSITION_MASK 0xffff -#define SNDRV_CHMAP_PHASE_INVERSE (0x01 << 16) -#define SNDRV_CHMAP_DRIVER_SPEC (0x02 << 16) - -SNDRV_CHMAP_PHASE_INVERSE indicates the channel is phase inverted, -(thus summing left and right channels would result in almost silence). -Some digital mic devices have this. - -When SNDRV_CHMAP_DRIVER_SPEC is set, all the channel position values -don't follow the standard definition above but driver-specific. - -* READ OPERATION - -The control read operation is for providing the current channel map of -the given stream. The control element returns an integer array -containing the position of each channel. - -When this is performed before the number of the channel is specified -(i.e. hw_params is set), it should return all channels set to -UNKNOWN. - -* WRITE OPERATION - -The control write operation is optional, and only for devices that can -change the channel configuration on the fly, such as HDMI. User needs -to pass an integer value containing the valid channel positions for -all channels of the assigned PCM substream. - -This operation is allowed only at PCM PREPARED state. When called in -other states, it shall return an error. diff --git a/Documentation/sound/alsa/ControlNames.txt b/Documentation/sound/alsa/ControlNames.txt index 3fc1cf50d28e..fea65bb6269e 100644 --- a/Documentation/sound/alsa/ControlNames.txt +++ b/Documentation/sound/alsa/ControlNames.txt @@ -1,6 +1,6 @@ This document describes standard names of mixer controls. -Syntax: [LOCATION] SOURCE [CHANNEL] [DIRECTION] FUNCTION +Syntax: SOURCE [DIRECTION] FUNCTION DIRECTION: <nothing> (both directions) @@ -14,29 +14,12 @@ FUNCTION: Volume Route (route control, hardware specific) -CHANNEL: - <nothing> (channel independent, or applies to all channels) - Front - Surround (rear left/right in 4.0/5.1 surround) - CLFE - Center - LFE - Side (side left/right for 7.1 surround) - -LOCATION: (physical location of source) - Front - Rear - Dock (docking station) - Internal - SOURCE: Master Master Mono Hardware Master Speaker (internal speaker) - Bass Speaker (internal LFE speaker) Headphone - Line Out Beep (beep generator) Phone Phone Input @@ -44,14 +27,14 @@ SOURCE: Synth FM Mic - Headset Mic (mic part of combined headset jack - 4-pin headphone + mic) - Headphone Mic (mic part of either/or - 3-pin headphone or mic) - Line (input only, use "Line Out" for output) + Line CD Video Zoom Video Aux PCM + PCM Front + PCM Rear PCM Pan Loopback Analog Loopback (D/A -> A/D loopback) @@ -64,18 +47,13 @@ SOURCE: Music I2S IEC958 - HDMI - SPDIF (output only) - SPDIF In - Digital In - HDMI/DP (either HDMI or DisplayPort) -Exceptions (deprecated): - [Analogue|Digital] Capture Source - [Analogue|Digital] Capture Switch (aka input gain switch) - [Analogue|Digital] Capture Volume (aka input gain volume) - [Analogue|Digital] Playback Switch (aka output gain switch) - [Analogue|Digital] Playback Volume (aka output gain volume) +Exceptions: + [Digital] Capture Source + [Digital] Capture Switch (aka input gain switch) + [Digital] Capture Volume (aka input gain volume) + [Digital] Playback Switch (aka output gain switch) + [Digital] Playback Volume (aka output gain volume) Tone Control - Switch Tone Control - Bass Tone Control - Treble diff --git a/Documentation/sound/alsa/HD-Audio-Controls.txt b/Documentation/sound/alsa/HD-Audio-Controls.txt index e9621e349e17..1482035243e6 100644 --- a/Documentation/sound/alsa/HD-Audio-Controls.txt +++ b/Documentation/sound/alsa/HD-Audio-Controls.txt @@ -98,19 +98,3 @@ Conexant codecs * Auto-Mute Mode See Reatek codecs. - - -Analog codecs --------------- - -* Channel Mode - This is an enum control to change the surround-channel setup, - appears only when the surround channels are available. - It gives the number of channels to be used, "2ch", "4ch" and "6ch". - According to the configuration, this also controls the - jack-retasking of multi-I/O jacks. - -* Independent HP - When this enum control is enabled, the headphone output is routed - from an individual stream (the third PCM such as hw:0,2) instead of - the primary stream. diff --git a/Documentation/sound/alsa/HD-Audio-DP-MST-audio.txt b/Documentation/sound/alsa/HD-Audio-DP-MST-audio.txt deleted file mode 100644 index 82744ac3513d..000000000000 --- a/Documentation/sound/alsa/HD-Audio-DP-MST-audio.txt +++ /dev/null @@ -1,74 +0,0 @@ -To support DP MST audio, HD Audio hdmi codec driver introduces virtual pin -and dynamic pcm assignment. - -Virtual pin is an extension of per_pin. The most difference of DP MST -from legacy is that DP MST introduces device entry. Each pin can contain -several device entries. Each device entry behaves as a pin. - -As each pin may contain several device entries and each codec may contain -several pins, if we use one pcm per per_pin, there will be many PCMs. -The new solution is to create a few PCMs and to dynamically bind pcm to -per_pin. Driver uses spec->dyn_pcm_assign flag to indicate whether to use -the new solution. - -PCM -=== -To be added - - -Jack -==== - -Presume: - - MST must be dyn_pcm_assign, and it is acomp (for Intel scenario); - - NON-MST may or may not be dyn_pcm_assign, it can be acomp or !acomp; - -So there are the following scenarios: - a. MST (&& dyn_pcm_assign && acomp) - b. NON-MST && dyn_pcm_assign && acomp - c. NON-MST && !dyn_pcm_assign && !acomp - -Below discussion will ignore MST and NON-MST difference as it doesn't -impact on jack handling too much. - -Driver uses struct hdmi_pcm pcm[] array in hdmi_spec and snd_jack is -a member of hdmi_pcm. Each pin has one struct hdmi_pcm * pcm pointer. - -For !dyn_pcm_assign, per_pin->pcm will assigned to spec->pcm[n] statically. - -For dyn_pcm_assign, per_pin->pcm will assigned to spec->pcm[n] -when monitor is hotplugged. - - -Build Jack ----------- - -- dyn_pcm_assign -Will not use hda_jack but use snd_jack in spec->pcm_rec[pcm_idx].jack directly. - -- !dyn_pcm_assign -Use hda_jack and assign spec->pcm_rec[pcm_idx].jack = jack->jack statically. - - -Unsolicited Event Enabling --------------------------- -Enable unsolicited event if !acomp. - - -Monitor Hotplug Event Handling ------------------------------- -- acomp -pin_eld_notify() -> check_presence_and_report() -> hdmi_present_sense() -> -sync_eld_via_acomp(). -Use directly snd_jack_report() on spec->pcm_rec[pcm_idx].jack for -both dyn_pcm_assign and !dyn_pcm_assign - -- !acomp -Hdmi_unsol_event() -> hdmi_intrinsic_event() -> check_presence_and_report() -> -hdmi_present_sense() -> hdmi_prepsent_sense_via_verbs() -Use directly snd_jack_report() on spec->pcm_rec[pcm_idx].jack for dyn_pcm_assign. -Use hda_jack mechanism to handle jack events. - - -Others to be added later -======================== diff --git a/Documentation/sound/alsa/HD-Audio-Models.txt b/Documentation/sound/alsa/HD-Audio-Models.txt index ec099d4343f2..f8961402a85f 100644 --- a/Documentation/sound/alsa/HD-Audio-Models.txt +++ b/Documentation/sound/alsa/HD-Audio-Models.txt @@ -8,74 +8,195 @@ ALC880 5stack-digout 5-jack in back, 2-jack in front, a SPDIF out 6stack 6-jack in back, 2-jack in front 6stack-digout 6-jack with a SPDIF out + w810 3-jack + z71v 3-jack (HP shared SPDIF) + asus 3-jack (ASUS Mobo) + asus-w1v ASUS W1V + asus-dig ASUS with SPDIF out + asus-dig2 ASUS with SPDIF out (using GPIO2) + uniwill 3-jack + fujitsu Fujitsu Laptops (Pi1536) + F1734 2-jack + lg LG laptop (m1 express dual) + lg-lw LG LW20/LW25 laptop + tcl TCL S700 + clevo Clevo laptops (m520G, m665n) + medion Medion Rim 2150 + test for testing/debugging purpose, almost all controls can be + adjusted. Appearing only when compiled with + $CONFIG_SND_DEBUG=y + auto auto-config reading BIOS (default) ALC260 ====== - gpio1 Enable GPIO1 - coef Enable EAPD via COEF table - fujitsu Quirk for FSC S7020 - fujitsu-jwse Quirk for FSC S7020 with jack modes and HP mic support + hp HP machines + hp-3013 HP machines (3013-variant) + hp-dc7600 HP DC7600 + fujitsu Fujitsu S7020 + acer Acer TravelMate + will Will laptops (PB V7900) + replacer Replacer 672V + favorit100 Maxdata Favorit 100XS + basic fixed pin assignment (old default model) + test for testing/debugging purpose, almost all controls can + adjusted. Appearing only when compiled with + $CONFIG_SND_DEBUG=y + auto auto-config reading BIOS (default) ALC262 ====== - inv-dmic Inverted internal mic workaround + fujitsu Fujitsu Laptop + hp-bpc HP xw4400/6400/8400/9400 laptops + hp-bpc-d7000 HP BPC D7000 + hp-tc-t5735 HP Thin Client T5735 + hp-rp5700 HP RP5700 + benq Benq ED8 + benq-t31 Benq T31 + hippo Hippo (ATI) with jack detection, Sony UX-90s + hippo_1 Hippo (Benq) with jack detection + sony-assamd Sony ASSAMD + toshiba-s06 Toshiba S06 + toshiba-rx1 Toshiba RX1 + tyan Tyan Thunder n6650W (S2915-E) + ultra Samsung Q1 Ultra Vista model + lenovo-3000 Lenovo 3000 y410 + nec NEC Versa S9100 + basic fixed pin assignment w/o SPDIF + auto auto-config reading BIOS (default) ALC267/268 ========== - inv-dmic Inverted internal mic workaround - hp-eapd Disable HP EAPD on NID 0x15 + quanta-il1 Quanta IL1 mini-notebook + 3stack 3-stack model + toshiba Toshiba A205 + acer Acer laptops + acer-dmic Acer laptops with digital-mic + acer-aspire Acer Aspire One + dell Dell OEM laptops (Vostro 1200) + zepto Zepto laptops + test for testing/debugging purpose, almost all controls can + adjusted. Appearing only when compiled with + $CONFIG_SND_DEBUG=y + auto auto-config reading BIOS (default) -ALC22x/23x/25x/269/27x/28x/29x (and vendor-specific ALC3xxx models) +ALC269 ====== - laptop-amic Laptops with analog-mic input - laptop-dmic Laptops with digital-mic input - alc269-dmic Enable ALC269(VA) digital mic workaround - alc271-dmic Enable ALC271X digital mic workaround - inv-dmic Inverted internal mic workaround - headset-mic Indicates a combined headset (headphone+mic) jack - headset-mode More comprehensive headset support for ALC269 & co - headset-mode-no-hp-mic Headset mode support without headphone mic - lenovo-dock Enables docking station I/O for some Lenovos - hp-gpio-led GPIO LED support on HP laptops - dell-headset-multi Headset jack, which can also be used as mic-in - dell-headset-dock Headset jack (without mic-in), and also dock I/O - alc283-dac-wcaps Fixups for Chromebook with ALC283 - alc283-sense-combo Combo jack sensing on ALC283 - tpt440-dock Pin configs for Lenovo Thinkpad Dock support - -ALC66x/67x/892 + basic Basic preset + quanta Quanta FL1 + laptop-amic Laptops with analog-mic input + laptop-dmic Laptops with digital-mic input + fujitsu FSC Amilo + lifebook Fujitsu Lifebook S6420 + auto auto-config reading BIOS (default) + +ALC662/663/272 ============== - mario Chromebook mario model fixup - asus-mode1 ASUS - asus-mode2 ASUS - asus-mode3 ASUS - asus-mode4 ASUS - asus-mode5 ASUS - asus-mode6 ASUS - asus-mode7 ASUS - asus-mode8 ASUS - inv-dmic Inverted internal mic workaround - dell-headset-multi Headset jack, which can also be used as mic-in + 3stack-dig 3-stack (2-channel) with SPDIF + 3stack-6ch 3-stack (6-channel) + 3stack-6ch-dig 3-stack (6-channel) with SPDIF + 5stack-dig 5-stack with SPDIF + lenovo-101e Lenovo laptop + eeepc-p701 ASUS Eeepc P701 + eeepc-ep20 ASUS Eeepc EP20 + ecs ECS/Foxconn mobo + m51va ASUS M51VA + g71v ASUS G71V + h13 ASUS H13 + g50v ASUS G50V + asus-mode1 ASUS + asus-mode2 ASUS + asus-mode3 ASUS + asus-mode4 ASUS + asus-mode5 ASUS + asus-mode6 ASUS + asus-mode7 ASUS + asus-mode8 ASUS + dell Dell with ALC272 + dell-zm1 Dell ZM1 with ALC272 + samsung-nc10 Samsung NC10 mini notebook + auto auto-config reading BIOS (default) ALC680 ====== - N/A + base Base model (ASUS NX90) + auto auto-config reading BIOS (default) -ALC88x/898/1150 +ALC882/883/885/888/889 ====================== - acer-aspire-4930g Acer Aspire 4930G/5930G/6530G/6930G/7730G - acer-aspire-8930g Acer Aspire 8330G/6935G - acer-aspire Acer Aspire others - inv-dmic Inverted internal mic workaround - no-primary-hp VAIO Z/VGC-LN51JGB workaround (for fixed speaker DAC) + 3stack-dig 3-jack with SPDIF I/O + 6stack-dig 6-jack digital with SPDIF I/O + arima Arima W820Di1 + targa Targa T8, MSI-1049 T8 + asus-a7j ASUS A7J + asus-a7m ASUS A7M + macpro MacPro support + mb5 Macbook 5,1 + macmini3 Macmini 3,1 + mba21 Macbook Air 2,1 + mbp3 Macbook Pro rev3 + imac24 iMac 24'' with jack detection + imac91 iMac 9,1 + w2jc ASUS W2JC + 3stack-2ch-dig 3-jack with SPDIF I/O (ALC883) + alc883-6stack-dig 6-jack digital with SPDIF I/O (ALC883) + 3stack-6ch 3-jack 6-channel + 3stack-6ch-dig 3-jack 6-channel with SPDIF I/O + 6stack-dig-demo 6-jack digital for Intel demo board + acer Acer laptops (Travelmate 3012WTMi, Aspire 5600, etc) + acer-aspire Acer Aspire 9810 + acer-aspire-4930g Acer Aspire 4930G + acer-aspire-6530g Acer Aspire 6530G + acer-aspire-7730g Acer Aspire 7730G + acer-aspire-8930g Acer Aspire 8930G + medion Medion Laptops + targa-dig Targa/MSI + targa-2ch-dig Targa/MSI with 2-channel + targa-8ch-dig Targa/MSI with 8-channel (MSI GX620) + laptop-eapd 3-jack with SPDIF I/O and EAPD (Clevo M540JE, M550JE) + lenovo-101e Lenovo 101E + lenovo-nb0763 Lenovo NB0763 + lenovo-ms7195-dig Lenovo MS7195 + lenovo-sky Lenovo Sky + haier-w66 Haier W66 + 3stack-hp HP machines with 3stack (Lucknow, Samba boards) + 6stack-dell Dell machines with 6stack (Inspiron 530) + mitac Mitac 8252D + clevo-m540r Clevo M540R (6ch + digital) + clevo-m720 Clevo M720 laptop series + fujitsu-pi2515 Fujitsu AMILO Pi2515 + fujitsu-xa3530 Fujitsu AMILO XA3530 + 3stack-6ch-intel Intel DG33* boards + intel-alc889a Intel IbexPeak with ALC889A + intel-x58 Intel DX58 with ALC889 + asus-p5q ASUS P5Q-EM boards + mb31 MacBook 3,1 + sony-vaio-tt Sony VAIO TT + auto auto-config reading BIOS (default) ALC861/660 ========== - N/A + 3stack 3-jack + 3stack-dig 3-jack with SPDIF I/O + 6stack-dig 6-jack with SPDIF I/O + 3stack-660 3-jack (for ALC660) + uniwill-m31 Uniwill M31 laptop + toshiba Toshiba laptop support + asus Asus laptop support + asus-laptop ASUS F2/F3 laptops + auto auto-config reading BIOS (default) ALC861VD/660VD ============== - N/A + 3stack 3-jack + 3stack-dig 3-jack with SPDIF OUT + 6stack-dig 6-jack with SPDIF OUT + 3stack-660 3-jack (for ALC660VD) + 3stack-660-digout 3-jack with SPDIF OUT (for ALC660VD) + lenovo Lenovo 3000 C200 + dallas Dallas laptops + hp HP TX1000 + asus-v1s ASUS V1Sn + auto auto-config reading BIOS (default) CMI9880 ======= @@ -88,8 +209,7 @@ CMI9880 AD1882 / AD1882A ================ - 3stack 3-stack mode - 3stack-automute 3-stack with automute front HP (default) + 3stack 3-stack mode (default) 6stack 6-stack mode AD1884A / AD1883 / AD1984A / AD1984B @@ -123,10 +243,14 @@ AD1984 AD1986A ======= + 6stack 6-jack, separate surrounds (default) 3stack 3-stack, shared surrounds laptop 2-channel only (FSC V2060, Samsung M50) - laptop-imic 2-channel with built-in mic - eapd Turn on EAPD constantly + laptop-eapd 2-channel with EAPD (ASUS A6J) + laptop-automute 2-channel with EAPD and HP-automute (Lenovo N100) + ultra 2-channel with EAPD (Samsung Ultra tablet PC) + samsung 2-channel with EAPD (Samsung R65) + samsung-p50 2-channel with HP-automute (Samsung P50) AD1988/AD1988B/AD1989A/AD1989B ============================== @@ -165,6 +289,7 @@ Conexant 5051 hp-dv6736 HP dv6736 hp-f700 HP Compaq Presario F700 ideapad Lenovo IdeaPad laptop + lenovo-x200 Lenovo X200 laptop toshiba Toshiba Satellite M300 Conexant 5066 @@ -251,7 +376,6 @@ STAC9227/9228/9229/927x 5stack-no-fp D965 5stack without front panel dell-3stack Dell Dimension E520 dell-bios Fixes with Dell BIOS setup - dell-bios-amic Fixes with Dell BIOS setup including analog mic volknob Fixes with volume-knob widget 0x24 auto BIOS setup (default) @@ -285,23 +409,10 @@ STAC92HD83* mic-ref Reference board with power management for ports dell-s14 Dell laptop dell-vostro-3500 Dell Vostro 3500 laptop + hp HP laptops with (inverted) mute-LED hp-dv7-4000 HP dv-7 4000 - hp_cNB11_intquad HP CNB models with 4 speakers - hp-zephyr HP Zephyr - hp-led HP with broken BIOS for mute LED - hp-inv-led HP with broken BIOS for inverted mute LED - hp-mic-led HP with mic-mute LED - headset-jack Dell Latitude with a 4-pin headset jack - hp-envy-bass Pin fixup for HP Envy bass speaker (NID 0x0f) - hp-envy-ts-bass Pin fixup for HP Envy TS bass speaker (NID 0x10) - hp-bnb13-eq Hardware equalizer setup for HP laptops auto BIOS setup (default) -STAC92HD95 -========== - hp-led LED support for HP laptops - hp-bass Bass HPF setup for HP Spectre 13 - STAC9872 ======== vaio VAIO laptop without SPDIF @@ -313,12 +424,6 @@ Cirrus Logic CS4206/4207 imac27 IMac 27 Inch auto BIOS setup (default) -Cirrus Logic CS4208 -=================== - mba6 MacBook Air 6,1 and 6,2 - gpio0 Enable GPIO 0 amp - auto BIOS setup (default) - VIA VT17xx/VT18xx/VT20xx ======================== auto BIOS setup (default) diff --git a/Documentation/sound/alsa/HD-Audio.txt b/Documentation/sound/alsa/HD-Audio.txt index d4510ebf2e8c..c82beb007634 100644 --- a/Documentation/sound/alsa/HD-Audio.txt +++ b/Documentation/sound/alsa/HD-Audio.txt @@ -59,12 +59,7 @@ a case, you can change the default method via `position_fix` option. `position_fix=1` means to use LPIB method explicitly. `position_fix=2` means to use the position-buffer. `position_fix=3` means to use a combination of both methods, needed -for some VIA controllers. The capture stream position is corrected -by comparing both LPIB and position-buffer values. -`position_fix=4` is another combination available for all controllers, -and uses LPIB for the playback and the position-buffer for the capture -streams. -0 is the default value for all other +for some VIA and ATI controllers. 0 is the default value for all other controllers, the automatic check and fallback to LPIB as described in the above. If you get a problem of repeated sounds, this option might help. @@ -176,14 +171,14 @@ support the automatic probing (yet as of 2.6.28). And, BIOS is often, yes, pretty often broken. It sets up wrong values and screws up the driver. -The preset model (or recently called as "fix-up") is provided -basically to overcome such a situation. When the matching preset -model is found in the white-list, the driver assumes the static -configuration of that preset with the correct pin setup, etc. -Thus, if you have a newer machine with a slightly different PCI SSID -(or codec SSID) from the existing one, you may have a good chance to -re-use the same model. You can pass the `model` option to specify the -preset model instead of PCI (and codec-) SSID look-up. +The preset model is provided basically to overcome such a situation. +When the matching preset model is found in the white-list, the driver +assumes the static configuration of that preset and builds the mixer +elements and PCM streams based on the static information. Thus, if +you have a newer machine with a slightly different PCI SSID from the +existing one, you may have a good chance to re-use the same model. +You can pass the `model` option to specify the preset model instead of +PCI SSID look-up. What `model` option values are available depends on the codec chip. Check your codec chip from the codec proc file (see "Codec Proc-File" @@ -199,12 +194,17 @@ non-working HD-audio hardware is to check HD-audio codec and several different `model` option values. If you have any luck, some of them might suit with your device well. -There are a few special model option values: -- when 'nofixup' is passed, the device-specific fixups in the codec - parser are skipped. -- when `generic` is passed, the codec-specific parser is skipped and - only the generic parser is used. +Some codecs such as ALC880 have a special model option `model=test`. +This configures the driver to provide as many mixer controls as +possible for every single pin feature except for the unsolicited +events (and maybe some other specials). Adjust each mixer element and +try the I/O in the way of trial-and-error until figuring out the whole +I/O pin mappings. +Note that `model=generic` has a special meaning. It means to use the +generic parser regardless of the codec. Usually the codec-specific +parser is much better than the generic parser (as now). Thus this +option is more about the debugging purpose. Speaker and Headphone Output ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -382,8 +382,9 @@ init_verbs:: (separated with a space). hints:: Shows / stores hint strings for codec parsers for any use. - Its format is `key = value`. For example, passing `jack_detect = no` - will disable the jack detection of the machine completely. + Its format is `key = value`. For example, passing `hp_detect = yes` + to IDT/STAC codec parser will result in the disablement of the + headphone detection. init_pin_configs:: Shows the initial pin default config values set by BIOS. driver_pin_configs:: @@ -415,69 +416,6 @@ re-configure based on that state, run like below: ------------------------------------------------------------------------ -Hint Strings -~~~~~~~~~~~~ -The codec parser have several switches and adjustment knobs for -matching better with the actual codec or device behavior. Many of -them can be adjusted dynamically via "hints" strings as mentioned in -the section above. For example, by passing `jack_detect = no` string -via sysfs or a patch file, you can disable the jack detection, thus -the codec parser will skip the features like auto-mute or mic -auto-switch. As a boolean value, either `yes`, `no`, `true`, `false`, -`1` or `0` can be passed. - -The generic parser supports the following hints: - -- jack_detect (bool): specify whether the jack detection is available - at all on this machine; default true -- inv_jack_detect (bool): indicates that the jack detection logic is - inverted -- trigger_sense (bool): indicates that the jack detection needs the - explicit call of AC_VERB_SET_PIN_SENSE verb -- inv_eapd (bool): indicates that the EAPD is implemented in the - inverted logic -- pcm_format_first (bool): sets the PCM format before the stream tag - and channel ID -- sticky_stream (bool): keep the PCM format, stream tag and ID as long - as possible; default true -- spdif_status_reset (bool): reset the SPDIF status bits at each time - the SPDIF stream is set up -- pin_amp_workaround (bool): the output pin may have multiple amp - values -- single_adc_amp (bool): ADCs can have only single input amps -- auto_mute (bool): enable/disable the headphone auto-mute feature; - default true -- auto_mic (bool): enable/disable the mic auto-switch feature; default - true -- line_in_auto_switch (bool): enable/disable the line-in auto-switch - feature; default false -- need_dac_fix (bool): limits the DACs depending on the channel count -- primary_hp (bool): probe headphone jacks as the primary outputs; - default true -- multi_io (bool): try probing multi-I/O config (e.g. shared - line-in/surround, mic/clfe jacks) -- multi_cap_vol (bool): provide multiple capture volumes -- inv_dmic_split (bool): provide split internal mic volume/switch for - phase-inverted digital mics -- indep_hp (bool): provide the independent headphone PCM stream and - the corresponding mixer control, if available -- add_stereo_mix_input (bool): add the stereo mix (analog-loopback - mix) to the input mux if 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 stream states -- power_down_unused (bool): power down the unused widgets, a subset of - power_save_node, and will be dropped in future -- add_hp_mic (bool): add the headphone to capture source if possible -- hp_mic_detect (bool): enable/disable the hp/mic shared input for a - single built-in mic case; default true -- mixer_nid (int): specifies the widget NID of the analog-loopback - mixer - - Early Patching ~~~~~~~~~~~~~~ When CONFIG_SND_HDA_PATCH_LOADER=y is set, you can pass a "patch" as a @@ -502,17 +440,14 @@ A patch file is a plain text file which looks like below: 0x20 0x400 0xff [hint] - jack_detect = no + hp_detect = yes ------------------------------------------------------------------------ The file needs to have a line `[codec]`. The next line should contain three numbers indicating the codec vendor-id (0x12345678 in the example), the codec subsystem-id (0xabcd1234) and the address (2) of the codec. The rest patch entries are applied to this specified codec -until another codec entry is given. Passing 0 or a negative number to -the first or the second value will make the check of the corresponding -field be skipped. It'll be useful for really broken devices that don't -initialize SSID properly. +until another codec entry is given. The `[model]` line allows to change the model name of the each codec. In the example above, it will be changed to model=auto. @@ -556,7 +491,7 @@ Also, the codec chip name can be rewritten via `[chip_name]` line. The hd-audio driver reads the file via request_firmware(). Thus, a patch file has to be located on the appropriate firmware path, typically, /lib/firmware. For example, when you pass the option -`patch=hda-init.fw`, the file /lib/firmware/hda-init.fw must be +`patch=hda-init.fw`, the file /lib/firmware/hda-init-fw must be present. The patch module option is specific to each card instance, and you @@ -588,72 +523,27 @@ cable is unplugged. Thus, if you hear noises, suspect first the power-saving. See /sys/module/snd_hda_intel/parameters/power_save to check the current value. If it's non-zero, the feature is turned on. -The recent kernel supports the runtime PM for the HD-audio controller -chip, too. It means that the HD-audio controller is also powered up / -down dynamically. The feature is enabled only for certain controller -chips like Intel LynxPoint. You can enable/disable this feature -forcibly by setting `power_save_controller` option, which is also -available at /sys/module/snd_hda_intel/parameters directory. - - -Tracepoints -~~~~~~~~~~~ -The hd-audio driver gives a few basic tracepoints. -`hda:hda_send_cmd` traces each CORB write while `hda:hda_get_response` -traces the response from RIRB (only when read from the codec driver). -`hda:hda_bus_reset` traces the bus-reset due to fatal error, etc, -`hda:hda_unsol_event` traces the unsolicited events, and -`hda:hda_power_down` and `hda:hda_power_up` trace the power down/up -via power-saving behavior. - -Enabling all tracepoints can be done like ------------------------------------------------------------------------- - # echo 1 > /sys/kernel/debug/tracing/events/hda/enable ------------------------------------------------------------------------- -then after some commands, you can traces from -/sys/kernel/debug/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 - # tracer: nop - # - # TASK-PID CPU# TIMESTAMP FUNCTION - # | | | | | - <...>-7807 [002] 105147.774889: hda_send_cmd: [0:0] val=e3a019 - <...>-7807 [002] 105147.774893: hda_send_cmd: [0:0] val=e39019 - <...>-7807 [002] 105147.999542: hda_send_cmd: [0:0] val=e3a01a - <...>-7807 [002] 105147.999543: hda_send_cmd: [0:0] val=e3901a - <...>-26764 [001] 349222.837143: hda_send_cmd: [0:0] val=e3a019 - <...>-26764 [001] 349222.837148: hda_send_cmd: [0:0] val=e39019 - <...>-26764 [001] 349223.058539: hda_send_cmd: [0:0] val=e3a01a - <...>-26764 [001] 349223.058541: hda_send_cmd: [0:0] val=e3901a ------------------------------------------------------------------------- -Here `[0:0]` indicates the card number and the codec address, and -`val` shows the value sent to the codec, respectively. The value is -a packed value, and you can decode it via hda-decode-verb program -included in hda-emu package below. For example, the value e3a019 is -to set the left output-amp value to 25. ------------------------------------------------------------------------- - % hda-decode-verb 0xe3a019 - raw value = 0x00e3a019 - cid = 0, nid = 0x0e, verb = 0x3a0, parm = 0x19 - raw value: verb = 0x3a0, parm = 0x19 - verbname = set_amp_gain_mute - amp raw val = 0xa019 - output, left, idx=0, mute=0, val=25 ------------------------------------------------------------------------- - Development Tree ~~~~~~~~~~~~~~~~ The latest development codes for HD-audio are found on sound git tree: -- git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/sound.git +- git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/sound-2.6.git The master branch or for-next branches can be used as the main -development branches in general while the development for the current -and next kernels are found in for-linus and for-next branches, -respectively. +development branches in general while the HD-audio specific patches +are committed in topic/hda branch. + +If you are using the latest Linus tree, it'd be better to pull the +above GIT tree onto it. If you are using the older kernels, an easy +way to try the latest ALSA code is to build from the snapshot +tarball. There are daily tarballs and the latest snapshot tarball. +All can be built just like normal alsa-driver release packages, that +is, installed via the usual spells: configure, make and make +install(-modules). See INSTALL in the package. The snapshot tarballs +are found at: + +- ftp://ftp.kernel.org/pub/linux/kernel/people/tiwai/snapshot/ Sending a Bug Report @@ -688,12 +578,7 @@ problems. alsa-info ~~~~~~~~~ The script `alsa-info.sh` is a very useful tool to gather the audio -device information. It's included in alsa-utils package. The latest -version can be found on git repository: - -- git://git.alsa-project.org/alsa-utils.git - -The script can be fetched directly from the following URL, too: +device information. You can fetch the latest version from: - http://www.alsa-project.org/alsa-info.sh @@ -758,13 +643,9 @@ won't be always updated. For example, the volume values are usually cached in the driver, and thus changing the widget amp value directly via hda-verb won't change the mixer value. -The hda-verb program is included now in alsa-tools: - -- git://git.alsa-project.org/alsa-tools.git +The hda-verb program is found in the ftp directory: -Also, the old stand-alone package is found in the ftp directory: - -- ftp://ftp.suse.com/pub/people/tiwai/misc/ +- ftp://ftp.kernel.org/pub/linux/kernel/people/tiwai/misc/ Also a git repository is available: @@ -830,24 +711,13 @@ can get a proc-file dump at the current state, get a list of control (mixer) elements, set/get the control element value, simulate the PCM operation, the jack plugging simulation, etc. -The program is found in the git repository below: - -- git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/hda-emu.git - -See README file in the repository for more details about hda-emu -program. - +The package is found in: -hda-jack-retask -~~~~~~~~~~~~~~~ -hda-jack-retask is a user-friendly GUI program to manipulate the -HD-audio pin control for jack retasking. If you have a problem about -the jack assignment, try this program and check whether you can get -useful results. Once when you figure out the proper pin assignment, -it can be fixed either in the driver code statically or via passing a -firmware patch file (see "Early Patching" section). +- ftp://ftp.kernel.org/pub/linux/kernel/people/tiwai/misc/ -The program is included in alsa-tools now: +A git repository is available: -- git://git.alsa-project.org/alsa-tools.git +- git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/hda-emu.git +See README file in the tarball for more details about hda-emu +program. diff --git a/Documentation/sound/alsa/Jack-Controls.txt b/Documentation/sound/alsa/Jack-Controls.txt deleted file mode 100644 index fe1c5e0c8555..000000000000 --- a/Documentation/sound/alsa/Jack-Controls.txt +++ /dev/null @@ -1,43 +0,0 @@ -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. - -The old ALSA jack code only created input devices for each registered -jack. These jack input devices are not readable by userspace devices -that run as non root. - -The new jack code creates embedded jack kcontrols for each jack that -can be read by any process. - -This can be combined with UCM to allow userspace to route audio more -intelligently based on jack insertion or removal events. - -Jack Kcontrol Internals -======================= - -Each jack will have a kcontrol list, so that we can create a kcontrol -and attach it to the jack, at jack creation stage. We can also add a -kcontrol to an existing jack, at anytime when required. - -Those kcontrols will be freed automatically when the Jack is freed. - -How to use jack kcontrols -========================= - -In order to keep compatibility, snd_jack_new() has been modified by -adding two params :- - - - @initial_kctl: if true, create a kcontrol and add it to the jack - list. - - @phantom_jack: Don't create a input device for phantom jacks. - -HDA jacks can set phantom_jack to true in order to create a phantom -jack and set initial_kctl to true to create an initial kcontrol with -the correct id. - -ASoC jacks should set initial_kctl as false. The pin name will be -assigned as the jack kcontrol name. diff --git a/Documentation/sound/alsa/MIXART.txt b/Documentation/sound/alsa/MIXART.txt index 4ee35b4fbe4a..ef42c44fa1f2 100644 --- a/Documentation/sound/alsa/MIXART.txt +++ b/Documentation/sound/alsa/MIXART.txt @@ -76,9 +76,9 @@ FIRMWARE when CONFIG_FW_LOADER is set. The mixartloader is necessary only for older versions or when you build the driver into kernel.] -For loading the firmware automatically after the module is loaded, use a -install command. For example, add the following entry to -/etc/modprobe.d/mixart.conf for miXart driver: +For loading the firmware automatically after the module is loaded, use +the post-install command. For example, add the following entry to +/etc/modprobe.conf for miXart driver: install snd-mixart /sbin/modprobe --first-time -i snd-mixart && \ /usr/bin/mixartloader diff --git a/Documentation/sound/alsa/OSS-Emulation.txt b/Documentation/sound/alsa/OSS-Emulation.txt index 152ca2a3f1bd..022aaeb0e9dd 100644 --- a/Documentation/sound/alsa/OSS-Emulation.txt +++ b/Documentation/sound/alsa/OSS-Emulation.txt @@ -19,7 +19,7 @@ the card number and the minor unit number. Usually you don't have to define these aliases by yourself. Only necessary step for auto-loading of OSS modules is to define the -card alias in /etc/modprobe.d/alsa.conf, such as +card alias in /etc/modprobe.conf, such as alias sound-slot-0 snd-emu10k1 diff --git a/Documentation/sound/alsa/Procfile.txt b/Documentation/sound/alsa/Procfile.txt index 7f8a0d325905..7fcd1ad96fcc 100644 --- a/Documentation/sound/alsa/Procfile.txt +++ b/Documentation/sound/alsa/Procfile.txt @@ -101,6 +101,10 @@ card*/pcm*/xrun_debug bit 0 = Enable XRUN/jiffies debug messages bit 1 = Show stack trace at XRUN / jiffies check bit 2 = Enable additional jiffies check + bit 3 = Log hwptr update at each period interrupt + bit 4 = Log hwptr update at each snd_pcm_update_hw_ptr() + bit 5 = Show last 10 positions on error + bit 6 = Do above only once When the bit 0 is set, the driver will show the messages to kernel log when an xrun is detected. The debug message is @@ -117,6 +121,15 @@ card*/pcm*/xrun_debug buggy) hardware that doesn't give smooth pointer updates. This feature is enabled via the bit 2. + Bits 3 and 4 are for logging the hwptr records. Note that + these will give flood of kernel messages. + + When bit 5 is set, the driver logs the last 10 xrun errors and + the proc file shows each jiffies, position, period_size, + buffer_size, old_hw_ptr, and hw_ptr_base values. + + When bit 6 is set, the full xrun log is shown only once. + card*/pcm*/sub*/info The general information of this PCM sub-stream. @@ -133,10 +146,6 @@ card*/pcm*/sub*/sw_params card*/pcm*/sub*/prealloc The buffer pre-allocation information. -card*/pcm*/sub*/xrun_injection - Triggers an XRUN to the running stream when any value is - written to this proc file. Used for fault injection. - This entry is write-only. AC97 Codec Information ---------------------- diff --git a/Documentation/sound/alsa/README.maya44 b/Documentation/sound/alsa/README.maya44 index 67b2ea1cc31d..0e41576fa13e 100644 --- a/Documentation/sound/alsa/README.maya44 +++ b/Documentation/sound/alsa/README.maya44 @@ -120,7 +120,7 @@ Mic Phantom+48V: switch for +48V phantom power for electrostatic microphones on Make sure this is not turned on while any other source is connected to input 1/2. It might damage the source and/or the maya44 card. -Mic/Line input: if switch is on, input jack 1/2 is microphone input (mono), otherwise line input (stereo). +Mic/Line input: if switch is is on, input jack 1/2 is microphone input (mono), otherwise line input (stereo). Bypass: analogue bypass from ADC input to output for channel 1+2. Same as "Monitor" in the windows driver. Bypass 1: same for channel 3+4. diff --git a/Documentation/sound/alsa/compress_offload.txt b/Documentation/sound/alsa/compress_offload.txt deleted file mode 100644 index 8ba556a131c3..000000000000 --- a/Documentation/sound/alsa/compress_offload.txt +++ /dev/null @@ -1,234 +0,0 @@ - compress_offload.txt - ===================== - Pierre-Louis.Bossart <pierre-louis.bossart@linux.intel.com> - Vinod Koul <vinod.koul@linux.intel.com> - -Overview - -Since its early days, the ALSA API was defined with PCM support or -constant bitrates payloads such as IEC61937 in mind. Arguments and -returned values in frames are the norm, making it a challenge to -extend the existing API to compressed data streams. - -In recent years, audio digital signal processors (DSP) were integrated -in system-on-chip designs, and DSPs are also integrated in audio -codecs. Processing compressed data on such DSPs results in a dramatic -reduction of power consumption compared to host-based -processing. Support for such hardware has not been very good in Linux, -mostly because of a lack of a generic API available in the mainline -kernel. - -Rather than requiring a compatibility break with an API change of the -ALSA PCM interface, a new 'Compressed Data' API is introduced to -provide a control and data-streaming interface for audio DSPs. - -The design of this API was inspired by the 2-year experience with the -Intel Moorestown SOC, with many corrections required to upstream the -API in the mainline kernel instead of the staging tree and make it -usable by others. - -Requirements - -The main requirements are: - -- separation between byte counts and time. Compressed formats may have - a header per file, per frame, or no header at all. The payload size - may vary from frame-to-frame. As a result, it is not possible to - estimate reliably the duration of audio buffers when handling - compressed data. Dedicated mechanisms are required to allow for - reliable audio-video synchronization, which requires precise - reporting of the number of samples rendered at any given time. - -- Handling of multiple formats. PCM data only requires a specification - of the sampling rate, number of channels and bits per sample. In - contrast, compressed data comes in a variety of formats. Audio DSPs - may also provide support for a limited number of audio encoders and - decoders embedded in firmware, or may support more choices through - dynamic download of libraries. - -- Focus on main formats. This API provides support for the most - popular formats used for audio and video capture and playback. It is - likely that as audio compression technology advances, new formats - will be added. - -- Handling of multiple configurations. Even for a given format like - AAC, some implementations may support AAC multichannel but HE-AAC - stereo. Likewise WMA10 level M3 may require too much memory and cpu - cycles. The new API needs to provide a generic way of listing these - formats. - -- Rendering/Grabbing only. This API does not provide any means of - hardware acceleration, where PCM samples are provided back to - user-space for additional processing. This API focuses instead on - streaming compressed data to a DSP, with the assumption that the - decoded samples are routed to a physical output or logical back-end. - - - Complexity hiding. Existing user-space multimedia frameworks all - have existing enums/structures for each compressed format. This new - API assumes the existence of a platform-specific compatibility layer - to expose, translate and make use of the capabilities of the audio - DSP, eg. Android HAL or PulseAudio sinks. By construction, regular - applications are not supposed to make use of this API. - - -Design - -The new API shares a number of concepts with the PCM API for flow -control. Start, pause, resume, drain and stop commands have the same -semantics no matter what the content is. - -The concept of memory ring buffer divided in a set of fragments is -borrowed from the ALSA PCM API. However, only sizes in bytes can be -specified. - -Seeks/trick modes are assumed to be handled by the host. - -The notion of rewinds/forwards is not supported. Data committed to the -ring buffer cannot be invalidated, except when dropping all buffers. - -The Compressed Data API does not make any assumptions on how the data -is transmitted to the audio DSP. DMA transfers from main memory to an -embedded audio cluster or to a SPI interface for external DSPs are -possible. As in the ALSA PCM case, a core set of routines is exposed; -each driver implementer will have to write support for a set of -mandatory routines and possibly make use of optional ones. - -The main additions are - -- get_caps -This routine returns the list of audio formats supported. Querying the -codecs on a capture stream will return encoders, decoders will be -listed for playback streams. - -- get_codec_caps For each codec, this routine returns a list of -capabilities. The intent is to make sure all the capabilities -correspond to valid settings, and to minimize the risks of -configuration failures. For example, for a complex codec such as AAC, -the number of channels supported may depend on a specific profile. If -the capabilities were exposed with a single descriptor, it may happen -that a specific combination of profiles/channels/formats may not be -supported. Likewise, embedded DSPs have limited memory and cpu cycles, -it is likely that some implementations make the list of capabilities -dynamic and dependent on existing workloads. In addition to codec -settings, this routine returns the minimum buffer size handled by the -implementation. This information can be a function of the DMA buffer -sizes, the number of bytes required to synchronize, etc, and can be -used by userspace to define how much needs to be written in the ring -buffer before playback can start. - -- set_params -This routine sets the configuration chosen for a specific codec. The -most important field in the parameters is the codec type; in most -cases decoders will ignore other fields, while encoders will strictly -comply to the settings - -- get_params -This routines returns the actual settings used by the DSP. Changes to -the settings should remain the exception. - -- get_timestamp -The timestamp becomes a multiple field structure. It lists the number -of bytes transferred, the number of samples processed and the number -of samples rendered/grabbed. All these values can be used to determine -the average bitrate, figure out if the ring buffer needs to be -refilled or the delay due to decoding/encoding/io on the DSP. - -Note that the list of codecs/profiles/modes was derived from the -OpenMAX AL specification instead of reinventing the wheel. -Modifications include: -- Addition of FLAC and IEC formats -- Merge of encoder/decoder capabilities -- Profiles/modes listed as bitmasks to make descriptors more compact -- Addition of set_params for decoders (missing in OpenMAX AL) -- Addition of AMR/AMR-WB encoding modes (missing in OpenMAX AL) -- Addition of format information for WMA -- Addition of encoding options when required (derived from OpenMAX IL) -- Addition of rateControlSupported (missing in OpenMAX AL) - -Gapless Playback -================ -When playing thru an album, the decoders have the ability to skip the encoder -delay and padding and directly move from one track content to another. The end -user can perceive this as gapless playback as we don't have silence while -switching from one track to another - -Also, there might be low-intensity noises due to encoding. Perfect gapless is -difficult to reach with all types of compressed data, but works fine with most -music content. The decoder needs to know the encoder delay and encoder padding. -So we need to pass this to DSP. This metadata is extracted from ID3/MP4 headers -and are not present by default in the bitstream, hence the need for a new -interface to pass this information to the DSP. Also DSP and userspace needs to -switch from one track to another and start using data for second track. - -The main additions are: - -- set_metadata -This routine sets the encoder delay and encoder padding. This can be used by -decoder to strip the silence. This needs to be set before the data in the track -is written. - -- set_next_track -This routine tells DSP that metadata and write operation sent after this would -correspond to subsequent track - -- partial drain -This is called when end of file is reached. The userspace can inform DSP that -EOF is reached and now DSP can start skipping padding delay. Also next write -data would belong to next track - -Sequence flow for gapless would be: -- Open -- Get caps / codec caps -- Set params -- Set metadata of the first track -- Fill data of the first track -- Trigger start -- User-space finished sending all, -- Indicate next track data by sending set_next_track -- Set metadata of the next track -- then call partial_drain to flush most of buffer in DSP -- Fill data of the next track -- DSP switches to second track -(note: order for partial_drain and write for next track can be reversed as well) - -Not supported: - -- Support for VoIP/circuit-switched calls is not the target of this - API. Support for dynamic bit-rate changes would require a tight - coupling between the DSP and the host stack, limiting power savings. - -- Packet-loss concealment is not supported. This would require an - additional interface to let the decoder synthesize data when frames - are lost during transmission. This may be added in the future. - -- Volume control/routing is not handled by this API. Devices exposing a - compressed data interface will be considered as regular ALSA devices; - volume changes and routing information will be provided with regular - ALSA kcontrols. - -- Embedded audio effects. Such effects should be enabled in the same - manner, no matter if the input was PCM or compressed. - -- multichannel IEC encoding. Unclear if this is required. - -- Encoding/decoding acceleration is not supported as mentioned - above. It is possible to route the output of a decoder to a capture - stream, or even implement transcoding capabilities. This routing - would be enabled with ALSA kcontrols. - -- Audio policy/resource management. This API does not provide any - hooks to query the utilization of the audio DSP, nor any preemption - mechanisms. - -- No notion of underrun/overrun. Since the bytes written are compressed - in nature and data written/read doesn't translate directly to - rendered output in time, this does not deal with underrun/overrun and - maybe dealt in user-library - -Credits: -- Mark Brown and Liam Girdwood for discussions on the need for this API -- Harsha Priya for her work on intel_sst compressed API -- Rakesh Ughreja for valuable feedback -- Sing Nallasellan, Sikkandar Madar and Prasanna Samaga for - demonstrating and quantifying the benefits of audio offload on a - real platform. diff --git a/Documentation/sound/alsa/hda_codec.txt b/Documentation/sound/alsa/hda_codec.txt new file mode 100644 index 000000000000..de8efbc7e4bd --- /dev/null +++ b/Documentation/sound/alsa/hda_codec.txt @@ -0,0 +1,322 @@ +Notes on Universal Interface for Intel High Definition Audio Codec +------------------------------------------------------------------ + +Takashi Iwai <tiwai@suse.de> + + +[Still a draft version] + + +General +======= + +The snd-hda-codec module supports the generic access function for the +High Definition (HD) audio codecs. It's designed to be independent +from the controller code like ac97 codec module. The real accessors +from/to the controller must be implemented in the lowlevel driver. + +The structure of this module is similar with ac97_codec module. +Each codec chip belongs to a bus class which communicates with the +controller. + + +Initialization of Bus Instance +============================== + +The card driver has to create struct hda_bus at first. The template +struct should be filled and passed to the constructor: + +struct hda_bus_template { + void *private_data; + struct pci_dev *pci; + const char *modelname; + struct hda_bus_ops ops; +}; + +The card driver can set and use the private_data field to retrieve its +own data in callback functions. The pci field is used when the patch +needs to check the PCI subsystem IDs, so on. For non-PCI system, it +doesn't have to be set, of course. +The modelname field specifies the board's specific configuration. The +string is passed to the codec parser, and it depends on the parser how +the string is used. +These fields, private_data, pci and modelname are all optional. + +The ops field contains the callback functions as the following: + +struct hda_bus_ops { + int (*command)(struct hda_codec *codec, hda_nid_t nid, int direct, + unsigned int verb, unsigned int parm); + unsigned int (*get_response)(struct hda_codec *codec); + void (*private_free)(struct hda_bus *); +#ifdef CONFIG_SND_HDA_POWER_SAVE + void (*pm_notify)(struct hda_codec *codec); +#endif +}; + +The command callback is called when the codec module needs to send a +VERB to the controller. It's always a single command. +The get_response callback is called when the codec requires the answer +for the last command. These two callbacks are mandatory and have to +be given. +The third, private_free callback, is optional. It's called in the +destructor to release any necessary data in the lowlevel driver. + +The pm_notify callback is available only with +CONFIG_SND_HDA_POWER_SAVE kconfig. It's called when the codec needs +to power up or may power down. The controller should check the all +belonging codecs on the bus whether they are actually powered off +(check codec->power_on), and optionally the driver may power down the +controller side, too. + +The bus instance is created via snd_hda_bus_new(). You need to pass +the card instance, the template, and the pointer to store the +resultant bus instance. + +int snd_hda_bus_new(struct snd_card *card, const struct hda_bus_template *temp, + struct hda_bus **busp); + +It returns zero if successful. A negative return value means any +error during creation. + + +Creation of Codec Instance +========================== + +Each codec chip on the board is then created on the BUS instance. +To create a codec instance, call snd_hda_codec_new(). + +int snd_hda_codec_new(struct hda_bus *bus, unsigned int codec_addr, + struct hda_codec **codecp); + +The first argument is the BUS instance, the second argument is the +address of the codec, and the last one is the pointer to store the +resultant codec instance (can be NULL if not needed). + +The codec is stored in a linked list of bus instance. You can follow +the codec list like: + + struct hda_codec *codec; + list_for_each_entry(codec, &bus->codec_list, list) { + ... + } + +The codec isn't initialized at this stage properly. The +initialization sequence is called when the controls are built later. + + +Codec Access +============ + +To access codec, use snd_hda_codec_read() and snd_hda_codec_write(). +snd_hda_param_read() is for reading parameters. +For writing a sequence of verbs, use snd_hda_sequence_write(). + +There are variants of cached read/write, snd_hda_codec_write_cache(), +snd_hda_sequence_write_cache(). These are used for recording the +register states for the power-management resume. When no PM is needed, +these are equivalent with non-cached version. + +To retrieve the number of sub nodes connected to the given node, use +snd_hda_get_sub_nodes(). The connection list can be obtained via +snd_hda_get_connections() call. + +When an unsolicited event happens, pass the event via +snd_hda_queue_unsol_event() so that the codec routines will process it +later. + + +(Mixer) Controls +================ + +To create mixer controls of all codecs, call +snd_hda_build_controls(). It then builds the mixers and does +initialization stuff on each codec. + + +PCM Stuff +========= + +snd_hda_build_pcms() gives the necessary information to create PCM +streams. When it's called, each codec belonging to the bus stores +codec->num_pcms and codec->pcm_info fields. The num_pcms indicates +the number of elements in pcm_info array. The card driver is supposed +to traverse the codec linked list, read the pcm information in +pcm_info array, and build pcm instances according to them. + +The pcm_info array contains the following record: + +/* PCM information for each substream */ +struct hda_pcm_stream { + unsigned int substreams; /* number of substreams, 0 = not exist */ + unsigned int channels_min; /* min. number of channels */ + unsigned int channels_max; /* max. number of channels */ + hda_nid_t nid; /* default NID to query rates/formats/bps, or set up */ + u32 rates; /* supported rates */ + u64 formats; /* supported formats (SNDRV_PCM_FMTBIT_) */ + unsigned int maxbps; /* supported max. bit per sample */ + struct hda_pcm_ops ops; +}; + +/* for PCM creation */ +struct hda_pcm { + char *name; + struct hda_pcm_stream stream[2]; +}; + +The name can be passed to snd_pcm_new(). The stream field contains +the information for playback (SNDRV_PCM_STREAM_PLAYBACK = 0) and +capture (SNDRV_PCM_STREAM_CAPTURE = 1) directions. The card driver +should pass substreams to snd_pcm_new() for the number of substreams +to create. + +The channels_min, channels_max, rates and formats should be copied to +runtime->hw record. They and maxbps fields are used also to compute +the format value for the HDA codec and controller. Call +snd_hda_calc_stream_format() to get the format value. + +The ops field contains the following callback functions: + +struct hda_pcm_ops { + int (*open)(struct hda_pcm_stream *info, struct hda_codec *codec, + struct snd_pcm_substream *substream); + int (*close)(struct hda_pcm_stream *info, struct hda_codec *codec, + struct snd_pcm_substream *substream); + int (*prepare)(struct hda_pcm_stream *info, struct hda_codec *codec, + unsigned int stream_tag, unsigned int format, + struct snd_pcm_substream *substream); + int (*cleanup)(struct hda_pcm_stream *info, struct hda_codec *codec, + struct snd_pcm_substream *substream); +}; + +All are non-NULL, so you can call them safely without NULL check. + +The open callback should be called in PCM open after runtime->hw is +set up. It may override some setting and constraints additionally. +Similarly, the close callback should be called in the PCM close. + +The prepare callback should be called in PCM prepare. This will set +up the codec chip properly for the operation. The cleanup should be +called in hw_free to clean up the configuration. + +The caller should check the return value, at least for open and +prepare callbacks. When a negative value is returned, some error +occurred. + + +Proc Files +========== + +Each codec dumps the widget node information in +/proc/asound/card*/codec#* file. This information would be really +helpful for debugging. Please provide its contents together with the +bug report. + + +Power Management +================ + +It's simple: +Call snd_hda_suspend() in the PM suspend callback. +Call snd_hda_resume() in the PM resume callback. + + +Codec Preset (Patch) +==================== + +To set up and handle the codec functionality fully, each codec may +have a codec preset (patch). It's defined in struct hda_codec_preset: + + struct hda_codec_preset { + unsigned int id; + unsigned int mask; + unsigned int subs; + unsigned int subs_mask; + unsigned int rev; + const char *name; + int (*patch)(struct hda_codec *codec); + }; + +When the codec id and codec subsystem id match with the given id and +subs fields bitwise (with bitmask mask and subs_mask), the callback +patch is called. The patch callback should initialize the codec and +set the codec->patch_ops field. This is defined as below: + + struct hda_codec_ops { + int (*build_controls)(struct hda_codec *codec); + int (*build_pcms)(struct hda_codec *codec); + int (*init)(struct hda_codec *codec); + void (*free)(struct hda_codec *codec); + void (*unsol_event)(struct hda_codec *codec, unsigned int res); + #ifdef CONFIG_PM + int (*suspend)(struct hda_codec *codec, pm_message_t state); + int (*resume)(struct hda_codec *codec); + #endif + #ifdef CONFIG_SND_HDA_POWER_SAVE + int (*check_power_status)(struct hda_codec *codec, + hda_nid_t nid); + #endif + }; + +The build_controls callback is called from snd_hda_build_controls(). +Similarly, the build_pcms callback is called from +snd_hda_build_pcms(). The init callback is called after +build_controls to initialize the hardware. +The free callback is called as a destructor. + +The unsol_event callback is called when an unsolicited event is +received. + +The suspend and resume callbacks are for power management. +They can be NULL if no special sequence is required. When the resume +callback is NULL, the driver calls the init callback and resumes the +registers from the cache. If other handling is needed, you'd need to +write your own resume callback. There, the amp values can be resumed +via + void snd_hda_codec_resume_amp(struct hda_codec *codec); +and the other codec registers via + void snd_hda_codec_resume_cache(struct hda_codec *codec); + +The check_power_status callback is called when the amp value of the +given widget NID is changed. The codec code can turn on/off the power +appropriately from this information. + +Each entry can be NULL if not necessary to be called. + + +Generic Parser +============== + +When the device doesn't match with any given presets, the widgets are +parsed via th generic parser (hda_generic.c). Its support is +limited: no multi-channel support, for example. + + +Digital I/O +=========== + +Call snd_hda_create_spdif_out_ctls() from the patch to create controls +related with SPDIF out. + + +Helper Functions +================ + +snd_hda_get_codec_name() stores the codec name on the given string. + +snd_hda_check_board_config() can be used to obtain the configuration +information matching with the device. Define the model string table +and the table with struct snd_pci_quirk entries (zero-terminated), +and pass it to the function. The function checks the modelname given +as a module parameter, and PCI subsystem IDs. If the matching entry +is found, it returns the config field value. + +snd_hda_add_new_ctls() can be used to create and add control entries. +Pass the zero-terminated array of struct snd_kcontrol_new + +Macros HDA_CODEC_VOLUME(), HDA_CODEC_MUTE() and their variables can be +used for the entry of struct snd_kcontrol_new. + +The input MUX helper callbacks for such a control are provided, too: +snd_hda_input_mux_info() and snd_hda_input_mux_put(). See +patch_realtek.c for example. diff --git a/Documentation/sound/alsa/hdspm.txt b/Documentation/sound/alsa/hdspm.txt index 7ba31948dea7..7a67ff71a9f8 100644 --- a/Documentation/sound/alsa/hdspm.txt +++ b/Documentation/sound/alsa/hdspm.txt @@ -359,4 +359,4 @@ Calling Parameter: enable_monitor int array (min = 1, max = 8), "Enable Analog Out on Channel 63/64 by default." - note: here the analog output is enabled (but not routed). + note: here the analog output is enabled (but not routed).
\ No newline at end of file diff --git a/Documentation/sound/alsa/img,spdif-in.txt b/Documentation/sound/alsa/img,spdif-in.txt deleted file mode 100644 index 8b7505785fa6..000000000000 --- a/Documentation/sound/alsa/img,spdif-in.txt +++ /dev/null @@ -1,49 +0,0 @@ -The Imagination Technologies SPDIF Input controller contains the following -controls: - -name='IEC958 Capture Mask',index=0 - -This control returns a mask that shows which of the IEC958 status bits -can be read using the 'IEC958 Capture Default' control. - -name='IEC958 Capture Default',index=0 - -This control returns the status bits contained within the SPDIF stream that -is being received. The 'IEC958 Capture Mask' shows which bits can be read -from this control. - -name='SPDIF In Multi Frequency Acquire',index=0 -name='SPDIF In Multi Frequency Acquire',index=1 -name='SPDIF In Multi Frequency Acquire',index=2 -name='SPDIF In Multi Frequency Acquire',index=3 - -This control is used to attempt acquisition of up to four different sample -rates. The active rate can be obtained by reading the 'SPDIF In Lock Frequency' -control. - -When the value of this control is set to {0,0,0,0}, the rate given to hw_params -will determine the single rate the block will capture. Else, the rate given to -hw_params will be ignored, and the block will attempt capture for each of the -four sample rates set here. - -If less than four rates are required, the same rate can be specified more than -once - -name='SPDIF In Lock Frequency',index=0 - -This control returns the active capture rate, or 0 if a lock has not been -acquired - -name='SPDIF In Lock TRK',index=0 - -This control is used to modify the locking/jitter rejection characteristics -of the block. Larger values increase the locking range, but reduce jitter -rejection. - -name='SPDIF In Lock Acquire Threshold',index=0 - -This control is used to change the threshold at which a lock is acquired. - -name='SPDIF In Lock Release Threshold',index=0 - -This control is used to change the threshold at which a lock is released. diff --git a/Documentation/sound/alsa/seq_oss.html b/Documentation/sound/alsa/seq_oss.html index 9663b45f6fde..d9776cf60c07 100644 --- a/Documentation/sound/alsa/seq_oss.html +++ b/Documentation/sound/alsa/seq_oss.html @@ -285,7 +285,7 @@ sample data. <H4> 7.2.4 Close Callback</H4> The <TT>close</TT> callback is called when this device is closed by the -application. If any private data was allocated in open callback, it must +applicaion. If any private data was allocated in open callback, it must be released in the close callback. The deletion of ALSA port should be done here, too. This callback must not be NULL. <H4> diff --git a/Documentation/sound/alsa/soc/DPCM.txt b/Documentation/sound/alsa/soc/DPCM.txt deleted file mode 100644 index 0110180b7ac6..000000000000 --- a/Documentation/sound/alsa/soc/DPCM.txt +++ /dev/null @@ -1,380 +0,0 @@ -Dynamic PCM -=========== - -1. Description -============== - -Dynamic PCM allows an ALSA PCM device to digitally route its PCM audio to -various digital endpoints during the PCM stream runtime. e.g. PCM0 can route -digital audio to I2S DAI0, I2S DAI1 or PDM DAI2. This is useful for on SoC DSP -drivers that expose several ALSA PCMs and can route to multiple DAIs. - -The DPCM runtime routing is determined by the ALSA mixer settings in the same -way as the analog signal is routed in an ASoC codec driver. DPCM uses a DAPM -graph representing the DSP internal audio paths and uses the mixer settings to -determine the patch used by each ALSA PCM. - -DPCM re-uses all the existing component codec, platform and DAI drivers without -any modifications. - - -Phone Audio System with SoC based DSP -------------------------------------- - -Consider the following phone audio subsystem. This will be used in this -document for all examples :- - -| Front End PCMs | SoC DSP | Back End DAIs | Audio devices | - - ************* -PCM0 <------------> * * <----DAI0-----> Codec Headset - * * -PCM1 <------------> * * <----DAI1-----> Codec Speakers - * DSP * -PCM2 <------------> * * <----DAI2-----> MODEM - * * -PCM3 <------------> * * <----DAI3-----> BT - * * - * * <----DAI4-----> DMIC - * * - * * <----DAI5-----> FM - ************* - -This diagram shows a simple smart phone audio subsystem. It supports Bluetooth, -FM digital radio, Speakers, Headset Jack, digital microphones and cellular -modem. This sound card exposes 4 DSP front end (FE) ALSA PCM devices and -supports 6 back end (BE) DAIs. Each FE PCM can digitally route audio data to any -of the BE DAIs. The FE PCM devices can also route audio to more than 1 BE DAI. - - - -Example - DPCM Switching playback from DAI0 to DAI1 ---------------------------------------------------- - -Audio is being played to the Headset. After a while the user removes the headset -and audio continues playing on the speakers. - -Playback on PCM0 to Headset would look like :- - - ************* -PCM0 <============> * * <====DAI0=====> Codec Headset - * * -PCM1 <------------> * * <----DAI1-----> Codec Speakers - * DSP * -PCM2 <------------> * * <----DAI2-----> MODEM - * * -PCM3 <------------> * * <----DAI3-----> BT - * * - * * <----DAI4-----> DMIC - * * - * * <----DAI5-----> FM - ************* - -The headset is removed from the jack by user so the speakers must now be used :- - - ************* -PCM0 <============> * * <----DAI0-----> Codec Headset - * * -PCM1 <------------> * * <====DAI1=====> Codec Speakers - * DSP * -PCM2 <------------> * * <----DAI2-----> MODEM - * * -PCM3 <------------> * * <----DAI3-----> BT - * * - * * <----DAI4-----> DMIC - * * - * * <----DAI5-----> FM - ************* - -The audio driver processes this as follows :- - - 1) Machine driver receives Jack removal event. - - 2) Machine driver OR audio HAL disables the Headset path. - - 3) DPCM runs the PCM trigger(stop), hw_free(), shutdown() operations on DAI0 - for headset since the path is now disabled. - - 4) Machine driver or audio HAL enables the speaker path. - - 5) DPCM runs the PCM ops for startup(), hw_params(), prepapre() and - trigger(start) for DAI1 Speakers since the path is enabled. - -In this example, the machine driver or userspace audio HAL can alter the routing -and then DPCM will take care of managing the DAI PCM operations to either bring -the link up or down. Audio playback does not stop during this transition. - - - -DPCM machine driver -=================== - -The DPCM enabled ASoC machine driver is similar to normal machine drivers -except that we also have to :- - - 1) Define the FE and BE DAI links. - - 2) Define any FE/BE PCM operations. - - 3) Define widget graph connections. - - -1 FE and BE DAI links ---------------------- - -| Front End PCMs | SoC DSP | Back End DAIs | Audio devices | - - ************* -PCM0 <------------> * * <----DAI0-----> Codec Headset - * * -PCM1 <------------> * * <----DAI1-----> Codec Speakers - * DSP * -PCM2 <------------> * * <----DAI2-----> MODEM - * * -PCM3 <------------> * * <----DAI3-----> BT - * * - * * <----DAI4-----> DMIC - * * - * * <----DAI5-----> FM - ************* - -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 :- - -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", - .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 -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). - -The FE DAI above sets the codec and code DAIs to dummy devices since the BE is -dynamic and will change depending on runtime config. - -The BE DAIs are configured as follows :- - -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", - .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 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 -like a BT phone call :- - - ************* -PCM0 <------------> * * <----DAI0-----> Codec Headset - * * -PCM1 <------------> * * <----DAI1-----> Codec Speakers - * DSP * -PCM2 <------------> * * <====DAI2=====> MODEM - * * -PCM3 <------------> * * <====DAI3=====> BT - * * - * * <----DAI4-----> DMIC - * * - * * <----DAI5-----> FM - ************* - -This allows the host CPU to sleep whilst the DSP, MODEM DAI and the BT DAI are -still in operation. - -A BE DAI link can also set the codec to a dummy device if the code is a device -that is managed externally. - -Likewise a BE DAI can also set a dummy cpu DAI if the CPU DAI is managed by the -DSP firmware. - - -2 FE/BE PCM operations ----------------------- - -The BE above also exports some PCM operations and a "fixup" callback. The fixup -callback is used by the machine driver to (re)configure the DAI based upon the -FE hw params. i.e. the DSP may perform SRC or ASRC from the FE to BE. - -e.g. DSP converts all FE hw params to run at fixed rate of 48k, 16bit, stereo for -DAI0. This means all FE hw_params have to be fixed in the machine driver for -DAI0 so that the DAI is running at desired configuration regardless of the FE -configuration. - -static int dai0_fixup(struct snd_soc_pcm_runtime *rtd, - struct snd_pcm_hw_params *params) -{ - struct snd_interval *rate = hw_param_interval(params, - SNDRV_PCM_HW_PARAM_RATE); - struct snd_interval *channels = hw_param_interval(params, - SNDRV_PCM_HW_PARAM_CHANNELS); - - /* The DSP will covert the FE rate to 48k, stereo */ - rate->min = rate->max = 48000; - channels->min = channels->max = 2; - - /* set DAI0 to 16 bit */ - snd_mask_set(¶ms->masks[SNDRV_PCM_HW_PARAM_FORMAT - - SNDRV_PCM_HW_PARAM_FIRST_MASK], - SNDRV_PCM_FORMAT_S16_LE); - return 0; -} - -The other PCM operation are the same as for regular DAI links. Use as necessary. - - -3 Widget graph connections --------------------------- - -The BE DAI links will normally be connected to the graph at initialisation time -by the ASoC DAPM core. However, if the BE codec or BE DAI is a dummy then this -has to be set explicitly in the driver :- - -/* BE for codec Headset - DAI0 is dummy and managed by DSP FW */ -{"DAI0 CODEC IN", NULL, "AIF1 Capture"}, -{"AIF1 Playback", NULL, "DAI0 CODEC OUT"}, - - -Writing a DPCM DSP driver -========================= - -The DPCM DSP driver looks much like a standard platform class ASoC driver -combined with elements from a codec class driver. A DSP platform driver must -implement :- - - 1) Front End PCM DAIs - i.e. struct snd_soc_dai_driver. - - 2) DAPM graph showing DSP audio routing from FE DAIs to BEs. - - 3) DAPM widgets from DSP graph. - - 4) Mixers for gains, routing, etc. - - 5) DMA configuration. - - 6) BE AIF widgets. - -Items 6 is important for routing the audio outside of the DSP. AIF need to be -defined for each BE and each stream direction. e.g for BE DAI0 above we would -have :- - -SND_SOC_DAPM_AIF_IN("DAI0 RX", NULL, 0, SND_SOC_NOPM, 0, 0), -SND_SOC_DAPM_AIF_OUT("DAI0 TX", NULL, 0, SND_SOC_NOPM, 0, 0), - -The BE AIF are used to connect the DSP graph to the graphs for the other -component drivers (e.g. codec graph). - - -Hostless PCM streams -==================== - -A hostless PCM stream is a stream that is not routed through the host CPU. An -example of this would be a phone call from handset to modem. - - - ************* -PCM0 <------------> * * <----DAI0-----> Codec Headset - * * -PCM1 <------------> * * <====DAI1=====> Codec Speakers/Mic - * DSP * -PCM2 <------------> * * <====DAI2=====> MODEM - * * -PCM3 <------------> * * <----DAI3-----> BT - * * - * * <----DAI4-----> DMIC - * * - * * <----DAI5-----> FM - ************* - -In this case the PCM data is routed via the DSP. The host CPU in this use case -is only used for control and can sleep during the runtime of the stream. - -The host can control the hostless link either by :- - - 1) Configuring the link as a CODEC <-> CODEC style link. In this case the link - is enabled or disabled by the state of the DAPM graph. This usually means - there is a mixer control that can be used to connect or disconnect the path - between both DAIs. - - 2) Hostless FE. This FE has a virtual connection to the BE DAI links on the DAPM - graph. Control is then carried out by the FE as regular PCM operations. - This method gives more control over the DAI links, but requires much more - userspace code to control the link. Its recommended to use CODEC<->CODEC - unless your HW needs more fine grained sequencing of the PCM ops. - - -CODEC <-> CODEC link --------------------- - -This DAI link is enabled when DAPM detects a valid path within the DAPM graph. -The machine driver sets some additional parameters to the DAI link i.e. - -static const struct snd_soc_pcm_stream dai_params = { - .formats = SNDRV_PCM_FMTBIT_S32_LE, - .rate_min = 8000, - .rate_max = 8000, - .channels_min = 2, - .channels_max = 2, -}; - -static struct snd_soc_dai_link dais[] = { - < ... more DAI links above ... > - { - .name = "MODEM", - .stream_name = "MODEM", - .cpu_dai_name = "dai2", - .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, - } - < ... more DAI links here ... > - -These parameters are used to configure the DAI hw_params() when DAPM detects a -valid path and then calls the PCM operations to start the link. DAPM will also -call the appropriate PCM operations to disable the DAI when the path is no -longer valid. - - -Hostless FE ------------ - -The DAI link(s) are enabled by a FE that does not read or write any PCM data. -This means creating a new FE that is connected with a virtual path to both -DAI links. The DAI links will be started when the FE PCM is started and stopped -when the FE PCM is stopped. Note that the FE PCM cannot read or write data in -this configuration. - - diff --git a/Documentation/sound/alsa/soc/codec.txt b/Documentation/sound/alsa/soc/codec.txt index db5f9c9ae149..bce23a4a7875 100644 --- a/Documentation/sound/alsa/soc/codec.txt +++ b/Documentation/sound/alsa/soc/codec.txt @@ -1,23 +1,22 @@ -ASoC Codec Class Driver -======================= +ASoC Codec Driver +================= -The codec class driver is generic and hardware independent code that configures -the codec, FM, MODEM, BT or external DSP to provide audio capture and playback. -It should contain no code that is specific to the target platform or machine. -All platform and machine specific code should be added to the platform and -machine drivers respectively. +The codec driver is generic and hardware independent code that configures the +codec to provide audio capture and playback. It should contain no code that is +specific to the target platform or machine. All platform and machine specific +code should be added to the platform and machine drivers respectively. -Each codec class driver *must* provide the following features:- +Each codec driver *must* provide the following features:- 1) Codec DAI and PCM configuration - 2) Codec control IO - using RegMap API + 2) Codec control IO - using I2C, 3 Wire(SPI) or both APIs 3) Mixers and audio controls 4) Codec audio operations - 5) DAPM description. - 6) DAPM event handler. Optionally, codec drivers can also provide:- + 5) DAPM description. + 6) DAPM event handler. 7) DAC Digital mute control. Its probably best to use this guide in conjunction with the existing codec @@ -65,9 +64,26 @@ struct snd_soc_dai_driver wm8731_dai = { 2 - Codec control IO -------------------- The codec can usually be controlled via an I2C or SPI style interface -(AC97 combines control with data in the DAI). The codec driver should use the -Regmap API for all codec IO. Please see include/linux/regmap.h and existing -codec drivers for example regmap usage. +(AC97 combines control with data in the DAI). The codec drivers provide +functions to read and write the codec registers along with supplying a +register cache:- + + /* IO control data and register cache */ + void *control_data; /* codec control (i2c/3wire) data */ + void *reg_cache; + +Codec read/write should do any data formatting and call the hardware +read write below to perform the IO. These functions are called by the +core and ALSA when performing DAPM or changing the mixer:- + + unsigned int (*read)(struct snd_soc_codec *, unsigned int); + int (*write)(struct snd_soc_codec *, unsigned int, unsigned int); + +Codec hardware IO functions - usually points to either the I2C, SPI or AC97 +read/write:- + + hw_write_t hw_write; + hw_read_t hw_read; 3 - Mixers and audio controls @@ -111,7 +127,7 @@ Defines a stereo enumerated control 4 - Codec Audio Operations -------------------------- -The codec driver also supports the following ALSA PCM operations:- +The codec driver also supports the following ALSA operations:- /* SoC audio ops */ struct snd_soc_ops { diff --git a/Documentation/sound/alsa/soc/dapm.txt b/Documentation/sound/alsa/soc/dapm.txt index c45bd79f291e..05bf5a0eee41 100644 --- a/Documentation/sound/alsa/soc/dapm.txt +++ b/Documentation/sound/alsa/soc/dapm.txt @@ -21,7 +21,7 @@ level power systems. There are 4 power domains within DAPM - 1. Codec bias domain - VREF, VMID (core codec and audio power) + 1. Codec domain - VREF, VMID (core codec and audio power) Usually controlled at codec probe/remove and suspend/resume, although can be set at stream time if power is not needed for sidetone, etc. @@ -30,7 +30,7 @@ There are 4 power domains within DAPM machine driver and responds to asynchronous events e.g when HP are inserted - 3. Path domain - audio subsystem signal paths + 3. Path domain - audio susbsystem signal paths Automatically set when mixer and mux settings are changed by the user. e.g. alsamixer, amixer. @@ -63,22 +63,14 @@ Audio DAPM widgets fall into a number of types:- o Line - Line Input/Output (and optional Jack) o Speaker - Speaker o Supply - Power or clock supply widget used by other widgets. - o Regulator - External regulator that supplies power to audio components. - o Clock - External clock that supplies clock to audio components. - o AIF IN - Audio Interface Input (with TDM slot mask). - o AIF OUT - Audio Interface Output (with TDM slot mask). - o Siggen - Signal Generator. - o DAI IN - Digital Audio Interface Input. - o DAI OUT - Digital Audio Interface Output. - o DAI Link - DAI Link between two DAI structures */ o Pre - Special PRE widget (exec before all others) o Post - Special POST widget (exec after all others) (Widgets are defined in include/sound/soc-dapm.h) -Widgets can be added to the sound card by any of the component driver types. -There are convenience macros defined in soc-dapm.h that can be used to quickly -build a list of widgets of the codecs and machines DAPM widgets. +Widgets are usually added in the codec driver and the machine driver. There are +convenience macros defined in soc-dapm.h that can be used to quickly build a +list of widgets of the codecs and machines DAPM widgets. Most widgets have a name, register, shift and invert. Some widgets have extra parameters for stream name and kcontrols. @@ -88,13 +80,11 @@ parameters for stream name and kcontrols. ------------------------- 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. +(analog to digital converters) and DACs (digital to analog converters). 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. @@ -104,11 +94,6 @@ e.g. stream widgets for HiFi playback and capture SND_SOC_DAPM_DAC("HiFi DAC", "HiFi Playback", REG, 3, 1), SND_SOC_DAPM_ADC("HiFi ADC", "HiFi Capture", REG, 2, 1), -e.g. stream widgets for AIF - -SND_SOC_DAPM_AIF_IN("AIF1RX", "AIF1 Playback", 0, SND_SOC_NOPM, 0, 0), -SND_SOC_DAPM_AIF_OUT("AIF1TX", "AIF1 Capture", 0, SND_SOC_NOPM, 0, 0), - 2.2 Path Domain Widgets ----------------------- @@ -132,18 +117,16 @@ SOC_DAPM_SINGLE("HiFi Playback Switch", WM8731_APANA, 4, 1, 0), SND_SOC_DAPM_MIXER("Output Mixer", WM8731_PWR, 4, 1, wm8731_output_mixer_controls, ARRAY_SIZE(wm8731_output_mixer_controls)), -If you don't want the mixer elements prefixed with the name of the mixer widget, +If you dont want the mixer elements prefixed with the name of the mixer widget, you can use SND_SOC_DAPM_MIXER_NAMED_CTL instead. the parameters are the same as for SND_SOC_DAPM_MIXER. - -2.3 Machine domain Widgets --------------------------- +2.3 Platform/Machine domain Widgets +----------------------------------- Machine widgets are different from codec widgets in that they don't have a codec register bit associated with them. A machine widget is assigned to each -machine audio component (non codec or DSP) that can be independently -powered. e.g. +machine audio component (non codec) that can be independently powered. e.g. o Speaker Amp o Microphone Bias @@ -163,12 +146,12 @@ static int spitz_mic_bias(struct snd_soc_dapm_widget* w, int event) SND_SOC_DAPM_MIC("Mic Jack", spitz_mic_bias), -2.4 Codec (BIAS) Domain ------------------------ +2.4 Codec Domain +---------------- -The codec bias power domain has no widgets and is handled by the codecs DAPM -event handler. This handler is called when the codec powerstate is changed wrt -to any stream event or by kernel PM events. +The codec power domain has no widgets and is handled by the codecs DAPM event +handler. This handler is called when the codec powerstate is changed wrt to any +stream event or by kernel PM events. 2.5 Virtual Widgets @@ -186,16 +169,15 @@ 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(). -3. Codec/DSP Widget Interconnections -==================================== +3. Codec 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. +Widgets are connected to each other within the codec and machine by audio paths +(called interconnections). Each interconnection must be defined in order to +create a map 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. +This is easiest with a diagram of the codec (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) @@ -265,9 +247,16 @@ machine and includes the codec. e.g. o Mic Jack o Codec Pins -Endpoints are added to the DAPM graph so that their usage can be determined in -order to save power. e.g. NC codecs pins will be switched OFF, unconnected -jacks can also be switched OFF. +When a codec pin is NC it can be marked as not used with a call to + +snd_soc_dapm_set_endpoint(codec, "Widget Name", 0); + +The last argument is 0 for inactive and 1 for active. This way the pin and its +input widget will never be powered up and consume power. + +This also applies to machine widgets. e.g. if a headphone is connected to a +jack then the jack can be marked active. If the headphone is removed, then +the headphone jack can be marked inactive. 5 DAPM Widget Events diff --git a/Documentation/sound/alsa/soc/machine.txt b/Documentation/sound/alsa/soc/machine.txt index 6bf2d2063b52..3e2ec9cbf397 100644 --- a/Documentation/sound/alsa/soc/machine.txt +++ b/Documentation/sound/alsa/soc/machine.txt @@ -1,10 +1,8 @@ ASoC Machine Driver =================== -The ASoC machine (or board) driver is the code that glues together all the -component drivers (e.g. codecs, platforms and DAIs). It also describes the -relationships between each component which include audio paths, GPIOs, -interrupts, clocking, jacks and voltage regulators. +The ASoC machine (or board) driver is the code that glues together the platform +and codec drivers. The machine driver can contain codec and platform specific code. It registers the audio subsystem with the kernel as a platform device and is represented by @@ -52,7 +50,8 @@ Machine DAI Configuration The machine DAI configuration glues all the codec and CPU DAIs together. It can also be used to set up the DAI system clock and for any machine related DAI initialisation e.g. the machine audio map can be connected to the codec audio -map, unconnected codec pins can be set as such. +map, unconnected codec pins can be set as such. Please see corgi.c, spitz.c +for examples. struct snd_soc_dai_link is used to set up each DAI in your machine. e.g. @@ -84,7 +83,8 @@ Machine Power Map The machine driver can optionally extend the codec power map and to become an audio power map of the audio subsystem. This allows for automatic power up/down of speaker/HP amplifiers, etc. Codec pins can be connected to the machines jack -sockets in the machine init function. +sockets in the machine init function. See soc/pxa/spitz.c and dapm.txt for +details. Machine Controls diff --git a/Documentation/sound/alsa/soc/overview.txt b/Documentation/sound/alsa/soc/overview.txt index f3f28b7ae242..138ac88c1461 100644 --- a/Documentation/sound/alsa/soc/overview.txt +++ b/Documentation/sound/alsa/soc/overview.txt @@ -49,23 +49,18 @@ features :- * Machine specific controls: Allow machines to add controls to the sound card (e.g. volume control for speaker amplifier). -To achieve all this, ASoC basically splits an embedded audio system into -multiple re-usable component drivers :- +To achieve all this, ASoC basically splits an embedded audio system into 3 +components :- - * Codec class drivers: The codec class driver is platform independent and - contains audio controls, audio interface capabilities, codec DAPM - definition and codec IO functions. This class extends to BT, FM and MODEM - ICs if required. Codec class drivers should be generic code that can run - on any architecture and machine. + * Codec driver: The codec driver is platform independent and contains audio + controls, audio interface capabilities, codec DAPM definition and codec IO + functions. - * Platform class drivers: The platform class driver includes the audio DMA - engine driver, digital audio interface (DAI) drivers (e.g. I2S, AC97, PCM) - and any audio DSP drivers for that platform. + * Platform driver: The platform driver contains the audio DMA engine and audio + interface drivers (e.g. I2S, AC97, PCM) for that platform. - * Machine class driver: The machine driver class acts as the glue that - describes and binds the other component drivers together to form an ALSA - "sound card device". It handles any machine specific controls and - machine level audio events (e.g. turning on an amp at start of playback). + * Machine driver: The machine driver handles any machine specific controls and + audio events (e.g. turning on an amp at start of playback). Documentation @@ -89,7 +84,3 @@ machine.txt: Machine driver internals. pop_clicks.txt: How to minimise audio artifacts. clocking.txt: ASoC clocking for best power performance. - -jack.txt: ASoC jack detection. - -DPCM.txt: Dynamic PCM - Describes DPCM with DSP examples. diff --git a/Documentation/sound/alsa/soc/platform.txt b/Documentation/sound/alsa/soc/platform.txt index 3a08a2c9150c..d57efad37e0a 100644 --- a/Documentation/sound/alsa/soc/platform.txt +++ b/Documentation/sound/alsa/soc/platform.txt @@ -1,9 +1,9 @@ ASoC Platform Driver ==================== -An ASoC platform driver class can be divided into audio DMA drivers, SoC DAI -drivers and DSP drivers. The platform drivers only target the SoC CPU and must -have no board specific code. +An ASoC platform driver can be divided into audio DMA and SoC DAI configuration +and control. The platform drivers only target the SoC CPU and must have no board +specific code. Audio DMA ========= @@ -64,16 +64,3 @@ Each SoC DAI driver must provide the following features:- 5) Suspend and resume (optional) Please see codec.txt for a description of items 1 - 4. - - -SoC DSP Drivers -=============== - -Each SoC DSP driver usually supplies the following features :- - - 1) DAPM graph - 2) Mixer controls - 3) DMA IO to/from DSP buffers (if applicable) - 4) Definition of DSP front end (FE) PCM devices. - -Please see DPCM.txt for a description of item 4. diff --git a/Documentation/sound/alsa/timestamping.txt b/Documentation/sound/alsa/timestamping.txt deleted file mode 100644 index 9d579aefbffd..000000000000 --- a/Documentation/sound/alsa/timestamping.txt +++ /dev/null @@ -1,200 +0,0 @@ -The ALSA API can provide two different system timestamps: - -- Trigger_tstamp is the system time snapshot taken when the .trigger -callback is invoked. This snapshot is taken by the ALSA core in the -general case, but specific hardware may have synchronization -capabilities or conversely may only be able to provide a correct -estimate with a delay. In the latter two cases, the low-level driver -is responsible for updating the trigger_tstamp at the most appropriate -and precise moment. Applications should not rely solely on the first -trigger_tstamp but update their internal calculations if the driver -provides a refined estimate with a delay. - -- tstamp is the current system timestamp updated during the last -event or application query. -The difference (tstamp - trigger_tstamp) defines the elapsed time. - -The ALSA API provides two basic pieces of information, avail -and delay, which combined with the trigger and current system -timestamps allow for applications to keep track of the 'fullness' of -the ring buffer and the amount of queued samples. - -The use of these different pointers and time information depends on -the application needs: - -- 'avail' reports how much can be written in the ring buffer -- 'delay' reports the time it will take to hear a new sample after all -queued samples have been played out. - -When timestamps are enabled, the avail/delay information is reported -along with a snapshot of system time. Applications can select from -CLOCK_REALTIME (NTP corrections including going backwards), -CLOCK_MONOTONIC (NTP corrections but never going backwards), -CLOCK_MONOTIC_RAW (without NTP corrections) and change the mode -dynamically with sw_params - - -The ALSA API also provide an audio_tstamp which reflects the passage -of time as measured by different components of audio hardware. In -ascii-art, this could be represented as follows (for the playback -case): - - ---------------------------------------------------------------> time - ^ ^ ^ ^ ^ - | | | | | - analog link dma app FullBuffer - time time time time time - | | | | | - |< codec delay >|<--hw delay-->|<queued samples>|<---avail->| - |<----------------- delay---------------------->| | - |<----ring buffer length---->| - -The analog time is taken at the last stage of the playback, as close -as possible to the actual transducer - -The link time is taken at the output of the SoC/chipset as the samples -are pushed on a link. The link time can be directly measured if -supported in hardware by sample counters or wallclocks (e.g. with -HDAudio 24MHz or PTP clock for networked solutions) or indirectly -estimated (e.g. with the frame counter in USB). - -The DMA time is measured using counters - typically the least reliable -of all measurements due to the bursty nature of DMA transfers. - -The app time corresponds to the time tracked by an application after -writing in the ring buffer. - -The application can query the hardware capabilities, define which -audio time it wants reported by selecting the relevant settings in -audio_tstamp_config fields, thus get an estimate of the timestamp -accuracy. It can also request the delay-to-analog be included in the -measurement. Direct access to the link time is very interesting on -platforms that provide an embedded DSP; measuring directly the link -time with dedicated hardware, possibly synchronized with system time, -removes the need to keep track of internal DSP processing times and -latency. - -In case the application requests an audio tstamp that is not supported -in hardware/low-level driver, the type is overridden as DEFAULT and the -timestamp will report the DMA time based on the hw_pointer value. - -For backwards compatibility with previous implementations that did not -provide timestamp selection, with a zero-valued COMPAT timestamp type -the results will default to the HDAudio wall clock for playback -streams and to the DMA time (hw_ptr) in all other cases. - -The audio timestamp accuracy can be returned to user-space, so that -appropriate decisions are made: - -- for dma time (default), the granularity of the transfers can be - inferred from the steps between updates and in turn provide - information on how much the application pointer can be rewound - safely. - -- the link time can be used to track long-term drifts between audio - and system time using the (tstamp-trigger_tstamp)/audio_tstamp - ratio, the precision helps define how much smoothing/low-pass - filtering is required. The link time can be either reset on startup - or reported as is (the latter being useful to compare progress of - different streams - but may require the wallclock to be always - running and not wrap-around during idle periods). If supported in - hardware, the absolute link time could also be used to define a - precise start time (patches WIP) - -- including the delay in the audio timestamp may - counter-intuitively not increase the precision of timestamps, e.g. if a - codec includes variable-latency DSP processing or a chain of - hardware components the delay is typically not known with precision. - -The accuracy is reported in nanosecond units (using an unsigned 32-bit -word), which gives a max precision of 4.29s, more than enough for -audio applications... - -Due to the varied nature of timestamping needs, even for a single -application, the audio_tstamp_config can be changed dynamically. In -the STATUS ioctl, the parameters are read-only and do not allow for -any application selection. To work around this limitation without -impacting legacy applications, a new STATUS_EXT ioctl is introduced -with read/write parameters. ALSA-lib will be modified to make use of -STATUS_EXT and effectively deprecate STATUS. - -The ALSA API only allows for a single audio timestamp to be reported -at a time. This is a conscious design decision, reading the audio -timestamps from hardware registers or from IPC takes time, the more -timestamps are read the more imprecise the combined measurements -are. To avoid any interpretation issues, a single (system, audio) -timestamp is reported. Applications that need different timestamps -will be required to issue multiple queries and perform an -interpolation of the results - -In some hardware-specific configuration, the system timestamp is -latched by a low-level audio subsystem, and the information provided -back to the driver. Due to potential delays in the communication with -the hardware, there is a risk of misalignment with the avail and delay -information. To make sure applications are not confused, a -driver_timestamp field is added in the snd_pcm_status structure; this -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: - -1. DMA timestamp, no compensation for DMA+analog delay -$ ./audio_time -p --ts_type=1 -playback: systime: 341121338 nsec, audio time 342000000 nsec, systime delta -878662 -playback: systime: 426236663 nsec, audio time 427187500 nsec, systime delta -950837 -playback: systime: 597080580 nsec, audio time 598000000 nsec, systime delta -919420 -playback: systime: 682059782 nsec, audio time 683020833 nsec, systime delta -961051 -playback: systime: 852896415 nsec, audio time 853854166 nsec, systime delta -957751 -playback: systime: 937903344 nsec, audio time 938854166 nsec, systime delta -950822 - -2. DMA timestamp, compensation for DMA+analog delay -$ ./audio_time -p --ts_type=1 -d -playback: systime: 341053347 nsec, audio time 341062500 nsec, systime delta -9153 -playback: systime: 426072447 nsec, audio time 426062500 nsec, systime delta 9947 -playback: systime: 596899518 nsec, audio time 596895833 nsec, systime delta 3685 -playback: systime: 681915317 nsec, audio time 681916666 nsec, systime delta -1349 -playback: systime: 852741306 nsec, audio time 852750000 nsec, systime delta -8694 - -3. link timestamp, compensation for DMA+analog delay -$ ./audio_time -p --ts_type=2 -d -playback: systime: 341060004 nsec, audio time 341062791 nsec, systime delta -2787 -playback: systime: 426242074 nsec, audio time 426244875 nsec, systime delta -2801 -playback: systime: 597080992 nsec, audio time 597084583 nsec, systime delta -3591 -playback: systime: 682084512 nsec, audio time 682088291 nsec, systime delta -3779 -playback: systime: 852936229 nsec, audio time 852940916 nsec, systime delta -4687 -playback: systime: 938107562 nsec, audio time 938112708 nsec, systime delta -5146 - -Example 1 shows that the timestamp at the DMA level is close to 1ms -ahead of the actual playback time (as a side time this sort of -measurement can help define rewind safeguards). Compensating for the -DMA-link delay in example 2 helps remove the hardware buffering but -the information is still very jittery, with up to one sample of -error. In example 3 where the timestamps are measured with the link -wallclock, the timestamps show a monotonic behavior and a lower -dispersion. - -Example 3 and 4 are with USB audio class. Example 3 shows a high -offset between audio time and system time due to buffering. Example 4 -shows how compensating for the delay exposes a 1ms accuracy (due to -the use of the frame counter by the driver) - -Example 3: DMA timestamp, no compensation for delay, delta of ~5ms -$ ./audio_time -p -Dhw:1 -t1 -playback: systime: 120174019 nsec, audio time 125000000 nsec, systime delta -4825981 -playback: systime: 245041136 nsec, audio time 250000000 nsec, systime delta -4958864 -playback: systime: 370106088 nsec, audio time 375000000 nsec, systime delta -4893912 -playback: systime: 495040065 nsec, audio time 500000000 nsec, systime delta -4959935 -playback: systime: 620038179 nsec, audio time 625000000 nsec, systime delta -4961821 -playback: systime: 745087741 nsec, audio time 750000000 nsec, systime delta -4912259 -playback: systime: 870037336 nsec, audio time 875000000 nsec, systime delta -4962664 - -Example 4: DMA timestamp, compensation for delay, delay of ~1ms -$ ./audio_time -p -Dhw:1 -t1 -d -playback: systime: 120190520 nsec, audio time 120000000 nsec, systime delta 190520 -playback: systime: 245036740 nsec, audio time 244000000 nsec, systime delta 1036740 -playback: systime: 370034081 nsec, audio time 369000000 nsec, systime delta 1034081 -playback: systime: 495159907 nsec, audio time 494000000 nsec, systime delta 1159907 -playback: systime: 620098824 nsec, audio time 619000000 nsec, systime delta 1098824 -playback: systime: 745031847 nsec, audio time 744000000 nsec, systime delta 1031847 |