[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>

1 files changed, 36 insertions, 71 deletions

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 @@ 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 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 @@ driver code in sound/soc/codecs/
 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 @@ read/write:-
 	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 an single enumerated control as follows:-
 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 @@ Please refer to the alsa driver PCM documentation for details.
 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 @@ dapm.txt for details of building the description.
 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 @@ Power states:-
 	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.