[ALSA] ASoC: documentation & maintainer

This patch adds documentation describing the ASoC architecture and a
maintainer entry for ASoC.
The documentation includes the following files:-
codec.txt: Codec driver internals.
DAI.txt: Description of Digital Audio Interface standards and how to
configure a DAI within your codec and CPU DAI drivers.
dapm.txt: Dynamic Audio Power Management.
platform.txt: Platform audio DMA and DAI.
machine.txt: Machine driver internals.
pop_clicks.txt: How to minimise audio artifacts.
clocking.txt: ASoC clocking for best power performance.

Signed-off-by: Liam Girdwood <liam.girdwood@wolfsonmicro.com>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
Signed-off-by: Jaroslav Kysela <perex@suse.cz>

8 files changed, 1525 insertions, 0 deletions

diff --git a/Documentation/sound/alsa/soc/DAI.txt b/Documentation/sound/alsa/soc/DAI.txt
new file mode 100644
index 00000000000..919de76bab8
--- /dev/null
+++ b/Documentation/sound/alsa/soc/DAI.txt
@@ -0,0 +1,380 @@
+ASoC currently supports the three main Digital Audio Interfaces (DAI) found on
+SoC controllers and portable audio CODECS today, namely AC97, I2S and PCM.
+
+
+AC97
+====
+
+  AC97 is a five wire interface commonly found on many PC sound cards. It is
+now also popular in many portable devices. This DAI has a reset line and time
+multiplexes its data on its SDATA_OUT (playback) and SDATA_IN (capture) lines.
+The bit clock (BCLK) is always driven by the CODEC (usually 12.288MHz) and the
+frame (FRAME) (usually 48kHz) is always driven by the controller. Each AC97
+frame is 21uS long and is divided into 13 time slots.
+
+The AC97 specification can be found at http://intel.com/
+
+
+I2S
+===
+
+ I2S is a common 4 wire DAI used in HiFi, STB and portable devices. The Tx and
+Rx lines are used for audio transmision, whilst the bit clock (BCLK) and
+left/right clock (LRC) synchronise the link. I2S is flexible in that either the
+controller or CODEC can drive (master) the BCLK and LRC clock lines. Bit clock
+usually varies depending on the sample rate and the master system clock
+(SYSCLK). LRCLK is the same as the sample rate. A few devices support separate
+ADC and DAC LRCLK's, this allows for similtanious capture and playback at
+different sample rates.
+
+I2S has several different operating modes:-
+
+ o I2S - MSB is transmitted on the falling edge of the first BCLK after LRC
+         transition.
+
+ o Left Justified - MSB is transmitted on transition of LRC.
+
+ o Right Justified - MSB is transmitted sample size BCLK's before LRC
+                     transition.
+
+PCM
+===
+
+PCM is another 4 wire interface, very similar to I2S, that can support a more
+flexible protocol. It has bit clock (BCLK) and sync (SYNC) lines that are used
+to synchronise the link whilst the Tx and Rx lines are used to transmit and
+receive the audio data. Bit clock usually varies depending on sample rate
+whilst sync runs at the sample rate. PCM also supports Time Division
+Multiplexing (TDM) in that several devices can use the bus similtaniuosly (This
+is sometimes referred to as network mode).
+
+Common PCM operating modes:-
+
+ o Mode A - MSB is transmitted on falling edge of first BCLK after FRAME/SYNC.
+
+ o Mode B - MSB is transmitted on rising edge of FRAME/SYNC.
+
+
+ASoC DAI Configuration
+======================
+
+Every CODEC DAI and SoC DAI must have their capabilities defined in order to
+be configured together at runtime when the audio and clocking parameters are
+known. This is achieved by creating an array of struct snd_soc_hw_mode in the
+the CODEC and SoC interface drivers. Each element in the array describes a DAI
+mode and each mode is usually based upon the DAI system clock to sample rate
+ratio (FS).
+
+i.e. 48k sample rate @ 256 FS = sytem clock of 12.288 MHz
+     48000 * 256 = 12288000
+
+The CPU and Codec DAI modes are then ANDed together at runtime to determine the
+rutime DAI configuration for both the Codec and CPU.
+
+When creating a new codec or SoC DAI it's probably best to start of with a few
+sample rates first and then test your interface.
+
+struct snd_soc_dai_mode is defined (in soc.h) as:-
+
+/* SoC DAI mode */
+struct snd_soc_hw_mode {
+	unsigned int fmt:16;		/* SND_SOC_DAIFMT_* */
+	unsigned int tdm:16;		/* SND_SOC_DAITDM_* */
+	unsigned int pcmfmt:6; 		/* SNDRV_PCM_FORMAT_* */
+	unsigned int pcmrate:16;	/* SND_SOC_DAIRATE_* */
+	unsigned int pcmdir:2;		/* SND_SOC_DAIDIR_* */
+	unsigned int flags:8;		/* hw flags */
+	unsigned int fs:32;			/* mclk to rate dividers */
+	unsigned int bfs:16;		/* mclk to bclk dividers */
+	unsigned long priv;	        /* private mode data */
+};
+
+fmt:
+----
+This field defines the DAI mode hardware format (e.g. I2S settings) and
+supports the following settings:-
+
+ 1) hardware DAI formats
+
+#define SND_SOC_DAIFMT_I2S        (1 << 0)	/* I2S mode */
+#define SND_SOC_DAIFMT_RIGHT_J    (1 << 1)	/* Right justified mode */
+#define SND_SOC_DAIFMT_LEFT_J     (1 << 2)	/* Left Justified mode */
+#define SND_SOC_DAIFMT_DSP_A      (1 << 3)	/* L data msb after FRM */
+#define SND_SOC_DAIFMT_DSP_B      (1 << 4)	/* L data msb during FRM */
+#define SND_SOC_DAIFMT_AC97       (1 << 5)	/* AC97 */
+
+ 2) hw DAI signal inversions
+
+#define SND_SOC_DAIFMT_NB_NF		(1 << 8)	/* normal bit clock + frame */
+#define SND_SOC_DAIFMT_NB_IF		(1 << 9)	/* normal bclk + inv frm */
+#define SND_SOC_DAIFMT_IB_NF		(1 << 10)	/* invert bclk + nor frm */
+#define SND_SOC_DAIFMT_IB_IF		(1 << 11)	/* invert bclk + frm */
+
+ 3) hw clock masters
+    This is wrt the codec, the inverse is true for the interface
+    i.e. if the codec is clk and frm master then the interface is
+    clk and frame slave.
+
+#define SND_SOC_DAIFMT_CBM_CFM		(1 << 12)	/* codec clk & frm master */
+#define SND_SOC_DAIFMT_CBS_CFM		(1 << 13)	/* codec clk slave & frm master */
+#define SND_SOC_DAIFMT_CBM_CFS		(1 << 14)	/* codec clk master & frame slave */
+#define SND_SOC_DAIFMT_CBS_CFS		(1 << 15)	/* codec clk & frm slave */
+
+At least one option from each section must be selected. Multiple selections are
+also supported e.g.
+
+ .fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_LEFT_J | SND_SOC_DAIFMT_RIGHT_J | \
+	SND_SOC_DAIFMT_NB_NF | SND_SOC_DAIFMT_NB_IF | SND_SOC_DAIFMT_IB_NF | \
+	SND_SOC_DAIFMT_IB_IF
+
+
+tdm:
+------
+This field defines the Time Division Multiplexing left and right word
+positions for the DAI mode if applicable. Set to SND_SOC_DAITDM_LRDW(0,0) for
+no TDM.
+
+
+pcmfmt:
+---------
+The hardware PCM format. This describes the PCM formats supported by the DAI
+mode e.g.
+
+ .hwpcmfmt = SNDRV_PCM_FORMAT_S16_LE | SNDRV_PCM_FORMAT_S20_3LE | \
+ 	SNDRV_PCM_FORMAT_S24_3LE
+
+pcmrate:
+----------
+The PCM sample rates supported by the DAI mode. e.g.
+
+ .hwpcmrate = SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_11025 | SNDRV_PCM_RATE_16000 | \
+	SNDRV_PCM_RATE_22050 | SNDRV_PCM_RATE_32000 | SNDRV_PCM_RATE_44100 | \
+	SNDRV_PCM_RATE_48000 | SNDRV_PCM_RATE_88200 | SNDRV_PCM_RATE_96000
+
+
+pcmdir:
+---------
+The stream directions supported by this mode. e.g. playback and capture
+
+
+flags:
+--------
+The DAI hardware flags supported by the mode.
+
+SND_SOC_DAI_BFS_DIV
+This flag states that bit clock is generated by dividing MCLK in this mode, if
+this flag is absent the bitclock generated by mulitiplying sample rate.
+
+NOTE: Bitclock division and mulitiplication modes can be safely matched by the
+core logic.
+
+
+fs:
+-----
+The FS supported by this DAI mode FS is the ratio between the system clock and
+the sample rate. See above
+
+bfs:
+------
+BFS is the ratio of BCLK to MCLK or the ratio of BCLK to sample rate (this
+depends on the codec or CPU DAI).
+
+The BFS supported by the DAI mode. This can either be the ratio between the
+bitclock (BCLK) and the sample rate OR the ratio between the system clock and
+the sample rate. Depends on the SND_SOC_DAI_BFS_DIV flag above.
+
+priv:
+-----
+private codec mode data.
+
+
+
+Examples
+========
+
+Note that Codec DAI and CPU DAI examples are interchangeable in these examples
+as long as the bus master is reversed. i.e.
+
+  SND_SOC_DAIFMT_CBM_CFM would become SND_SOC_DAIFMT_CBS_CFS
+  and vice versa.
+
+This applies to all SND_SOC_DAIFMT_CB*_CF*.
+
+Example 1
+---------
+
+Simple codec that only runs at 8k & 48k @ 256FS in master mode, can generate a
+BCLK of either MCLK/2 or MCLK/4.
+
+	/* codec master */
+	{SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, SND_SOC_DAITDM_LRDW(0,0),
+	SNDRV_PCM_FORMAT_S16_LE, SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_48000,
+	SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, SND_SOC_DAI_BFS_DIV,
+	256, SND_SOC_FSBD(2) | SND_SOC_FSBD(4)},
+
+
+Example 2
+---------
+Simple codec that only runs at 8k & 48k @ 256FS in master mode, can generate a
+BCLK of either Rate * 32 or Rate * 64.
+
+	/* codec master */
+	{SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, SND_SOC_DAITDM_LRDW(0,0),
+	SNDRV_PCM_FORMAT_S16_LE, SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_48000,
+	SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, 0,
+	256, SND_SOC_FSB(32) | SND_SOC_FSB(64)},
+
+
+Example 3
+---------
+Codec that only runs at 8k & 48k @ 256FS in master mode, can generate a
+BCLK of either Rate * 32 or Rate * 64. Codec can also run in slave mode as long
+as BCLK is rate * 32 or rate * 64.
+
+	/* codec master */
+	{SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, SND_SOC_DAITDM_LRDW(0,0),
+	SNDRV_PCM_FORMAT_S16_LE, SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_48000,
+	SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, 0,
+	256, SND_SOC_FSB(32) | SND_SOC_FSB(64)},
+
+	/* codec slave */
+	{SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBS_CFS, SND_SOC_DAITDM_LRDW(0,0),
+	SNDRV_PCM_FORMAT_S16_LE, SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_48000,
+	SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, 0,
+	SND_SOC_FS_ALL, SND_SOC_FSB(32) | SND_SOC_FSB(64)},
+
+
+Example 4
+---------
+Codec that only runs at 8k, 16k, 32k, 48k, 96k @ 128FS, 192FS & 256FS in master
+mode and can generate a BCLK of MCLK / (1,2,4,8,16). Codec can also run in slave
+mode as and does not care about FS or BCLK (as long as there is enough bandwidth).
+
+	#define CODEC_FSB \
+	(SND_SOC_FSBD(1) | SND_SOC_FSBD(2) | SND_SOC_FSBD(4) | \
+	SND_SOC_FSBD(8) | SND_SOC_FSBD(16))
+
+	#define CODEC_RATES \
+	(SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_16000 | SNDRV_PCM_RATE_32000 |\
+	 SNDRV_PCM_RATE_48000 | SNDRV_PCM_RATE_96000)
+
+	/* codec master @ 128, 192 & 256 FS */
+	{SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, SND_SOC_DAITDM_LRDW(0,0),
+	SNDRV_PCM_FORMAT_S16_LE, CODEC_RATES,
+	SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, SND_SOC_DAI_BFS_DIV,
+	128, CODEC_FSB},
+
+	{SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, SND_SOC_DAITDM_LRDW(0,0),
+	SNDRV_PCM_FORMAT_S16_LE, CODEC_RATES,
+	SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, SND_SOC_DAI_BFS_DIV,
+	192, CODEC_FSB},
+
+	{SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, SND_SOC_DAITDM_LRDW(0,0),
+	SNDRV_PCM_FORMAT_S16_LE, CODEC_RATES,
+	SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, SND_SOC_DAI_BFS_DIV,
+	256, CODEC_FSB},
+
+	/* codec slave */
+	{SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBS_CFS, SND_SOC_DAITDM_LRDW(0,0),
+	SNDRV_PCM_FORMAT_S16_LE, CODEC_RATES,
+	SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, 0,
+	SND_SOC_FS_ALL, SND_SOC_FSB_ALL},
+
+
+Example 5
+---------
+Codec that only runs at 8k, 44.1k, 48k @ different FS in master mode (for use
+with a fixed MCLK) and can generate a BCLK of MCLK / (1,2,4,8,16).
+Codec can also run in slave mode as and does not care about FS or BCLK (as long
+as there is enough bandwidth). Codec can support 16, 24 and 32 bit PCM sample
+sizes.
+
+	#define CODEC_FSB \
+	(SND_SOC_FSBD(1) | SND_SOC_FSBD(2) | SND_SOC_FSBD(4) | \
+	SND_SOC_FSBD(8) | SND_SOC_FSBD(16))
+
+	#define CODEC_PCM_FORMATS \
+	(SNDRV_PCM_FORMAT_S16_LE | SNDRV_PCM_FORMAT_S20_3LE | \
+	SNDRV_PCM_FORMAT_S24_3LE | SNDRV_PCM_FORMAT_S24_LE | SNDRV_PCM_FORMAT_S32_LE)
+
+	/* codec master */
+	{SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, SND_SOC_DAITDM_LRDW(0,0),
+	SNDRV_PCM_FORMAT_S16_LE, SNDRV_PCM_RATE_8000,
+	SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, SND_SOC_DAI_BFS_DIV,
+	1536, CODEC_FSB},
+
+	{SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, SND_SOC_DAITDM_LRDW(0,0),
+	SNDRV_PCM_FORMAT_S16_LE, SNDRV_PCM_RATE_44100,
+	SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, SND_SOC_DAI_BFS_DIV,
+	272, CODEC_FSB},
+
+	{SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBM_CFM, SND_SOC_DAITDM_LRDW(0,0),
+	SNDRV_PCM_FORMAT_S16_LE, SNDRV_PCM_RATE_48000,
+	SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, SND_SOC_DAI_BFS_DIV,
+	256, CODEC_FSB},
+
+	/* codec slave */
+	{SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_CBS_CFS, SND_SOC_DAITDM_LRDW(0,0),
+	SNDRV_PCM_FORMAT_S16_LE, CODEC_RATES,
+	SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE, 0,
+	SND_SOC_FS_ALL, SND_SOC_FSB_ALL},
+
+
+Example 6
+---------
+AC97 Codec that does not support VRA (i.e only runs at 48k).
+
+	#define AC97_DIR \
+	(SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE)
+
+
+	#define AC97_PCM_FORMATS \
+	(SNDRV_PCM_FORMAT_S16_LE | SNDRV_PCM_FORMAT_S18_3LE | \
+	SNDRV_PCM_FORMAT_S20_3LE)
+
+	/* AC97 with no VRA */
+	{0, 0,	AC97_PCM_FORMATS,	SNDRV_PCM_RATE_48000},
+
+
+Example 7
+---------
+
+CPU DAI that supports 8k - 48k @ 256FS and BCLK = MCLK / 4 in master mode.
+Slave mode (CPU DAI is FRAME master) supports 8k - 96k at any FS as long as
+BCLK = 64 * rate. (Intel XScale I2S controller).
+
+	#define PXA_I2S_DAIFMT \
+	(SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_LEFT_J | SND_SOC_DAIFMT_NB_NF)
+
+	#define PXA_I2S_DIR \
+	(SND_SOC_DAIDIR_PLAYBACK | SND_SOC_DAIDIR_CAPTURE)
+
+	#define PXA_I2S_RATES \
+	(SNDRV_PCM_RATE_8000 | SNDRV_PCM_RATE_11025 | SNDRV_PCM_RATE_16000 | \
+	SNDRV_PCM_RATE_22050 | SNDRV_PCM_RATE_32000 | SNDRV_PCM_RATE_44100 | \
+	SNDRV_PCM_RATE_48000 | SNDRV_PCM_RATE_88200 | SNDRV_PCM_RATE_96000)
+
+	/* pxa2xx I2S frame and clock master modes */
+	{PXA_I2S_DAIFMT | SND_SOC_DAIFMT_CBS_CFS, SND_SOC_DAITDM_LRDW(0,0), SNDRV_PCM_FORMAT_S16_LE,
+		SNDRV_PCM_RATE_8000, PXA_I2S_DIR, SND_SOC_DAI_BFS_DIV, 256,
+		SND_SOC_FSBD(4), 0x48},
+	{PXA_I2S_DAIFMT | SND_SOC_DAIFMT_CBS_CFS, SND_SOC_DAITDM_LRDW(0,0), SNDRV_PCM_FORMAT_S16_LE,
+		SNDRV_PCM_RATE_11025, PXA_I2S_DIR, SND_SOC_DAI_BFS_DIV, 256,
+		SND_SOC_FSBD(4), 0x34},
+	{PXA_I2S_DAIFMT | SND_SOC_DAIFMT_CBS_CFS, SND_SOC_DAITDM_LRDW(0,0), SNDRV_PCM_FORMAT_S16_LE,
+		SNDRV_PCM_RATE_16000, PXA_I2S_DIR, SND_SOC_DAI_BFS_DIV, 256,
+		SND_SOC_FSBD(4), 0x24},
+	{PXA_I2S_DAIFMT | SND_SOC_DAIFMT_CBS_CFS, SND_SOC_DAITDM_LRDW(0,0), SNDRV_PCM_FORMAT_S16_LE,
+		SNDRV_PCM_RATE_22050, PXA_I2S_DIR, SND_SOC_DAI_BFS_DIV, 256,
+		SND_SOC_FSBD(4), 0x1a},
+	{PXA_I2S_DAIFMT | SND_SOC_DAIFMT_CBS_CFS, SND_SOC_DAITDM_LRDW(0,0), SNDRV_PCM_FORMAT_S16_LE,
+		SNDRV_PCM_RATE_44100, PXA_I2S_DIR, SND_SOC_DAI_BFS_DIV, 256,
+		SND_SOC_FSBD(4), 0xd},
+	{PXA_I2S_DAIFMT | SND_SOC_DAIFMT_CBS_CFS, SND_SOC_DAITDM_LRDW(0,0), SNDRV_PCM_FORMAT_S16_LE,
+		SNDRV_PCM_RATE_48000, PXA_I2S_DIR, SND_SOC_DAI_BFS_DIV, 256,
+		SND_SOC_FSBD(4), 0xc},
+
+	/* pxa2xx I2S frame master and clock slave mode */
+	{PXA_I2S_DAIFMT | SND_SOC_DAIFMT_CBM_CFS, SND_SOC_DAITDM_LRDW(0,0), SNDRV_PCM_FORMAT_S16_LE,
+		PXA_I2S_RATES, PXA_I2S_DIR, 0, SND_SOC_FS_ALL, SND_SOC_FSB(64)},
+
diff --git a/Documentation/sound/alsa/soc/clocking.txt b/Documentation/sound/alsa/soc/clocking.txt
new file mode 100644
index 00000000000..88a16c9e197
--- /dev/null
+++ b/Documentation/sound/alsa/soc/clocking.txt
@@ -0,0 +1,309 @@
+Audio Clocking
+==============
+
+This text describes the audio clocking terms in ASoC and digital audio in
+general. Note: Audio clocking can be complex !
+
+
+Master Clock
+------------
+
+Every audio subsystem is driven by a master clock (sometimes refered to as MCLK
+or SYSCLK). This audio master clock can be derived from a number of sources
+(e.g. crystal, PLL, CPU clock) and is responsible for producing the correct
+audio playback and capture sample rates.
+
+Some master clocks (e.g. PLL's and CPU based clocks) are configuarble in that
+their speed can be altered by software (depending on the system use and to save
+power). Other master clocks are fixed at at set frequency (i.e. crystals).
+
+
+DAI Clocks
+----------
+The Digital Audio Interface is usually driven by a Bit Clock (often referred to
+as BCLK). This clock is used to drive the digital audio data across the link
+between the codec and CPU.
+
+The DAI also has a frame clock to signal the start of each audio frame. This
+clock is sometimes referred to as LRC (left right clock) or FRAME. This clock
+runs at exactly the sample rate.
+
+Bit Clock is usually always a ratio of MCLK or a multiple of LRC. i.e.
+
+BCLK = MCLK / x
+
+ or
+
+BCLK = LRC * x
+
+This relationship depends on the codec or SoC CPU in particular. ASoC can quite
+easily match a codec that generates BCLK by division (FSBD) with a CPU that
+generates BCLK by multiplication (FSB).
+
+
+ASoC Clocking
+-------------
+
+The ASoC core determines the clocking for each particular configuration at
+runtime. This is to allow for dynamic audio clocking wereby the audio clock is
+variable and depends on the system state or device usage scenario. i.e. a voice
+call requires slower clocks (and hence less power) than MP3 playback.
+
+ASoC will call the config_sysclock() function for the target machine during the
+audio parameters configuration. The function is responsible for then clocking
+the machine audio subsytem and returning the audio clock speed to the core.
+This function should also call the codec and cpu DAI clock_config() functions
+to configure their respective internal clocking if required.
+
+
+ASoC Clocking Control Flow
+--------------------------
+
+The ASoC core will call the machine drivers config_sysclock() when most of the
+DAI capabilities are known. The machine driver is then responsible for calling
+the codec and/or CPU DAI drivers with the selected capabilities and the current
+MCLK. Note that the machine driver is also resonsible for setting the MCLK (and
+enabling it).
+
+   (1) Match Codec and CPU DAI capabilities. At this point we have
+       matched the majority of the DAI fields and now need to make sure this
+       mode is currently clockable.
+
+   (2) machine->config_sysclk() is now called with the matched DAI FS, sample
+       rate and BCLK master. This function then gets/sets the current audio
+       clock (depening on usage) and calls the codec and CPUI DAI drivers with
+       the FS, rate, BCLK master and MCLK.
+
+   (3) Codec/CPU DAI config_sysclock(). This function checks that the FS, rate,
+       BCLK master and MCLK are acceptable for the codec or CPU DAI. It also
+       sets the DAI internal state to work with said clocks.
+
+The config_sysclk() functions for CPU, codec and machine should return the MCLK
+on success and 0 on failure.
+
+
+Examples (b = BCLK, l = LRC)
+============================
+
+Example 1
+---------
+
+Simple codec that only runs at 48k @ 256FS in master mode.
+
+CPU only runs as slave DAI, however it generates a variable MCLK.
+
+             --------                 ---------
+            |        | <----mclk---  |         |
+            | Codec  |b -----------> |  CPU    |
+            |        |l -----------> |         |
+            |        |               |         |
+             --------                 ---------
+
+The codec driver has the following config_sysclock()
+
+	static unsigned int config_sysclk(struct snd_soc_codec_dai *dai,
+		struct snd_soc_clock_info *info, unsigned int clk)
+	{
+		/* make sure clock is 256 * rate */
+		if(info->rate << 8 == clk) {
+			dai->mclk = clk;
+			return clk;
+		}
+
+		return 0;
+	}
+
+The CPU I2S DAI driver has the following config_sysclk()
+
+	static unsigned int config_sysclk(struct snd_soc_codec_dai *dai,
+		struct snd_soc_clock_info *info, unsigned int clk)
+	{
+		/* can we support this clk */
+		if(set_audio_clk(clk) < 0)
+			return -EINVAL;
+
+		dai->mclk = clk;
+		return dai->clk;
+	}
+
+The machine driver config_sysclk() in this example is as follows:-
+
+	unsigned int machine_config_sysclk(struct snd_soc_pcm_runtime *rtd,
+		struct snd_soc_clock_info *info)
+	{
+		int clk = info->rate * info->fs;
+
+		/* check that CPU can deliver clock */
+		if(rtd->cpu_dai->config_sysclk(rtd->cpu_dai, info, clk) < 0)
+			return -EINVAL;
+
+		/* can codec work with this clock */
+		return rtd->codec_dai->config_sysclk(rtd->codec_dai, info, clk);
+	}
+
+
+Example 2
+---------
+
+Codec that can master at 8k and 48k at various FS (and hence supports a fixed
+set of input MCLK's) and can also be slave at various FS .
+
+The CPU can master at 8k and 48k @256 FS and can be slave at any FS.
+
+MCLK is a 12.288MHz crystal on this machine.
+
+             --------                 ---------
+            |        |  <---xtal---> |         |
+            | Codec  |b <----------> |  CPU    |
+            |        |l <----------> |         |
+            |        |               |         |
+             --------                 ---------
+
+
+The codec driver has the following config_sysclock()
+
+	/* supported input clocks */
+	const static int hifi_clks[] = {11289600, 12000000, 12288000,
+		16934400, 18432000};
+
+	static unsigned int config_hsysclk(struct snd_soc_codec_dai *dai,
+		struct snd_soc_clock_info *info, unsigned int clk)
+	{
+		int i;
+
+		/* is clk supported  */
+		for(i = 0; i < ARRAY_SIZE(hifi_clks); i++) {
+			if(clk == hifi_clks[i]) {
+				dai->mclk = clk;
+				return clk;
+			}
+		}
+
+		/* this clk is not supported */
+		return 0;
+	}
+
+The CPU I2S DAI driver has the following config_sysclk()
+
+	static unsigned int config_sysclk(struct snd_soc_codec_dai *dai,
+		struct snd_soc_clock_info *info, unsigned int clk)
+	{
+		/* are we master or slave */
+		if (info->bclk_master &
+			(SND_SOC_DAIFMT_CBM_CFM | SND_SOC_DAIFMT_CBM_CFS)) {
+
+			/* we can only master @ 256FS */
+			if(info->rate << 8 == clk) {
+				dai->mclk = clk;
+				return dai->mclk;
+			}
+		} else {
+			/* slave we can run at any FS */
+			dai->mclk = clk;
+			return dai->mclk;
+		}
+
+		/* not supported */
+		return dai->clk;
+	}
+
+The machine driver config_sysclk() in this example is as follows:-
+
+	unsigned int machine_config_sysclk(struct snd_soc_pcm_runtime *rtd,
+		struct snd_soc_clock_info *info)
+	{
+		int clk = 12288000; /* 12.288MHz */
+
+		/* who's driving the link */
+		if (info->bclk_master &
+			(SND_SOC_DAIFMT_CBM_CFM | SND_SOC_DAIFMT_CBM_CFS)) {
+			/* codec master */
+
+			/* check that CPU can work with clock */
+			if(rtd->cpu_dai->config_sysclk(rtd->cpu_dai, info, clk) < 0)
+				return -EINVAL;
+
+			/* can codec work with this clock */
+			return rtd->codec_dai->config_sysclk(rtd->codec_dai, info, clk);
+		} else {
+			/* cpu master */
+
+			/* check that codec can work with clock */
+			if(rtd->codec_dai->config_sysclk(rtd->codec_dai, info, clk) < 0)
+				return -EINVAL;
+
+			/* can CPU work with this clock */
+			return rtd->cpu_dai->config_sysclk(rtd->cpu_dai, info, clk);
+		}
+	}
+
+
+
+Example 3
+---------
+
+Codec that masters at 8k ... 48k @256 FS. Codec can also be slave and
+doesn't care about FS. The codec has an internal PLL and dividers to generate
+the necessary internal clocks (for 256FS).
+
+CPU can only be slave and doesn't care about FS.
+
+MCLK is a non controllable 13MHz clock from the CPU.
+
+
+             --------                 ---------
+            |        | <----mclk---  |         |
+            | Codec  |b <----------> |  CPU    |
+            |        |l <----------> |         |
+            |        |               |         |
+             --------                 ---------
+
+The codec driver has the following config_sysclock()
+
+	/* valid PCM clock dividers * 2 */
+	static int pcm_divs[] = {2, 6, 11, 4, 8, 12, 16};
+
+	static unsigned int config_vsysclk(struct snd_soc_codec_dai *dai,
+		struct snd_soc_clock_info *info, unsigned int clk)
+	{
+		int i, j, best_clk = info->fs * info->rate;
+
+		/* can we run at this clk without the PLL ? */
+		for (i = 0; i < ARRAY_SIZE(pcm_divs); i++) {
+			if ((best_clk >> 1) * pcm_divs[i] == clk) {
+				dai->pll_in = 0;
+				dai->clk_div = pcm_divs[i];
+				dai->mclk = best_clk;
+				return dai->mclk;
+			}
+		}
+
+		/* now check for PLL support */
+		for (i = 0; i < ARRAY_SIZE(pll_div); i++) {
+			if (pll_div[i].pll_in == clk) {
+				for (j = 0; j < ARRAY_SIZE(pcm_divs); j++) {
+					if (pll_div[i].pll_out == pcm_divs[j] * (best_clk >> 1)) {
+						dai->pll_in = clk;
+						dai->pll_out = pll_div[i].pll_out;
+						dai->clk_div = pcm_divs[j];
+						dai->mclk = best_clk;
+						return dai->mclk;
+					}
+				}
+			}
+		}
+
+		/* this clk is not supported */
+		return 0;
+	}
+
+
+The CPU I2S DAI driver has the does not need a config_sysclk() as it can slave
+at any FS.
+
+	unsigned int config_sysclk(struct snd_soc_pcm_runtime *rtd,
+		struct snd_soc_clock_info *info)
+	{
+		/* codec has pll that generates mclk from 13MHz xtal */
+		return rtd->codec_dai->config_sysclk(rtd->codec_dai, info, 13000000);
+	}
diff --git a/Documentation/sound/alsa/soc/codec.txt b/Documentation/sound/alsa/soc/codec.txt
new file mode 100644
index 00000000000..47b36cb1684
--- /dev/null
+++ b/Documentation/sound/alsa/soc/codec.txt
@@ -0,0 +1,232 @@
+ASoC Codec Driver
+=================
+
+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 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
+
+Optionally, codec drivers can also provide:-
+
+ 8) DAPM description.
+ 9) DAPM event handler.
+10) DAC Digital mute control.
+
+It's probably best to use this guide in conjuction with the existing codec
+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.
+
+e.g.
+
+static struct snd_soc_pcm_codec wm8731_pcm_client = {
+	.name = "WM8731",
+	.playback = {
+		.stream_name = "Playback",
+		.channels_min = 1,
+		.channels_max = 2,
+	},
+	.capture = {
+		.stream_name = "Capture",
+		.channels_min = 1,
+		.channels_max = 2,
+	},
+	.config_sysclk = wm8731_config_sysclk,
+	.ops = {
+		.prepare = wm8731_pcm_prepare,
+	},
+	.caps = {
+		.num_modes = ARRAY_SIZE(wm8731_hwfmt),
+		.modes = &wm8731_hwfmt[0],
+	},
+};
+
+
+4 - 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
+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;
+
+
+5 - Mixers and audio controls
+-----------------------------
+All the codec mixers and audio controls can be defined using the convenience
+macros defined in soc.h.
+
+    #define SOC_SINGLE(xname, reg, shift, mask, invert)
+
+Defines a single control as follows:-
+
+  xname = Control name e.g. "Playback Volume"
+  reg = codec register
+  shift = control bit(s) offset in register
+  mask = control bit size(s) e.g. mask of 7 = 3 bits
+  invert = the control is inverted
+
+Other macros include:-
+
+    #define SOC_DOUBLE(xname, reg, shift_left, shift_right, mask, invert)
+
+A stereo control
+
+    #define SOC_DOUBLE_R(xname, reg_left, reg_right, shift, mask, invert)
+
+A stereo control spanning 2 registers
+
+    #define SOC_ENUM_SINGLE(xreg, xshift, xmask, xtexts)
+
+Defines an single enumerated control as follows:-
+
+   xreg = register
+   xshift = control bit(s) offset in register
+   xmask = control bit(s) size
+   xtexts = pointer to array of strings that describe each setting
+
+   #define SOC_ENUM_DOUBLE(xreg, xshift_l, xshift_r, xmask, xtexts)
+
+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
+--------------------------
+The codec driver also supports the following alsa operations:-
+
+/* SoC audio ops */
+struct snd_soc_ops {
+	int (*startup)(snd_pcm_substream_t *);
+	void (*shutdown)(snd_pcm_substream_t *);
+	int (*hw_params)(snd_pcm_substream_t *, snd_pcm_hw_params_t *);
+	int (*hw_free)(snd_pcm_substream_t *);
+	int (*prepare)(snd_pcm_substream_t *);
+};
+
+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.
+---------------------
+The Dynamic Audio Power Management description describes the codec's power
+components, their relationships and registers to the ASoC core. Please read
+dapm.txt for details of building the description.
+
+Please also see the examples in other codec drivers.
+
+
+9 - 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
+when not in use.
+
+Power states:-
+
+	SNDRV_CTL_POWER_D0: /* full On */
+	/* vref/mid, clk and osc on, active */
+
+	SNDRV_CTL_POWER_D1: /* partial On */
+	SNDRV_CTL_POWER_D2: /* partial On */
+
+	SNDRV_CTL_POWER_D3hot: /* Off, with power */
+	/* everything off except vref/vmid, inactive */
+
+	SNDRV_CTL_POWER_D3cold: /* Everything Off, without power */
+
+
+10 - 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.
+
+A callback can be created that is called by the core for each codec DAI when the
+mute is applied or freed.
+
+i.e.
+
+static int wm8974_mute(struct snd_soc_codec *codec,
+	struct snd_soc_codec_dai *dai, int mute)
+{
+	u16 mute_reg = wm8974_read_reg_cache(codec, WM8974_DAC) & 0xffbf;
+	if(mute)
+		wm8974_write(codec, WM8974_DAC, mute_reg | 0x40);
+	else
+		wm8974_write(codec, WM8974_DAC, mute_reg);
+	return 0;
+}
diff --git a/Documentation/sound/alsa/soc/dapm.txt b/Documentation/sound/alsa/soc/dapm.txt
new file mode 100644
index 00000000000..c11877f5b4a
--- /dev/null
+++ b/Documentation/sound/alsa/soc/dapm.txt
@@ -0,0 +1,297 @@
+Dynamic Audio Power Management for Portable Devices
+===================================================
+
+1. Description
+==============
+
+Dynamic Audio Power Management (DAPM) is designed to allow portable Linux devices
+to use the minimum amount of power within the audio subsystem at all times. It
+is independent of other kernel PM and as such, can easily co-exist with the
+other PM systems.
+
+DAPM is also completely transparent to all user space applications as all power
+switching is done within the ASoC core. No code changes or recompiling are
+required for user space applications. DAPM makes power switching descisions based
+upon any audio stream (capture/playback) activity and audio mixer settings
+within the device.
+
+DAPM spans the whole machine. It covers power control within the entire audio
+subsystem, this includes internal codec power blocks and machine level power
+systems.
+
+There are 4 power domains within DAPM
+
+   1. Codec domain - VREF, VMID (core codec and audio power)
+      Usually controlled at codec probe/remove and suspend/resume, although
+      can