aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2012-01-12 11:00:30 -0500
committerLinus Torvalds <torvalds@linux-foundation.org>2012-01-12 11:00:30 -0500
commita429638cac1e5c656818a45aaff78df7b743004e (patch)
tree0465e0d7a431bff97a3dd5a1f91d9b30c69ae0d8 /Documentation
parent5cf9a4e69c1ff0ccdd1d2b7404f95c0531355274 (diff)
parent9e4ce164ee3a1d07580f017069c25d180b0aa785 (diff)
Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/sound
* 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/sound: (526 commits) ASoC: twl6040 - Add method to query optimum PDM_DL1 gain ALSA: hda - Fix the lost power-setup of seconary pins after PM resume ALSA: usb-audio: add Yamaha MOX6/MOX8 support ALSA: virtuoso: add S/PDIF input support for all Xonars ALSA: ice1724 - Support for ooAoo SQ210a ALSA: ice1724 - Allow card info based on model only ALSA: ice1724 - Create capture pcm only for ADC-enabled configurations ALSA: hdspm - Provide unique driver id based on card serial ASoC: Dynamically allocate the rtd device for a non-empty release() ASoC: Fix recursive dependency due to select ATMEL_SSC in SND_ATMEL_SOC_SSC ALSA: hda - Fix the detection of "Loopback Mixing" control for VIA codecs ALSA: hda - Return the error from get_wcaps_type() for invalid NIDs ALSA: hda - Use auto-parser for HP laptops with cx20459 codec ALSA: asihpi - Fix potential Oops in snd_asihpi_cmode_info() ALSA: hdsp - Fix potential Oops in snd_hdsp_info_pref_sync_ref() ALSA: hda/cirrus - support for iMac12,2 model ASoC: cx20442: add bias control over a platform provided regulator ALSA: usb-audio - Avoid flood of frame-active debug messages ALSA: snd-usb-us122l: Delete calls to preempt_disable mfd: Put WM8994 into cache only mode when suspending ... Fix up trivial conflicts in: - arch/arm/mach-s3c64xx/mach-crag6410.c: renamed speyside_wm8962 to tobermory, added littlemill right next to it - drivers/base/regmap/{regcache.c,regmap.c}: duplicate diff that had already come in with other changes in the regmap tree
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/DocBook/writing-an-alsa-driver.tmpl2
-rw-r--r--Documentation/devicetree/bindings/sound/tegra-audio-wm8903.txt71
-rw-r--r--Documentation/devicetree/bindings/sound/tegra20-das.txt12
-rw-r--r--Documentation/devicetree/bindings/sound/tegra20-i2s.txt17
-rw-r--r--Documentation/devicetree/bindings/sound/wm8903.txt50
-rw-r--r--Documentation/devicetree/bindings/sound/wm8994.txt18
-rw-r--r--Documentation/devicetree/bindings/vendor-prefixes.txt1
-rw-r--r--Documentation/sound/alsa/HD-Audio-Models.txt15
-rw-r--r--Documentation/sound/alsa/compress_offload.txt188
9 files changed, 359 insertions, 15 deletions
diff --git a/Documentation/DocBook/writing-an-alsa-driver.tmpl b/Documentation/DocBook/writing-an-alsa-driver.tmpl
index 5de23c007078..cab4ec58e46e 100644
--- a/Documentation/DocBook/writing-an-alsa-driver.tmpl
+++ b/Documentation/DocBook/writing-an-alsa-driver.tmpl
@@ -404,7 +404,7 @@
404 /* SNDRV_CARDS: maximum number of cards supported by this module */ 404 /* SNDRV_CARDS: maximum number of cards supported by this module */
405 static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX; 405 static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
406 static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR; 406 static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
407 static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP; 407 static bool enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
408 408
409 /* definition of the chip-specific record */ 409 /* definition of the chip-specific record */
410 struct mychip { 410 struct mychip {
diff --git a/Documentation/devicetree/bindings/sound/tegra-audio-wm8903.txt b/Documentation/devicetree/bindings/sound/tegra-audio-wm8903.txt
new file mode 100644
index 000000000000..d5b0da8bf1d8
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/tegra-audio-wm8903.txt
@@ -0,0 +1,71 @@
1NVIDIA Tegra audio complex
2
3Required properties:
4- compatible : "nvidia,tegra-audio-wm8903"
5- nvidia,model : The user-visible name of this sound complex.
6- nvidia,audio-routing : A list of the connections between audio components.
7 Each entry is a pair of strings, the first being the connection's sink,
8 the second being the connection's source. Valid names for sources and
9 sinks are the WM8903's pins, and the jacks on the board:
10
11 WM8903 pins:
12
13 * IN1L
14 * IN1R
15 * IN2L
16 * IN2R
17 * IN3L
18 * IN3R
19 * DMICDAT
20 * HPOUTL
21 * HPOUTR
22 * LINEOUTL
23 * LINEOUTR
24 * LOP
25 * LON
26 * ROP
27 * RON
28 * MICBIAS
29
30 Board connectors:
31
32 * Headphone Jack
33 * Int Spk
34 * Mic Jack
35
36- nvidia,i2s-controller : The phandle of the Tegra I2S1 controller
37- nvidia,audio-codec : The phandle of the WM8903 audio codec
38
39Optional properties:
40- nvidia,spkr-en-gpios : The GPIO that enables the speakers
41- nvidia,hp-mute-gpios : The GPIO that mutes the headphones
42- nvidia,hp-det-gpios : The GPIO that detect headphones are plugged in
43- nvidia,int-mic-en-gpios : The GPIO that enables the internal microphone
44- nvidia,ext-mic-en-gpios : The GPIO that enables the external microphone
45
46Example:
47
48sound {
49 compatible = "nvidia,tegra-audio-wm8903-harmony",
50 "nvidia,tegra-audio-wm8903"
51 nvidia,model = "tegra-wm8903-harmony";
52
53 nvidia,audio-routing =
54 "Headphone Jack", "HPOUTR",
55 "Headphone Jack", "HPOUTL",
56 "Int Spk", "ROP",
57 "Int Spk", "RON",
58 "Int Spk", "LOP",
59 "Int Spk", "LON",
60 "Mic Jack", "MICBIAS",
61 "IN1L", "Mic Jack";
62
63 nvidia,i2s-controller = <&i2s1>;
64 nvidia,audio-codec = <&wm8903>;
65
66 nvidia,spkr-en-gpios = <&codec 2 0>;
67 nvidia,hp-det-gpios = <&gpio 178 0>; /* gpio PW2 */
68 nvidia,int-mic-en-gpios = <&gpio 184 0>; /*gpio PX0 */
69 nvidia,ext-mic-en-gpios = <&gpio 185 0>; /* gpio PX1 */
70};
71
diff --git a/Documentation/devicetree/bindings/sound/tegra20-das.txt b/Documentation/devicetree/bindings/sound/tegra20-das.txt
new file mode 100644
index 000000000000..6de3a7ee4efb
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/tegra20-das.txt
@@ -0,0 +1,12 @@
1NVIDIA Tegra 20 DAS (Digital Audio Switch) controller
2
3Required properties:
4- compatible : "nvidia,tegra20-das"
5- reg : Should contain DAS registers location and length
6
7Example:
8
9das@70000c00 {
10 compatible = "nvidia,tegra20-das";
11 reg = <0x70000c00 0x80>;
12};
diff --git a/Documentation/devicetree/bindings/sound/tegra20-i2s.txt b/Documentation/devicetree/bindings/sound/tegra20-i2s.txt
new file mode 100644
index 000000000000..0df2b5c816e3
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/tegra20-i2s.txt
@@ -0,0 +1,17 @@
1NVIDIA Tegra 20 I2S controller
2
3Required properties:
4- compatible : "nvidia,tegra20-i2s"
5- reg : Should contain I2S registers location and length
6- interrupts : Should contain I2S interrupt
7- nvidia,dma-request-selector : The Tegra DMA controller's phandle and
8 request selector for this I2S controller
9
10Example:
11
12i2s@70002800 {
13 compatible = "nvidia,tegra20-i2s";
14 reg = <0x70002800 0x200>;
15 interrupts = < 45 >;
16 nvidia,dma-request-selector = < &apbdma 2 >;
17};
diff --git a/Documentation/devicetree/bindings/sound/wm8903.txt b/Documentation/devicetree/bindings/sound/wm8903.txt
new file mode 100644
index 000000000000..f102cbc42694
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/wm8903.txt
@@ -0,0 +1,50 @@
1WM8903 audio CODEC
2
3This device supports I2C only.
4
5Required properties:
6
7 - compatible : "wlf,wm8903"
8
9 - reg : the I2C address of the device.
10
11 - gpio-controller : Indicates this device is a GPIO controller.
12
13 - #gpio-cells : Should be two. The first cell is the pin number and the
14 second cell is used to specify optional parameters (currently unused).
15
16Optional properties:
17
18 - interrupts : The interrupt line the codec is connected to.
19
20 - micdet-cfg : Default register value for R6 (Mic Bias). If absent, the
21 default is 0.
22
23 - micdet-delay : The debounce delay for microphone detection in mS. If
24 absent, the default is 100.
25
26 - gpio-cfg : A list of GPIO configuration register values. The list must
27 be 5 entries long. If absent, no configuration of these registers is
28 performed. If any entry has the value 0xffffffff, that GPIO's
29 configuration will not be modified.
30
31Example:
32
33codec: wm8903@1a {
34 compatible = "wlf,wm8903";
35 reg = <0x1a>;
36 interrupts = < 347 >;
37
38 gpio-controller;
39 #gpio-cells = <2>;
40
41 micdet-cfg = <0>;
42 micdet-delay = <100>;
43 gpio-cfg = <
44 0x0600 /* DMIC_LR, output */
45 0x0680 /* DMIC_DAT, input */
46 0x0000 /* GPIO, output, low */
47 0x0200 /* Interrupt, output */
48 0x01a0 /* BCLK, input, active high */
49 >;
50};
diff --git a/Documentation/devicetree/bindings/sound/wm8994.txt b/Documentation/devicetree/bindings/sound/wm8994.txt
new file mode 100644
index 000000000000..7a7eb1e7bda6
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/wm8994.txt
@@ -0,0 +1,18 @@
1WM1811/WM8994/WM8958 audio CODEC
2
3These devices support both I2C and SPI (configured with pin strapping
4on the board).
5
6Required properties:
7
8 - compatible : "wlf,wm1811", "wlf,wm8994", "wlf,wm8958"
9
10 - reg : the I2C address of the device for I2C, the chip select
11 number for SPI.
12
13Example:
14
15codec: wm8994@1a {
16 compatible = "wlf,wm8994";
17 reg = <0x1a>;
18};
diff --git a/Documentation/devicetree/bindings/vendor-prefixes.txt b/Documentation/devicetree/bindings/vendor-prefixes.txt
index 6fdb450b05fb..ecc6a6cd26c1 100644
--- a/Documentation/devicetree/bindings/vendor-prefixes.txt
+++ b/Documentation/devicetree/bindings/vendor-prefixes.txt
@@ -42,4 +42,5 @@ sirf SiRF Technology, Inc.
42st STMicroelectronics 42st STMicroelectronics
43stericsson ST-Ericsson 43stericsson ST-Ericsson
44ti Texas Instruments 44ti Texas Instruments
45wlf Wolfson Microelectronics
45xlnx Xilinx 46xlnx Xilinx
diff --git a/Documentation/sound/alsa/HD-Audio-Models.txt b/Documentation/sound/alsa/HD-Audio-Models.txt
index edad99abec21..c8c54544abc5 100644
--- a/Documentation/sound/alsa/HD-Audio-Models.txt
+++ b/Documentation/sound/alsa/HD-Audio-Models.txt
@@ -42,19 +42,7 @@ ALC260
42 42
43ALC262 43ALC262
44====== 44======
45 fujitsu Fujitsu Laptop 45 N/A
46 benq Benq ED8
47 benq-t31 Benq T31
48 hippo Hippo (ATI) with jack detection, Sony UX-90s
49 hippo_1 Hippo (Benq) with jack detection
50 toshiba-s06 Toshiba S06
51 toshiba-rx1 Toshiba RX1
52 tyan Tyan Thunder n6650W (S2915-E)
53 ultra Samsung Q1 Ultra Vista model
54 lenovo-3000 Lenovo 3000 y410
55 nec NEC Versa S9100
56 basic fixed pin assignment w/o SPDIF
57 auto auto-config reading BIOS (default)
58 46
59ALC267/268 47ALC267/268
60========== 48==========
@@ -350,7 +338,6 @@ STAC92HD83*
350 mic-ref Reference board with power management for ports 338 mic-ref Reference board with power management for ports
351 dell-s14 Dell laptop 339 dell-s14 Dell laptop
352 dell-vostro-3500 Dell Vostro 3500 laptop 340 dell-vostro-3500 Dell Vostro 3500 laptop
353 hp HP laptops with (inverted) mute-LED
354 hp-dv7-4000 HP dv-7 4000 341 hp-dv7-4000 HP dv-7 4000
355 auto BIOS setup (default) 342 auto BIOS setup (default)
356 343
diff --git a/Documentation/sound/alsa/compress_offload.txt b/Documentation/sound/alsa/compress_offload.txt
new file mode 100644
index 000000000000..c83a835350f0
--- /dev/null
+++ b/Documentation/sound/alsa/compress_offload.txt
@@ -0,0 +1,188 @@
1 compress_offload.txt
2 =====================
3 Pierre-Louis.Bossart <pierre-louis.bossart@linux.intel.com>
4 Vinod Koul <vinod.koul@linux.intel.com>
5
6Overview
7
8Since its early days, the ALSA API was defined with PCM support or
9constant bitrates payloads such as IEC61937 in mind. Arguments and
10returned values in frames are the norm, making it a challenge to
11extend the existing API to compressed data streams.
12
13In recent years, audio digital signal processors (DSP) were integrated
14in system-on-chip designs, and DSPs are also integrated in audio
15codecs. Processing compressed data on such DSPs results in a dramatic
16reduction of power consumption compared to host-based
17processing. Support for such hardware has not been very good in Linux,
18mostly because of a lack of a generic API available in the mainline
19kernel.
20
21Rather than requiring a compability break with an API change of the
22ALSA PCM interface, a new 'Compressed Data' API is introduced to
23provide a control and data-streaming interface for audio DSPs.
24
25The design of this API was inspired by the 2-year experience with the
26Intel Moorestown SOC, with many corrections required to upstream the
27API in the mainline kernel instead of the staging tree and make it
28usable by others.
29
30Requirements
31
32The main requirements are:
33
34- separation between byte counts and time. Compressed formats may have
35 a header per file, per frame, or no header at all. The payload size
36 may vary from frame-to-frame. As a result, it is not possible to
37 estimate reliably the duration of audio buffers when handling
38 compressed data. Dedicated mechanisms are required to allow for
39 reliable audio-video synchronization, which requires precise
40 reporting of the number of samples rendered at any given time.
41
42- Handling of multiple formats. PCM data only requires a specification
43 of the sampling rate, number of channels and bits per sample. In
44 contrast, compressed data comes in a variety of formats. Audio DSPs
45 may also provide support for a limited number of audio encoders and
46 decoders embedded in firmware, or may support more choices through
47 dynamic download of libraries.
48
49- Focus on main formats. This API provides support for the most
50 popular formats used for audio and video capture and playback. It is
51 likely that as audio compression technology advances, new formats
52 will be added.
53
54- Handling of multiple configurations. Even for a given format like
55 AAC, some implementations may support AAC multichannel but HE-AAC
56 stereo. Likewise WMA10 level M3 may require too much memory and cpu
57 cycles. The new API needs to provide a generic way of listing these
58 formats.
59
60- Rendering/Grabbing only. This API does not provide any means of
61 hardware acceleration, where PCM samples are provided back to
62 user-space for additional processing. This API focuses instead on
63 streaming compressed data to a DSP, with the assumption that the
64 decoded samples are routed to a physical output or logical back-end.
65
66 - Complexity hiding. Existing user-space multimedia frameworks all
67 have existing enums/structures for each compressed format. This new
68 API assumes the existence of a platform-specific compatibility layer
69 to expose, translate and make use of the capabilities of the audio
70 DSP, eg. Android HAL or PulseAudio sinks. By construction, regular
71 applications are not supposed to make use of this API.
72
73
74Design
75
76The new API shares a number of concepts with with the PCM API for flow
77control. Start, pause, resume, drain and stop commands have the same
78semantics no matter what the content is.
79
80The concept of memory ring buffer divided in a set of fragments is
81borrowed from the ALSA PCM API. However, only sizes in bytes can be
82specified.
83
84Seeks/trick modes are assumed to be handled by the host.
85
86The notion of rewinds/forwards is not supported. Data committed to the
87ring buffer cannot be invalidated, except when dropping all buffers.
88
89The Compressed Data API does not make any assumptions on how the data
90is transmitted to the audio DSP. DMA transfers from main memory to an
91embedded audio cluster or to a SPI interface for external DSPs are
92possible. As in the ALSA PCM case, a core set of routines is exposed;
93each driver implementer will have to write support for a set of
94mandatory routines and possibly make use of optional ones.
95
96The main additions are
97
98- get_caps
99This routine returns the list of audio formats supported. Querying the
100codecs on a capture stream will return encoders, decoders will be
101listed for playback streams.
102
103- get_codec_caps For each codec, this routine returns a list of
104capabilities. The intent is to make sure all the capabilities
105correspond to valid settings, and to minimize the risks of
106configuration failures. For example, for a complex codec such as AAC,
107the number of channels supported may depend on a specific profile. If
108the capabilities were exposed with a single descriptor, it may happen
109that a specific combination of profiles/channels/formats may not be
110supported. Likewise, embedded DSPs have limited memory and cpu cycles,
111it is likely that some implementations make the list of capabilities
112dynamic and dependent on existing workloads. In addition to codec
113settings, this routine returns the minimum buffer size handled by the
114implementation. This information can be a function of the DMA buffer
115sizes, the number of bytes required to synchronize, etc, and can be
116used by userspace to define how much needs to be written in the ring
117buffer before playback can start.
118
119- set_params
120This routine sets the configuration chosen for a specific codec. The
121most important field in the parameters is the codec type; in most
122cases decoders will ignore other fields, while encoders will strictly
123comply to the settings
124
125- get_params
126This routines returns the actual settings used by the DSP. Changes to
127the settings should remain the exception.
128
129- get_timestamp
130The timestamp becomes a multiple field structure. It lists the number
131of bytes transferred, the number of samples processed and the number
132of samples rendered/grabbed. All these values can be used to determine
133the avarage bitrate, figure out if the ring buffer needs to be
134refilled or the delay due to decoding/encoding/io on the DSP.
135
136Note that the list of codecs/profiles/modes was derived from the
137OpenMAX AL specification instead of reinventing the wheel.
138Modifications include:
139- Addition of FLAC and IEC formats
140- Merge of encoder/decoder capabilities
141- Profiles/modes listed as bitmasks to make descriptors more compact
142- Addition of set_params for decoders (missing in OpenMAX AL)
143- Addition of AMR/AMR-WB encoding modes (missing in OpenMAX AL)
144- Addition of format information for WMA
145- Addition of encoding options when required (derived from OpenMAX IL)
146- Addition of rateControlSupported (missing in OpenMAX AL)
147
148Not supported:
149
150- Support for VoIP/circuit-switched calls is not the target of this
151 API. Support for dynamic bit-rate changes would require a tight
152 coupling between the DSP and the host stack, limiting power savings.
153
154- Packet-loss concealment is not supported. This would require an
155 additional interface to let the decoder synthesize data when frames
156 are lost during transmission. This may be added in the future.
157
158- Volume control/routing is not handled by this API. Devices exposing a
159 compressed data interface will be considered as regular ALSA devices;
160 volume changes and routing information will be provided with regular
161 ALSA kcontrols.
162
163- Embedded audio effects. Such effects should be enabled in the same
164 manner, no matter if the input was PCM or compressed.
165
166- multichannel IEC encoding. Unclear if this is required.
167
168- Encoding/decoding acceleration is not supported as mentioned
169 above. It is possible to route the output of a decoder to a capture
170 stream, or even implement transcoding capabilities. This routing
171 would be enabled with ALSA kcontrols.
172
173- Audio policy/resource management. This API does not provide any
174 hooks to query the utilization of the audio DSP, nor any premption
175 mechanisms.
176
177- No notion of underun/overrun. Since the bytes written are compressed
178 in nature and data written/read doesn't translate directly to
179 rendered output in time, this does not deal with underrun/overun and
180 maybe dealt in user-library
181
182Credits:
183- Mark Brown and Liam Girdwood for discussions on the need for this API
184- Harsha Priya for her work on intel_sst compressed API
185- Rakesh Ughreja for valuable feedback
186- Sing Nallasellan, Sikkandar Madar and Prasanna Samaga for
187 demonstrating and quantifying the benefits of audio offload on a
188 real platform.