diff options
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/HOWTO | 1 | ||||
-rw-r--r-- | Documentation/crypto/api-intro.txt | 4 | ||||
-rw-r--r-- | Documentation/feature-removal-schedule.txt | 29 | ||||
-rw-r--r-- | Documentation/s390/Debugging390.txt | 2 | ||||
-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 | ||||
-rw-r--r-- | Documentation/usb/proc_usb_info.txt | 21 | ||||
-rw-r--r-- | Documentation/usb/usbmon.txt | 152 | ||||
-rw-r--r-- | Documentation/video-output.txt | 34 |
19 files changed, 1199 insertions, 58 deletions
diff --git a/Documentation/HOWTO b/Documentation/HOWTO index 8d51c148f721..48123dba5e6a 100644 --- a/Documentation/HOWTO +++ b/Documentation/HOWTO | |||
@@ -30,6 +30,7 @@ are not a good substitute for a solid C education and/or years of | |||
30 | experience, the following books are good for, if anything, reference: | 30 | experience, the following books are good for, if anything, reference: |
31 | - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall] | 31 | - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall] |
32 | - "Practical C Programming" by Steve Oualline [O'Reilly] | 32 | - "Practical C Programming" by Steve Oualline [O'Reilly] |
33 | - "C: A Reference Manual" by Harbison and Steele [Prentice Hall] | ||
33 | 34 | ||
34 | The kernel is written using GNU C and the GNU toolchain. While it | 35 | The kernel is written using GNU C and the GNU toolchain. While it |
35 | adheres to the ISO C89 standard, it uses a number of extensions that are | 36 | adheres to the ISO C89 standard, it uses a number of extensions that are |
diff --git a/Documentation/crypto/api-intro.txt b/Documentation/crypto/api-intro.txt index 5a03a2801d67..e41a79aa71ce 100644 --- a/Documentation/crypto/api-intro.txt +++ b/Documentation/crypto/api-intro.txt | |||
@@ -193,6 +193,7 @@ Original developers of the crypto algorithms: | |||
193 | Kartikey Mahendra Bhatt (CAST6) | 193 | Kartikey Mahendra Bhatt (CAST6) |
194 | Jon Oberheide (ARC4) | 194 | Jon Oberheide (ARC4) |
195 | Jouni Malinen (Michael MIC) | 195 | Jouni Malinen (Michael MIC) |
196 | NTT(Nippon Telegraph and Telephone Corporation) (Camellia) | ||
196 | 197 | ||
197 | SHA1 algorithm contributors: | 198 | SHA1 algorithm contributors: |
198 | Jean-Francois Dive | 199 | Jean-Francois Dive |
@@ -246,6 +247,9 @@ Tiger algorithm contributors: | |||
246 | VIA PadLock contributors: | 247 | VIA PadLock contributors: |
247 | Michal Ludvig | 248 | Michal Ludvig |
248 | 249 | ||
250 | Camellia algorithm contributors: | ||
251 | NTT(Nippon Telegraph and Telephone Corporation) (Camellia) | ||
252 | |||
249 | Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com> | 253 | Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com> |
250 | 254 | ||
251 | Please send any credits updates or corrections to: | 255 | Please send any credits updates or corrections to: |
diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index f4937a3fc520..fa844fd7bded 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt | |||
@@ -170,18 +170,6 @@ Who: Greg Kroah-Hartman <gregkh@suse.de> | |||
170 | 170 | ||
171 | --------------------------- | 171 | --------------------------- |
172 | 172 | ||
173 | What: find_trylock_page | ||
174 | When: January 2007 | ||
175 | Why: The interface no longer has any callers left in the kernel. It | ||
176 | is an odd interface (compared with other find_*_page functions), in | ||
177 | that it does not take a refcount to the page, only the page lock. | ||
178 | It should be replaced with find_get_page or find_lock_page if possible. | ||
179 | This feature removal can be reevaluated if users of the interface | ||
180 | cannot cleanly use something else. | ||
181 | Who: Nick Piggin <npiggin@suse.de> | ||
182 | |||
183 | --------------------------- | ||
184 | |||
185 | What: Interrupt only SA_* flags | 173 | What: Interrupt only SA_* flags |
186 | When: Januar 2007 | 174 | When: Januar 2007 |
187 | Why: The interrupt related SA_* flags are replaced by IRQF_* to move them | 175 | Why: The interrupt related SA_* flags are replaced by IRQF_* to move them |
@@ -258,6 +246,7 @@ Who: Venkatesh Pallipadi <venkatesh.pallipadi@intel.com> | |||
258 | 246 | ||
259 | --------------------------- | 247 | --------------------------- |
260 | 248 | ||
249 | <<<<<<< test:Documentation/feature-removal-schedule.txt | ||
261 | What: ACPI hotkey driver (CONFIG_ACPI_HOTKEY) | 250 | What: ACPI hotkey driver (CONFIG_ACPI_HOTKEY) |
262 | When: 2.6.21 | 251 | When: 2.6.21 |
263 | Why: hotkey.c was an attempt to consolidate multiple drivers that use | 252 | Why: hotkey.c was an attempt to consolidate multiple drivers that use |
@@ -290,11 +279,18 @@ Why: The ACPI namespace is effectively the symbol list for | |||
290 | the BIOS can be extracted and disassembled with acpidump | 279 | the BIOS can be extracted and disassembled with acpidump |
291 | and iasl as documented in the pmtools package here: | 280 | and iasl as documented in the pmtools package here: |
292 | http://ftp.kernel.org/pub/linux/kernel/people/lenb/acpi/utils | 281 | http://ftp.kernel.org/pub/linux/kernel/people/lenb/acpi/utils |
293 | |||
294 | Who: Len Brown <len.brown@intel.com> | 282 | Who: Len Brown <len.brown@intel.com> |
295 | 283 | ||
296 | --------------------------- | 284 | --------------------------- |
297 | 285 | ||
286 | What: ACPI procfs interface | ||
287 | When: July 2007 | ||
288 | Why: After ACPI sysfs conversion, ACPI attributes will be duplicated | ||
289 | in sysfs and the ACPI procfs interface should be removed. | ||
290 | Who: Zhang Rui <rui.zhang@intel.com> | ||
291 | |||
292 | --------------------------- | ||
293 | |||
298 | What: /proc/acpi/button | 294 | What: /proc/acpi/button |
299 | When: August 2007 | 295 | When: August 2007 |
300 | Why: /proc/acpi/button has been replaced by events to the input layer | 296 | Why: /proc/acpi/button has been replaced by events to the input layer |
@@ -309,3 +305,10 @@ Why: Unmaintained for years, superceded by JFFS2 for years. | |||
309 | Who: Jeff Garzik <jeff@garzik.org> | 305 | Who: Jeff Garzik <jeff@garzik.org> |
310 | 306 | ||
311 | --------------------------- | 307 | --------------------------- |
308 | |||
309 | What: sk98lin network driver | ||
310 | When: July 2007 | ||
311 | Why: In kernel tree version of driver is unmaintained. Sk98lin driver | ||
312 | replaced by the skge driver. | ||
313 | Who: Stephen Hemminger <shemminger@osdl.org> | ||
314 | |||
diff --git a/Documentation/s390/Debugging390.txt b/Documentation/s390/Debugging390.txt index 3f9ddbc23b27..0993969609cf 100644 --- a/Documentation/s390/Debugging390.txt +++ b/Documentation/s390/Debugging390.txt | |||
@@ -480,7 +480,7 @@ r2 argument 0 / return value 0 call-clobbered | |||
480 | r3 argument 1 / return value 1 (if long long) call-clobbered | 480 | r3 argument 1 / return value 1 (if long long) call-clobbered |
481 | r4 argument 2 call-clobbered | 481 | r4 argument 2 call-clobbered |
482 | r5 argument 3 call-clobbered | 482 | r5 argument 3 call-clobbered |
483 | r6 argument 5 saved | 483 | r6 argument 4 saved |
484 | r7 pointer-to arguments 5 to ... saved | 484 | r7 pointer-to arguments 5 to ... saved |
485 | r8 this & that saved | 485 | r8 this & that saved |
486 | r9 this & that saved | 486 | r9 this & that saved |
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. | ||
diff --git a/Documentation/usb/proc_usb_info.txt b/Documentation/usb/proc_usb_info.txt index 22c5331260ca..077e9032d0cd 100644 --- a/Documentation/usb/proc_usb_info.txt +++ b/Documentation/usb/proc_usb_info.txt | |||
@@ -213,15 +213,16 @@ C:* #Ifs=dd Cfg#=dd Atr=xx MPwr=dddmA | |||
213 | 213 | ||
214 | Interface descriptor info (can be multiple per Config): | 214 | Interface descriptor info (can be multiple per Config): |
215 | 215 | ||
216 | I: If#=dd Alt=dd #EPs=dd Cls=xx(sssss) Sub=xx Prot=xx Driver=ssss | 216 | I:* If#=dd Alt=dd #EPs=dd Cls=xx(sssss) Sub=xx Prot=xx Driver=ssss |
217 | | | | | | | | |__Driver name | 217 | | | | | | | | | |__Driver name |
218 | | | | | | | | or "(none)" | 218 | | | | | | | | | or "(none)" |
219 | | | | | | | |__InterfaceProtocol | 219 | | | | | | | | |__InterfaceProtocol |
220 | | | | | | |__InterfaceSubClass | 220 | | | | | | | |__InterfaceSubClass |
221 | | | | | |__InterfaceClass | 221 | | | | | | |__InterfaceClass |
222 | | | | |__NumberOfEndpoints | 222 | | | | | |__NumberOfEndpoints |
223 | | | |__AlternateSettingNumber | 223 | | | | |__AlternateSettingNumber |
224 | | |__InterfaceNumber | 224 | | | |__InterfaceNumber |
225 | | |__ "*" indicates the active altsetting (others are " ") | ||
225 | |__Interface info tag | 226 | |__Interface info tag |
226 | 227 | ||
227 | A given interface may have one or more "alternate" settings. | 228 | A given interface may have one or more "alternate" settings. |
@@ -277,7 +278,7 @@ of the USB devices on a system's root hub. (See more below | |||
277 | on how to do this.) | 278 | on how to do this.) |
278 | 279 | ||
279 | The Interface lines can be used to determine what driver is | 280 | The Interface lines can be used to determine what driver is |
280 | being used for each device. | 281 | being used for each device, and which altsetting it activated. |
281 | 282 | ||
282 | The Configuration lines could be used to list maximum power | 283 | The Configuration lines could be used to list maximum power |
283 | (in milliamps) that a system's USB devices are using. | 284 | (in milliamps) that a system's USB devices are using. |
diff --git a/Documentation/usb/usbmon.txt b/Documentation/usb/usbmon.txt index e65ec828d7aa..0f6808abd612 100644 --- a/Documentation/usb/usbmon.txt +++ b/Documentation/usb/usbmon.txt | |||
@@ -77,7 +77,7 @@ that the file size is not excessive for your favourite editor. | |||
77 | 77 | ||
78 | The '1t' type data consists of a stream of events, such as URB submission, | 78 | The '1t' type data consists of a stream of events, such as URB submission, |
79 | URB callback, submission error. Every event is a text line, which consists | 79 | URB callback, submission error. Every event is a text line, which consists |
80 | of whitespace separated words. The number of position of words may depend | 80 | of whitespace separated words. The number or position of words may depend |
81 | on the event type, but there is a set of words, common for all types. | 81 | on the event type, but there is a set of words, common for all types. |
82 | 82 | ||
83 | Here is the list of words, from left to right: | 83 | Here is the list of words, from left to right: |
@@ -170,4 +170,152 @@ dd65f0e8 4128379808 C Bo:005:02 0 31 > | |||
170 | 170 | ||
171 | * Raw binary format and API | 171 | * Raw binary format and API |
172 | 172 | ||
173 | TBD | 173 | The overall architecture of the API is about the same as the one above, |
174 | only the events are delivered in binary format. Each event is sent in | ||
175 | the following structure (its name is made up, so that we can refer to it): | ||
176 | |||
177 | struct usbmon_packet { | ||
178 | u64 id; /* 0: URB ID - from submission to callback */ | ||
179 | unsigned char type; /* 8: Same as text; extensible. */ | ||
180 | unsigned char xfer_type; /* ISO (0), Intr, Control, Bulk (3) */ | ||
181 | unsigned char epnum; /* Endpoint number and transfer direction */ | ||
182 | unsigned char devnum; /* Device address */ | ||
183 | u16 busnum; /* 12: Bus number */ | ||
184 | char flag_setup; /* 14: Same as text */ | ||
185 | char flag_data; /* 15: Same as text; Binary zero is OK. */ | ||
186 | s64 ts_sec; /* 16: gettimeofday */ | ||
187 | s32 ts_usec; /* 24: gettimeofday */ | ||
188 | int status; /* 28: */ | ||
189 | unsigned int length; /* 32: Length of data (submitted or actual) */ | ||
190 | unsigned int len_cap; /* 36: Delivered length */ | ||
191 | unsigned char setup[8]; /* 40: Only for Control 'S' */ | ||
192 | }; /* 48 bytes total */ | ||
193 | |||
194 | These events can be received from a character device by reading with read(2), | ||
195 | with an ioctl(2), or by accessing the buffer with mmap. | ||
196 | |||
197 | The character device is usually called /dev/usbmonN, where N is the USB bus | ||
198 | number. Number zero (/dev/usbmon0) is special and means "all buses". | ||
199 | However, this feature is not implemented yet. Note that specific naming | ||
200 | policy is set by your Linux distribution. | ||
201 | |||
202 | If you create /dev/usbmon0 by hand, make sure that it is owned by root | ||
203 | and has mode 0600. Otherwise, unpriviledged users will be able to snoop | ||
204 | keyboard traffic. | ||
205 | |||
206 | The following ioctl calls are available, with MON_IOC_MAGIC 0x92: | ||
207 | |||
208 | MON_IOCQ_URB_LEN, defined as _IO(MON_IOC_MAGIC, 1) | ||
209 | |||
210 | This call returns the length of data in the next event. Note that majority of | ||
211 | events contain no data, so if this call returns zero, it does not mean that | ||
212 | no events are available. | ||
213 | |||
214 | MON_IOCG_STATS, defined as _IOR(MON_IOC_MAGIC, 3, struct mon_bin_stats) | ||
215 | |||
216 | The argument is a pointer to the following structure: | ||
217 | |||
218 | struct mon_bin_stats { | ||
219 | u32 queued; | ||
220 | u32 dropped; | ||
221 | }; | ||
222 | |||
223 | The member "queued" refers to the number of events currently queued in the | ||
224 | buffer (and not to the number of events processed since the last reset). | ||
225 | |||
226 | The member "dropped" is the number of events lost since the last call | ||
227 | to MON_IOCG_STATS. | ||
228 | |||
229 | MON_IOCT_RING_SIZE, defined as _IO(MON_IOC_MAGIC, 4) | ||
230 | |||
231 | This call sets the buffer size. The argument is the size in bytes. | ||
232 | The size may be rounded down to the next chunk (or page). If the requested | ||
233 | size is out of [unspecified] bounds for this kernel, the call fails with | ||
234 | -EINVAL. | ||
235 | |||
236 | MON_IOCQ_RING_SIZE, defined as _IO(MON_IOC_MAGIC, 5) | ||
237 | |||
238 | This call returns the current size of the buffer in bytes. | ||
239 | |||
240 | MON_IOCX_GET, defined as _IOW(MON_IOC_MAGIC, 6, struct mon_get_arg) | ||
241 | |||
242 | This call waits for events to arrive if none were in the kernel buffer, | ||
243 | then returns the first event. Its argument is a pointer to the following | ||
244 | structure: | ||
245 | |||
246 | struct mon_get_arg { | ||
247 | struct usbmon_packet *hdr; | ||
248 | void *data; | ||
249 | size_t alloc; /* Length of data (can be zero) */ | ||
250 | }; | ||
251 | |||
252 | Before the call, hdr, data, and alloc should be filled. Upon return, the area | ||
253 | pointed by hdr contains the next event structure, and the data buffer contains | ||
254 | the data, if any. The event is removed from the kernel buffer. | ||
255 | |||
256 | MON_IOCX_MFETCH, defined as _IOWR(MON_IOC_MAGIC, 7, struct mon_mfetch_arg) | ||
257 | |||
258 | This ioctl is primarily used when the application accesses the buffer | ||
259 | with mmap(2). Its argument is a pointer to the following structure: | ||
260 | |||
261 | struct mon_mfetch_arg { | ||
262 | uint32_t *offvec; /* Vector of events fetched */ | ||
263 | uint32_t nfetch; /* Number of events to fetch (out: fetched) */ | ||
264 | uint32_t nflush; /* Number of events to flush */ | ||
265 | }; | ||
266 | |||
267 | The ioctl operates in 3 stages. | ||
268 | |||
269 | First, it removes and discards up to nflush events from the kernel buffer. | ||
270 | The actual number of events discarded is returned in nflush. | ||
271 | |||
272 | Second, it waits for an event to be present in the buffer, unless the pseudo- | ||
273 | device is open with O_NONBLOCK. | ||
274 | |||
275 | Third, it extracts up to nfetch offsets into the mmap buffer, and stores | ||
276 | them into the offvec. The actual number of event offsets is stored into | ||
277 | the nfetch. | ||
278 | |||
279 | MON_IOCH_MFLUSH, defined as _IO(MON_IOC_MAGIC, 8) | ||
280 | |||
281 | This call removes a number of events from the kernel buffer. Its argument | ||
282 | is the number of events to remove. If the buffer contains fewer events | ||
283 | than requested, all events present are removed, and no error is reported. | ||
284 | This works when no events are available too. | ||
285 | |||
286 | FIONBIO | ||
287 | |||
288 | The ioctl FIONBIO may be implemented in the future, if there's a need. | ||
289 | |||
290 | In addition to ioctl(2) and read(2), the special file of binary API can | ||
291 | be polled with select(2) and poll(2). But lseek(2) does not work. | ||
292 | |||
293 | * Memory-mapped access of the kernel buffer for the binary API | ||
294 | |||
295 | The basic idea is simple: | ||
296 | |||
297 | To prepare, map the buffer by getting the current size, then using mmap(2). | ||
298 | Then, execute a loop similar to the one written in pseudo-code below: | ||
299 | |||
300 | struct mon_mfetch_arg fetch; | ||
301 | struct usbmon_packet *hdr; | ||
302 | int nflush = 0; | ||
303 | for (;;) { | ||
304 | fetch.offvec = vec; // Has N 32-bit words | ||
305 | fetch.nfetch = N; // Or less than N | ||
306 | fetch.nflush = nflush; | ||
307 | ioctl(fd, MON_IOCX_MFETCH, &fetch); // Process errors, too | ||
308 | nflush = fetch.nfetch; // This many packets to flush when done | ||
309 | for (i = 0; i < nflush; i++) { | ||
310 | hdr = (struct ubsmon_packet *) &mmap_area[vec[i]]; | ||
311 | if (hdr->type == '@') // Filler packet | ||
312 | continue; | ||
313 | caddr_t data = &mmap_area[vec[i]] + 64; | ||
314 | process_packet(hdr, data); | ||
315 | } | ||
316 | } | ||
317 | |||
318 | Thus, the main idea is to execute only one ioctl per N events. | ||
319 | |||
320 | Although the buffer is circular, the returned headers and data do not cross | ||
321 | the end of the buffer, so the above pseudo-code does not need any gathering. | ||
diff --git a/Documentation/video-output.txt b/Documentation/video-output.txt new file mode 100644 index 000000000000..e517011be4f9 --- /dev/null +++ b/Documentation/video-output.txt | |||
@@ -0,0 +1,34 @@ | |||
1 | |||
2 | Video Output Switcher Control | ||
3 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
4 | 2006 luming.yu@intel.com | ||
5 | |||
6 | The output sysfs class driver provides an abstract video output layer that | ||
7 | can be used to hook platform specific methods to enable/disable video output | ||
8 | device through common sysfs interface. For example, on my IBM ThinkPad T42 | ||
9 | laptop, The ACPI video driver registered its output devices and read/write | ||
10 | method for 'state' with output sysfs class. The user interface under sysfs is: | ||
11 | |||
12 | linux:/sys/class/video_output # tree . | ||
13 | . | ||
14 | |-- CRT0 | ||
15 | | |-- device -> ../../../devices/pci0000:00/0000:00:01.0 | ||
16 | | |-- state | ||
17 | | |-- subsystem -> ../../../class/video_output | ||
18 | | `-- uevent | ||
19 | |-- DVI0 | ||
20 | | |-- device -> ../../../devices/pci0000:00/0000:00:01.0 | ||
21 | | |-- state | ||
22 | | |-- subsystem -> ../../../class/video_output | ||
23 | | `-- uevent | ||
24 | |-- LCD0 | ||
25 | | |-- device -> ../../../devices/pci0000:00/0000:00:01.0 | ||
26 | | |-- state | ||
27 | | |-- subsystem -> ../../../class/video_output | ||
28 | | `-- uevent | ||
29 | `-- TV0 | ||
30 | |-- device -> ../../../devices/pci0000:00/0000:00:01.0 | ||
31 | |-- state | ||
32 | |-- subsystem -> ../../../class/video_output | ||
33 | `-- uevent | ||
34 | |||