[ALSA] ASoC documentation updates
This patch updates the documentation for ASoC to reflect the recent
changes in API between 0.12.x and 0.13.x
Changes:-
o Removed all reference to old API's.
o Removed references and examples of automatic DAI config and matching.
o Fixed 80 char line length on some files.
Signed-off-by: Liam Girdwood <lg@opensource.wolfsonmicro.com>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
Signed-off-by: Jaroslav Kysela <perex@suse.cz>
diff --git a/Documentation/sound/alsa/soc/codec.txt b/Documentation/sound/alsa/soc/codec.txt
index 274657a..48983c7 100644
--- a/Documentation/sound/alsa/soc/codec.txt
+++ b/Documentation/sound/alsa/soc/codec.txt
@@ -6,21 +6,18 @@
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 driver must provide the following features:-
+Each codec driver *must* provide the following features:-
- 1) Digital audio interface (DAI) description
- 2) Digital audio interface configuration
- 3) PCM's description
- 4) Codec control IO - using I2C, 3 Wire(SPI) or both API's
- 5) Mixers and audio controls
- 6) Sysclk configuration
- 7) Codec audio operations
+ 1) Codec DAI and PCM configuration
+ 2) Codec control IO - using I2C, 3 Wire(SPI) or both API's
+ 3) Mixers and audio controls
+ 4) Codec audio operations
Optionally, codec drivers can also provide:-
- 8) DAPM description.
- 9) DAPM event handler.
-10) DAC Digital mute control.
+ 5) DAPM description.
+ 6) DAPM event handler.
+ 7) DAC Digital mute control.
It's probably best to use this guide in conjuction with the existing codec
driver code in sound/soc/codecs/
@@ -28,58 +25,47 @@
ASoC Codec driver breakdown
===========================
-1 - Digital Audio Interface (DAI) description
----------------------------------------------
-The DAI is a digital audio data transfer link between the codec and host SoC
-CPU. It typically has data transfer capabilities in both directions
-(playback and capture) and can run at a variety of different speeds.
-Supported interfaces currently include AC97, I2S and generic PCM style links.
-Please read DAI.txt for implementation information.
-
-
-2 - Digital Audio Interface (DAI) configuration
------------------------------------------------
-DAI configuration is handled by the codec_pcm_prepare function and is
-responsible for configuring and starting the DAI on the codec. This can be
-called multiple times and is atomic. It can access the runtime parameters.
-
-This usually consists of a large function with numerous switch statements to
-set up each configuration option. These options are set by the core at runtime.
-
-
-3 - Codec PCM's
----------------
-Each codec must have it's PCM's defined. This defines the number of channels,
-stream names, callbacks and codec name. It is also used to register the DAI
-with the ASoC core. The PCM structure also associates the DAI capabilities with
-the ALSA PCM.
+1 - Codec DAI and PCM configuration
+-----------------------------------
+Each codec driver must have a struct snd_soc_codec_dai to define it's DAI and
+PCM's capablities and operations. This struct is exported so that it can be
+registered with the core by your machine driver.
e.g.
-static struct snd_soc_pcm_codec wm8731_pcm_client = {
+struct snd_soc_codec_dai wm8731_dai = {
.name = "WM8731",
+ /* playback capabilities */
.playback = {
.stream_name = "Playback",
.channels_min = 1,
.channels_max = 2,
- },
+ .rates = WM8731_RATES,
+ .formats = WM8731_FORMATS,},
+ /* capture capabilities */
.capture = {
.stream_name = "Capture",
.channels_min = 1,
.channels_max = 2,
- },
- .config_sysclk = wm8731_config_sysclk,
+ .rates = WM8731_RATES,
+ .formats = WM8731_FORMATS,},
+ /* pcm operations - see section 4 below */
.ops = {
.prepare = wm8731_pcm_prepare,
+ .hw_params = wm8731_hw_params,
+ .shutdown = wm8731_shutdown,
},
- .caps = {
- .num_modes = ARRAY_SIZE(wm8731_hwfmt),
- .modes = &wm8731_hwfmt[0],
- },
+ /* DAI operations - see DAI.txt */
+ .dai_ops = {
+ .digital_mute = wm8731_mute,
+ .set_sysclk = wm8731_set_dai_sysclk,
+ .set_fmt = wm8731_set_dai_fmt,
+ }
};
+EXPORT_SYMBOL_GPL(wm8731_dai);
-4 - Codec control IO
+2 - Codec control IO
--------------------
The codec can ususally be controlled via an I2C or SPI style interface (AC97
combines control with data in the DAI). The codec drivers will have to provide
@@ -104,7 +90,7 @@
hw_read_t hw_read;
-5 - Mixers and audio controls
+3 - Mixers and audio controls
-----------------------------
All the codec mixers and audio controls can be defined using the convenience
macros defined in soc.h.
@@ -143,28 +129,7 @@
Defines a stereo enumerated control
-6 - System clock configuration.
--------------------------------
-The system clock that drives the audio subsystem can change depending on sample
-rate and the system power state. i.e.
-
-o Higher sample rates sometimes need a higher system clock.
-o Low system power states can sometimes limit the available clocks.
-
-This function is a callback that the machine driver can call to set and
-determine if the clock and sample rate combination is supported by the codec at
-the present time (and system state).
-
-NOTE: If the codec has a PLL then it has a lot more flexability wrt clock and
-sample rate combinations.
-
-Your config_sysclock function should return the MCLK if it's a valid
-combination for your codec else 0;
-
-Please read clocking.txt now.
-
-
-7 - Codec Audio Operations
+4 - Codec Audio Operations
--------------------------
The codec driver also supports the following alsa operations:-
@@ -181,7 +146,7 @@
http://www.alsa-project.org/~iwai/writing-an-alsa-driver/c436.htm
-8 - DAPM description.
+5 - DAPM description.
---------------------
The Dynamic Audio Power Management description describes the codec's power
components, their relationships and registers to the ASoC core. Please read
@@ -190,7 +155,7 @@
Please also see the examples in other codec drivers.
-9 - DAPM event handler
+6 - DAPM event handler
----------------------
This function is a callback that handles codec domain PM calls and system
domain PM calls (e.g. suspend and resume). It's used to put the codec to sleep
@@ -210,7 +175,7 @@
SNDRV_CTL_POWER_D3cold: /* Everything Off, without power */
-10 - Codec DAC digital mute control.
+7 - Codec DAC digital mute control.
------------------------------------
Most codecs have a digital mute before the DAC's that can be used to minimise
any system noise. The mute stops any digital data from entering the DAC.