Merge branch 'topic/restize-docs' into for-next

Documentation/sound/index.rst

@@ -7,6 +7,7 @@ Linux Sound Subsystem Documentation
 
    kernel-api/index
    designs/index
+   soc/index
    alsa-configuration
    hd-audio/index
    cards/index

Documentation/sound/alsa/soc/clocking.txt → Documentation/sound/soc/clocking.rst

+==============
 Audio Clocking
 ==============
 
@@ -30,15 +31,9 @@ runs at exactly the sample rate (LRC = Rate).
 
 Bit Clock can be generated as follows:-
 
-BCLK = MCLK / x
-
- or
-
-BCLK = LRC * x
-
- or
-
-BCLK = LRC * Channels * Word Size
+- BCLK = MCLK / x, or
+- BCLK = LRC * x, or
+- BCLK = LRC * Channels * Word Size
 
 This relationship depends on the codec or SoC CPU in particular. In general
 it is best to configure BCLK to the lowest possible speed (depending on your

Documentation/sound/soc/codec-to-codec.rst

+==============================================
+Creating codec to codec dai link for ALSA dapm
+==============================================
+
+Mostly the flow of audio is always from CPU to codec so your system
+will look as below:
+::
+
+   ---------          ---------
+  |         |  dai   |         |
+      CPU    ------->    codec
+  |         |        |         |
+   ---------          ---------
+
+In case your system looks as below:
+::
+
+                       ---------
+                      |         |
+                        codec-2
+                      |         |
+                      ---------
+                           |
+                         dai-2
+                           |
+   ----------          ---------
+  |          |  dai-1 |         |
+      CPU     ------->  codec-1
+  |          |        |         |
+   ----------          ---------
+                           |
+                         dai-3
+                           |
+                       ---------
+                      |         |
+                        codec-3
+                      |         |
+                       ---------
+
+Suppose codec-2 is a bluetooth chip and codec-3 is connected to
+a speaker and you have a below scenario:
+codec-2 will receive the audio data and the user wants to play that
+audio through codec-3 without involving the CPU.This
+aforementioned case is the ideal case when codec to codec
+connection should be used.
+
+Your dai_link should appear as below in your machine
+file:
+::
+
+ /*
+  * this pcm stream only supports 24 bit, 2 channel and
+  * 48k sampling rate.
+  */
+ static const struct snd_soc_pcm_stream dsp_codec_params = {
+        .formats = SNDRV_PCM_FMTBIT_S24_LE,
+        .rate_min = 48000,
+        .rate_max = 48000,
+        .channels_min = 2,
+        .channels_max = 2,
+ };
+
+ {
+    .name = "CPU-DSP",
+    .stream_name = "CPU-DSP",
+    .cpu_dai_name = "samsung-i2s.0",
+    .codec_name = "codec-2,
+    .codec_dai_name = "codec-2-dai_name",
+    .platform_name = "samsung-i2s.0",
+    .dai_fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_NB_NF
+            | SND_SOC_DAIFMT_CBM_CFM,
+    .ignore_suspend = 1,
+    .params = &dsp_codec_params,
+ },
+ {
+    .name = "DSP-CODEC",
+    .stream_name = "DSP-CODEC",
+    .cpu_dai_name = "wm0010-sdi2",
+    .codec_name = "codec-3,
+    .codec_dai_name = "codec-3-dai_name",
+    .dai_fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_NB_NF
+            | SND_SOC_DAIFMT_CBM_CFM,
+    .ignore_suspend = 1,
+    .params = &dsp_codec_params,
+ },
+
+Above code snippet is motivated from sound/soc/samsung/speyside.c.
+
+Note the "params" callback which lets the dapm know that this
+dai_link is a codec to codec connection.
+
+In dapm core a route is created between cpu_dai playback widget
+and codec_dai capture widget for playback path and vice-versa is
+true for capture path. In order for this aforementioned route to get
+triggered, DAPM needs to find a valid endpoint which could be either
+a sink or source widget corresponding to playback and capture path
+respectively.
+
+In order to trigger this dai_link widget, a thin codec driver for
+the speaker amp can be created as demonstrated in wm8727.c file, it
+sets appropriate constraints for the device even if it needs no control.
+
+Make sure to name your corresponding cpu and codec playback and capture
+dai names ending with "Playback" and "Capture" respectively as dapm core
+will link and power those dais based on the name.
+
+Note that in current device tree there is no way to mark a dai_link
+as codec to codec. However, it may change in future.

Documentation/sound/alsa/soc/codec.txt → Documentation/sound/soc/codec.rst

+=======================
 ASoC Codec Class Driver
 =======================
 
@@ -9,16 +10,16 @@ machine drivers respectively.
 
 Each codec class driver *must* provide the following features:-
 
- 1) Codec DAI and PCM configuration
- 2) Codec control IO - using RegMap API
- 3) Mixers and audio controls
- 4) Codec audio operations
- 5) DAPM description.
- 6) DAPM event handler.
+1. Codec DAI and PCM configuration
+2. Codec control IO - using RegMap API
+3. Mixers and audio controls
+4. Codec audio operations
+5. DAPM description.
+6. DAPM event handler.
 
 Optionally, codec drivers can also provide:-
 
