aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorJames Bottomley <jejb@mulgrave.il.steeleye.com>2007-02-10 14:45:43 -0500
committerJames Bottomley <jejb@mulgrave.il.steeleye.com>2007-02-10 14:45:43 -0500
commit81b7bbd1932a04869d4c8635a75222dfc6089f96 (patch)
tree285ae868a1e3a41fb0dbfe346c28e380949bcb55 /Documentation
parent98051995ab44b993f992946055edc6115351f725 (diff)
parent66efc5a7e3061c3597ac43a8bb1026488d57e66b (diff)
Merge branch 'linus'
Conflicts: drivers/scsi/ipr.c Signed-off-by: James Bottomley <James.Bottomley@SteelEye.com>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/HOWTO1
-rw-r--r--Documentation/crypto/api-intro.txt4
-rw-r--r--Documentation/driver-model/devres.txt268
-rw-r--r--Documentation/feature-removal-schedule.txt45
-rw-r--r--Documentation/s390/Debugging390.txt2
-rw-r--r--Documentation/sound/alsa/ALSA-Configuration.txt60
-rw-r--r--Documentation/sound/alsa/DocBook/alsa-driver-api.tmpl4
-rw-r--r--Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl33
-rw-r--r--Documentation/sound/alsa/hda_codec.txt10
-rw-r--r--Documentation/sound/alsa/soc/DAI.txt56
-rw-r--r--Documentation/sound/alsa/soc/clocking.txt51
-rw-r--r--Documentation/sound/alsa/soc/codec.txt197
-rw-r--r--Documentation/sound/alsa/soc/dapm.txt297
-rw-r--r--Documentation/sound/alsa/soc/machine.txt113
-rw-r--r--Documentation/sound/alsa/soc/overview.txt83
-rw-r--r--Documentation/sound/alsa/soc/platform.txt58
-rw-r--r--Documentation/sound/alsa/soc/pops_clicks.txt52
-rw-r--r--Documentation/sysrq.txt66
-rw-r--r--Documentation/usb/proc_usb_info.txt21
-rw-r--r--Documentation/usb/usbmon.txt152
-rw-r--r--Documentation/video-output.txt34
21 files changed, 1502 insertions, 105 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
30experience, the following books are good for, if anything, reference: 30experience, 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
34The kernel is written using GNU C and the GNU toolchain. While it 35The kernel is written using GNU C and the GNU toolchain. While it
35adheres to the ISO C89 standard, it uses a number of extensions that are 36adheres 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
197SHA1 algorithm contributors: 198SHA1 algorithm contributors:
198 Jean-Francois Dive 199 Jean-Francois Dive
@@ -246,6 +247,9 @@ Tiger algorithm contributors:
246VIA PadLock contributors: 247VIA PadLock contributors:
247 Michal Ludvig 248 Michal Ludvig
248 249
250Camellia algorithm contributors:
251 NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
252
249Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com> 253Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com>
250 254
251Please send any credits updates or corrections to: 255Please send any credits updates or corrections to:
diff --git a/Documentation/driver-model/devres.txt b/Documentation/driver-model/devres.txt
new file mode 100644
index 000000000000..5163b85308f5
--- /dev/null
+++ b/Documentation/driver-model/devres.txt
@@ -0,0 +1,268 @@
1Devres - Managed Device Resource
2================================
3
4Tejun Heo <teheo@suse.de>
5
6First draft 10 January 2007
7
8
91. Intro : Huh? Devres?
102. Devres : Devres in a nutshell
113. Devres Group : Group devres'es and release them together
124. Details : Life time rules, calling context, ...
135. Overhead : How much do we have to pay for this?
146. List of managed interfaces : Currently implemented managed interfaces
15
16
17 1. Intro
18 --------
19
20devres came up while trying to convert libata to use iomap. Each
21iomapped address should be kept and unmapped on driver detach. For
22example, a plain SFF ATA controller (that is, good old PCI IDE) in
23native mode makes use of 5 PCI BARs and all of them should be
24maintained.
25
26As with many other device drivers, libata low level drivers have
27sufficient bugs in ->remove and ->probe failure path. Well, yes,
28that's probably because libata low level driver developers are lazy
29bunch, but aren't all low level driver developers? After spending a
30day fiddling with braindamaged hardware with no document or
31braindamaged document, if it's finally working, well, it's working.
32
33For one reason or another, low level drivers don't receive as much
34attention or testing as core code, and bugs on driver detach or
35initilaization failure doesn't happen often enough to be noticeable.
36Init failure path is worse because it's much less travelled while
37needs to handle multiple entry points.
38
39So, many low level drivers end up leaking resources on driver detach
40and having half broken failure path implementation in ->probe() which
41would leak resources or even cause oops when failure occurs. iomap
42adds more to this mix. So do msi and msix.
43
44
45 2. Devres
46 ---------
47
48devres is basically linked list of arbitrarily sized memory areas
49associated with a struct device. Each devres entry is associated with
50a release function. A devres can be released in several ways. No
51matter what, all devres entries are released on driver detach. On
52release, the associated release function is invoked and then the
53devres entry is freed.
54
55Managed interface is created for resources commonly used by device
56drivers using devres. For example, coherent DMA memory is acquired
57using dma_alloc_coherent(). The managed version is called
58dmam_alloc_coherent(). It is identical to dma_alloc_coherent() except
59for the DMA memory allocated using it is managed and will be
60automatically released on driver detach. Implementation looks like
61the following.
62
63 struct dma_devres {
64 size_t size;
65 void *vaddr;
66 dma_addr_t dma_handle;
67 };
68
69 static void dmam_coherent_release(struct device *dev, void *res)
70 {
71 struct dma_devres *this = res;
72
73 dma_free_coherent(dev, this->size, this->vaddr, this->dma_handle);
74 }
75
76 dmam_alloc_coherent(dev, size, dma_handle, gfp)
77 {
78 struct dma_devres *dr;
79 void *vaddr;
80
81 dr = devres_alloc(dmam_coherent_release, sizeof(*dr), gfp);
82 ...
83
84 /* alloc DMA memory as usual */
85 vaddr = dma_alloc_coherent(...);
86 ...
87
88 /* record size, vaddr, dma_handle in dr */
89 dr->vaddr = vaddr;
90 ...
91
92 devres_add(dev, dr);
93
94 return vaddr;
95 }
96
97If a driver uses dmam_alloc_coherent(), the area is guaranteed to be
98freed whether initialization fails half-way or the device gets
99detached. If most resources are acquired using managed interface, a
100driver can have much simpler init and exit code. Init path basically
101looks like the following.
102
103 my_init_one()
104 {
105 struct mydev *d;
106
107 d = devm_kzalloc(dev, sizeof(*d), GFP_KERNEL);
108 if (!d)
109 return -ENOMEM;
110
111 d->ring = dmam_alloc_coherent(...);
112 if (!d->ring)
113 return -ENOMEM;
114
115 if (check something)
116 return -EINVAL;
117 ...
118
119 return register_to_upper_layer(d);
120 }
121
122And exit path,
123
124 my_remove_one()
125 {
126 unregister_from_upper_layer(d);
127 shutdown_my_hardware();
128 }
129
130As shown above, low level drivers can be simplified a lot by using
131devres. Complexity is shifted from less maintained low level drivers
132to better maintained higher layer. Also, as init failure path is
133shared with exit path, both can get more testing.
134
135
136 3. Devres group
137 ---------------
138
139Devres entries can be grouped using devres group. When a group is
140released, all contained normal devres entries and properly nested
141groups are released. One usage is to rollback series of acquired
142resources on failure. For example,
143
144 if (!devres_open_group(dev, NULL, GFP_KERNEL))
145 return -ENOMEM;
146
147 acquire A;
148 if (failed)
149 goto err;
150
151 acquire B;
152 if (failed)
153 goto err;
154 ...
155
156 devres_remove_group(dev, NULL);
157 return 0;
158
159 err:
160 devres_release_group(dev, NULL);
161 return err_code;
162
163As resource acquision failure usually means probe failure, constructs
164like above are usually useful in midlayer driver (e.g. libata core
165layer) where interface function shouldn't have side effect on failure.
166For LLDs, just returning error code suffices in most cases.
167
168Each group is identified by void *id. It can either be explicitly
169specified by @id argument to devres_open_group() or automatically
170created by passing NULL as @id as in the above example. In both
171cases, devres_open_group() returns the group's id. The returned id
172can be passed to other devres functions to select the target group.
173If NULL is given to those functions, the latest open group is
174selected.
175
176For example, you can do something like the following.
177
178 int my_midlayer_create_something()
179 {
180 if (!devres_open_group(dev, my_midlayer_create_something, GFP_KERNEL))
181 return -ENOMEM;
182
183 ...
184
185 devres_close_group(dev, my_midlayer_something);
186 return 0;
187 }
188
189 void my_midlayer_destroy_something()
190 {
191 devres_release_group(dev, my_midlayer_create_soemthing);
192 }
193
194
195 4. Details
196 ----------
197
198Lifetime of a devres entry begins on devres allocation and finishes
199when it is released or destroyed (removed and freed) - no reference
200counting.
201
202devres core guarantees atomicity to all basic devres operations and
203has support for single-instance devres types (atomic
204lookup-and-add-if-not-found). Other than that, synchronizing
205concurrent accesses to allocated devres data is caller's
206responsibility. This is usually non-issue because bus ops and
207resource allocations already do the job.
208
209For an example of single-instance devres type, read pcim_iomap_table()
210in lib/iomap.c.
211
212All devres interface functions can be called without context if the
213right gfp mask is given.
214
215
216 5. Overhead
217 -----------
218
219Each devres bookkeeping info is allocated together with requested data
220area. With debug option turned off, bookkeeping info occupies 16
221bytes on 32bit machines and 24 bytes on 64bit (three pointers rounded
222up to ull alignment). If singly linked list is used, it can be
223reduced to two pointers (8 bytes on 32bit, 16 bytes on 64bit).
224
225Each devres group occupies 8 pointers. It can be reduced to 6 if
226singly linked list is used.
227
228Memory space overhead on ahci controller with two ports is between 300
229and 400 bytes on 32bit machine after naive conversion (we can
230certainly invest a bit more effort into libata core layer).
231
232
233 6. List of managed interfaces
234 -----------------------------
235
236IO region
237 devm_request_region()
238 devm_request_mem_region()
239 devm_release_region()
240 devm_release_mem_region()
241
242IRQ
243 devm_request_irq()
244 devm_free_irq()
245
246DMA
247 dmam_alloc_coherent()
248 dmam_free_coherent()
249 dmam_alloc_noncoherent()
250 dmam_free_noncoherent()
251 dmam_declare_coherent_memory()
252 dmam_pool_create()
253 dmam_pool_destroy()
254
255PCI
256 pcim_enable_device() : after success, all PCI ops become managed
257 pcim_pin_device() : keep PCI device enabled after release
258
259IOMAP
260 devm_ioport_map()
261 devm_ioport_unmap()
262 devm_ioremap()
263 devm_ioremap_nocache()
264 devm_iounmap()
265 pcim_iomap()
266 pcim_iounmap()
267 pcim_iomap_table() : array of mapped addresses indexed by BAR
268 pcim_iomap_regions() : do request_region() and iomap() on multiple BARs
diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt
index 0ba6af02cdaf..fa844fd7bded 100644
--- a/Documentation/feature-removal-schedule.txt
+++ b/Documentation/feature-removal-schedule.txt
@@ -50,22 +50,6 @@ Who: Dan Dennedy <dan@dennedy.org>, Stefan Richter <stefanr@s5r6.in-berlin.de>
50 50
51--------------------------- 51---------------------------
52 52
53What: ieee1394 core's unused exports (CONFIG_IEEE1394_EXPORT_FULL_API)
54When: January 2007
55Why: There are no projects known to use these exported symbols, except
56 dfg1394 (uses one symbol whose functionality is core-internal now).
57Who: Stefan Richter <stefanr@s5r6.in-berlin.de>
58
59---------------------------
60
61What: ieee1394's *_oui sysfs attributes (CONFIG_IEEE1394_OUI_DB)
62When: January 2007
63Files: drivers/ieee1394/: oui.db, oui2c.sh
64Why: big size, little value
65Who: Stefan Richter <stefanr@s5r6.in-berlin.de>
66
67---------------------------
68
69What: Video4Linux API 1 ioctls and video_decoder.h from Video devices. 53What: Video4Linux API 1 ioctls and video_decoder.h from Video devices.
70When: December 2006 54When: December 2006
71Why: V4L1 AP1 was replaced by V4L2 API. during migration from 2.4 to 2.6 55Why: V4L1 AP1 was replaced by V4L2 API. during migration from 2.4 to 2.6
@@ -186,18 +170,6 @@ Who: Greg Kroah-Hartman <gregkh@suse.de>
186 170
187--------------------------- 171---------------------------
188 172
189What: find_trylock_page
190When: January 2007
191Why: The interface no longer has any callers left in the kernel. It
192 is an odd interface (compared with other find_*_page functions), in
193 that it does not take a refcount to the page, only the page lock.
194 It should be replaced with find_get_page or find_lock_page if possible.
195 This feature removal can be reevaluated if users of the interface
196 cannot cleanly use something else.
197Who: Nick Piggin <npiggin@suse.de>
198
199---------------------------
200
201What: Interrupt only SA_* flags 173What: Interrupt only SA_* flags
202When: Januar 2007 174When: Januar 2007
203Why: The interrupt related SA_* flags are replaced by IRQF_* to move them 175Why: The interrupt related SA_* flags are replaced by IRQF_* to move them
@@ -274,6 +246,7 @@ Who: Venkatesh Pallipadi <venkatesh.pallipadi@intel.com>
274 246
275--------------------------- 247---------------------------
276 248
249<<<<<<< test:Documentation/feature-removal-schedule.txt
277What: ACPI hotkey driver (CONFIG_ACPI_HOTKEY) 250What: ACPI hotkey driver (CONFIG_ACPI_HOTKEY)
278When: 2.6.21 251When: 2.6.21
279Why: hotkey.c was an attempt to consolidate multiple drivers that use 252Why: hotkey.c was an attempt to consolidate multiple drivers that use
@@ -306,11 +279,18 @@ Why: The ACPI namespace is effectively the symbol list for
306 the BIOS can be extracted and disassembled with acpidump 279 the BIOS can be extracted and disassembled with acpidump
307 and iasl as documented in the pmtools package here: 280 and iasl as documented in the pmtools package here:
308 http://ftp.kernel.org/pub/linux/kernel/people/lenb/acpi/utils 281 http://ftp.kernel.org/pub/linux/kernel/people/lenb/acpi/utils
309
310Who: Len Brown <len.brown@intel.com> 282Who: Len Brown <len.brown@intel.com>
311 283
312--------------------------- 284---------------------------
313 285
286What: ACPI procfs interface
287When: July 2007
288Why: After ACPI sysfs conversion, ACPI attributes will be duplicated
289 in sysfs and the ACPI procfs interface should be removed.
290Who: Zhang Rui <rui.zhang@intel.com>
291
292---------------------------
293
314What: /proc/acpi/button 294What: /proc/acpi/button
315When: August 2007 295When: August 2007
316Why: /proc/acpi/button has been replaced by events to the input layer 296Why: /proc/acpi/button has been replaced by events to the input layer
@@ -325,3 +305,10 @@ Why: Unmaintained for years, superceded by JFFS2 for years.
325Who: Jeff Garzik <jeff@garzik.org> 305Who: Jeff Garzik <jeff@garzik.org>
326 306
327--------------------------- 307---------------------------
308
309What: sk98lin network driver
310When: July 2007
311Why: In kernel tree version of driver is unmaintained. Sk98lin driver
312 replaced by the skge driver.
313Who: 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
480r3 argument 1 / return value 1 (if long long) call-clobbered 480r3 argument 1 / return value 1 (if long long) call-clobbered
481r4 argument 2 call-clobbered 481r4 argument 2 call-clobbered
482r5 argument 3 call-clobbered 482r5 argument 3 call-clobbered
483r6 argument 5 saved 483r6 argument 4 saved
484r7 pointer-to arguments 5 to ... saved 484r7 pointer-to arguments 5 to ... saved
485r8 this & that saved 485r8 this & that saved
486r9 this & that saved 486r9 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-&gt;runtime</constant>. 2126 accessible via <constant>substream-&gt;runtime</constant>.
2128 This runtime pointer holds the various information; it holds 2127 This runtime pointer holds the various information; it holds
2129 the copy of hw_params and sw_params configurations, the buffer 2128 the copy of hw_params and sw_params configurations, the buffer
2130 pointers, mmap records, spinlocks, etc. Almost everyhing you 2129 pointers, mmap records, spinlocks, etc. Almost everything you
2131 need for controlling the PCM can be found there. 2130 need for controlling the PCM can be found there.
2132 </para> 2131 </para>
2133 2132
@@ -2340,7 +2339,7 @@ struct _snd_pcm_runtime {
2340 2339
2341 <para> 2340 <para>
2342 When the PCM substreams can be synchronized (typically, 2341 When the PCM substreams can be synchronized (typically,
2343 synchorinized start/stop of a playback and a capture streams), 2342 synchronized start/stop of a playback and a capture streams),
2344 you can give <constant>SNDRV_PCM_INFO_SYNC_START</constant>, 2343 you can give <constant>SNDRV_PCM_INFO_SYNC_START</constant>,
2345 too. In this case, you'll need to check the linked-list of 2344 too. In this case, you'll need to check the linked-list of
2346 PCM substreams in the trigger callback. This will be 2345 PCM substreams in the trigger callback. This will be
@@ -3062,8 +3061,7 @@ struct _snd_pcm_runtime {
3062 <title>Interrupt Handler Case #1</title> 3061 <title>Interrupt Handler Case #1</title>
3063 <programlisting> 3062 <programlisting>
3064<![CDATA[ 3063<![CDATA[
3065 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id, 3064 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
3066 struct pt_regs *regs)
3067 { 3065 {
3068 struct mychip *chip = dev_id; 3066 struct mychip *chip = dev_id;
3069 spin_lock(&chip->lock); 3067 spin_lock(&chip->lock);
@@ -3106,8 +3104,7 @@ struct _snd_pcm_runtime {
3106 <title>Interrupt Handler Case #2</title> 3104 <title>Interrupt Handler Case #2</title>
3107 <programlisting> 3105 <programlisting>
3108<![CDATA[ 3106<![CDATA[
3109 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id, 3107 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
3110 struct pt_regs *regs)
3111 { 3108 {
3112 struct mychip *chip = dev_id; 3109 struct mychip *chip = dev_id;
3113 spin_lock(&chip->lock); 3110 spin_lock(&chip->lock);
@@ -3247,7 +3244,7 @@ struct _snd_pcm_runtime {
3247 You can even define your own constraint rules. 3244 You can even define your own constraint rules.
3248 For example, let's suppose my_chip can manage a substream of 1 channel 3245 For example, let's suppose my_chip can manage a substream of 1 channel
3249 if and only if the format is S16_LE, otherwise it supports any format 3246 if and only if the format is S16_LE, otherwise it supports any format
3250 specified in the <structname>snd_pcm_hardware</structname> stucture (or in any 3247 specified in the <structname>snd_pcm_hardware</structname> structure (or in any
3251 other constraint_list). You can build a rule like this: 3248 other constraint_list). You can build a rule like this:
3252 3249
3253 <example> 3250 <example>
@@ -3691,16 +3688,6 @@ struct _snd_pcm_runtime {
3691 </para> 3688 </para>
3692 3689
3693 <para> 3690 <para>
3694 Here, the chip instance is retrieved via
3695 <function>snd_kcontrol_chip()</function> macro. This macro
3696 just accesses to kcontrol-&gt;private_data. The
3697 kcontrol-&gt;private_data field is
3698 given as the argument of <function>snd_ctl_new()</function>
3699 (see the later subsection
3700 <link linkend="control-interface-constructor"><citetitle>Constructor</citetitle></link>).
3701 </para>
3702
3703 <para>
3704 The <structfield>value</structfield> field is depending on 3691 The <structfield>value</structfield> field is depending on
3705 the type of control as well as on info callback. For example, 3692 the type of control as well as on info callback. For example,
3706 the sb driver uses this field to store the register offset, 3693 the sb driver uses this field to store the register offset,
@@ -3780,7 +3767,7 @@ struct _snd_pcm_runtime {
3780 <para> 3767 <para>
3781 Like <structfield>get</structfield> callback, 3768 Like <structfield>get</structfield> callback,
3782 when the control has more than one elements, 3769 when the control has more than one elements,
3783 all elemehts must be evaluated in this callback, too. 3770 all elements must be evaluated in this callback, too.
3784 </para> 3771 </para>
3785 </section> 3772 </section>
3786 3773
@@ -5541,12 +5528,12 @@ struct _snd_pcm_runtime {
5541 #ifdef CONFIG_PM 5528 #ifdef CONFIG_PM
5542 static int snd_my_suspend(struct pci_dev *pci, pm_message_t state) 5529 static int snd_my_suspend(struct pci_dev *pci, pm_message_t state)
5543 { 5530 {
5544 .... /* do things for suspsend */ 5531 .... /* do things for suspend */
5545 return 0; 5532 return 0;
5546 } 5533 }
5547 static int snd_my_resume(struct pci_dev *pci) 5534 static int snd_my_resume(struct pci_dev *pci)
5548 { 5535 {
5549 .... /* do things for suspsend */ 5536 .... /* do things for suspend */
5550 return 0; 5537 return 0;
5551 } 5538 }
5552 #endif 5539 #endif
@@ -6111,7 +6098,7 @@ struct _snd_pcm_runtime {
6111<!-- ****************************************************** --> 6098<!-- ****************************************************** -->
6112<!-- Acknowledgments --> 6099<!-- Acknowledgments -->
6113<!-- ****************************************************** --> 6100<!-- ****************************************************** -->
6114 <chapter id="acknowledments"> 6101 <chapter id="acknowledgments">
6115 <title>Acknowledgments</title> 6102 <title>Acknowledgments</title>
6116 <para> 6103 <para>
6117 I would like to thank Phil Kerr for his help for improvement and 6104 I would like to thank Phil Kerr for his help for improvement and
diff --git a/Documentation/sound/alsa/hda_codec.txt b/Documentation/sound/alsa/hda_codec.txt
index 0be57ed81302..4eaae2a45534 100644
--- a/Documentation/sound/alsa/hda_codec.txt
+++ b/Documentation/sound/alsa/hda_codec.txt
@@ -277,11 +277,11 @@ Helper Functions
277snd_hda_get_codec_name() stores the codec name on the given string. 277snd_hda_get_codec_name() stores the codec name on the given string.
278 278
279snd_hda_check_board_config() can be used to obtain the configuration 279snd_hda_check_board_config() can be used to obtain the configuration
280information matching with the device. Define the table with struct 280information matching with the device. Define the model string table
281hda_board_config entries (zero-terminated), and pass it to the 281and the table with struct snd_pci_quirk entries (zero-terminated),
282function. The function checks the modelname given as a module 282and pass it to the function. The function checks the modelname given
283parameter, and PCI subsystem IDs. If the matching entry is found, it 283as a module parameter, and PCI subsystem IDs. If the matching entry
284returns the config field value. 284is found, it returns the config field value.
285 285
286snd_hda_add_new_ctls() can be used to create and add control entries. 286snd_hda_add_new_ctls() can be used to create and add control entries.
287Pass the zero-terminated array of struct snd_kcontrol_new. The same array 287Pass the zero-terminated array of struct snd_kcontrol_new. The same array
diff --git a/Documentation/sound/alsa/soc/DAI.txt b/Documentation/sound/alsa/soc/DAI.txt
new file mode 100644
index 000000000000..58cbfd01ea8f
--- /dev/null
+++ b/Documentation/sound/alsa/soc/DAI.txt
@@ -0,0 +1,56 @@
1ASoC currently supports the three main Digital Audio Interfaces (DAI) found on
2SoC controllers and portable audio CODECS today, namely AC97, I2S and PCM.
3
4
5AC97
6====
7
8 AC97 is a five wire interface commonly found on many PC sound cards. It is
9now also popular in many portable devices. This DAI has a reset line and time
10multiplexes its data on its SDATA_OUT (playback) and SDATA_IN (capture) lines.
11The bit clock (BCLK) is always driven by the CODEC (usually 12.288MHz) and the
12frame (FRAME) (usually 48kHz) is always driven by the controller. Each AC97
13frame is 21uS long and is divided into 13 time slots.
14
15The AC97 specification can be found at :-
16http://www.intel.com/design/chipsets/audio/ac97_r23.pdf
17
18
19I2S
20===
21
22 I2S is a common 4 wire DAI used in HiFi, STB and portable devices. The Tx and
23Rx lines are used for audio transmision, whilst the bit clock (BCLK) and
24left/right clock (LRC) synchronise the link. I2S is flexible in that either the
25controller or CODEC can drive (master) the BCLK and LRC clock lines. Bit clock
26usually varies depending on the sample rate and the master system clock
27(SYSCLK). LRCLK is the same as the sample rate. A few devices support separate
28ADC and DAC LRCLK's, this allows for similtanious capture and playback at
29different sample rates.
30
31I2S has several different operating modes:-
32
33 o I2S - MSB is transmitted on the falling edge of the first BCLK after LRC
34 transition.
35
36 o Left Justified - MSB is transmitted on transition of LRC.
37
38 o Right Justified - MSB is transmitted sample size BCLK's before LRC
39 transition.
40
41PCM
42===
43
44PCM is another 4 wire interface, very similar to I2S, that can support a more
45flexible protocol. It has bit clock (BCLK) and sync (SYNC) lines that are used
46to synchronise the link whilst the Tx and Rx lines are used to transmit and
47receive the audio data. Bit clock usually varies depending on sample rate
48whilst sync runs at the sample rate. PCM also supports Time Division
49Multiplexing (TDM) in that several devices can use the bus similtaniuosly (This
50is sometimes referred to as network mode).
51
52Common PCM operating modes:-
53
54 o Mode A - MSB is transmitted on falling edge of first BCLK after FRAME/SYNC.
55
56 o Mode B - MSB is transmitted on rising edge of FRAME/SYNC.
diff --git a/Documentation/sound/alsa/soc/clocking.txt b/Documentation/sound/alsa/soc/clocking.txt
new file mode 100644
index 000000000000..e93960d53a1e
--- /dev/null
+++ b/Documentation/sound/alsa/soc/clocking.txt
@@ -0,0 +1,51 @@
1Audio Clocking
2==============
3
4This text describes the audio clocking terms in ASoC and digital audio in
5general. Note: Audio clocking can be complex !
6
7
8Master Clock
9------------
10
11Every audio subsystem is driven by a master clock (sometimes refered to as MCLK
12or SYSCLK). This audio master clock can be derived from a number of sources
13(e.g. crystal, PLL, CPU clock) and is responsible for producing the correct
14audio playback and capture sample rates.
15
16Some master clocks (e.g. PLL's and CPU based clocks) are configuarble in that
17their speed can be altered by software (depending on the system use and to save
18power). Other master clocks are fixed at at set frequency (i.e. crystals).
19
20
21DAI Clocks
22----------
23The Digital Audio Interface is usually driven by a Bit Clock (often referred to
24as BCLK). This clock is used to drive the digital audio data across the link
25between the codec and CPU.
26
27The DAI also has a frame clock to signal the start of each audio frame. This
28clock is sometimes referred to as LRC (left right clock) or FRAME. This clock
29runs at exactly the sample rate (LRC = Rate).
30
31Bit Clock can be generated as follows:-
32
33BCLK = MCLK / x
34
35 or
36
37BCLK = LRC * x
38
39 or
40
41BCLK = LRC * Channels * Word Size
42
43This relationship depends on the codec or SoC CPU in particular. In general
44it's best to configure BCLK to the lowest possible speed (depending on your
45rate, number of channels and wordsize) to save on power.
46
47It's also desireable to use the codec (if possible) to drive (or master) the
48audio clocks as it's usually gives more accurate sample rates than the CPU.
49
50
51
diff --git a/Documentation/sound/alsa/soc/codec.txt b/Documentation/sound/alsa/soc/codec.txt
new file mode 100644
index 000000000000..48983c75aad9
--- /dev/null
+++ b/Documentation/sound/alsa/soc/codec.txt
@@ -0,0 +1,197 @@
1ASoC Codec Driver
2=================
3
4The codec driver is generic and hardware independent code that configures the
5codec to provide audio capture and playback. It should contain no code that is
6specific to the target platform or machine. All platform and machine specific
7code should be added to the platform and machine drivers respectively.
8
9Each codec driver *must* provide the following features:-
10
11 1) Codec DAI and PCM configuration
12 2) Codec control IO - using I2C, 3 Wire(SPI) or both API's
13 3) Mixers and audio controls
14 4) Codec audio operations
15
16Optionally, codec drivers can also provide:-
17
18 5) DAPM description.
19 6) DAPM event handler.
20 7) DAC Digital mute control.
21
22It's probably best to use this guide in conjuction with the existing codec
23driver code in sound/soc/codecs/
24
25ASoC Codec driver breakdown
26===========================
27
281 - Codec DAI and PCM configuration
29-----------------------------------
30Each codec driver must have a struct snd_soc_codec_dai to define it's DAI and
31PCM's capablities and operations. This struct is exported so that it can be
32registered with the core by your machine driver.
33
34e.g.
35
36struct snd_soc_codec_dai wm8731_dai = {
37 .name = "WM8731",
38 /* playback capabilities */
39 .playback = {
40 .stream_name = "Playback",
41 .channels_min = 1,
42 .channels_max = 2,
43 .rates = WM8731_RATES,
44 .formats = WM8731_FORMATS,},
45 /* capture capabilities */
46 .capture = {
47 .stream_name = "Capture",
48 .channels_min = 1,
49 .channels_max = 2,
50 .rates = WM8731_RATES,
51 .formats = WM8731_FORMATS,},
52 /* pcm operations - see section 4 below */
53 .ops = {
54 .prepare = wm8731_pcm_prepare,
55 .hw_params = wm8731_hw_params,
56 .shutdown = wm8731_shutdown,
57 },
58 /* DAI operations - see DAI.txt */
59 .dai_ops = {
60 .digital_mute = wm8731_mute,
61 .set_sysclk = wm8731_set_dai_sysclk,
62 .set_fmt = wm8731_set_dai_fmt,
63 }
64};
65EXPORT_SYMBOL_GPL(wm8731_dai);
66
67
682 - Codec control IO
69--------------------
70The codec can ususally be controlled via an I2C or SPI style interface (AC97
71combines control with data in the DAI). The codec drivers will have to provide
72functions to read and write the codec registers along with supplying a register
73cache:-
74
75 /* IO control data and register cache */
76 void *control_data; /* codec control (i2c/3wire) data */
77 void *reg_cache;
78
79Codec read/write should do any data formatting and call the hardware read write
80below to perform the IO. These functions are called by the core and alsa when
81performing DAPM or changing the mixer:-
82
83 unsigned int (*read)(struct snd_soc_codec *, unsigned int);
84 int (*write)(struct snd_soc_codec *, unsigned int, unsigned int);
85
86Codec hardware IO functions - usually points to either the I2C, SPI or AC97
87read/write:-
88
89 hw_write_t hw_write;
90 hw_read_t hw_read;
91
92
933 - Mixers and audio controls
94-----------------------------
95All the codec mixers and audio controls can be defined using the convenience
96macros defined in soc.h.
97
98 #define SOC_SINGLE(xname, reg, shift, mask, invert)
99
100Defines a single control as follows:-
101
102 xname = Control name e.g. "Playback Volume"
103 reg = codec register
104 shift = control bit(s) offset in register
105 mask = control bit size(s) e.g. mask of 7 = 3 bits
106 invert = the control is inverted
107
108Other macros include:-
109
110 #define SOC_DOUBLE(xname, reg, shift_left, shift_right, mask, invert)
111
112A stereo control
113
114 #define SOC_DOUBLE_R(xname, reg_left, reg_right, shift, mask, invert)
115
116A stereo control spanning 2 registers
117
118 #define SOC_ENUM_SINGLE(xreg, xshift, xmask, xtexts)
119
120Defines an single enumerated control as follows:-
121
122 xreg = register
123 xshift = control bit(s) offset in register
124 xmask = control bit(s) size
125 xtexts = pointer to array of strings that describe each setting
126
127 #define SOC_ENUM_DOUBLE(xreg, xshift_l, xshift_r, xmask, xtexts)
128
129Defines a stereo enumerated control
130
131
1324 - Codec Audio Operations
133--------------------------
134The codec driver also supports the following alsa operations:-
135
136/* SoC audio ops */
137struct snd_soc_ops {
138 int (*startup)(struct snd_pcm_substream *);
139 void (*shutdown)(struct snd_pcm_substream *);
140 int (*hw_params)(struct snd_pcm_substream *, struct snd_pcm_hw_params *);
141 int (*hw_free)(struct snd_pcm_substream *);
142 int (*prepare)(struct snd_pcm_substream *);
143};
144
145Please refer to the alsa driver PCM documentation for details.
146http://www.alsa-project.org/~iwai/writing-an-alsa-driver/c436.htm
147
148
1495 - DAPM description.
150---------------------
151The Dynamic Audio Power Management description describes the codec's power
152components, their relationships and registers to the ASoC core. Please read
153dapm.txt for details of building the description.
154
155Please also see the examples in other codec drivers.
156
157
1586 - DAPM event handler
159----------------------
160This function is a callback that handles codec domain PM calls and system
161domain PM calls (e.g. suspend and resume). It's used to put the codec to sleep
162when not in use.
163
164Power states:-
165
166 SNDRV_CTL_POWER_D0: /* full On */
167 /* vref/mid, clk and osc on, active */
168
169 SNDRV_CTL_POWER_D1: /* partial On */
170 SNDRV_CTL_POWER_D2: /* partial On */
171
172 SNDRV_CTL_POWER_D3hot: /* Off, with power */
173 /* everything off except vref/vmid, inactive */
174
175 SNDRV_CTL_POWER_D3cold: /* Everything Off, without power */
176
177
1787 - Codec DAC digital mute control.
179------------------------------------
180Most codecs have a digital mute before the DAC's that can be used to minimise
181any system noise. The mute stops any digital data from entering the DAC.
182
183A callback can be created that is called by the core for each codec DAI when the
184mute is applied or freed.
185
186i.e.
187
188static int wm8974_mute(struct snd_soc_codec *codec,
189 struct snd_soc_codec_dai *dai, int mute)
190{
191 u16 mute_reg = wm8974_read_reg_cache(codec, WM8974_DAC) & 0xffbf;
192 if(mute)
193 wm8974_write(codec, WM8974_DAC, mute_reg | 0x40);
194 else
195 wm8974_write(codec, WM8974_DAC, mute_reg);
196 return 0;
197}
diff --git a/Documentation/sound/alsa/soc/dapm.txt b/Documentation/sound/alsa/soc/dapm.txt
new file mode 100644
index 000000000000..c11877f5b4a1
--- /dev/null
+++ b/Documentation/sound/alsa/soc/dapm.txt
@@ -0,0 +1,297 @@
1Dynamic Audio Power Management for Portable Devices
2===================================================
3
41. Description
5==============
6
7Dynamic Audio Power Management (DAPM) is designed to allow portable Linux devices
8to use the minimum amount of power within the audio subsystem at all times. It
9is independent of other kernel PM and as such, can easily co-exist with the
10other PM systems.
11
12DAPM is also completely transparent to all user space applications as all power
13switching is done within the ASoC core. No code changes or recompiling are
14required for user space applications. DAPM makes power switching descisions based
15upon any audio stream (capture/playback) activity and audio mixer settings
16within the device.
17
18DAPM spans the whole machine. It covers power control within the entire audio
19subsystem, this includes internal codec power blocks and machine level power
20systems.
21
22There are 4 power domains within DAPM
23
24 1. Codec domain - VREF, VMID (core codec and audio power)
25 Usually controlled at codec probe/remove and suspend/resume, although
26 can be set at stream time if power is not needed for sidetone, etc.
27
28 2. Platform/Machine domain - physically connected inputs and outputs
29 Is platform/machine and user action specific, is configured by the
30 machine driver and responds to asynchronous events e.g when HP
31 are inserted
32
33 3. Path domain - audio susbsystem signal paths
34 Automatically set when mixer and mux settings are changed by the user.
35 e.g. alsamixer, amixer.
36
37 4. Stream domain - DAC's and ADC's.
38 Enabled and disabled when stream playback/capture is started and
39 stopped respectively. e.g. aplay, arecord.
40
41All DAPM power switching descisons are made automatically by consulting an audio
42routing map of the whole machine. This map is specific to each machine and
43consists of the interconnections between every audio component (including
44internal codec components). All audio components that effect power are called
45widgets hereafter.
46
47
482. DAPM Widgets
49===============
50
51Audio DAPM widgets fall into a number of types:-
52
53 o Mixer - Mixes several analog signals into a single analog signal.
54 o Mux - An analog switch that outputs only 1 of it's inputs.
55 o PGA - A programmable gain amplifier or attenuation widget.
56 o ADC - Analog to Digital Converter
57 o DAC - Digital to Analog Converter
58 o Switch - An analog switch
59 o Input - A codec input pin
60 o Output - A codec output pin
61 o Headphone - Headphone (and optional Jack)
62 o Mic - Mic (and optional Jack)
63 o Line - Line Input/Output (and optional Jack)
64 o Speaker - Speaker
65 o Pre - Special PRE widget (exec before all others)
66 o Post - Special POST widget (exec after all others)
67
68(Widgets are defined in include/sound/soc-dapm.h)
69
70Widgets are usually added in the codec driver and the machine driver. There are
71convience macros defined in soc-dapm.h that can be used to quickly build a
72list of widgets of the codecs and machines DAPM widgets.
73
74Most widgets have a name, register, shift and invert. Some widgets have extra
75parameters for stream name and kcontrols.
76
77
782.1 Stream Domain Widgets
79-------------------------
80
81Stream Widgets relate to the stream power domain and only consist of ADC's
82(analog to digital converters) and DAC's (digital to analog converters).
83
84Stream widgets have the following format:-
85
86SND_SOC_DAPM_DAC(name, stream name, reg, shift, invert),
87
88NOTE: the stream name must match the corresponding stream name in your codecs
89snd_soc_codec_dai.
90
91e.g. stream widgets for HiFi playback and capture
92
93SND_SOC_DAPM_DAC("HiFi DAC", "HiFi Playback", REG, 3, 1),
94SND_SOC_DAPM_ADC("HiFi ADC", "HiFi Capture", REG, 2, 1),
95
96
972.2 Path Domain Widgets
98-----------------------
99
100Path domain widgets have a ability to control or effect the audio signal or
101audio paths within the audio subsystem. They have the following form:-
102
103SND_SOC_DAPM_PGA(name, reg, shift, invert, controls, num_controls)
104
105Any widget kcontrols can be set using the controls and num_controls members.
106
107e.g. Mixer widget (the kcontrols are declared first)
108
109/* Output Mixer */
110static const snd_kcontrol_new_t wm8731_output_mixer_controls[] = {
111SOC_DAPM_SINGLE("Line Bypass Switch", WM8731_APANA, 3, 1, 0),
112SOC_DAPM_SINGLE("Mic Sidetone Switch", WM8731_APANA, 5, 1, 0),
113SOC_DAPM_SINGLE("HiFi Playback Switch", WM8731_APANA, 4, 1, 0),
114};
115
116SND_SOC_DAPM_MIXER("Output Mixer", WM8731_PWR, 4, 1, wm8731_output_mixer_controls,
117 ARRAY_SIZE(wm8731_output_mixer_controls)),
118
119
1202.3 Platform/Machine domain Widgets
121-----------------------------------
122
123Machine widgets are different from codec widgets in that they don't have a
124codec register bit associated with them. A machine widget is assigned to each
125machine audio component (non codec) that can be independently powered. e.g.
126
127 o Speaker Amp
128 o Microphone Bias
129 o Jack connectors
130
131A machine widget can have an optional call back.
132
133e.g. Jack connector widget for an external Mic that enables Mic Bias
134when the Mic is inserted:-
135
136static int spitz_mic_bias(struct snd_soc_dapm_widget* w, int event)
137{
138 if(SND_SOC_DAPM_EVENT_ON(event))
139 set_scoop_gpio(&spitzscoop2_device.dev, SPITZ_SCP2_MIC_BIAS);
140 else
141 reset_scoop_gpio(&spitzscoop2_device.dev, SPITZ_SCP2_MIC_BIAS);
142
143 return 0;
144}
145
146SND_SOC_DAPM_MIC("Mic Jack", spitz_mic_bias),
147
148
1492.4 Codec Domain
150----------------
151
152The Codec power domain has no widgets and is handled by the codecs DAPM event
153handler. This handler is called when the codec powerstate is changed wrt to any
154stream event or by kernel PM events.
155
156
1572.5 Virtual Widgets
158-------------------
159
160Sometimes widgets exist in the codec or machine audio map that don't have any
161corresponding register bit for power control. In this case it's necessary to
162create a virtual widget - a widget with no control bits e.g.
163
164SND_SOC_DAPM_MIXER("AC97 Mixer", SND_SOC_DAPM_NOPM, 0, 0, NULL, 0),
165
166This can be used to merge to signal paths together in software.
167
168After all the widgets have been defined, they can then be added to the DAPM
169subsystem individually with a call to snd_soc_dapm_new_control().
170
171
1723. Codec Widget Interconnections
173================================
174
175Widgets are connected to each other within the codec and machine by audio
176paths (called interconnections). Each interconnection must be defined in order
177to create a map of all audio paths between widgets.
178This is easiest with a diagram of the codec (and schematic of the machine audio
179system), as it requires joining widgets together via their audio signal paths.
180
181i.e. from the WM8731 codec's output mixer (wm8731.c)
182
183The WM8731 output mixer has 3 inputs (sources)
184
185 1. Line Bypass Input
186 2. DAC (HiFi playback)
187 3. Mic Sidetone Input
188
189Each input in this example has a kcontrol associated with it (defined in example
190above) and is connected to the output mixer via it's kcontrol name. We can now
191connect the destination widget (wrt audio signal) with it's source widgets.
192
193 /* output mixer */
194 {"Output Mixer", "Line Bypass Switch", "Line Input"},
195 {"Output Mixer", "HiFi Playback Switch", "DAC"},
196 {"Output Mixer", "Mic Sidetone Switch", "Mic Bias"},
197
198So we have :-
199
200 Destination Widget <=== Path Name <=== Source Widget
201
202Or:-
203
204 Sink, Path, Source
205
206Or :-
207
208 "Output Mixer" is connected to the "DAC" via the "HiFi Playback Switch".
209
210When there is no path name connecting widgets (e.g. a direct connection) we
211pass NULL for the path name.
212
213Interconnections are created with a call to:-
214
215snd_soc_dapm_connect_input(codec, sink, path, source);
216
217Finally, snd_soc_dapm_new_widgets(codec) must be called after all widgets and
218interconnections have been registered with the core. This causes the core to
219scan the codec and machine so that the internal DAPM state matches the
220physical state of the machine.
221
222
2233.1 Machine Widget Interconnections
224-----------------------------------
225Machine widget interconnections are created in the same way as codec ones and
226directly connect the codec pins to machine level widgets.
227
228e.g. connects the speaker out codec pins to the internal speaker.
229
230 /* ext speaker connected to codec pins LOUT2, ROUT2 */
231 {"Ext Spk", NULL , "ROUT2"},
232 {"Ext Spk", NULL , "LOUT2"},
233
234This allows the DAPM to power on and off pins that are connected (and in use)
235and pins that are NC respectively.
236
237
2384 Endpoint Widgets
239===================
240An endpoint is a start or end point (widget) of an audio signal within the
241machine and includes the codec. e.g.
242
243 o Headphone Jack
244 o Internal Speaker
245 o Internal Mic
246 o Mic Jack
247 o Codec Pins
248
249When a codec pin is NC it can be marked as not used with a call to
250
251snd_soc_dapm_set_endpoint(codec, "Widget Name", 0);
252
253The last argument is 0 for inactive and 1 for active. This way the pin and its
254input widget will never be powered up and consume power.
255
256This also applies to machine widgets. e.g. if a headphone is connected to a
257jack then the jack can be marked active. If the headphone is removed, then
258the headphone jack can be marked inactive.
259
260
2615 DAPM Widget Events
262====================
263
264Some widgets can register their interest with the DAPM core in PM events.
265e.g. A Speaker with an amplifier registers a widget so the amplifier can be
266powered only when the spk is in use.
267
268/* turn speaker amplifier on/off depending on use */
269static int corgi_amp_event(struct snd_soc_dapm_widget *w, int event)
270{
271 if (SND_SOC_DAPM_EVENT_ON(event))
272 set_scoop_gpio(&corgiscoop_device.dev, CORGI_SCP_APM_ON);
273 else
274 reset_scoop_gpio(&corgiscoop_device.dev, CORGI_SCP_APM_ON);
275
276 return 0;
277}
278
279/* corgi machine dapm widgets */
280static const struct snd_soc_dapm_widget wm8731_dapm_widgets =
281 SND_SOC_DAPM_SPK("Ext Spk", corgi_amp_event);
282
283Please see soc-dapm.h for all other widgets that support events.
284
285
2865.1 Event types
287---------------
288
289The following event types are supported by event widgets.
290
291/* dapm event types */
292#define SND_SOC_DAPM_PRE_PMU 0x1 /* before widget power up */
293#define SND_SOC_DAPM_POST_PMU 0x2 /* after widget power up */
294#define SND_SOC_DAPM_PRE_PMD 0x4 /* before widget power down */
295#define SND_SOC_DAPM_POST_PMD 0x8 /* after widget power down */
296#define SND_SOC_DAPM_PRE_REG 0x10 /* before audio path setup */
297#define SND_SOC_DAPM_POST_REG 0x20 /* after audio path setup */
diff --git a/Documentation/sound/alsa/soc/machine.txt b/Documentation/sound/alsa/soc/machine.txt
new file mode 100644
index 000000000000..72bd222f2a21
--- /dev/null
+++ b/Documentation/sound/alsa/soc/machine.txt
@@ -0,0 +1,113 @@
1ASoC Machine Driver
2===================
3
4The ASoC machine (or board) driver is the code that glues together the platform
5and codec drivers.
6
7The machine driver can contain codec and platform specific code. It registers
8the audio subsystem with the kernel as a platform device and is represented by
9the following struct:-
10
11/* SoC machine */
12struct snd_soc_machine {
13 char *name;
14
15 int (*probe)(struct platform_device *pdev);
16 int (*remove)(struct platform_device *pdev);
17
18 /* the pre and post PM functions are used to do any PM work before and
19 * after the codec and DAI's do any PM work. */
20 int (*suspend_pre)(struct platform_device *pdev, pm_message_t state);
21 int (*suspend_post)(struct platform_device *pdev, pm_message_t state);
22 int (*resume_pre)(struct platform_device *pdev);
23 int (*resume_post)(struct platform_device *pdev);
24
25 /* machine stream operations */
26 struct snd_soc_ops *ops;
27
28 /* CPU <--> Codec DAI links */
29 struct snd_soc_dai_link *dai_link;
30 int num_links;
31};
32
33probe()/remove()
34----------------
35probe/remove are optional. Do any machine specific probe here.
36
37
38suspend()/resume()
39------------------
40The machine driver has pre and post versions of suspend and resume to take care
41of any machine audio tasks that have to be done before or after the codec, DAI's
42and DMA is suspended and resumed. Optional.
43
44
45Machine operations
46------------------
47The machine specific audio operations can be set here. Again this is optional.
48
49
50Machine DAI Configuration
51-------------------------
52The machine DAI configuration glues all the codec and CPU DAI's together. It can
53also be used to set up the DAI system clock and for any machine related DAI
54initialisation e.g. the machine audio map can be connected to the codec audio
55map, unconnnected codec pins can be set as such. Please see corgi.c, spitz.c
56for examples.
57
58struct snd_soc_dai_link is used to set up each DAI in your machine. e.g.
59
60/* corgi digital audio interface glue - connects codec <--> CPU */
61static struct snd_soc_dai_link corgi_dai = {
62 .name = "WM8731",
63 .stream_name = "WM8731",
64 .cpu_dai = &pxa_i2s_dai,
65 .codec_dai = &wm8731_dai,
66 .init = corgi_wm8731_init,
67 .ops = &corgi_ops,
68};
69
70struct snd_soc_machine then sets up the machine with it's DAI's. e.g.
71
72/* corgi audio machine driver */
73static struct snd_soc_machine snd_soc_machine_corgi = {
74 .name = "Corgi",
75 .dai_link = &corgi_dai,
76 .num_links = 1,
77};
78
79
80Machine Audio Subsystem
81-----------------------
82
83The machine soc device glues the platform, machine and codec driver together.
84Private data can also be set here. e.g.
85
86/* corgi audio private data */
87static struct wm8731_setup_data corgi_wm8731_setup = {
88 .i2c_address = 0x1b,
89};
90
91/* corgi audio subsystem */
92static struct snd_soc_device corgi_snd_devdata = {
93 .machine = &snd_soc_machine_corgi,
94 .platform = &pxa2xx_soc_platform,
95 .codec_dev = &soc_codec_dev_wm8731,
96 .codec_data = &corgi_wm8731_setup,
97};
98
99
100Machine Power Map
101-----------------
102
103The machine driver can optionally extend the codec power map and to become an
104audio power map of the audio subsystem. This allows for automatic power up/down
105of speaker/HP amplifiers, etc. Codec pins can be connected to the machines jack
106sockets in the machine init function. See soc/pxa/spitz.c and dapm.txt for
107details.
108
109
110Machine Controls
111----------------
112
113Machine specific audio mixer controls can be added in the dai init function. \ No newline at end of file
diff --git a/Documentation/sound/alsa/soc/overview.txt b/Documentation/sound/alsa/soc/overview.txt
new file mode 100644
index 000000000000..753c5cc5984a
--- /dev/null
+++ b/Documentation/sound/alsa/soc/overview.txt
@@ -0,0 +1,83 @@
1ALSA SoC Layer
2==============
3
4The overall project goal of the ALSA System on Chip (ASoC) layer is to provide
5better ALSA support for embedded system on chip procesors (e.g. pxa2xx, au1x00,
6iMX, etc) and portable audio codecs. Currently there is some support in the
7kernel for SoC audio, however it has some limitations:-
8
9 * Currently, codec drivers are often tightly coupled to the underlying SoC
10 cpu. This is not ideal and leads to code duplication i.e. Linux now has 4
11 different wm8731 drivers for 4 different SoC platforms.
12
13 * There is no standard method to signal user initiated audio events.
14 e.g. Headphone/Mic insertion, Headphone/Mic detection after an insertion
15 event. These are quite common events on portable devices and ofter require
16 machine specific code to re route audio, enable amps etc after such an event.
17
18 * Current drivers tend to power up the entire codec when playing
19 (or recording) audio. This is fine for a PC, but tends to waste a lot of
20 power on portable devices. There is also no support for saving power via
21 changing codec oversampling rates, bias currents, etc.
22
23
24ASoC Design
25===========
26
27The ASoC layer is designed to address these issues and provide the following
28features :-
29
30 * Codec independence. Allows reuse of codec drivers on other platforms
31 and machines.
32
33 * Easy I2S/PCM audio interface setup between codec and SoC. Each SoC interface
34 and codec registers it's audio interface capabilities with the core and are
35 subsequently matched and configured when the application hw params are known.
36
37 * Dynamic Audio Power Management (DAPM). DAPM automatically sets the codec to
38 it's minimum power state at all times. This includes powering up/down
39 internal power blocks depending on the internal codec audio routing and any
40 active streams.
41
42 * Pop and click reduction. Pops and clicks can be reduced by powering the
43 codec up/down in the correct sequence (including using digital mute). ASoC
44 signals the codec when to change power states.
45
46 * Machine specific controls: Allow machines to add controls to the sound card
47 e.g. volume control for speaker amp.
48
49To achieve all this, ASoC basically splits an embedded audio system into 3
50components :-
51
52 * Codec driver: The codec driver is platform independent and contains audio
53 controls, audio interface capabilities, codec dapm definition and codec IO
54 functions.
55
56 * Platform driver: The platform driver contains the audio dma engine and audio
57 interface drivers (e.g. I2S, AC97, PCM) for that platform.
58
59 * Machine driver: The machine driver handles any machine specific controls and
60 audio events. i.e. turing on an amp at start of playback.
61
62
63Documentation
64=============
65
66The documentation is spilt into the following sections:-
67
68overview.txt: This file.
69
70codec.txt: Codec driver internals.
71
72DAI.txt: Description of Digital Audio Interface standards and how to configure
73a DAI within your codec and CPU DAI drivers.
74
75dapm.txt: Dynamic Audio Power Management
76
77platform.txt: Platform audio DMA and DAI.
78
79machine.txt: Machine driver internals.
80
81pop_clicks.txt: How to minimise audio artifacts.
82
83clocking.txt: ASoC clocking for best power performance. \ No newline at end of file
diff --git a/Documentation/sound/alsa/soc/platform.txt b/Documentation/sound/alsa/soc/platform.txt
new file mode 100644
index 000000000000..e95b16d5a53b
--- /dev/null
+++ b/Documentation/sound/alsa/soc/platform.txt
@@ -0,0 +1,58 @@
1ASoC Platform Driver
2====================
3
4An ASoC platform driver can be divided into audio DMA and SoC DAI configuration
5and control. The platform drivers only target the SoC CPU and must have no board
6specific code.
7
8Audio DMA
9=========
10
11The platform DMA driver optionally supports the following alsa operations:-
12
13/* SoC audio ops */
14struct snd_soc_ops {
15 int (*startup)(struct snd_pcm_substream *);
16 void (*shutdown)(struct snd_pcm_substream *);
17 int (*hw_params)(struct snd_pcm_substream *, struct snd_pcm_hw_params *);
18 int (*hw_free)(struct snd_pcm_substream *);
19 int (*prepare)(struct snd_pcm_substream *);
20 int (*trigger)(struct snd_pcm_substream *, int);
21};
22
23The platform driver exports it's DMA functionailty via struct snd_soc_platform:-
24
25struct snd_soc_platform {
26 char *name;
27
28 int (*probe)(struct platform_device *pdev);
29 int (*remove)(struct platform_device *pdev);
30 int (*suspend)(struct platform_device *pdev, struct snd_soc_cpu_dai *cpu_dai);
31 int (*resume)(struct platform_device *pdev, struct snd_soc_cpu_dai *cpu_dai);
32
33 /* pcm creation and destruction */
34 int (*pcm_new)(struct snd_card *, struct snd_soc_codec_dai *, struct snd_pcm *);
35 void (*pcm_free)(struct snd_pcm *);
36
37 /* platform stream ops */
38 struct snd_pcm_ops *pcm_ops;
39};
40
41Please refer to the alsa driver documentation for details of audio DMA.
42http://www.alsa-project.org/~iwai/writing-an-alsa-driver/c436.htm
43
44An example DMA driver is soc/pxa/pxa2xx-pcm.c
45
46
47SoC DAI Drivers
48===============
49
50Each SoC DAI driver must provide the following features:-
51
52 1) Digital audio interface (DAI) description
53 2) Digital audio interface configuration
54 3) PCM's description
55 4) Sysclk configuration
56 5) Suspend and resume (optional)
57
58Please see codec.txt for a description of items 1 - 4.
diff --git a/Documentation/sound/alsa/soc/pops_clicks.txt b/Documentation/sound/alsa/soc/pops_clicks.txt
new file mode 100644
index 000000000000..2cf7ee5b3d74
--- /dev/null
+++ b/Documentation/sound/alsa/soc/pops_clicks.txt
@@ -0,0 +1,52 @@
1Audio Pops and Clicks
2=====================
3
4Pops and clicks are unwanted audio artifacts caused by the powering up and down
5of components within the audio subsystem. This is noticable on PC's when an
6audio module is either loaded or unloaded (at module load time the sound card is
7powered up and causes a popping noise on the speakers).
8
9Pops and clicks can be more frequent on portable systems with DAPM. This is
10because the components within the subsystem are being dynamically powered
11depending on the audio usage and this can subsequently cause a small pop or
12click every time a component power state is changed.
13
14
15Minimising Playback Pops and Clicks
16===================================
17
18Playback pops in portable audio subsystems cannot be completely eliminated atm,
19however future audio codec hardware will have better pop and click supression.
20Pops can be reduced within playback by powering the audio components in a
21specific order. This order is different for startup and shutdown and follows
22some basic rules:-
23
24 Startup Order :- DAC --> Mixers --> Output PGA --> Digital Unmute
25
26 Shutdown Order :- Digital Mute --> Output PGA --> Mixers --> DAC
27
28This assumes that the codec PCM output path from the DAC is via a mixer and then
29a PGA (programmable gain amplifier) before being output to the speakers.
30
31
32Minimising Capture Pops and Clicks
33==================================
34
35Capture artifacts are somewhat easier to get rid as we can delay activating the
36ADC until all the pops have occured. This follows similar power rules to
37playback in that components are powered in a sequence depending upon stream
38startup or shutdown.
39
40 Startup Order - Input PGA --> Mixers --> ADC
41
42 Shutdown Order - ADC --> Mixers --> Input PGA
43
44
45Zipper Noise
46============
47An unwanted zipper noise can occur within the audio playback or capture stream
48when a volume control is changed near its maximum gain value. The zipper noise
49is heard when the gain increase or decrease changes the mean audio signal
50amplitude too quickly. It can be minimised by enabling the zero cross setting
51for each volume control. The ZC forces the gain change to occur when the signal
52crosses the zero amplitude line.
diff --git a/Documentation/sysrq.txt b/Documentation/sysrq.txt
index e0188a23fd5e..61613166981b 100644
--- a/Documentation/sysrq.txt
+++ b/Documentation/sysrq.txt
@@ -1,6 +1,6 @@
1Linux Magic System Request Key Hacks 1Linux Magic System Request Key Hacks
2Documentation for sysrq.c version 1.15 2Documentation for sysrq.c
3Last update: $Date: 2001/01/28 10:15:59 $ 3Last update: 2007-JAN-06
4 4
5* What is the magic SysRq key? 5* What is the magic SysRq key?
6~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 6~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -35,7 +35,7 @@ You can set the value in the file by the following command:
35 35
36Note that the value of /proc/sys/kernel/sysrq influences only the invocation 36Note that the value of /proc/sys/kernel/sysrq influences only the invocation
37via a keyboard. Invocation of any operation via /proc/sysrq-trigger is always 37via a keyboard. Invocation of any operation via /proc/sysrq-trigger is always
38allowed. 38allowed (by a user with admin privileges).
39 39
40* How do I use the magic SysRq key? 40* How do I use the magic SysRq key?
41~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 41~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -58,7 +58,7 @@ On PowerPC - Press 'ALT - Print Screen (or F13) - <command key>,
58On other - If you know of the key combos for other architectures, please 58On other - If you know of the key combos for other architectures, please
59 let me know so I can add them to this section. 59 let me know so I can add them to this section.
60 60
61On all - write a character to /proc/sysrq-trigger. eg: 61On all - write a character to /proc/sysrq-trigger. e.g.:
62 62
63 echo t > /proc/sysrq-trigger 63 echo t > /proc/sysrq-trigger
64 64
@@ -74,6 +74,8 @@ On all - write a character to /proc/sysrq-trigger. eg:
74 74
75'c' - Will perform a kexec reboot in order to take a crashdump. 75'c' - Will perform a kexec reboot in order to take a crashdump.
76 76
77'd' - Shows all locks that are held.
78
77'o' - Will shut your system off (if configured and supported). 79'o' - Will shut your system off (if configured and supported).
78 80
79's' - Will attempt to sync all mounted filesystems. 81's' - Will attempt to sync all mounted filesystems.
@@ -87,38 +89,43 @@ On all - write a character to /proc/sysrq-trigger. eg:
87 89
88'm' - Will dump current memory info to your console. 90'm' - Will dump current memory info to your console.
89 91
92'n' - Used to make RT tasks nice-able
93
90'v' - Dumps Voyager SMP processor info to your console. 94'v' - Dumps Voyager SMP processor info to your console.
91 95
96'w' - Dumps tasks that are in uninterruptable (blocked) state.
97
98'x' - Used by xmon interface on ppc/powerpc platforms.
99
92'0'-'9' - Sets the console log level, controlling which kernel messages 100'0'-'9' - Sets the console log level, controlling which kernel messages
93 will be printed to your console. ('0', for example would make 101 will be printed to your console. ('0', for example would make
94 it so that only emergency messages like PANICs or OOPSes would 102 it so that only emergency messages like PANICs or OOPSes would
95 make it to your console.) 103 make it to your console.)
96 104
97'f' - Will call oom_kill to kill a memory hog process 105'f' - Will call oom_kill to kill a memory hog process.
98 106
99'e' - Send a SIGTERM to all processes, except for init. 107'e' - Send a SIGTERM to all processes, except for init.
100 108
101'i' - Send a SIGKILL to all processes, except for init. 109'g' - Used by kgdb on ppc platforms.
102 110
103'l' - Send a SIGKILL to all processes, INCLUDING init. (Your system 111'i' - Send a SIGKILL to all processes, except for init.
104 will be non-functional after this.)
105 112
106'h' - Will display help ( actually any other key than those listed 113'h' - Will display help (actually any other key than those listed
107 above will display help. but 'h' is easy to remember :-) 114 above will display help. but 'h' is easy to remember :-)
108 115
109* Okay, so what can I use them for? 116* Okay, so what can I use them for?
110~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 117~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
111Well, un'R'aw is very handy when your X server or a svgalib program crashes. 118Well, un'R'aw is very handy when your X server or a svgalib program crashes.
112 119
113sa'K' (Secure Access Key) is useful when you want to be sure there are no 120sa'K' (Secure Access Key) is useful when you want to be sure there is no
114trojan program is running at console and which could grab your password 121trojan program running at console which could grab your password
115when you would try to login. It will kill all programs on given console 122when you would try to login. It will kill all programs on given console,
116and thus letting you make sure that the login prompt you see is actually 123thus letting you make sure that the login prompt you see is actually
117the one from init, not some trojan program. 124the one from init, not some trojan program.
118IMPORTANT: In its true form it is not a true SAK like the one in a :IMPORTANT 125IMPORTANT: In its true form it is not a true SAK like the one in a :IMPORTANT
119IMPORTANT: c2 compliant system, and it should not be mistaken as :IMPORTANT 126IMPORTANT: c2 compliant system, and it should not be mistaken as :IMPORTANT
120IMPORTANT: such. :IMPORTANT 127IMPORTANT: such. :IMPORTANT
121 It seems other find it useful as (System Attention Key) which is 128 It seems others find it useful as (System Attention Key) which is
122useful when you want to exit a program that will not let you switch consoles. 129useful when you want to exit a program that will not let you switch consoles.
123(For example, X or a svgalib program.) 130(For example, X or a svgalib program.)
124 131
@@ -139,8 +146,8 @@ OK or Done message...)
139Again, the unmount (remount read-only) hasn't taken place until you see the 146Again, the unmount (remount read-only) hasn't taken place until you see the
140"OK" and "Done" message appear on the screen. 147"OK" and "Done" message appear on the screen.
141 148
142The loglevel'0'-'9' is useful when your console is being flooded with 149The loglevels '0'-'9' are useful when your console is being flooded with
143kernel messages you do not want to see. Setting '0' will prevent all but 150kernel messages you do not want to see. Selecting '0' will prevent all but
144the most urgent kernel messages from reaching your console. (They will 151the most urgent kernel messages from reaching your console. (They will
145still be logged if syslogd/klogd are alive, though.) 152still be logged if syslogd/klogd are alive, though.)
146 153
@@ -152,7 +159,7 @@ processes.
152~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 159~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
153That happens to me, also. I've found that tapping shift, alt, and control 160That happens to me, also. I've found that tapping shift, alt, and control
154on both sides of the keyboard, and hitting an invalid sysrq sequence again 161on both sides of the keyboard, and hitting an invalid sysrq sequence again
155will fix the problem. (ie, something like alt-sysrq-z). Switching to another 162will fix the problem. (i.e., something like alt-sysrq-z). Switching to another
156virtual console (ALT+Fn) and then back again should also help. 163virtual console (ALT+Fn) and then back again should also help.
157 164
158* I hit SysRq, but nothing seems to happen, what's wrong? 165* I hit SysRq, but nothing seems to happen, what's wrong?
@@ -174,11 +181,11 @@ handler function you will use, B) a help_msg string, that will print when SysRQ
174prints help, and C) an action_msg string, that will print right before your 181prints help, and C) an action_msg string, that will print right before your
175handler is called. Your handler must conform to the prototype in 'sysrq.h'. 182handler is called. Your handler must conform to the prototype in 'sysrq.h'.
176 183
177After the sysrq_key_op is created, you can call the macro 184After the sysrq_key_op is created, you can call the kernel function
178register_sysrq_key(int key, struct sysrq_key_op *op_p) that is defined in 185register_sysrq_key(int key, struct sysrq_key_op *op_p); this will
179sysrq.h, this will register the operation pointed to by 'op_p' at table 186register the operation pointed to by 'op_p' at table key 'key',
180key 'key', if that slot in the table is blank. At module unload time, you must 187if that slot in the table is blank. At module unload time, you must call
181call the macro unregister_sysrq_key(int key, struct sysrq_key_op *op_p), which 188the function unregister_sysrq_key(int key, struct sysrq_key_op *op_p), which
182will remove the key op pointed to by 'op_p' from the key 'key', if and only if 189will remove the key op pointed to by 'op_p' from the key 'key', if and only if
183it is currently registered in that slot. This is in case the slot has been 190it is currently registered in that slot. This is in case the slot has been
184overwritten since you registered it. 191overwritten since you registered it.
@@ -186,15 +193,12 @@ overwritten since you registered it.
186The Magic SysRQ system works by registering key operations against a key op 193The Magic SysRQ system works by registering key operations against a key op
187lookup table, which is defined in 'drivers/char/sysrq.c'. This key table has 194lookup table, which is defined in 'drivers/char/sysrq.c'. This key table has
188a number of operations registered into it at compile time, but is mutable, 195a number of operations registered into it at compile time, but is mutable,
189and 4 functions are exported for interface to it: __sysrq_lock_table, 196and 2 functions are exported for interface to it:
190__sysrq_unlock_table, __sysrq_get_key_op, and __sysrq_put_key_op. The 197 register_sysrq_key and unregister_sysrq_key.
191functions __sysrq_swap_key_ops and __sysrq_swap_key_ops_nolock are defined 198Of course, never ever leave an invalid pointer in the table. I.e., when
192in the header itself, and the REGISTER and UNREGISTER macros are built from 199your module that called register_sysrq_key() exits, it must call
193these. More complex (and dangerous!) manipulations of the table are possible 200unregister_sysrq_key() to clean up the sysrq key table entry that it used.
194using these functions, but you must be careful to always lock the table before 201Null pointers in the table are always safe. :)
195you read or write from it, and to unlock it again when you are done. (And of
196course, to never ever leave an invalid pointer in the table). Null pointers in
197the table are always safe :)
198 202
199If for some reason you feel the need to call the handle_sysrq function from 203If for some reason you feel the need to call the handle_sysrq function from
200within a function called by handle_sysrq, you must be aware that you are in 204within a function called by handle_sysrq, you must be aware that you are in
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
214Interface descriptor info (can be multiple per Config): 214Interface descriptor info (can be multiple per Config):
215 215
216I: If#=dd Alt=dd #EPs=dd Cls=xx(sssss) Sub=xx Prot=xx Driver=ssss 216I:* 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
277on how to do this.) 278on how to do this.)
278 279
279The Interface lines can be used to determine what driver is 280The Interface lines can be used to determine what driver is
280being used for each device. 281being used for each device, and which altsetting it activated.
281 282
282The Configuration lines could be used to list maximum power 283The 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
78The '1t' type data consists of a stream of events, such as URB submission, 78The '1t' type data consists of a stream of events, such as URB submission,
79URB callback, submission error. Every event is a text line, which consists 79URB callback, submission error. Every event is a text line, which consists
80of whitespace separated words. The number of position of words may depend 80of whitespace separated words. The number or position of words may depend
81on the event type, but there is a set of words, common for all types. 81on the event type, but there is a set of words, common for all types.
82 82
83Here is the list of words, from left to right: 83Here 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
173TBD 173The overall architecture of the API is about the same as the one above,
174only the events are delivered in binary format. Each event is sent in
175the following structure (its name is made up, so that we can refer to it):
176
177struct 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
194These events can be received from a character device by reading with read(2),
195with an ioctl(2), or by accessing the buffer with mmap.
196
197The character device is usually called /dev/usbmonN, where N is the USB bus
198number. Number zero (/dev/usbmon0) is special and means "all buses".
199However, this feature is not implemented yet. Note that specific naming
200policy is set by your Linux distribution.
201
202If you create /dev/usbmon0 by hand, make sure that it is owned by root
203and has mode 0600. Otherwise, unpriviledged users will be able to snoop
204keyboard traffic.
205
206The following ioctl calls are available, with MON_IOC_MAGIC 0x92:
207
208 MON_IOCQ_URB_LEN, defined as _IO(MON_IOC_MAGIC, 1)
209
210This call returns the length of data in the next event. Note that majority of
211events contain no data, so if this call returns zero, it does not mean that
212no events are available.
213
214 MON_IOCG_STATS, defined as _IOR(MON_IOC_MAGIC, 3, struct mon_bin_stats)
215
216The argument is a pointer to the following structure:
217
218struct mon_bin_stats {
219 u32 queued;
220 u32 dropped;
221};
222
223The member "queued" refers to the number of events currently queued in the
224buffer (and not to the number of events processed since the last reset).
225
226The member "dropped" is the number of events lost since the last call
227to MON_IOCG_STATS.
228
229 MON_IOCT_RING_SIZE, defined as _IO(MON_IOC_MAGIC, 4)
230
231This call sets the buffer size. The argument is the size in bytes.
232The size may be rounded down to the next chunk (or page). If the requested
233size 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
238This 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
242This call waits for events to arrive if none were in the kernel buffer,
243then returns the first event. Its argument is a pointer to the following
244structure:
245
246struct mon_get_arg {
247 struct usbmon_packet *hdr;
248 void *data;
249 size_t alloc; /* Length of data (can be zero) */
250};
251
252Before the call, hdr, data, and alloc should be filled. Upon return, the area
253pointed by hdr contains the next event structure, and the data buffer contains
254the 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
258This ioctl is primarily used when the application accesses the buffer
259with mmap(2). Its argument is a pointer to the following structure:
260
261struct 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
267The ioctl operates in 3 stages.
268
269First, it removes and discards up to nflush events from the kernel buffer.
270The actual number of events discarded is returned in nflush.
271
272Second, it waits for an event to be present in the buffer, unless the pseudo-
273device is open with O_NONBLOCK.
274
275Third, it extracts up to nfetch offsets into the mmap buffer, and stores
276them into the offvec. The actual number of event offsets is stored into
277the nfetch.
278
279 MON_IOCH_MFLUSH, defined as _IO(MON_IOC_MAGIC, 8)
280
281This call removes a number of events from the kernel buffer. Its argument
282is the number of events to remove. If the buffer contains fewer events
283than requested, all events present are removed, and no error is reported.
284This works when no events are available too.
285
286 FIONBIO
287
288The ioctl FIONBIO may be implemented in the future, if there's a need.
289
290In addition to ioctl(2) and read(2), the special file of binary API can
291be 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
295The basic idea is simple:
296
297To prepare, map the buffer by getting the current size, then using mmap(2).
298Then, 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
318Thus, the main idea is to execute only one ioctl per N events.
319
320Although the buffer is circular, the returned headers and data do not cross
321the 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
6The output sysfs class driver provides an abstract video output layer that
7can be used to hook platform specific methods to enable/disable video output
8device through common sysfs interface. For example, on my IBM ThinkPad T42
9laptop, The ACPI video driver registered its output devices and read/write
10method for 'state' with output sysfs class. The user interface under sysfs is:
11
12linux:/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