diff options
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/sound/alsa/ALSA-Configuration.txt | 60 | ||||
-rw-r--r-- | Documentation/sound/alsa/DocBook/alsa-driver-api.tmpl | 4 | ||||
-rw-r--r-- | Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl | 33 | ||||
-rw-r--r-- | Documentation/sound/alsa/hda_codec.txt | 10 | ||||
-rw-r--r-- | Documentation/sound/alsa/soc/DAI.txt | 56 | ||||
-rw-r--r-- | Documentation/sound/alsa/soc/clocking.txt | 51 | ||||
-rw-r--r-- | Documentation/sound/alsa/soc/codec.txt | 197 | ||||
-rw-r--r-- | Documentation/sound/alsa/soc/dapm.txt | 297 | ||||
-rw-r--r-- | Documentation/sound/alsa/soc/machine.txt | 113 | ||||
-rw-r--r-- | Documentation/sound/alsa/soc/overview.txt | 83 | ||||
-rw-r--r-- | Documentation/sound/alsa/soc/platform.txt | 58 | ||||
-rw-r--r-- | Documentation/sound/alsa/soc/pops_clicks.txt | 52 |
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->runtime</constant>. | 2126 | accessible via <constant>substream->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->private_data. The | ||
3697 | kcontrol->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 | |||
277 | snd_hda_get_codec_name() stores the codec name on the given string. | 277 | snd_hda_get_codec_name() stores the codec name on the given string. |
278 | 278 | ||
279 | snd_hda_check_board_config() can be used to obtain the configuration | 279 | snd_hda_check_board_config() can be used to obtain the configuration |
280 | information matching with the device. Define the table with struct | 280 | information matching with the device. Define the model string table |
281 | hda_board_config entries (zero-terminated), and pass it to the | 281 | and the table with struct snd_pci_quirk entries (zero-terminated), |
282 | function. The function checks the modelname given as a module | 282 | and pass it to the function. The function checks the modelname given |
283 | parameter, and PCI subsystem IDs. If the matching entry is found, it | 283 | as a module parameter, and PCI subsystem IDs. If the matching entry |
284 | returns the config field value. | 284 | is found, it returns the config field value. |
285 | 285 | ||
286 | snd_hda_add_new_ctls() can be used to create and add control entries. | 286 | snd_hda_add_new_ctls() can be used to create and add control entries. |
287 | Pass the zero-terminated array of struct snd_kcontrol_new. The same array | 287 | Pass 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 @@ | |||
1 | ASoC currently supports the three main Digital Audio Interfaces (DAI) found on | ||
2 | SoC controllers and portable audio CODECS today, namely AC97, I2S and PCM. | ||
3 | |||
4 | |||
5 | AC97 | ||
6 | ==== | ||
7 | |||
8 | AC97 is a five wire interface commonly found on many PC sound cards. It is | ||
9 | now also popular in many portable devices. This DAI has a reset line and time | ||
10 | multiplexes its data on its SDATA_OUT (playback) and SDATA_IN (capture) lines. | ||
11 | The bit clock (BCLK) is always driven by the CODEC (usually 12.288MHz) and the | ||
12 | frame (FRAME) (usually 48kHz) is always driven by the controller. Each AC97 | ||
13 | frame is 21uS long and is divided into 13 time slots. | ||
14 | |||
15 | The AC97 specification can be found at :- | ||
16 | http://www.intel.com/design/chipsets/audio/ac97_r23.pdf | ||
17 | |||
18 | |||
19 | I2S | ||
20 | === | ||
21 | |||
22 | I2S is a common 4 wire DAI used in HiFi, STB and portable devices. The Tx and | ||
23 | Rx lines are used for audio transmision, whilst the bit clock (BCLK) and | ||
24 | left/right clock (LRC) synchronise the link. I2S is flexible in that either the | ||
25 | controller or CODEC can drive (master) the BCLK and LRC clock lines. Bit clock | ||
26 | usually 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 | ||
28 | ADC and DAC LRCLK's, this allows for similtanious capture and playback at | ||
29 | different sample rates. | ||
30 | |||
31 | I2S 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 | |||
41 | PCM | ||
42 | === | ||
43 | |||
44 | PCM is another 4 wire interface, very similar to I2S, that can support a more | ||
45 | flexible protocol. It has bit clock (BCLK) and sync (SYNC) lines that are used | ||
46 | to synchronise the link whilst the Tx and Rx lines are used to transmit and | ||
47 | receive the audio data. Bit clock usually varies depending on sample rate | ||
48 | whilst sync runs at the sample rate. PCM also supports Time Division | ||
49 | Multiplexing (TDM) in that several devices can use the bus similtaniuosly (This | ||
50 | is sometimes referred to as network mode). | ||
51 | |||
52 | Common 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 @@ | |||
1 | Audio Clocking | ||
2 | ============== | ||
3 | |||
4 | This text describes the audio clocking terms in ASoC and digital audio in | ||
5 | general. Note: Audio clocking can be complex ! | ||
6 | |||
7 | |||
8 | Master Clock | ||
9 | ------------ | ||
10 | |||
11 | Every audio subsystem is driven by a master clock (sometimes refered to as MCLK | ||
12 | or 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 | ||
14 | audio playback and capture sample rates. | ||
15 | |||
16 | Some master clocks (e.g. PLL's and CPU based clocks) are configuarble in that | ||
17 | their speed can be altered by software (depending on the system use and to save | ||
18 | power). Other master clocks are fixed at at set frequency (i.e. crystals). | ||
19 | |||
20 | |||
21 | DAI Clocks | ||
22 | ---------- | ||
23 | The Digital Audio Interface is usually driven by a Bit Clock (often referred to | ||
24 | as BCLK). This clock is used to drive the digital audio data across the link | ||
25 | between the codec and CPU. | ||
26 | |||
27 | The DAI also has a frame clock to signal the start of each audio frame. This | ||
28 | clock is sometimes referred to as LRC (left right clock) or FRAME. This clock | ||
29 | runs at exactly the sample rate (LRC = Rate). | ||
30 | |||
31 | Bit Clock can be generated as follows:- | ||
32 | |||
33 | BCLK = MCLK / x | ||
34 | |||
35 | or | ||
36 | |||
37 | BCLK = LRC * x | ||
38 | |||
39 | or | ||
40 | |||
41 | BCLK = LRC * Channels * Word Size | ||
42 | |||
43 | This relationship depends on the codec or SoC CPU in particular. In general | ||
44 | it's best to configure BCLK to the lowest possible speed (depending on your | ||
45 | rate, number of channels and wordsize) to save on power. | ||
46 | |||
47 | It's also desireable to use the codec (if possible) to drive (or master) the | ||
48 | audio 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 @@ | |||
1 | ASoC Codec Driver | ||
2 | ================= | ||
3 | |||
4 | The codec driver is generic and hardware independent code that configures the | ||
5 | codec to provide audio capture and playback. It should contain no code that is | ||
6 | specific to the target platform or machine. All platform and machine specific | ||
7 | code should be added to the platform and machine drivers respectively. | ||
8 | |||
9 | Each 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 | |||
16 | Optionally, codec drivers can also provide:- | ||
17 | |||
18 | 5) DAPM description. | ||
19 | 6) DAPM event handler. | ||
20 | 7) DAC Digital mute control. | ||
21 | |||
22 | It's probably best to use this guide in conjuction with the existing codec | ||
23 | driver code in sound/soc/codecs/ | ||
24 | |||
25 | ASoC Codec driver breakdown | ||
26 | =========================== | ||
27 | |||
28 | 1 - Codec DAI and PCM configuration | ||
29 | ----------------------------------- | ||
30 | Each codec driver must have a struct snd_soc_codec_dai to define it's DAI and | ||
31 | PCM's capablities and operations. This struct is exported so that it can be | ||
32 | registered with the core by your machine driver. | ||
33 | |||
34 | e.g. | ||
35 | |||
36 | struct 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 | }; | ||
65 | EXPORT_SYMBOL_GPL(wm8731_dai); | ||
66 | |||
67 | |||
68 | 2 - Codec control IO | ||
69 | -------------------- | ||
70 | The codec can ususally be controlled via an I2C or SPI style interface (AC97 | ||
71 | combines control with data in the DAI). The codec drivers will have to provide | ||
72 | functions to read and write the codec registers along with supplying a register | ||
73 | cache:- | ||
74 | |||
75 | /* IO control data and register cache */ | ||
76 | void *control_data; /* codec control (i2c/3wire) data */ | ||
77 | void *reg_cache; | ||
78 | |||
79 | Codec read/write should do any data formatting and call the hardware read write | ||
80 | below to perform the IO. These functions are called by the core and alsa when | ||
81 | performing 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 | |||
86 | Codec hardware IO functions - usually points to either the I2C, SPI or AC97 | ||
87 | read/write:- | ||
88 | |||
89 | hw_write_t hw_write; | ||
90 | hw_read_t hw_read; | ||
91 | |||
92 | |||
93 | 3 - Mixers and audio controls | ||
94 | ----------------------------- | ||
95 | All the codec mixers and audio controls can be defined using the convenience | ||
96 | macros defined in soc.h. | ||
97 | |||
98 | #define SOC_SINGLE(xname, reg, shift, mask, invert) | ||
99 | |||
100 | Defines 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 | |||
108 | Other macros include:- | ||
109 | |||
110 | #define SOC_DOUBLE(xname, reg, shift_left, shift_right, mask, invert) | ||
111 | |||
112 | A stereo control | ||
113 | |||
114 | #define SOC_DOUBLE_R(xname, reg_left, reg_right, shift, mask, invert) | ||
115 | |||
116 | A stereo control spanning 2 registers | ||
117 | |||
118 | #define SOC_ENUM_SINGLE(xreg, xshift, xmask, xtexts) | ||
119 | |||
120 | Defines 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 | |||
129 | Defines a stereo enumerated control | ||
130 | |||
131 | |||
132 | 4 - Codec Audio Operations | ||
133 | -------------------------- | ||
134 | The codec driver also supports the following alsa operations:- | ||
135 | |||
136 | /* SoC audio ops */ | ||
137 | struct 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 | |||
145 | Please refer to the alsa driver PCM documentation for details. | ||
146 | http://www.alsa-project.org/~iwai/writing-an-alsa-driver/c436.htm | ||
147 | |||
148 | |||
149 | 5 - DAPM description. | ||
150 | --------------------- | ||
151 | The Dynamic Audio Power Management description describes the codec's power | ||
152 | components, their relationships and registers to the ASoC core. Please read | ||
153 | dapm.txt for details of building the description. | ||
154 | |||
155 | Please also see the examples in other codec drivers. | ||
156 | |||
157 | |||
158 | 6 - DAPM event handler | ||
159 | ---------------------- | ||
160 | This function is a callback that handles codec domain PM calls and system | ||
161 | domain PM calls (e.g. suspend and resume). It's used to put the codec to sleep | ||
162 | when not in use. | ||
163 | |||
164 | Power 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 | |||
178 | 7 - Codec DAC digital mute control. | ||
179 | ------------------------------------ | ||
180 | Most codecs have a digital mute before the DAC's that can be used to minimise | ||
181 | any system noise. The mute stops any digital data from entering the DAC. | ||
182 | |||
183 | A callback can be created that is called by the core for each codec DAI when the | ||
184 | mute is applied or freed. | ||
185 | |||
186 | i.e. | ||
187 | |||
188 | static 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 @@ | |||
1 | Dynamic Audio Power Management for Portable Devices | ||
2 | =================================================== | ||
3 | |||
4 | 1. Description | ||
5 | ============== | ||
6 | |||
7 | Dynamic Audio Power Management (DAPM) is designed to allow portable Linux devices | ||
8 | to use the minimum amount of power within the audio subsystem at all times. It | ||
9 | is independent of other kernel PM and as such, can easily co-exist with the | ||
10 | other PM systems. | ||
11 | |||
12 | DAPM is also completely transparent to all user space applications as all power | ||
13 | switching is done within the ASoC core. No code changes or recompiling are | ||
14 | required for user space applications. DAPM makes power switching descisions based | ||
15 | upon any audio stream (capture/playback) activity and audio mixer settings | ||
16 | within the device. | ||
17 | |||
18 | DAPM spans the whole machine. It covers power control within the entire audio | ||
19 | subsystem, this includes internal codec power blocks and machine level power | ||
20 | systems. | ||
21 | |||
22 | There 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 | |||
41 | All DAPM power switching descisons are made automatically by consulting an audio | ||
42 | routing map of the whole machine. This map is specific to each machine and | ||
43 | consists of the interconnections between every audio component (including | ||
44 | internal codec components). All audio components that effect power are called | ||
45 | widgets hereafter. | ||
46 | |||
47 | |||
48 | 2. DAPM Widgets | ||
49 | =============== | ||
50 | |||
51 | Audio 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 | |||
70 | Widgets are usually added in the codec driver and the machine driver. There are | ||
71 | convience macros defined in soc-dapm.h that can be used to quickly build a | ||
72 | list of widgets of the codecs and machines DAPM widgets. | ||
73 | |||
74 | Most widgets have a name, register, shift and invert. Some widgets have extra | ||
75 | parameters for stream name and kcontrols. | ||
76 | |||
77 | |||
78 | 2.1 Stream Domain Widgets | ||
79 | ------------------------- | ||
80 | |||
81 | Stream 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 | |||
84 | Stream widgets have the following format:- | ||
85 | |||
86 | SND_SOC_DAPM_DAC(name, stream name, reg, shift, invert), | ||
87 | |||
88 | NOTE: the stream name must match the corresponding stream name in your codecs | ||
89 | snd_soc_codec_dai. | ||
90 | |||
91 | e.g. stream widgets for HiFi playback and capture | ||
92 | |||
93 | SND_SOC_DAPM_DAC("HiFi DAC", "HiFi Playback", REG, 3, 1), | ||
94 | SND_SOC_DAPM_ADC("HiFi ADC", "HiFi Capture", REG, 2, 1), | ||
95 | |||
96 | |||
97 | 2.2 Path Domain Widgets | ||
98 | ----------------------- | ||
99 | |||
100 | Path domain widgets have a ability to control or effect the audio signal or | ||
101 | audio paths within the audio subsystem. They have the following form:- | ||
102 | |||
103 | SND_SOC_DAPM_PGA(name, reg, shift, invert, controls, num_controls) | ||
104 | |||
105 | Any widget kcontrols can be set using the controls and num_controls members. | ||
106 | |||
107 | e.g. Mixer widget (the kcontrols are declared first) | ||
108 | |||
109 | /* Output Mixer */ | ||
110 | static const snd_kcontrol_new_t wm8731_output_mixer_controls[] = { | ||
111 | SOC_DAPM_SINGLE("Line Bypass Switch", WM8731_APANA, 3, 1, 0), | ||
112 | SOC_DAPM_SINGLE("Mic Sidetone Switch", WM8731_APANA, 5, 1, 0), | ||
113 | SOC_DAPM_SINGLE("HiFi Playback Switch", WM8731_APANA, 4, 1, 0), | ||
114 | }; | ||
115 | |||
116 | SND_SOC_DAPM_MIXER("Output Mixer", WM8731_PWR, 4, 1, wm8731_output_mixer_controls, | ||
117 | ARRAY_SIZE(wm8731_output_mixer_controls)), | ||
118 | |||
119 | |||
120 | 2.3 Platform/Machine domain Widgets | ||
121 | ----------------------------------- | ||
122 | |||
123 | Machine widgets are different from codec widgets in that they don't have a | ||
124 | codec register bit associated with them. A machine widget is assigned to each | ||
125 | machine 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 | |||
131 | A machine widget can have an optional call back. | ||
132 | |||
133 | e.g. Jack connector widget for an external Mic that enables Mic Bias | ||
134 | when the Mic is inserted:- | ||
135 | |||
136 | static 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 | |||
146 | SND_SOC_DAPM_MIC("Mic Jack", spitz_mic_bias), | ||
147 | |||
148 | |||
149 | 2.4 Codec Domain | ||
150 | ---------------- | ||
151 | |||
152 | The Codec power domain has no widgets and is handled by the codecs DAPM event | ||
153 | handler. This handler is called when the codec powerstate is changed wrt to any | ||
154 | stream event or by kernel PM events. | ||
155 | |||
156 | |||
157 | 2.5 Virtual Widgets | ||
158 | ------------------- | ||
159 | |||
160 | Sometimes widgets exist in the codec or machine audio map that don't have any | ||
161 | corresponding register bit for power control. In this case it's necessary to | ||
162 | create a virtual widget - a widget with no control bits e.g. | ||
163 | |||
164 | SND_SOC_DAPM_MIXER("AC97 Mixer", SND_SOC_DAPM_NOPM, 0, 0, NULL, 0), | ||
165 | |||
166 | This can be used to merge to signal paths together in software. | ||
167 | |||
168 | After all the widgets have been defined, they can then be added to the DAPM | ||
169 | subsystem individually with a call to snd_soc_dapm_new_control(). | ||
170 | |||
171 | |||
172 | 3. Codec Widget Interconnections | ||
173 | ================================ | ||
174 | |||
175 | Widgets are connected to each other within the codec and machine by audio | ||
176 | paths (called interconnections). Each interconnection must be defined in order | ||
177 | to create a map of all audio paths between widgets. | ||
178 | This is easiest with a diagram of the codec (and schematic of the machine audio | ||
179 | system), as it requires joining widgets together via their audio signal paths. | ||
180 | |||
181 | i.e. from the WM8731 codec's output mixer (wm8731.c) | ||
182 | |||
183 | The WM8731 output mixer has 3 inputs (sources) | ||
184 | |||
185 | 1. Line Bypass Input | ||
186 | 2. DAC (HiFi playback) | ||
187 | 3. Mic Sidetone Input | ||
188 | |||
189 | Each input in this example has a kcontrol associated with it (defined in example | ||
190 | above) and is connected to the output mixer via it's kcontrol name. We can now | ||
191 | connect 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 | |||
198 | So we have :- | ||
199 | |||
200 | Destination Widget <=== Path Name <=== Source Widget | ||
201 | |||
202 | Or:- | ||
203 | |||
204 | Sink, Path, Source | ||
205 | |||
206 | Or :- | ||
207 | |||
208 | "Output Mixer" is connected to the "DAC" via the "HiFi Playback Switch". | ||
209 | |||
210 | When there is no path name connecting widgets (e.g. a direct connection) we | ||
211 | pass NULL for the path name. | ||
212 | |||
213 | Interconnections are created with a call to:- | ||
214 | |||
215 | snd_soc_dapm_connect_input(codec, sink, path, source); | ||
216 | |||
217 | Finally, snd_soc_dapm_new_widgets(codec) must be called after all widgets and | ||
218 | interconnections have been registered with the core. This causes the core to | ||
219 | scan the codec and machine so that the internal DAPM state matches the | ||
220 | physical state of the machine. | ||
221 | |||
222 | |||
223 | 3.1 Machine Widget Interconnections | ||
224 | ----------------------------------- | ||
225 | Machine widget interconnections are created in the same way as codec ones and | ||
226 | directly connect the codec pins to machine level widgets. | ||
227 | |||
228 | e.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 | |||
234 | This allows the DAPM to power on and off pins that are connected (and in use) | ||
235 | and pins that are NC respectively. | ||
236 | |||
237 | |||
238 | 4 Endpoint Widgets | ||
239 | =================== | ||
240 | An endpoint is a start or end point (widget) of an audio signal within the | ||
241 | machine 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 | |||
249 | When a codec pin is NC it can be marked as not used with a call to | ||
250 | |||
251 | snd_soc_dapm_set_endpoint(codec, "Widget Name", 0); | ||
252 | |||
253 | The last argument is 0 for inactive and 1 for active. This way the pin and its | ||
254 | input widget will never be powered up and consume power. | ||
255 | |||
256 | This also applies to machine widgets. e.g. if a headphone is connected to a | ||
257 | jack then the jack can be marked active. If the headphone is removed, then | ||
258 | the headphone jack can be marked inactive. | ||
259 | |||
260 | |||
261 | 5 DAPM Widget Events | ||
262 | ==================== | ||
263 | |||
264 | Some widgets can register their interest with the DAPM core in PM events. | ||
265 | e.g. A Speaker with an amplifier registers a widget so the amplifier can be | ||
266 | powered only when the spk is in use. | ||
267 | |||
268 | /* turn speaker amplifier on/off depending on use */ | ||
269 | static 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 */ | ||
280 | static const struct snd_soc_dapm_widget wm8731_dapm_widgets = | ||
281 | SND_SOC_DAPM_SPK("Ext Spk", corgi_amp_event); | ||
282 | |||
283 | Please see soc-dapm.h for all other widgets that support events. | ||
284 | |||
285 | |||
286 | 5.1 Event types | ||
287 | --------------- | ||
288 | |||
289 | The 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 @@ | |||
1 | ASoC Machine Driver | ||
2 | =================== | ||
3 | |||
4 | The ASoC machine (or board) driver is the code that glues together the platform | ||
5 | and codec drivers. | ||
6 | |||
7 | The machine driver can contain codec and platform specific code. It registers | ||
8 | the audio subsystem with the kernel as a platform device and is represented by | ||
9 | the following struct:- | ||
10 | |||
11 | /* SoC machine */ | ||
12 | struct 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 | |||
33 | probe()/remove() | ||
34 | ---------------- | ||
35 | probe/remove are optional. Do any machine specific probe here. | ||
36 | |||
37 | |||
38 | suspend()/resume() | ||
39 | ------------------ | ||
40 | The machine driver has pre and post versions of suspend and resume to take care | ||
41 | of any machine audio tasks that have to be done before or after the codec, DAI's | ||
42 | and DMA is suspended and resumed. Optional. | ||
43 | |||
44 | |||
45 | Machine operations | ||
46 | ------------------ | ||
47 | The machine specific audio operations can be set here. Again this is optional. | ||
48 | |||
49 | |||
50 | Machine DAI Configuration | ||
51 | ------------------------- | ||
52 | The machine DAI configuration glues all the codec and CPU DAI's together. It can | ||
53 | also be used to set up the DAI system clock and for any machine related DAI | ||
54 | initialisation e.g. the machine audio map can be connected to the codec audio | ||
55 | map, unconnnected codec pins can be set as such. Please see corgi.c, spitz.c | ||
56 | for examples. | ||
57 | |||
58 | struct 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 */ | ||
61 | static 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 | |||
70 | struct snd_soc_machine then sets up the machine with it's DAI's. e.g. | ||
71 | |||
72 | /* corgi audio machine driver */ | ||
73 | static struct snd_soc_machine snd_soc_machine_corgi = { | ||
74 | .name = "Corgi", | ||
75 | .dai_link = &corgi_dai, | ||
76 | .num_links = 1, | ||
77 | }; | ||
78 | |||
79 | |||
80 | Machine Audio Subsystem | ||
81 | ----------------------- | ||
82 | |||
83 | The machine soc device glues the platform, machine and codec driver together. | ||
84 | Private data can also be set here. e.g. | ||
85 | |||
86 | /* corgi audio private data */ | ||
87 | static struct wm8731_setup_data corgi_wm8731_setup = { | ||
88 | .i2c_address = 0x1b, | ||
89 | }; | ||
90 | |||
91 | /* corgi audio subsystem */ | ||
92 | static 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 | |||
100 | Machine Power Map | ||
101 | ----------------- | ||
102 | |||
103 | The machine driver can optionally extend the codec power map and to become an | ||
104 | audio power map of the audio subsystem. This allows for automatic power up/down | ||
105 | of speaker/HP amplifiers, etc. Codec pins can be connected to the machines jack | ||
106 | sockets in the machine init function. See soc/pxa/spitz.c and dapm.txt for | ||
107 | details. | ||
108 | |||
109 | |||
110 | Machine Controls | ||
111 | ---------------- | ||
112 | |||
113 | Machine 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 @@ | |||
1 | ALSA SoC Layer | ||
2 | ============== | ||
3 | |||
4 | The overall project goal of the ALSA System on Chip (ASoC) layer is to provide | ||
5 | better ALSA support for embedded system on chip procesors (e.g. pxa2xx, au1x00, | ||
6 | iMX, etc) and portable audio codecs. Currently there is some support in the | ||
7 | kernel 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 | |||
24 | ASoC Design | ||
25 | =========== | ||
26 | |||
27 | The ASoC layer is designed to address these issues and provide the following | ||
28 | features :- | ||
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 | |||
49 | To achieve all this, ASoC basically splits an embedded audio system into 3 | ||
50 | components :- | ||
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 | |||
63 | Documentation | ||
64 | ============= | ||
65 | |||
66 | The documentation is spilt into the following sections:- | ||
67 | |||
68 | overview.txt: This file. | ||
69 | |||
70 | codec.txt: Codec driver internals. | ||
71 | |||
72 | DAI.txt: Description of Digital Audio Interface standards and how to configure | ||
73 | a DAI within your codec and CPU DAI drivers. | ||
74 | |||
75 | dapm.txt: Dynamic Audio Power Management | ||
76 | |||
77 | platform.txt: Platform audio DMA and DAI. | ||
78 | |||
79 | machine.txt: Machine driver internals. | ||
80 | |||
81 | pop_clicks.txt: How to minimise audio artifacts. | ||
82 | |||
83 | clocking.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 @@ | |||
1 | ASoC Platform Driver | ||
2 | ==================== | ||
3 | |||
4 | An ASoC platform driver can be divided into audio DMA and SoC DAI configuration | ||
5 | and control. The platform drivers only target the SoC CPU and must have no board | ||
6 | specific code. | ||
7 | |||
8 | Audio DMA | ||
9 | ========= | ||
10 | |||
11 | The platform DMA driver optionally supports the following alsa operations:- | ||
12 | |||
13 | /* SoC audio ops */ | ||
14 | struct 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 | |||
23 | The platform driver exports it's DMA functionailty via struct snd_soc_platform:- | ||
24 | |||
25 | struct 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 | |||
41 | Please refer to the alsa driver documentation for details of audio DMA. | ||
42 | http://www.alsa-project.org/~iwai/writing-an-alsa-driver/c436.htm | ||
43 | |||
44 | An example DMA driver is soc/pxa/pxa2xx-pcm.c | ||
45 | |||
46 | |||
47 | SoC DAI Drivers | ||
48 | =============== | ||
49 | |||
50 | Each 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 | |||
58 | Please 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 @@ | |||
1 | Audio Pops and Clicks | ||
2 | ===================== | ||
3 | |||
4 | Pops and clicks are unwanted audio artifacts caused by the powering up and down | ||
5 | of components within the audio subsystem. This is noticable on PC's when an | ||
6 | audio module is either loaded or unloaded (at module load time the sound card is | ||
7 | powered up and causes a popping noise on the speakers). | ||
8 | |||
9 | Pops and clicks can be more frequent on portable systems with DAPM. This is | ||
10 | because the components within the subsystem are being dynamically powered | ||
11 | depending on the audio usage and this can subsequently cause a small pop or | ||
12 | click every time a component power state is changed. | ||
13 | |||
14 | |||
15 | Minimising Playback Pops and Clicks | ||
16 | =================================== | ||
17 | |||
18 | Playback pops in portable audio subsystems cannot be completely eliminated atm, | ||
19 | however future audio codec hardware will have better pop and click supression. | ||
20 | Pops can be reduced within playback by powering the audio components in a | ||
21 | specific order. This order is different for startup and shutdown and follows | ||
22 | some basic rules:- | ||
23 | |||
24 | Startup Order :- DAC --> Mixers --> Output PGA --> Digital Unmute | ||
25 | |||
26 | Shutdown Order :- Digital Mute --> Output PGA --> Mixers --> DAC | ||
27 | |||
28 | This assumes that the codec PCM output path from the DAC is via a mixer and then | ||
29 | a PGA (programmable gain amplifier) before being output to the speakers. | ||
30 | |||
31 | |||
32 | Minimising Capture Pops and Clicks | ||
33 | ================================== | ||
34 | |||
35 | Capture artifacts are somewhat easier to get rid as we can delay activating the | ||
36 | ADC until all the pops have occured. This follows similar power rules to | ||
37 | playback in that components are powered in a sequence depending upon stream | ||
38 | startup or shutdown. | ||
39 | |||
40 | Startup Order - Input PGA --> Mixers --> ADC | ||
41 | |||
42 | Shutdown Order - ADC --> Mixers --> Input PGA | ||
43 | |||
44 | |||
45 | Zipper Noise | ||
46 | ============ | ||
47 | An unwanted zipper noise can occur within the audio playback or capture stream | ||
48 | when a volume control is changed near its maximum gain value. The zipper noise | ||
49 | is heard when the gain increase or decrease changes the mean audio signal | ||
50 | amplitude too quickly. It can be minimised by enabling the zero cross setting | ||
51 | for each volume control. The ZC forces the gain change to occur when the signal | ||
52 | crosses the zero amplitude line. | ||