- 7) DAC Digital mute control.
+7. DAC Digital mute control.
 
 Its probably best to use this guide in conjunction with the existing codec
 driver code in sound/soc/codecs/
@@ -26,24 +27,25 @@ driver code in sound/soc/codecs/
 ASoC Codec driver breakdown
 ===========================
 
-1 - Codec DAI and PCM configuration
------------------------------------
+Codec DAI and PCM configuration
+-------------------------------
 Each codec driver must have a struct snd_soc_dai_driver to define its DAI and
 PCM capabilities 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_dai_ops wm8731_dai_ops = {
+  static struct snd_soc_dai_ops wm8731_dai_ops = {
 	.prepare	= wm8731_pcm_prepare,
 	.hw_params	= wm8731_hw_params,
 	.shutdown	= wm8731_shutdown,
 	.digital_mute	= wm8731_mute,
 	.set_sysclk	= wm8731_set_dai_sysclk,
 	.set_fmt	= wm8731_set_dai_fmt,
-};
-
-struct snd_soc_dai_driver wm8731_dai = {
+  };
+  
+  struct snd_soc_dai_driver wm8731_dai = {
 	.name = "wm8731-hifi",
 	.playback = {
 		.stream_name = "Playback",
@@ -59,25 +61,27 @@ struct snd_soc_dai_driver wm8731_dai = {
 		.formats = WM8731_FORMATS,},
 	.ops = &wm8731_dai_ops,
 	.symmetric_rates = 1,
-};
+  };
 
 
-2 - Codec control IO
---------------------
+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.
 
 
-3 - Mixers and audio controls
------------------------------
+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
@@ -86,18 +90,22 @@ Defines a single control as follows:-
   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
@@ -109,25 +117,26 @@ Defines an single enumerated control as follows:-
 Defines a stereo enumerated control
 
 
-4 - Codec Audio Operations
---------------------------
+Codec Audio Operations
+----------------------
 The codec driver also supports the following ALSA PCM operations:-
+::
 
-/* SoC audio ops */
-struct snd_soc_ops {
+  /* SoC audio ops */
+  struct snd_soc_ops {
 	int (*startup)(struct snd_pcm_substream *);
 	void (*shutdown)(struct snd_pcm_substream *);
 	int (*hw_params)(struct snd_pcm_substream *, struct snd_pcm_hw_params *);
 	int (*hw_free)(struct snd_pcm_substream *);
 	int (*prepare)(struct snd_pcm_substream *);
-};
+  };
 
 Please refer to the ALSA driver PCM documentation for details.
 http://www.alsa-project.org/~iwai/writing-an-alsa-driver/
 
 
-5 - DAPM description.
----------------------
+DAPM description
+----------------
 The Dynamic Audio Power Management description describes the codec power
 components and their relationships and registers to the ASoC core.
 Please read dapm.txt for details of building the description.
@@ -135,13 +144,14 @@ Please read dapm.txt for details of building the description.
 Please also see the examples in other codec drivers.
 
 
-6 - DAPM event handler
-----------------------
+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 is 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 */
@@ -155,8 +165,8 @@ Power states:-
 	SNDRV_CTL_POWER_D3cold: /* Everything Off, without power */
 
 
-7 - Codec DAC digital mute control
-----------------------------------
+Codec DAC digital mute control
+------------------------------
 Most codecs have a digital mute before the DACs that can be used to
 minimise any system noise.  The mute stops any digital data from
 entering the DAC.
@@ -165,9 +175,10 @@ 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_dai *dai, int mute)
-{
+  static int wm8974_mute(struct snd_soc_dai *dai, int mute)
+  {
 	struct snd_soc_codec *codec = dai->codec;
 	u16 mute_reg = snd_soc_read(codec, WM8974_DAC) & 0xffbf;
 
@@ -176,4 +187,4 @@ static int wm8974_mute(struct snd_soc_dai *dai, int mute)
 	else
 		snd_soc_write(codec, WM8974_DAC, mute_reg);
 	return 0;
-}
+  }

