aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/sound/alsa/ALSA-Configuration.txt60
-rw-r--r--Documentation/sound/alsa/DocBook/alsa-driver-api.tmpl4
-rw-r--r--Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl33
-rw-r--r--Documentation/sound/alsa/hda_codec.txt10
-rw-r--r--Documentation/sound/alsa/soc/DAI.txt56
-rw-r--r--Documentation/sound/alsa/soc/clocking.txt51
-rw-r--r--Documentation/sound/alsa/soc/codec.txt197
-rw-r--r--Documentation/sound/alsa/soc/dapm.txt297
-rw-r--r--Documentation/sound/alsa/soc/machine.txt113
-rw-r--r--Documentation/sound/alsa/soc/overview.txt83
-rw-r--r--Documentation/sound/alsa/soc/platform.txt58
-rw-r--r--Documentation/sound/alsa/soc/pops_clicks.txt52
12 files changed, 982 insertions, 32 deletions
diff --git a/Documentation/sound/alsa/ALSA-Configuration.txt b/Documentation/sound/alsa/ALSA-Configuration.txt
index 9fef210ab50a..c30ff1bb2d10 100644
--- a/Documentation/sound/alsa/ALSA-Configuration.txt
+++ b/Documentation/sound/alsa/ALSA-Configuration.txt
@@ -242,6 +242,12 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
242 ac97_clock - AC'97 clock (default = 48000) 242 ac97_clock - AC'97 clock (default = 48000)
243 ac97_quirk - AC'97 workaround for strange hardware 243 ac97_quirk - AC'97 workaround for strange hardware
244 See "AC97 Quirk Option" section below. 244 See "AC97 Quirk Option" section below.
245 ac97_codec - Workaround to specify which AC'97 codec
246 instead of probing. If this works for you
247 file a bug with your `lspci -vn` output.
248 -2 -- Force probing.
249 -1 -- Default behavior.
250 0-2 -- Use the specified codec.
245 spdif_aclink - S/PDIF transfer over AC-link (default = 1) 251 spdif_aclink - S/PDIF transfer over AC-link (default = 1)
246 252
247 This module supports one card and autoprobe. 253 This module supports one card and autoprobe.
@@ -779,6 +785,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
779 asus-dig ASUS with SPDIF out 785 asus-dig ASUS with SPDIF out
780 asus-dig2 ASUS with SPDIF out (using GPIO2) 786 asus-dig2 ASUS with SPDIF out (using GPIO2)
781 uniwill 3-jack 787 uniwill 3-jack
788 fujitsu Fujitsu Laptops (Pi1536)
782 F1734 2-jack 789 F1734 2-jack
783 lg LG laptop (m1 express dual) 790 lg LG laptop (m1 express dual)
784 lg-lw LG LW20/LW25 laptop 791 lg-lw LG LW20/LW25 laptop
@@ -800,14 +807,18 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
800 ALC262 807 ALC262
801 fujitsu Fujitsu Laptop 808 fujitsu Fujitsu Laptop
802 hp-bpc HP xw4400/6400/8400/9400 laptops 809 hp-bpc HP xw4400/6400/8400/9400 laptops
810 hp-bpc-d7000 HP BPC D7000
803 benq Benq ED8 811 benq Benq ED8
812 hippo Hippo (ATI) with jack detection, Sony UX-90s
813 hippo_1 Hippo (Benq) with jack detection
804 basic fixed pin assignment w/o SPDIF 814 basic fixed pin assignment w/o SPDIF
805 auto auto-config reading BIOS (default) 815 auto auto-config reading BIOS (default)
806 816
807 ALC882/885 817 ALC882/885
808 3stack-dig 3-jack with SPDIF I/O 818 3stack-dig 3-jack with SPDIF I/O
809 6stck-dig 6-jack digital with SPDIF I/O 819 6stack-dig 6-jack digital with SPDIF I/O
810 arima Arima W820Di1 820 arima Arima W820Di1
821 macpro MacPro support
811 auto auto-config reading BIOS (default) 822 auto auto-config reading BIOS (default)
812 823
813 ALC883/888 824 ALC883/888
@@ -817,6 +828,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
817 3stack-6ch-dig 3-jack 6-channel with SPDIF I/O 828 3stack-6ch-dig 3-jack 6-channel with SPDIF I/O
818 6stack-dig-demo 6-jack digital for Intel demo board 829 6stack-dig-demo 6-jack digital for Intel demo board
819 acer Acer laptops (Travelmate 3012WTMi, Aspire 5600, etc) 830 acer Acer laptops (Travelmate 3012WTMi, Aspire 5600, etc)
831 medion Medion Laptops
832 targa-dig Targa/MSI
833 targa-2ch-dig Targs/MSI with 2-channel
834 laptop-eapd 3-jack with SPDIF I/O and EAPD (Clevo M540JE, M550JE)
820 auto auto-config reading BIOS (default) 835 auto auto-config reading BIOS (default)
821 836
822 ALC861/660 837 ALC861/660
@@ -825,6 +840,16 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
825 6stack-dig 6-jack with SPDIF I/O 840 6stack-dig 6-jack with SPDIF I/O
826 3stack-660 3-jack (for ALC660) 841 3stack-660 3-jack (for ALC660)
827 uniwill-m31 Uniwill M31 laptop 842 uniwill-m31 Uniwill M31 laptop
843 toshiba Toshiba laptop support
844 asus Asus laptop support
845 asus-laptop ASUS F2/F3 laptops
846 auto auto-config reading BIOS (default)
847
848 ALC861VD/660VD
849 3stack 3-jack
850 3stack-dig 3-jack with SPDIF OUT
851 6stack-dig 6-jack with SPDIF OUT
852 3stack-660 3-jack (for ALC660VD)
828 auto auto-config reading BIOS (default) 853 auto auto-config reading BIOS (default)
829 854
830 CMI9880 855 CMI9880
@@ -845,6 +870,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
845 3stack 3-stack, shared surrounds 870 3stack 3-stack, shared surrounds
846 laptop 2-channel only (FSC V2060, Samsung M50) 871 laptop 2-channel only (FSC V2060, Samsung M50)
847 laptop-eapd 2-channel with EAPD (Samsung R65, ASUS A6J) 872 laptop-eapd 2-channel with EAPD (Samsung R65, ASUS A6J)
873 ultra 2-channel with EAPD (Samsung Ultra tablet PC)
848 874
849 AD1988 875 AD1988
850 6stack 6-jack 876 6stack 6-jack
@@ -854,12 +880,31 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
854 laptop 3-jack with hp-jack automute 880 laptop 3-jack with hp-jack automute
855 laptop-dig ditto with SPDIF 881 laptop-dig ditto with SPDIF
856 auto auto-config reading BIOS (default) 882 auto auto-config reading BIOS (default)
883
884 Conexant 5045
885 laptop Laptop config
886 test for testing/debugging purpose, almost all controls
887 can be adjusted. Appearing only when compiled with
888 $CONFIG_SND_DEBUG=y
889
890 Conexant 5047
891 laptop Basic Laptop config
892 laptop-hp Laptop config for some HP models (subdevice 30A5)
893 laptop-eapd Laptop config with EAPD support
894 test for testing/debugging purpose, almost all controls
895 can be adjusted. Appearing only when compiled with
896 $CONFIG_SND_DEBUG=y
857 897
858 STAC9200/9205/9220/9221/9254 898 STAC9200/9205/9220/9221/9254
859 ref Reference board 899 ref Reference board
860 3stack D945 3stack 900 3stack D945 3stack
861 5stack D945 5stack + SPDIF 901 5stack D945 5stack + SPDIF
862 902
903 STAC9202/9250/9251
904 ref Reference board, base config
905 m2-2 Some Gateway MX series laptops
906 m6 Some Gateway NX series laptops
907
863 STAC9227/9228/9229/927x 908 STAC9227/9228/9229/927x
864 ref Reference board 909 ref Reference board
865 3stack D965 3stack 910 3stack D965 3stack
@@ -974,6 +1019,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
974 Module for Envy24HT (VT/ICE1724), Envy24PT (VT1720) based PCI sound cards. 1019 Module for Envy24HT (VT/ICE1724), Envy24PT (VT1720) based PCI sound cards.
975 * MidiMan M Audio Revolution 5.1 1020 * MidiMan M Audio Revolution 5.1
976 * MidiMan M Audio Revolution 7.1 1021 * MidiMan M Audio Revolution 7.1
1022 * MidiMan M Audio Audiophile 192
977 * AMP Ltd AUDIO2000 1023 * AMP Ltd AUDIO2000
978 * TerraTec Aureon 5.1 Sky 1024 * TerraTec Aureon 5.1 Sky
979 * TerraTec Aureon 7.1 Space 1025 * TerraTec Aureon 7.1 Space
@@ -993,7 +1039,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
993 1039
994 model - Use the given board model, one of the following: 1040 model - Use the given board model, one of the following:
995 revo51, revo71, amp2000, prodigy71, prodigy71lt, 1041 revo51, revo71, amp2000, prodigy71, prodigy71lt,
996 prodigy192, aureon51, aureon71, universe, 1042 prodigy192, aureon51, aureon71, universe, ap192,
997 k8x800, phase22, phase28, ms300, av710 1043 k8x800, phase22, phase28, ms300, av710
998 1044
999 This module supports multiple cards and autoprobe. 1045 This module supports multiple cards and autoprobe.
@@ -1049,6 +1095,9 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
1049 buggy_semaphore - Enable workaround for hardwares with buggy 1095 buggy_semaphore - Enable workaround for hardwares with buggy
1050 semaphores (e.g. on some ASUS laptops) 1096 semaphores (e.g. on some ASUS laptops)
1051 (default off) 1097 (default off)
1098 spdif_aclink - Use S/PDIF over AC-link instead of direct connection
1099 from the controller chip
1100 (0 = off, 1 = on, -1 = default)
1052 1101
1053 This module supports one chip and autoprobe. 1102 This module supports one chip and autoprobe.
1054 1103
@@ -1371,6 +1420,13 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
1371 1420
1372 This module supports multiple cards. 1421 This module supports multiple cards.
1373 1422
1423 Module snd-portman2x4
1424 ---------------------
1425
1426 Module for Midiman Portman 2x4 parallel port MIDI interface
1427
1428 This module supports multiple cards.
1429
1374 Module snd-powermac (on ppc only) 1430 Module snd-powermac (on ppc only)
1375 --------------------------------- 1431 ---------------------------------
1376 1432
diff --git a/Documentation/sound/alsa/DocBook/alsa-driver-api.tmpl b/Documentation/sound/alsa/DocBook/alsa-driver-api.tmpl
index 1f3ae3e32d69..c4d2e3507af9 100644
--- a/Documentation/sound/alsa/DocBook/alsa-driver-api.tmpl
+++ b/Documentation/sound/alsa/DocBook/alsa-driver-api.tmpl
@@ -36,7 +36,7 @@
36 </bookinfo> 36 </bookinfo>
37 37
38 <chapter><title>Management of Cards and Devices</title> 38 <chapter><title>Management of Cards and Devices</title>
39 <sect1><title>Card Managment</title> 39 <sect1><title>Card Management</title>
40!Esound/core/init.c 40!Esound/core/init.c
41 </sect1> 41 </sect1>
42 <sect1><title>Device Components</title> 42 <sect1><title>Device Components</title>
@@ -59,7 +59,7 @@
59 <sect1><title>PCM Format Helpers</title> 59 <sect1><title>PCM Format Helpers</title>
60!Esound/core/pcm_misc.c 60!Esound/core/pcm_misc.c
61 </sect1> 61 </sect1>
62 <sect1><title>PCM Memory Managment</title> 62 <sect1><title>PCM Memory Management</title>
63!Esound/core/pcm_memory.c 63!Esound/core/pcm_memory.c
64 </sect1> 64 </sect1>
65 </chapter> 65 </chapter>
diff --git a/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl b/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl
index ccd0a953953d..74d3a35b59bc 100644
--- a/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl
+++ b/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl
@@ -1360,8 +1360,7 @@
1360 <informalexample> 1360 <informalexample>
1361 <programlisting> 1361 <programlisting>
1362<![CDATA[ 1362<![CDATA[
1363 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id, 1363 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
1364 struct pt_regs *regs)
1365 { 1364 {
1366 struct mychip *chip = dev_id; 1365 struct mychip *chip = dev_id;
1367 .... 1366 ....
@@ -2127,7 +2126,7 @@
2127 accessible via <constant>substream-&gt;runtime</constant>. 2126 accessible via <constant>substream-&gt;runtime</constant>.
2128 This runtime pointer holds the various information; it holds 2127 This runtime pointer holds the various information; it holds
2129 the copy of hw_params and sw_params configurations, the buffer 2128 the copy of hw_params and sw_params configurations, the buffer
2130 pointers, mmap records, spinlocks, etc. Almost everyhing you 2129 pointers, mmap records, spinlocks, etc. Almost everything you
2131 need for controlling the PCM can be found there. 2130 need for controlling the PCM can be found there.
2132 </para> 2131 </para>
2133 2132
@@ -2340,7 +2339,7 @@ struct _snd_pcm_runtime {
2340 2339
2341 <para> 2340 <para>
2342 When the PCM substreams can be synchronized (typically, 2341 When the PCM substreams can be synchronized (typically,
2343 synchorinized start/stop of a playback and a capture streams), 2342 synchronized start/stop of a playback and a capture streams),
2344 you can give <constant>SNDRV_PCM_INFO_SYNC_START</constant>, 2343 you can give <constant>SNDRV_PCM_INFO_SYNC_START</constant>,
2345 too. In this case, you'll need to check the linked-list of 2344 too. In this case, you'll need to check the linked-list of
2346 PCM substreams in the trigger callback. This will be 2345 PCM substreams in the trigger callback. This will be
@@ -3062,8 +3061,7 @@ struct _snd_pcm_runtime {
3062 <title>Interrupt Handler Case #1</title> 3061 <title>Interrupt Handler Case #1</title>
3063 <programlisting> 3062 <programlisting>
3064<![CDATA[ 3063<![CDATA[
3065 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id, 3064 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
3066 struct pt_regs *regs)
3067 { 3065 {
3068 struct mychip *chip = dev_id; 3066 struct mychip *chip = dev_id;
3069 spin_lock(&chip->lock); 3067 spin_lock(&chip->lock);
@@ -3106,8 +3104,7 @@ struct _snd_pcm_runtime {
3106 <title>Interrupt Handler Case #2</title> 3104 <title>Interrupt Handler Case #2</title>
3107 <programlisting> 3105 <programlisting>
3108<![CDATA[ 3106<![CDATA[
3109 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id, 3107 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
3110 struct pt_regs *regs)
3111 { 3108 {
3112 struct mychip *chip = dev_id; 3109 struct mychip *chip = dev_id;
3113 spin_lock(&chip->lock); 3110 spin_lock(&chip->lock);
@@ -3247,7 +3244,7 @@ struct _snd_pcm_runtime {
3247 You can even define your own constraint rules. 3244 You can even define your own constraint rules.
3248 For example, let's suppose my_chip can manage a substream of 1 channel 3245 For example, let's suppose my_chip can manage a substream of 1 channel
3249 if and only if the format is S16_LE, otherwise it supports any format 3246 if and only if the format is S16_LE, otherwise it supports any format
3250 specified in the <structname>snd_pcm_hardware</structname> stucture (or in any 3247 specified in the <structname>snd_pcm_hardware</structname> structure (or in any
3251 other constraint_list). You can build a rule like this: 3248 other constraint_list). You can build a rule like this:
3252 3249
3253 <example> 3250 <example>
@@ -3691,16 +3688,6 @@ struct _snd_pcm_runtime {
3691 </para> 3688 </para>
3692 3689
3693 <para> 3690 <para>
3694 Here, the chip instance is retrieved via
3695 <function>snd_kcontrol_chip()</function> macro. This macro
3696 just accesses to kcontrol-&gt;private_data. The
3697 kcontrol-&gt;private_data field is
3698 given as the argument of <function>snd_ctl_new()</function>
3699 (see the later subsection
3700 <link linkend="control-interface-constructor"><citetitle>Constructor</citetitle></link>).
3701 </para>
3702
3703 <para>
3704 The <structfield>value</structfield> field is depending on 3691 The <structfield>value</structfield> field is depending on
3705 the type of control as well as on info callback. For example, 3692 the type of control as well as on info callback. For example,
3706 the sb driver uses this field to store the register offset, 3693 the sb driver uses this field to store the register offset,
@@ -3780,7 +3767,7 @@ struct _snd_pcm_runtime {
3780 <para> 3767 <para>
3781 Like <structfield>get</structfield> callback, 3768 Like <structfield>get</structfield> callback,
3782 when the control has more than one elements, 3769 when the control has more than one elements,
3783 all elemehts must be evaluated in this callback, too. 3770 all elements must be evaluated in this callback, too.
3784 </para> 3771 </para>
3785 </section> 3772 </section>
3786 3773
@@ -5541,12 +5528,12 @@ struct _snd_pcm_runtime {
5541 #ifdef CONFIG_PM 5528 #ifdef CONFIG_PM
5542 static int snd_my_suspend(struct pci_dev *pci, pm_message_t state) 5529 static int snd_my_suspend(struct pci_dev *pci, pm_message_t state)
5543 { 5530 {
5544 .... /* do things for suspsend */ 5531 .... /* do things for suspend */
5545 return 0; 5532 return 0;
5546 } 5533 }
5547 static int snd_my_resume(struct pci_dev *pci) 5534 static int snd_my_resume(struct pci_dev *pci)
5548 { 5535 {
5549 .... /* do things for suspsend */ 5536 .... /* do things for suspend */
5550 return 0; 5537 return 0;
5551 } 5538 }
5552 #endif 5539 #endif
@@ -6111,7 +6098,7 @@ struct _snd_pcm_runtime {
6111<!-- ****************************************************** --> 6098<!-- ****************************************************** -->
6112<!-- Acknowledgments --> 6099<!-- Acknowledgments -->
6113<!-- ****************************************************** --> 6100<!-- ****************************************************** -->
6114 <chapter id="acknowledments"> 6101 <chapter id="acknowledgments">
6115 <title>Acknowledgments</title> 6102 <title>Acknowledgments</title>
6116 <para> 6103 <para>
6117 I would like to thank Phil Kerr for his help for improvement and 6104 I would like to thank Phil Kerr for his help for improvement and
diff --git a/Documentation/sound/alsa/hda_codec.txt b/Documentation/sound/alsa/hda_codec.txt
index 0be57ed81302..4eaae2a45534 100644
--- a/Documentation/sound/alsa/hda_codec.txt
+++ b/Documentation/sound/alsa/hda_codec.txt
@@ -277,11 +277,11 @@ Helper Functions
277snd_hda_get_codec_name() stores the codec name on the given string. 277snd_hda_get_codec_name() stores the codec name on the given string.
278 278
279snd_hda_check_board_config() can be used to obtain the configuration 279snd_hda_check_board_config() can be used to obtain the configuration
280information matching with the device. Define the table with struct 280information matching with the device. Define the model string table
281hda_board_config entries (zero-terminated), and pass it to the 281and the table with struct snd_pci_quirk entries (zero-terminated),
282function. The function checks the modelname given as a module 282and pass it to the function. The function checks the modelname given
283parameter, and PCI subsystem IDs. If the matching entry is found, it 283as a module parameter, and PCI subsystem IDs. If the matching entry
284returns the config field value. 284is found, it returns the config field value.
285 285
286snd_hda_add_new_ctls() can be used to create and add control entries. 286snd_hda_add_new_ctls() can be used to create and add control entries.
287Pass the zero-terminated array of struct snd_kcontrol_new. The same array 287Pass the zero-terminated array of struct snd_kcontrol_new. The same array
diff --git a/Documentation/sound/alsa/soc/DAI.txt b/Documentation/sound/alsa/soc/DAI.txt
new file mode 100644
index 000000000000..58cbfd01ea8f
--- /dev/null
+++ b/Documentation/sound/alsa/soc/DAI.txt
@@ -0,0 +1,56 @@
1ASoC currently supports the three main Digital Audio Interfaces (DAI) found on
2SoC controllers and portable audio CODECS today, namely AC97, I2S and PCM.
3
4
5AC97
6====
7
8 AC97 is a five wire interface commonly found on many PC sound cards. It is
9now also popular in many portable devices. This DAI has a reset line and time
10multiplexes its data on its SDATA_OUT (playback) and SDATA_IN (capture) lines.
11The bit clock (BCLK) is always driven by the CODEC (usually 12.288MHz) and the
12frame (FRAME) (usually 48kHz) is always driven by the controller. Each AC97
13frame is 21uS long and is divided into 13 time slots.
14
15The AC97 specification can be found at :-
16http://www.intel.com/design/chipsets/audio/ac97_r23.pdf
17
18
19I2S
20===
21
22 I2S is a common 4 wire DAI used in HiFi, STB and portable devices. The Tx and
23Rx lines are used for audio transmision, whilst the bit clock (BCLK) and
24left/right clock (LRC) synchronise the link. I2S is flexible in that either the
25controller or CODEC can drive (master) the BCLK and LRC clock lines. Bit clock
26usually varies depending on the sample rate and the master system clock
27(SYSCLK). LRCLK is the same as the sample rate. A few devices support separate
28ADC and DAC LRCLK's, this allows for similtanious capture and playback at
29different sample rates.
30
31I2S has several different operating modes:-
32
33 o I2S - MSB is transmitted on the falling edge of the first BCLK after LRC
34 transition.
35
36 o Left Justified - MSB is transmitted on transition of LRC.
37
38 o Right Justified - MSB is transmitted sample size BCLK's before LRC
39 transition.
40
41PCM
42===
43
44PCM is another 4 wire interface, very similar to I2S, that can support a more
45flexible protocol. It has bit clock (BCLK) and sync (SYNC) lines that are used
46to synchronise the link whilst the Tx and Rx lines are used to transmit and
47receive the audio data. Bit clock usually varies depending on sample rate
48whilst sync runs at the sample rate. PCM also supports Time Division
49Multiplexing (TDM) in that several devices can use the bus similtaniuosly (This
50is sometimes referred to as network mode).
51
52Common PCM operating modes:-
53
54 o Mode A - MSB is transmitted on falling edge of first BCLK after FRAME/SYNC.
55
56 o Mode B - MSB is transmitted on rising edge of FRAME/SYNC.
diff --git a/Documentation/sound/alsa/soc/clocking.txt b/Documentation/sound/alsa/soc/clocking.txt
new file mode 100644
index 000000000000..e93960d53a1e
--- /dev/null
+++ b/Documentation/sound/alsa/soc/clocking.txt
@@ -0,0 +1,51 @@
1Audio Clocking
2==============
3
4This text describes the audio clocking terms in ASoC and digital audio in
5general. Note: Audio clocking can be complex !
6
7
8Master Clock
9------------
10
11Every audio subsystem is driven by a master clock (sometimes refered to as MCLK
12or SYSCLK). This audio master clock can be derived from a number of sources
13(e.g. crystal, PLL, CPU clock) and is responsible for producing the correct
14audio playback and capture sample rates.
15
16Some master clocks (e.g. PLL's and CPU based clocks) are configuarble in that
17their speed can be altered by software (depending on the system use and to save
18power). Other master clocks are fixed at at set frequency (i.e. crystals).
19
20
21DAI Clocks
22----------
23The Digital Audio Interface is usually driven by a Bit Clock (often referred to
24as BCLK). This clock is used to drive the digital audio data across the link
25between the codec and CPU.
26
27The DAI also has a frame clock to signal the start of each audio frame. This
28clock is sometimes referred to as LRC (left right clock) or FRAME. This clock
29runs at exactly the sample rate (LRC = Rate).
30
31Bit Clock can be generated as follows:-
32
33BCLK = MCLK / x
34
35 or
36
37BCLK = LRC * x
38
39 or
40
41BCLK = LRC * Channels * Word Size
42
43This relationship depends on the codec or SoC CPU in particular. In general
44it's best to configure BCLK to the lowest possible speed (depending on your
45rate, number of channels and wordsize) to save on power.
46
47It's also desireable to use the codec (if possible) to drive (or master) the
48audio clocks as it's usually gives more accurate sample rates than the CPU.
49
50
51
diff --git a/Documentation/sound/alsa/soc/codec.txt b/Documentation/sound/alsa/soc/codec.txt
new file mode 100644
index 000000000000..48983c75aad9
--- /dev/null
+++ b/Documentation/sound/alsa/soc/codec.txt
@@ -0,0 +1,197 @@
1ASoC Codec Driver
2=================
3
4The codec driver is generic and hardware independent code that configures the
5codec to provide audio capture and playback. It should contain no code that is
6specific to the target platform or machine. All platform and machine specific
7code should be added to the platform and machine drivers respectively.
8
9Each codec driver *must* provide the following features:-
10
11 1) Codec DAI and PCM configuration
12 2) Codec control IO - using I2C, 3 Wire(SPI) or both API's
13 3) Mixers and audio controls
14 4) Codec audio operations
15
16Optionally, codec drivers can also provide:-
17
18 5) DAPM description.
19 6) DAPM event handler.
20 7) DAC Digital mute control.
21
22It's probably best to use this guide in conjuction with the existing codec
23driver code in sound/soc/codecs/
24
25ASoC Codec driver breakdown
26===========================
27
281 - Codec DAI and PCM configuration
29-----------------------------------
30Each codec driver must have a struct snd_soc_codec_dai to define it's DAI and
31PCM's capablities and operations. This struct is exported so that it can be
32registered with the core by your machine driver.
33
34e.g.
35
36struct snd_soc_codec_dai wm8731_dai = {
37 .name = "WM8731",
38 /* playback capabilities */
39 .playback = {
40 .stream_name = "Playback",
41 .channels_min = 1,
42 .channels_max = 2,
43 .rates = WM8731_RATES,
44 .formats = WM8731_FORMATS,},
45 /* capture capabilities */
46 .capture = {
47 .stream_name = "Capture",
48 .channels_min = 1,
49 .channels_max = 2,
50 .rates = WM8731_RATES,
51 .formats = WM8731_FORMATS,},
52 /* pcm operations - see section 4 below */
53 .ops = {
54 .prepare = wm8731_pcm_prepare,
55 .hw_params = wm8731_hw_params,
56 .shutdown = wm8731_shutdown,
57 },
58 /* DAI operations - see DAI.txt */
59 .dai_ops = {
60 .digital_mute = wm8731_mute,
61 .set_sysclk = wm8731_set_dai_sysclk,
62 .set_fmt = wm8731_set_dai_fmt,
63 }
64};
65EXPORT_SYMBOL_GPL(wm8731_dai);
66
67
682 - Codec control IO
69--------------------
70The codec can ususally be controlled via an I2C or SPI style interface (AC97
71combines control with data in the DAI). The codec drivers will have to provide
72functions to read and write the codec registers along with supplying a register
73cache:-
74
75 /* IO control data and register cache */
76 void *control_data; /* codec control (i2c/3wire) data */
77 void *reg_cache;
78
79Codec read/write should do any data formatting and call the hardware read write
80below to perform the IO. These functions are called by the core and alsa when
81performing DAPM or changing the mixer:-
82
83 unsigned int (*read)(struct snd_soc_codec *, unsigned int);
84 int (*write)(struct snd_soc_codec *, unsigned int, unsigned int);
85
86Codec hardware IO functions - usually points to either the I2C, SPI or AC97
87read/write:-
88
89 hw_write_t hw_write;
90 hw_read_t hw_read;
91
92
933 - Mixers and audio controls
94-----------------------------
95All the codec mixers and audio controls can be defined using the convenience
96macros defined in soc.h.
97
98 #define SOC_SINGLE(xname, reg, shift, mask, invert)
99
100Defines a single control as follows:-
101
102 xname = Control name e.g. "Playback Volume"
103 reg = codec register
104 shift = control bit(s) offset in register
105 mask = control bit size(s) e.g. mask of 7 = 3 bits
106 invert = the control is inverted
107
108Other macros include:-
109
110 #define SOC_DOUBLE(xname, reg, shift_left, shift_right, mask, invert)
111
112A stereo control
113
114 #define SOC_DOUBLE_R(xname, reg_left, reg_right, shift, mask, invert)
115
116A stereo control spanning 2 registers
117
118 #define SOC_ENUM_SINGLE(xreg, xshift, xmask, xtexts)
119
120Defines an single enumerated control as follows:-
121
122 xreg = register
123 xshift = control bit(s) offset in register
124 xmask = control bit(s) size
125 xtexts = pointer to array of strings that describe each setting
126
127 #define SOC_ENUM_DOUBLE(xreg, xshift_l, xshift_r, xmask, xtexts)
128
129Defines a stereo enumerated control
130
131
1324 - Codec Audio Operations
133--------------------------
134The codec driver also supports the following alsa operations:-
135
136/* SoC audio ops */
137struct snd_soc_ops {
138 int (*startup)(struct snd_pcm_substream *);
139 void (*shutdown)(struct snd_pcm_substream *);
140 int (*hw_params)(struct snd_pcm_substream *, struct snd_pcm_hw_params *);
141 int (*hw_free)(struct snd_pcm_substream *);
142 int (*prepare)(struct snd_pcm_substream *);
143};
144
145Please refer to the alsa driver PCM documentation for details.
146http://www.alsa-project.org/~iwai/writing-an-alsa-driver/c436.htm
147
148
1495 - DAPM description.
150---------------------
151The Dynamic Audio Power Management description describes the codec's power
152components, their relationships and registers to the ASoC core. Please read
153dapm.txt for details of building the description.
154
155Please also see the examples in other codec drivers.
156
157
1586 - DAPM event handler
159----------------------
160This function is a callback that handles codec domain PM calls and system
161domain PM calls (e.g. suspend and resume). It's used to put the codec to sleep
162when not in use.
163
164Power states:-
165
166 SNDRV_CTL_POWER_D0: /* full On */
167 /* vref/mid, clk and osc on, active */
168
169 SNDRV_CTL_POWER_D1: /* partial On */
170 SNDRV_CTL_POWER_D2: /* partial On */
171
172 SNDRV_CTL_POWER_D3hot: /* Off, with power */
173 /* everything off except vref/vmid, inactive */
174
175 SNDRV_CTL_POWER_D3cold: /* Everything Off, without power */
176
177
1787 - Codec DAC digital mute control.
179------------------------------------
180Most codecs have a digital mute before the DAC's that can be used to minimise
181any system noise. The mute stops any digital data from entering the DAC.
182
183A callback can be created that is called by the core for each codec DAI when the
184mute is applied or freed.
185
186i.e.
187
188static int wm8974_mute(struct snd_soc_codec *codec,
189 struct snd_soc_codec_dai *dai, int mute)
190{
191 u16 mute_reg = wm8974_read_reg_cache(codec, WM8974_DAC) & 0xffbf;
192 if(mute)
193 wm8974_write(codec, WM8974_DAC, mute_reg | 0x40);
194 else
195 wm8974_write(codec, WM8974_DAC, mute_reg);
196 return 0;
197}
diff --git a/Documentation/sound/alsa/soc/dapm.txt b/Documentation/sound/alsa/soc/dapm.txt
new file mode 100644
index 000000000000..c11877f5b4a1
--- /dev/null
+++ b/Documentation/sound/alsa/soc/dapm.txt
@@ -0,0 +1,297 @@
1Dynamic Audio Power Management for Portable Devices
2===================================================
3
41. Description
5==============
6
7Dynamic Audio Power Management (DAPM) is designed to allow portable Linux devices
8to use the minimum amount of power within the audio subsystem at all times. It
9is independent of other kernel PM and as such, can easily co-exist with the
10other PM systems.
11
12DAPM is also completely transparent to all user space applications as all power
13switching is done within the ASoC core. No code changes or recompiling are
14required for user space applications. DAPM makes power switching descisions based
15upon any audio stream (capture/playback) activity and audio mixer settings
16within the device.
17
18DAPM spans the whole machine. It covers power control within the entire audio
19subsystem, this includes internal codec power blocks and machine level power
20systems.
21
22There are 4 power domains within DAPM
23
24 1. Codec domain - VREF, VMID (core codec and audio power)
25 Usually controlled at codec probe/remove and suspend/resume, although
26 can be set at stream time if power is not needed for sidetone, etc.
27
28 2. Platform/Machine domain - physically connected inputs and outputs
29 Is platform/machine and user action specific, is configured by the
30 machine driver and responds to asynchronous events e.g when HP
31 are inserted
32
33 3. Path domain - audio susbsystem signal paths
34 Automatically set when mixer and mux settings are changed by the user.
35 e.g. alsamixer, amixer.
36
37 4. Stream domain - DAC's and ADC's.
38 Enabled and disabled when stream playback/capture is started and
39 stopped respectively. e.g. aplay, arecord.
40
41All DAPM power switching descisons are made automatically by consulting an audio
42routing map of the whole machine. This map is specific to each machine and
43consists of the interconnections between every audio component (including
44internal codec components). All audio components that effect power are called
45widgets hereafter.
46
47
482. DAPM Widgets
49===============
50
51Audio DAPM widgets fall into a number of types:-
52
53 o Mixer - Mixes several analog signals into a single analog signal.
54 o Mux - An analog switch that outputs only 1 of it's inputs.
55 o PGA - A programmable gain amplifier or attenuation widget.
56 o ADC - Analog to Digital Converter
57 o DAC - Digital to Analog Converter
58 o Switch - An analog switch
59 o Input - A codec input pin
60 o Output - A codec output pin
61 o Headphone - Headphone (and optional Jack)
62 o Mic - Mic (and optional Jack)
63 o Line - Line Input/Output (and optional Jack)
64 o Speaker - Speaker
65 o Pre - Special PRE widget (exec before all others)
66 o Post - Special POST widget (exec after all others)
67
68(Widgets are defined in include/sound/soc-dapm.h)
69
70Widgets are usually added in the codec driver and the machine driver. There are
71convience macros defined in soc-dapm.h that can be used to quickly build a
72list of widgets of the codecs and machines DAPM widgets.
73
74Most widgets have a name, register, shift and invert. Some widgets have extra
75parameters for stream name and kcontrols.
76
77
782.1 Stream Domain Widgets
79-------------------------
80
81Stream Widgets relate to the stream power domain and only consist of ADC's
82(analog to digital converters) and DAC's (digital to analog converters).
83
84Stream widgets have the following format:-
85
86SND_SOC_DAPM_DAC(name, stream name, reg, shift, invert),
87
88NOTE: the stream name must match the corresponding stream name in your codecs
89snd_soc_codec_dai.
90
91e.g. stream widgets for HiFi playback and capture
92
93SND_SOC_DAPM_DAC("HiFi DAC", "HiFi Playback", REG, 3, 1),
94SND_SOC_DAPM_ADC("HiFi ADC", "HiFi Capture", REG, 2, 1),
95
96
972.2 Path Domain Widgets
98-----------------------
99
100Path domain widgets have a ability to control or effect the audio signal or
101audio paths within the audio subsystem. They have the following form:-
102
103SND_SOC_DAPM_PGA(name, reg, shift, invert, controls, num_controls)
104
105Any widget kcontrols can be set using the controls and num_controls members.
106
107e.g. Mixer widget (the kcontrols are declared first)
108
109/* Output Mixer */
110static const snd_kcontrol_new_t wm8731_output_mixer_controls[] = {
111SOC_DAPM_SINGLE("Line Bypass Switch", WM8731_APANA, 3, 1, 0),
112SOC_DAPM_SINGLE("Mic Sidetone Switch", WM8731_APANA, 5, 1, 0),
113SOC_DAPM_SINGLE("HiFi Playback Switch", WM8731_APANA, 4, 1, 0),
114};
115
116SND_SOC_DAPM_MIXER("Output Mixer", WM8731_PWR, 4, 1, wm8731_output_mixer_controls,
117 ARRAY_SIZE(wm8731_output_mixer_controls)),
118
119
1202.3 Platform/Machine domain Widgets
121-----------------------------------
122
123Machine widgets are different from codec widgets in that they don't have a
124codec register bit associated with them. A machine widget is assigned to each
125machine audio component (non codec) that can be independently powered. e.g.
126
127 o Speaker Amp
128 o Microphone Bias
129 o Jack connectors
130
131A machine widget can have an optional call back.
132
133e.g. Jack connector widget for an external Mic that enables Mic Bias
134when the Mic is inserted:-
135
136static int spitz_mic_bias(struct snd_soc_dapm_widget* w, int event)
137{
138 if(SND_SOC_DAPM_EVENT_ON(event))
139 set_scoop_gpio(&spitzscoop2_device.dev, SPITZ_SCP2_MIC_BIAS);
140 else
141 reset_scoop_gpio(&spitzscoop2_device.dev, SPITZ_SCP2_MIC_BIAS);
142
143 return 0;
144}
145
146SND_SOC_DAPM_MIC("Mic Jack", spitz_mic_bias),
147
148
1492.4 Codec Domain
150----------------
151
152The Codec power domain has no widgets and is handled by the codecs DAPM event
153handler. This handler is called when the codec powerstate is changed wrt to any
154stream event or by kernel PM events.
155
156
1572.5 Virtual Widgets
158-------------------
159
160Sometimes widgets exist in the codec or machine audio map that don't have any
161corresponding register bit for power control. In this case it's necessary to
162create a virtual widget - a widget with no control bits e.g.
163
164SND_SOC_DAPM_MIXER("AC97 Mixer", SND_SOC_DAPM_NOPM, 0, 0, NULL, 0),
165
166This can be used to merge to signal paths together in software.
167
168After all the widgets have been defined, they can then be added to the DAPM
169subsystem individually with a call to snd_soc_dapm_new_control().
170
171
1723. Codec Widget Interconnections
173================================
174
175Widgets are connected to each other within the codec and machine by audio
176paths (called interconnections). Each interconnection must be defined in order
177to create a map of all audio paths between widgets.
178This is easiest with a diagram of the codec (and schematic of the machine audio
179system), as it requires joining widgets together via their audio signal paths.
180
181i.e. from the WM8731 codec's output mixer (wm8731.c)
182
183The WM8731 output mixer has 3 inputs (sources)
184
185 1. Line Bypass Input
186 2. DAC (HiFi playback)
187 3. Mic Sidetone Input
188
189Each input in this example has a kcontrol associated with it (defined in example
190above) and is connected to the output mixer via it's kcontrol name. We can now
191connect the destination widget (wrt audio signal) with it's source widgets.
192
193 /* output mixer */
194 {"Output Mixer", "Line Bypass Switch", "Line Input"},
195 {"Output Mixer", "HiFi Playback Switch", "DAC"},
196 {"Output Mixer", "Mic Sidetone Switch", "Mic Bias"},
197
198So we have :-
199
200 Destination Widget <=== Path Name <=== Source Widget
201
202Or:-
203
204 Sink, Path, Source
205
206Or :-
207
208 "Output Mixer" is connected to the "DAC" via the "HiFi Playback Switch".
209
210When there is no path name connecting widgets (e.g. a direct connection) we
211pass NULL for the path name.
212
213Interconnections are created with a call to:-
214
215snd_soc_dapm_connect_input(codec, sink, path, source);
216
217Finally, snd_soc_dapm_new_widgets(codec) must be called after all widgets and
218interconnections have been registered with the core. This causes the core to
219scan the codec and machine so that the internal DAPM state matches the
220physical state of the machine.
221
222
2233.1 Machine Widget Interconnections
224-----------------------------------
225Machine widget interconnections are created in the same way as codec ones and
226directly connect the codec pins to machine level widgets.
227
228e.g. connects the speaker out codec pins to the internal speaker.
229
230 /* ext speaker connected to codec pins LOUT2, ROUT2 */
231 {"Ext Spk", NULL , "ROUT2"},
232 {"Ext Spk", NULL , "LOUT2"},
233
234This allows the DAPM to power on and off pins that are connected (and in use)
235and pins that are NC respectively.
236
237
2384 Endpoint Widgets
239===================
240An endpoint is a start or end point (widget) of an audio signal within the
241machine and includes the codec. e.g.
242
243 o Headphone Jack
244 o Internal Speaker
245 o Internal Mic
246 o Mic Jack
247 o Codec Pins
248
249When a codec pin is NC it can be marked as not used with a call to
250
251snd_soc_dapm_set_endpoint(codec, "Widget Name", 0);
252
253The last argument is 0 for inactive and 1 for active. This way the pin and its
254input widget will never be powered up and consume power.
255
256This also applies to machine widgets. e.g. if a headphone is connected to a
257jack then the jack can be marked active. If the headphone is removed, then
258the headphone jack can be marked inactive.
259
260
2615 DAPM Widget Events
262====================
263
264Some widgets can register their interest with the DAPM core in PM events.
265e.g. A Speaker with an amplifier registers a widget so the amplifier can be
266powered only when the spk is in use.
267
268/* turn speaker amplifier on/off depending on use */
269static int corgi_amp_event(struct snd_soc_dapm_widget *w, int event)
270{
271 if (SND_SOC_DAPM_EVENT_ON(event))
272 set_scoop_gpio(&corgiscoop_device.dev, CORGI_SCP_APM_ON);
273 else
274 reset_scoop_gpio(&corgiscoop_device.dev, CORGI_SCP_APM_ON);
275
276 return 0;
277}
278
279/* corgi machine dapm widgets */
280static const struct snd_soc_dapm_widget wm8731_dapm_widgets =
281 SND_SOC_DAPM_SPK("Ext Spk", corgi_amp_event);
282
283Please see soc-dapm.h for all other widgets that support events.
284
285
2865.1 Event types
287---------------
288
289The following event types are supported by event widgets.
290
291/* dapm event types */
292#define SND_SOC_DAPM_PRE_PMU 0x1 /* before widget power up */
293#define SND_SOC_DAPM_POST_PMU 0x2 /* after widget power up */
294#define SND_SOC_DAPM_PRE_PMD 0x4 /* before widget power down */
295#define SND_SOC_DAPM_POST_PMD 0x8 /* after widget power down */
296#define SND_SOC_DAPM_PRE_REG 0x10 /* before audio path setup */
297#define SND_SOC_DAPM_POST_REG 0x20 /* after audio path setup */
diff --git a/Documentation/sound/alsa/soc/machine.txt b/Documentation/sound/alsa/soc/machine.txt
new file mode 100644
index 000000000000..72bd222f2a21
--- /dev/null
+++ b/Documentation/sound/alsa/soc/machine.txt
@@ -0,0 +1,113 @@
1ASoC Machine Driver
2===================
3
4The ASoC machine (or board) driver is the code that glues together the platform
5and codec drivers.
6
7The machine driver can contain codec and platform specific code. It registers
8the audio subsystem with the kernel as a platform device and is represented by
9the following struct:-
10
11/* SoC machine */
12struct snd_soc_machine {
13 char *name;
14
15 int (*probe)(struct platform_device *pdev);
16 int (*remove)(struct platform_device *pdev);
17
18 /* the pre and post PM functions are used to do any PM work before and
19 * after the codec and DAI's do any PM work. */
20 int (*suspend_pre)(struct platform_device *pdev, pm_message_t state);
21 int (*suspend_post)(struct platform_device *pdev, pm_message_t state);
22 int (*resume_pre)(struct platform_device *pdev);
23 int (*resume_post)(struct platform_device *pdev);
24
25 /* machine stream operations */
26 struct snd_soc_ops *ops;
27
28 /* CPU <--> Codec DAI links */
29 struct snd_soc_dai_link *dai_link;
30 int num_links;
31};
32
33probe()/remove()
34----------------
35probe/remove are optional. Do any machine specific probe here.
36
37
38suspend()/resume()
39------------------
40The machine driver has pre and post versions of suspend and resume to take care
41of any machine audio tasks that have to be done before or after the codec, DAI's
42and DMA is suspended and resumed. Optional.
43
44
45Machine operations
46------------------
47The machine specific audio operations can be set here. Again this is optional.
48
49
50Machine DAI Configuration
51-------------------------
52The machine DAI configuration glues all the codec and CPU DAI's together. It can
53also be used to set up the DAI system clock and for any machine related DAI
54initialisation e.g. the machine audio map can be connected to the codec audio
55map, unconnnected codec pins can be set as such. Please see corgi.c, spitz.c
56for examples.
57
58struct snd_soc_dai_link is used to set up each DAI in your machine. e.g.
59
60/* corgi digital audio interface glue - connects codec <--> CPU */
61static struct snd_soc_dai_link corgi_dai = {
62 .name = "WM8731",
63 .stream_name = "WM8731",
64 .cpu_dai = &pxa_i2s_dai,
65 .codec_dai = &wm8731_dai,
66 .init = corgi_wm8731_init,
67 .ops = &corgi_ops,
68};
69
70struct snd_soc_machine then sets up the machine with it's DAI's. e.g.
71
72/* corgi audio machine driver */
73static struct snd_soc_machine snd_soc_machine_corgi = {
74 .name = "Corgi",
75 .dai_link = &corgi_dai,
76 .num_links = 1,
77};
78
79
80Machine Audio Subsystem
81-----------------------
82
83The machine soc device glues the platform, machine and codec driver together.
84Private data can also be set here. e.g.
85
86/* corgi audio private data */
87static struct wm8731_setup_data corgi_wm8731_setup = {
88 .i2c_address = 0x1b,
89};
90
91/* corgi audio subsystem */
92static struct snd_soc_device corgi_snd_devdata = {
93 .machine = &snd_soc_machine_corgi,
94 .platform = &pxa2xx_soc_platform,
95 .codec_dev = &soc_codec_dev_wm8731,
96 .codec_data = &corgi_wm8731_setup,
97};
98
99
100Machine Power Map
101-----------------
102
103The machine driver can optionally extend the codec power map and to become an
104audio power map of the audio subsystem. This allows for automatic power up/down
105of speaker/HP amplifiers, etc. Codec pins can be connected to the machines jack
106sockets in the machine init function. See soc/pxa/spitz.c and dapm.txt for
107details.
108
109
110Machine Controls
111----------------
112
113Machine specific audio mixer controls can be added in the dai init function. \ No newline at end of file
diff --git a/Documentation/sound/alsa/soc/overview.txt b/Documentation/sound/alsa/soc/overview.txt
new file mode 100644
index 000000000000..753c5cc5984a
--- /dev/null
+++ b/Documentation/sound/alsa/soc/overview.txt
@@ -0,0 +1,83 @@
1ALSA SoC Layer
2==============
3
4The overall project goal of the ALSA System on Chip (ASoC) layer is to provide
5better ALSA support for embedded system on chip procesors (e.g. pxa2xx, au1x00,
6iMX, etc) and portable audio codecs. Currently there is some support in the
7kernel for SoC audio, however it has some limitations:-
8
9 * Currently, codec drivers are often tightly coupled to the underlying SoC
10 cpu. This is not ideal and leads to code duplication i.e. Linux now has 4
11 different wm8731 drivers for 4 different SoC platforms.
12
13 * There is no standard method to signal user initiated audio events.
14 e.g. Headphone/Mic insertion, Headphone/Mic detection after an insertion
15 event. These are quite common events on portable devices and ofter require
16 machine specific code to re route audio, enable amps etc after such an event.
17
18 * Current drivers tend to power up the entire codec when playing
19 (or recording) audio. This is fine for a PC, but tends to waste a lot of
20 power on portable devices. There is also no support for saving power via
21 changing codec oversampling rates, bias currents, etc.
22
23
24ASoC Design
25===========
26
27The ASoC layer is designed to address these issues and provide the following
28features :-
29
30 * Codec independence. Allows reuse of codec drivers on other platforms
31 and machines.
32
33 * Easy I2S/PCM audio interface setup between codec and SoC. Each SoC interface
34 and codec registers it's audio interface capabilities with the core and are
35 subsequently matched and configured when the application hw params are known.
36
37 * Dynamic Audio Power Management (DAPM). DAPM automatically sets the codec to
38 it's minimum power state at all times. This includes powering up/down
39 internal power blocks depending on the internal codec audio routing and any
40 active streams.
41
42 * Pop and click reduction. Pops and clicks can be reduced by powering the
43 codec up/down in the correct sequence (including using digital mute). ASoC
44 signals the codec when to change power states.
45
46 * Machine specific controls: Allow machines to add controls to the sound card
47 e.g. volume control for speaker amp.
48
49To achieve all this, ASoC basically splits an embedded audio system into 3
50components :-
51
52 * Codec driver: The codec driver is platform independent and contains audio
53 controls, audio interface capabilities, codec dapm definition and codec IO
54 functions.
55
56 * Platform driver: The platform driver contains the audio dma engine and audio
57 interface drivers (e.g. I2S, AC97, PCM) for that platform.
58
59 * Machine driver: The machine driver handles any machine specific controls and
60 audio events. i.e. turing on an amp at start of playback.
61
62
63Documentation
64=============
65
66The documentation is spilt into the following sections:-
67
68overview.txt: This file.
69
70codec.txt: Codec driver internals.
71
72DAI.txt: Description of Digital Audio Interface standards and how to configure
73a DAI within your codec and CPU DAI drivers.
74
75dapm.txt: Dynamic Audio Power Management
76
77platform.txt: Platform audio DMA and DAI.
78
79machine.txt: Machine driver internals.
80
81pop_clicks.txt: How to minimise audio artifacts.
82
83clocking.txt: ASoC clocking for best power performance. \ No newline at end of file
diff --git a/Documentation/sound/alsa/soc/platform.txt b/Documentation/sound/alsa/soc/platform.txt
new file mode 100644
index 000000000000..e95b16d5a53b
--- /dev/null
+++ b/Documentation/sound/alsa/soc/platform.txt
@@ -0,0 +1,58 @@
1ASoC Platform Driver
2====================
3
4An ASoC platform driver can be divided into audio DMA and SoC DAI configuration
5and control. The platform drivers only target the SoC CPU and must have no board
6specific code.
7
8Audio DMA
9=========
10
11The platform DMA driver optionally supports the following alsa operations:-
12
13/* SoC audio ops */
14struct snd_soc_ops {
15 int (*startup)(struct snd_pcm_substream *);
16 void (*shutdown)(struct snd_pcm_substream *);
17 int (*hw_params)(struct snd_pcm_substream *, struct snd_pcm_hw_params *);
18 int (*hw_free)(struct snd_pcm_substream *);
19 int (*prepare)(struct snd_pcm_substream *);
20 int (*trigger)(struct snd_pcm_substream *, int);
21};
22
23The platform driver exports it's DMA functionailty via struct snd_soc_platform:-
24
25struct snd_soc_platform {
26 char *name;
27
28 int (*probe)(struct platform_device *pdev);
29 int (*remove)(struct platform_device *pdev);
30 int (*suspend)(struct platform_device *pdev, struct snd_soc_cpu_dai *cpu_dai);
31 int (*resume)(struct platform_device *pdev, struct snd_soc_cpu_dai *cpu_dai);
32
33 /* pcm creation and destruction */
34 int (*pcm_new)(struct snd_card *, struct snd_soc_codec_dai *, struct snd_pcm *);
35 void (*pcm_free)(struct snd_pcm *);
36
37 /* platform stream ops */
38 struct snd_pcm_ops *pcm_ops;
39};
40
41Please refer to the alsa driver documentation for details of audio DMA.
42http://www.alsa-project.org/~iwai/writing-an-alsa-driver/c436.htm
43
44An example DMA driver is soc/pxa/pxa2xx-pcm.c
45
46
47SoC DAI Drivers
48===============
49
50Each SoC DAI driver must provide the following features:-
51
52 1) Digital audio interface (DAI) description
53 2) Digital audio interface configuration
54 3) PCM's description
55 4) Sysclk configuration
56 5) Suspend and resume (optional)
57
58Please see codec.txt for a description of items 1 - 4.
diff --git a/Documentation/sound/alsa/soc/pops_clicks.txt b/Documentation/sound/alsa/soc/pops_clicks.txt
new file mode 100644
index 000000000000..2cf7ee5b3d74
--- /dev/null
+++ b/Documentation/sound/alsa/soc/pops_clicks.txt
@@ -0,0 +1,52 @@
1Audio Pops and Clicks
2=====================
3
4Pops and clicks are unwanted audio artifacts caused by the powering up and down
5of components within the audio subsystem. This is noticable on PC's when an
6audio module is either loaded or unloaded (at module load time the sound card is
7powered up and causes a popping noise on the speakers).
8
9Pops and clicks can be more frequent on portable systems with DAPM. This is
10because the components within the subsystem are being dynamically powered
11depending on the audio usage and this can subsequently cause a small pop or
12click every time a component power state is changed.
13
14
15Minimising Playback Pops and Clicks
16===================================
17
18Playback pops in portable audio subsystems cannot be completely eliminated atm,
19however future audio codec hardware will have better pop and click supression.
20Pops can be reduced within playback by powering the audio components in a
21specific order. This order is different for startup and shutdown and follows
22some basic rules:-
23
24 Startup Order :- DAC --> Mixers --> Output PGA --> Digital Unmute
25
26 Shutdown Order :- Digital Mute --> Output PGA --> Mixers --> DAC
27
28This assumes that the codec PCM output path from the DAC is via a mixer and then
29a PGA (programmable gain amplifier) before being output to the speakers.
30
31
32Minimising Capture Pops and Clicks
33==================================
34
35Capture artifacts are somewhat easier to get rid as we can delay activating the
36ADC until all the pops have occured. This follows similar power rules to
37playback in that components are powered in a sequence depending upon stream
38startup or shutdown.
39
40 Startup Order - Input PGA --> Mixers --> ADC
41
42 Shutdown Order - ADC --> Mixers --> Input PGA
43
44
45Zipper Noise
46============
47An unwanted zipper noise can occur within the audio playback or capture stream
48when a volume control is changed near its maximum gain value. The zipper noise
49is heard when the gain increase or decrease changes the mean audio signal
50amplitude too quickly. It can be minimised by enabling the zero cross setting
51for each volume control. The ZC forces the gain change to occur when the signal
52crosses the zero amplitude line.