Documentation/sound/alsa/soc/DAI.txt → Documentation/sound/soc/dai.rst

+==================================
+ASoC Digital Audio Interface (DAI)
+==================================
+
 ASoC currently supports the three main Digital Audio Interfaces (DAI) found on
 SoC controllers and portable audio CODECs today, namely AC97, I2S and PCM.
 
@@ -5,21 +9,21 @@ 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
+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 :-
+The AC97 specification can be found at :
 http://www.intel.com/p/en_US/business/design
 
 
 I2S
 ===
 
- I2S is a common 4 wire DAI used in HiFi, STB and portable devices. The Tx and
+I2S is a common 4 wire DAI used in HiFi, STB and portable devices. The Tx and
 Rx lines are used for audio transmission, 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
@@ -30,13 +34,15 @@ 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.
+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.
+Left Justified
+  MSB is transmitted on transition of LRC.
 
- o Right Justified - MSB is transmitted sample size BCLKs before LRC
-                     transition.
+Right Justified
+  MSB is transmitted sample size BCLKs before LRC transition.
 
 PCM
 ===
@@ -51,6 +57,8 @@ 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.
+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.
+Mode B
+  MSB is transmitted on rising edge of FRAME/SYNC.

Documentation/sound/soc/index.rst

+==============
+ALSA SoC Layer
+==============
+
+The documentation is spilt into the following sections:-
+
+.. toctree::
+   :maxdepth: 2
+
+   overview
+   codec
+   dai
+   dapm
+   platform
+   machine
+   pops-clicks
+   clocking
+   jack
+   dpcm
+   codec-to-codec

Documentation/sound/alsa/soc/jack.txt → Documentation/sound/soc/jack.rst

+===================
 ASoC jack detection
 ===================
 

Documentation/sound/alsa/soc/machine.txt → Documentation/sound/soc/machine.rst

+===================
 ASoC Machine Driver
 ===================
 
@@ -9,9 +10,10 @@ interrupts, clocking, jacks and voltage regulators.
 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
 the following struct:-
+::
 
-/* SoC machine */
-struct snd_soc_card {
+  /* SoC machine */
+  struct snd_soc_card {
 	char *name;
 
 	...
@@ -33,7 +35,7 @@ struct snd_soc_card {
 	int num_links;
 
 	...
-};
+  };
 
 probe()/remove()
 ----------------
@@ -55,9 +57,10 @@ initialisation e.g. the machine audio map can be connected to the codec audio
 map, unconnected codec pins can be set as such.
 
 struct snd_soc_dai_link is used to set up each DAI in your machine. e.g.
+::
 
-/* corgi digital audio interface glue - connects codec <--> CPU */
-static struct snd_soc_dai_link corgi_dai = {
+  /* corgi digital audio interface glue - connects codec <--> CPU */
+  static struct snd_soc_dai_link corgi_dai = {
 	.name = "WM8731",
 	.stream_name = "WM8731",
 	.cpu_dai_name = "pxa-is2-dai",
@@ -66,16 +69,17 @@ static struct snd_soc_dai_link corgi_dai = {
 	.codec_name = "wm8713-codec.0-001a",
 	.init = corgi_wm8731_init,
 	.ops = &corgi_ops,
-};
+  };
 
 struct snd_soc_card then sets up the machine with its DAIs. e.g.
+::
 
-/* corgi audio machine driver */
-static struct snd_soc_card snd_soc_corgi = {
+  /* corgi audio machine driver */
+  static struct snd_soc_card snd_soc_corgi = {
 	.name = "Corgi",
 	.dai_link = &corgi_dai,
 	.num_links = 1,
-};
+  };
 
 
 Machine Power Map

Documentation/sound/alsa/soc/overview.txt → Documentation/sound/soc/overview.rst

-ALSA SoC Layer
-==============
+=======================
+ALSA SoC Layer Overview
+=======================
 
 The overall project goal of the ALSA System on Chip (ASoC) layer is to
 provide better ALSA support for embedded system-on-chip processors (e.g.
@@ -66,30 +67,3 @@ multiple re-usable component drivers :-
     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).
-
-
-Documentation
-=============
-
-The documentation is spilt into the following sections:-
-
-overview.txt: This file.
-
-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.
-
-jack.txt: ASoC jack detection.
-
-DPCM.txt: Dynamic PCM - Describes DPCM with DSP examples.

Documentation/sound/alsa/soc/platform.txt → Documentation/sound/soc/platform.rst

+====================
 ASoC Platform Driver
 ====================
 
@@ -9,21 +10,23 @@ Audio DMA
 =========
 
 The platform DMA driver optionally supports the following ALSA operations:-
+::
 
-/* SoC audio ops */
-struct snd_soc_ops {
+  /* SoC audio ops */
+  struct snd_soc_ops {
 	int (*startup)(struct snd_pcm_substream *);
 	void (*shutdown)(struct snd_pcm_substream *);
 	int (*hw_params)(struct snd_pcm_substream *, struct snd_pcm_hw_params *);
 	int (*hw_free)(struct snd_pcm_substream *);
 	int (*prepare)(struct snd_pcm_substream *);
 	int (*trigger)(struct snd_pcm_substream *, int);
-};
+  };
 
 The platform driver exports its DMA functionality via struct
 snd_soc_platform_driver:-
+::
 
-struct snd_soc_platform_driver {
+  struct snd_soc_platform_driver {
 	char *name;
 
 	int (*probe)(struct platform_device *pdev);
@@ -44,7 +47,7 @@ struct snd_soc_platform_driver {
 
 	/* platform stream ops */
 	struct snd_pcm_ops *pcm_ops;
-};
+  };
 
 Please refer to the ALSA driver documentation for details of audio DMA.
 http://www.alsa-project.org/~iwai/writing-an-alsa-driver/
@@ -57,11 +60,11 @@ SoC DAI Drivers
 
 Each SoC DAI driver must provide the following features:-
 
- 1) Digital audio interface (DAI) description
- 2) Digital audio interface configuration
- 3) PCM's description
- 4) SYSCLK configuration
- 5) Suspend and resume (optional)
+1. Digital audio interface (DAI) description
+2. Digital audio interface configuration
+3. PCM's description
+4. SYSCLK configuration
+5. Suspend and resume (optional)
 
 Please see codec.txt for a description of items 1 - 4.
 
@@ -71,9 +74,9 @@ 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.
+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.

Documentation/sound/alsa/soc/pops_clicks.txt → Documentation/sound/soc/pops-clicks.rst

+=====================
 Audio Pops and Clicks
 =====================
 
@@ -20,10 +21,11 @@ currently, however future audio codec hardware will have better pop and click
 suppression.  Pops can be reduced within playback by powering the audio
 components in a specific order. This order is different for startup and
 shutdown and follows some basic rules:-
+::
 
- Startup Order :- DAC --> Mixers --> Output PGA --> Digital Unmute
-
- Shutdown Order :- Digital Mute --> Output PGA --> Mixers --> DAC
+   Startup Order :- DAC --> Mixers --> Output PGA --> Digital Unmute
+  
+   Shutdown Order :- Digital Mute --> Output PGA --> Mixers --> DAC
 
 This assumes that the codec PCM output path from the DAC is via a mixer and then
 a PGA (programmable gain amplifier) before being output to the speakers.
@@ -36,10 +38,11 @@ Capture artifacts are somewhat easier to get rid as we can delay activating the
 ADC until all the pops have occurred. This follows similar power rules to
 playback in that components are powered in a sequence depending upon stream
 startup or shutdown.
+::
 
- Startup Order - Input PGA --> Mixers --> ADC
-
- Shutdown Order - ADC --> Mixers --> Input PGA
+   Startup Order - Input PGA --> Mixers --> ADC
+  
+   Shutdown Order - ADC --> Mixers --> Input PGA
 
 
 Zipper Noise