aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/ABI/obsolete/dv13949
-rw-r--r--Documentation/ABI/testing/debugfs-pktcdvd5
-rw-r--r--Documentation/ABI/testing/sysfs-bus-usb41
-rw-r--r--Documentation/ABI/testing/sysfs-class-pktcdvd2
-rw-r--r--Documentation/DocBook/gadget.tmpl4
-rw-r--r--Documentation/DocBook/kernel-api.tmpl9
-rw-r--r--Documentation/DocBook/stylesheet.xsl1
-rw-r--r--Documentation/DocBook/usb.tmpl6
-rw-r--r--Documentation/HOWTO1
-rw-r--r--Documentation/SubmitChecklist4
-rw-r--r--Documentation/acpi-hotkey.txt38
-rw-r--r--Documentation/arm/Samsung-S3C24XX/DMA.txt46
-rw-r--r--Documentation/arm/Samsung-S3C24XX/Overview.txt21
-rw-r--r--Documentation/arm/Samsung-S3C24XX/Suspend.txt35
-rw-r--r--Documentation/auxdisplay/cfag12864b105
-rw-r--r--Documentation/auxdisplay/cfag12864b-example.c282
-rw-r--r--Documentation/auxdisplay/ks010855
-rw-r--r--Documentation/cdrom/packet-writing.txt2
-rw-r--r--Documentation/cpu-load.txt113
-rw-r--r--Documentation/cpusets.txt3
-rw-r--r--Documentation/crypto/api-intro.txt6
-rw-r--r--Documentation/driver-model/devres.txt268
-rw-r--r--Documentation/driver-model/platform.txt4
-rw-r--r--Documentation/drivers/edac/edac.txt16
-rw-r--r--Documentation/fb/s3fb.txt78
-rw-r--r--Documentation/feature-removal-schedule.txt151
-rw-r--r--Documentation/filesystems/00-INDEX4
-rw-r--r--Documentation/filesystems/9p.txt4
-rw-r--r--Documentation/filesystems/afs.txt214
-rw-r--r--Documentation/filesystems/proc.txt114
-rw-r--r--Documentation/filesystems/relay.txt9
-rw-r--r--Documentation/filesystems/sysfs-pci.txt2
-rw-r--r--Documentation/filesystems/ufs.txt9
-rw-r--r--Documentation/filesystems/vfs.txt5
-rw-r--r--Documentation/gpio.txt306
-rw-r--r--Documentation/hrtimer/timer_stats.txt68
-rw-r--r--Documentation/hrtimers/highres.txt249
-rw-r--r--Documentation/hrtimers/hrtimers.txt (renamed from Documentation/hrtimers.txt)0
-rw-r--r--Documentation/hwmon/it8710
-rw-r--r--Documentation/hwmon/sysfs-interface15
-rw-r--r--Documentation/hwmon/w83627ehf54
-rw-r--r--Documentation/i2c/busses/i2c-i80160
-rw-r--r--Documentation/i2c/busses/i2c-parport15
-rw-r--r--Documentation/i2c/busses/i2c-piix42
-rw-r--r--Documentation/i2c/busses/i2c-viapro7
-rw-r--r--Documentation/i2c/porting-clients6
-rw-r--r--Documentation/i2c/smbus-protocol2
-rw-r--r--Documentation/i2c/writing-clients58
-rw-r--r--Documentation/ia64/err_inject.txt1068
-rw-r--r--Documentation/ide.txt29
-rw-r--r--Documentation/infiniband/user_mad.txt8
-rw-r--r--Documentation/ioctl-number.txt3
-rw-r--r--Documentation/isdn/README.gigaset65
-rw-r--r--Documentation/kbuild/makefiles.txt28
-rw-r--r--Documentation/kdump/kdump.txt32
-rw-r--r--Documentation/kernel-doc-nano-HOWTO.txt39
-rw-r--r--Documentation/kernel-docs.txt257
-rw-r--r--Documentation/kernel-parameters.txt112
-rw-r--r--Documentation/keys.txt12
-rw-r--r--Documentation/local_ops.txt163
-rw-r--r--Documentation/magic-number.txt1
-rw-r--r--Documentation/networking/ax25.txt18
-rw-r--r--Documentation/networking/bcm43xx.txt97
-rw-r--r--Documentation/networking/bonding.txt35
-rw-r--r--Documentation/networking/dccp.txt10
-rw-r--r--Documentation/networking/ip-sysctl.txt66
-rw-r--r--Documentation/networking/rxrpc.txt859
-rw-r--r--Documentation/networking/wan-router.txt1
-rw-r--r--Documentation/nfsroot.txt4
-rw-r--r--Documentation/oops-tracing.txt6
-rw-r--r--Documentation/pci.txt4
-rw-r--r--Documentation/power/pci.txt17
-rw-r--r--Documentation/powerpc/booting-without-of.txt274
-rw-r--r--Documentation/powerpc/mpc52xx-device-tree-bindings.txt183
-rw-r--r--Documentation/rbtree.txt192
-rw-r--r--Documentation/rtc.txt46
-rw-r--r--Documentation/s390/Debugging390.txt2
-rw-r--r--Documentation/s390/crypto/crypto-API.txt83
-rw-r--r--Documentation/s390/zfcpdump.txt87
-rw-r--r--Documentation/scsi/ChangeLog.megaraid16
-rw-r--r--Documentation/sh/new-machine.txt4
-rw-r--r--Documentation/sony-laptop.txt117
-rw-r--r--Documentation/sound/alsa/ALSA-Configuration.txt74
-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/sparse.txt10
-rw-r--r--Documentation/spi/spi-summary3
-rw-r--r--Documentation/sysrq.txt46
-rw-r--r--Documentation/thinkpad-acpi.txt (renamed from Documentation/ibm-acpi.txt)585
-rw-r--r--Documentation/usb/proc_usb_info.txt21
-rw-r--r--Documentation/usb/usbmon.txt232
-rw-r--r--Documentation/video-output.txt34
-rw-r--r--Documentation/video4linux/CARDLIST.bttv4
-rw-r--r--Documentation/video4linux/CARDLIST.cx882
-rw-r--r--Documentation/video4linux/CARDLIST.ivtv18
-rw-r--r--Documentation/video4linux/CARDLIST.saa713411
-rw-r--r--Documentation/video4linux/CARDLIST.usbvision64
-rw-r--r--Documentation/video4linux/CQcam.txt6
-rw-r--r--Documentation/video4linux/README.ivtv187
-rw-r--r--Documentation/video4linux/Zoran4
-rw-r--r--Documentation/video4linux/bttv/Insmod-options2
-rw-r--r--Documentation/video4linux/cx2341x/fw-decoder-api.txt58
-rw-r--r--Documentation/video4linux/cx2341x/fw-decoder-regs.txt817
-rw-r--r--Documentation/video4linux/cx2341x/fw-dma.txt16
-rw-r--r--Documentation/video4linux/cx2341x/fw-encoder-api.txt71
-rw-r--r--Documentation/video4linux/cx2341x/fw-memory.txt10
-rw-r--r--Documentation/video4linux/cx2341x/fw-osd-api.txt12
-rw-r--r--Documentation/video4linux/et61x251.txt7
-rw-r--r--Documentation/video4linux/meye.txt7
-rw-r--r--Documentation/video4linux/sn9c102.txt292
-rw-r--r--Documentation/video4linux/zc0301.txt10
-rw-r--r--Documentation/video4linux/zr364xx.txt65
-rw-r--r--Documentation/x86_64/boot-options.txt134
-rw-r--r--Documentation/x86_64/cpu-hotplug-spec2
-rw-r--r--Documentation/x86_64/kernel-stacks26
-rw-r--r--Documentation/x86_64/machinecheck70
-rw-r--r--Documentation/x86_64/mm.txt22
126 files changed, 8977 insertions, 1355 deletions
diff --git a/Documentation/ABI/obsolete/dv1394 b/Documentation/ABI/obsolete/dv1394
new file mode 100644
index 000000000000..2ee36864ca10
--- /dev/null
+++ b/Documentation/ABI/obsolete/dv1394
@@ -0,0 +1,9 @@
1What: dv1394 (a.k.a. "OHCI-DV I/O support" for FireWire)
2Contact: linux1394-devel@lists.sourceforge.net
3Description:
4 New application development should use raw1394 + userspace libraries
5 instead, notably libiec61883 which is functionally equivalent.
6
7Users:
8 ffmpeg/libavformat (used by a variety of media players)
9 dvgrab v1.x (replaced by dvgrab2 on top of raw1394 and resp. libraries)
diff --git a/Documentation/ABI/testing/debugfs-pktcdvd b/Documentation/ABI/testing/debugfs-pktcdvd
index 03dbd883cc41..bf9c16b64c34 100644
--- a/Documentation/ABI/testing/debugfs-pktcdvd
+++ b/Documentation/ABI/testing/debugfs-pktcdvd
@@ -1,6 +1,6 @@
1What: /debug/pktcdvd/pktcdvd[0-7] 1What: /debug/pktcdvd/pktcdvd[0-7]
2Date: Oct. 2006 2Date: Oct. 2006
3KernelVersion: 2.6.19 3KernelVersion: 2.6.20
4Contact: Thomas Maier <balagi@justmail.de> 4Contact: Thomas Maier <balagi@justmail.de>
5Description: 5Description:
6 6
@@ -11,8 +11,7 @@ The pktcdvd module (packet writing driver) creates
11these files in debugfs: 11these files in debugfs:
12 12
13/debug/pktcdvd/pktcdvd[0-7]/ 13/debug/pktcdvd/pktcdvd[0-7]/
14 info (0444) Lots of human readable driver 14 info (0444) Lots of driver statistics and infos.
15 statistics and infos. Multiple lines!
16 15
17Example: 16Example:
18------- 17-------
diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb
new file mode 100644
index 000000000000..f9937add033d
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-usb
@@ -0,0 +1,41 @@
1What: /sys/bus/usb/devices/.../power/autosuspend
2Date: March 2007
3KernelVersion: 2.6.21
4Contact: Alan Stern <stern@rowland.harvard.edu>
5Description:
6 Each USB device directory will contain a file named
7 power/autosuspend. This file holds the time (in seconds)
8 the device must be idle before it will be autosuspended.
9 0 means the device will be autosuspended as soon as
10 possible. Negative values will prevent the device from
11 being autosuspended at all, and writing a negative value
12 will resume the device if it is already suspended.
13
14 The autosuspend delay for newly-created devices is set to
15 the value of the usbcore.autosuspend module parameter.
16
17What: /sys/bus/usb/devices/.../power/level
18Date: March 2007
19KernelVersion: 2.6.21
20Contact: Alan Stern <stern@rowland.harvard.edu>
21Description:
22 Each USB device directory will contain a file named
23 power/level. This file holds a power-level setting for
24 the device, one of "on", "auto", or "suspend".
25
26 "on" means that the device is not allowed to autosuspend,
27 although normal suspends for system sleep will still
28 be honored. "auto" means the device will autosuspend
29 and autoresume in the usual manner, according to the
30 capabilities of its driver. "suspend" means the device
31 is forced into a suspended state and it will not autoresume
32 in response to I/O requests. However remote-wakeup requests
33 from the device may still be enabled (the remote-wakeup
34 setting is controlled separately by the power/wakeup
35 attribute).
36
37 During normal use, devices should be left in the "auto"
38 level. The other levels are meant for administrative uses.
39 If you want to suspend a device immediately but leave it
40 free to wake up in response to I/O requests, you should
41 write "0" to power/autosuspend.
diff --git a/Documentation/ABI/testing/sysfs-class-pktcdvd b/Documentation/ABI/testing/sysfs-class-pktcdvd
index c4c55edc9a5c..b1c3f0263359 100644
--- a/Documentation/ABI/testing/sysfs-class-pktcdvd
+++ b/Documentation/ABI/testing/sysfs-class-pktcdvd
@@ -1,6 +1,6 @@
1What: /sys/class/pktcdvd/ 1What: /sys/class/pktcdvd/
2Date: Oct. 2006 2Date: Oct. 2006
3KernelVersion: 2.6.19 3KernelVersion: 2.6.20
4Contact: Thomas Maier <balagi@justmail.de> 4Contact: Thomas Maier <balagi@justmail.de>
5Description: 5Description:
6 6
diff --git a/Documentation/DocBook/gadget.tmpl b/Documentation/DocBook/gadget.tmpl
index a34442436128..e7fc96433408 100644
--- a/Documentation/DocBook/gadget.tmpl
+++ b/Documentation/DocBook/gadget.tmpl
@@ -482,13 +482,13 @@ slightly.
482<para>Gadget drivers 482<para>Gadget drivers
483rely on common USB structures and constants 483rely on common USB structures and constants
484defined in the 484defined in the
485<filename>&lt;linux/usb_ch9.h&gt;</filename> 485<filename>&lt;linux/usb/ch9.h&gt;</filename>
486header file, which is standard in Linux 2.6 kernels. 486header file, which is standard in Linux 2.6 kernels.
487These are the same types and constants used by host 487These are the same types and constants used by host
488side drivers (and usbcore). 488side drivers (and usbcore).
489</para> 489</para>
490 490
491!Iinclude/linux/usb_ch9.h 491!Iinclude/linux/usb/ch9.h
492</sect1> 492</sect1>
493 493
494<sect1 id="core"><title>Core Objects and Methods</title> 494<sect1 id="core"><title>Core Objects and Methods</title>
diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl
index 3fa0c4b4541e..b61dfc79e1b8 100644
--- a/Documentation/DocBook/kernel-api.tmpl
+++ b/Documentation/DocBook/kernel-api.tmpl
@@ -236,6 +236,12 @@ X!Ilib/string.c
236!Enet/core/dev.c 236!Enet/core/dev.c
237!Enet/ethernet/eth.c 237!Enet/ethernet/eth.c
238!Iinclude/linux/etherdevice.h 238!Iinclude/linux/etherdevice.h
239!Edrivers/net/phy/phy.c
240!Idrivers/net/phy/phy.c
241!Edrivers/net/phy/phy_device.c
242!Idrivers/net/phy/phy_device.c
243!Edrivers/net/phy/mdio_bus.c
244!Idrivers/net/phy/mdio_bus.c
239<!-- FIXME: Removed for now since no structured comments in source 245<!-- FIXME: Removed for now since no structured comments in source
240X!Enet/core/wireless.c 246X!Enet/core/wireless.c
241--> 247-->
@@ -316,6 +322,9 @@ X!Earch/i386/kernel/mca.c
316 <sect1><title>DMI Interfaces</title> 322 <sect1><title>DMI Interfaces</title>
317!Edrivers/firmware/dmi_scan.c 323!Edrivers/firmware/dmi_scan.c
318 </sect1> 324 </sect1>
325 <sect1><title>EDD Interfaces</title>
326!Idrivers/firmware/edd.c
327 </sect1>
319 </chapter> 328 </chapter>
320 329
321 <chapter id="security"> 330 <chapter id="security">
diff --git a/Documentation/DocBook/stylesheet.xsl b/Documentation/DocBook/stylesheet.xsl
index 3ccce886c349..974e17ccf106 100644
--- a/Documentation/DocBook/stylesheet.xsl
+++ b/Documentation/DocBook/stylesheet.xsl
@@ -4,4 +4,5 @@
4<param name="funcsynopsis.style">ansi</param> 4<param name="funcsynopsis.style">ansi</param>
5<param name="funcsynopsis.tabular.threshold">80</param> 5<param name="funcsynopsis.tabular.threshold">80</param>
6<!-- <param name="paper.type">A4</param> --> 6<!-- <param name="paper.type">A4</param> -->
7<param name="generate.section.toc.level">2</param>
7</stylesheet> 8</stylesheet>
diff --git a/Documentation/DocBook/usb.tmpl b/Documentation/DocBook/usb.tmpl
index 143e5ff7deb8..a2ebd651b05a 100644
--- a/Documentation/DocBook/usb.tmpl
+++ b/Documentation/DocBook/usb.tmpl
@@ -187,13 +187,13 @@
187 187
188<chapter><title>USB-Standard Types</title> 188<chapter><title>USB-Standard Types</title>
189 189
190 <para>In <filename>&lt;linux/usb_ch9.h&gt;</filename> you will find 190 <para>In <filename>&lt;linux/usb/ch9.h&gt;</filename> you will find
191 the USB data types defined in chapter 9 of the USB specification. 191 the USB data types defined in chapter 9 of the USB specification.
192 These data types are used throughout USB, and in APIs including 192 These data types are used throughout USB, and in APIs including
193 this host side API, gadget APIs, and usbfs. 193 this host side API, gadget APIs, and usbfs.
194 </para> 194 </para>
195 195
196!Iinclude/linux/usb_ch9.h 196!Iinclude/linux/usb/ch9.h
197 197
198 </chapter> 198 </chapter>
199 199
@@ -574,7 +574,7 @@ for (;;) {
574#include &lt;asm/byteorder.h&gt;</programlisting> 574#include &lt;asm/byteorder.h&gt;</programlisting>
575 The standard USB device model requests, from "Chapter 9" of 575 The standard USB device model requests, from "Chapter 9" of
576 the USB 2.0 specification, are automatically included from 576 the USB 2.0 specification, are automatically included from
577 the <filename>&lt;linux/usb_ch9.h&gt;</filename> header. 577 the <filename>&lt;linux/usb/ch9.h&gt;</filename> header.
578 </para> 578 </para>
579 579
580 <para>Unless noted otherwise, the ioctl requests 580 <para>Unless noted otherwise, the ioctl requests
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/SubmitChecklist b/Documentation/SubmitChecklist
index bfbb2718a279..bd23dc0bc0c7 100644
--- a/Documentation/SubmitChecklist
+++ b/Documentation/SubmitChecklist
@@ -76,3 +76,7 @@ kernel patches.
7622: Newly-added code has been compiled with `gcc -W'. This will generate 7622: Newly-added code has been compiled with `gcc -W'. This will generate
77 lots of noise, but is good for finding bugs like "warning: comparison 77 lots of noise, but is good for finding bugs like "warning: comparison
78 between signed and unsigned". 78 between signed and unsigned".
79
8023: Tested after it has been merged into the -mm patchset to make sure
81 that it still works with all of the other queued patches and various
82 changes in the VM, VFS, and other subsystems.
diff --git a/Documentation/acpi-hotkey.txt b/Documentation/acpi-hotkey.txt
deleted file mode 100644
index 38040fa37649..000000000000
--- a/Documentation/acpi-hotkey.txt
+++ /dev/null
@@ -1,38 +0,0 @@
1driver/acpi/hotkey.c implement:
21. /proc/acpi/hotkey/event_config
3(event based hotkey or event config interface):
4a. add a event based hotkey(event) :
5echo "0:bus::action:method:num:num" > event_config
6
7b. delete a event based hotkey(event):
8echo "1:::::num:num" > event_config
9
10c. modify a event based hotkey(event):
11echo "2:bus::action:method:num:num" > event_config
12
132. /proc/acpi/hotkey/poll_config
14(polling based hotkey or event config interface):
15a.add a polling based hotkey(event) :
16echo "0:bus:method:action:method:num" > poll_config
17this adding command will create a proc file
18/proc/acpi/hotkey/method, which is used to get
19result of polling.
20
21b.delete a polling based hotkey(event):
22echo "1:::::num" > event_config
23
24c.modify a polling based hotkey(event):
25echo "2:bus:method:action:method:num" > poll_config
26
273./proc/acpi/hotkey/action
28(interface to call aml method associated with a
29specific hotkey(event))
30echo "event_num:event_type:event_argument" >
31 /proc/acpi/hotkey/action.
32The result of the execution of this aml method is
33attached to /proc/acpi/hotkey/poll_method, which is dynamically
34created. Please use command "cat /proc/acpi/hotkey/polling_method"
35to retrieve it.
36
37Note: Use cmdline "acpi_generic_hotkey" to over-ride
38platform-specific with generic driver.
diff --git a/Documentation/arm/Samsung-S3C24XX/DMA.txt b/Documentation/arm/Samsung-S3C24XX/DMA.txt
new file mode 100644
index 000000000000..37f4edcc5d87
--- /dev/null
+++ b/Documentation/arm/Samsung-S3C24XX/DMA.txt
@@ -0,0 +1,46 @@
1 S3C2410 DMA
2 ===========
3
4Introduction
5------------
6
7 The kernel provides an interface to manage DMA transfers
8 using the DMA channels in the cpu, so that the central
9 duty of managing channel mappings, and programming the
10 channel generators is in one place.
11
12
13DMA Channel Ordering
14--------------------
15
16 Many of the range do not have connections for the DMA
17 channels to all sources, which means that some devices
18 have a restricted number of channels that can be used.
19
20 To allow flexibilty for each cpu type and board, the
21 dma code can be given an dma ordering structure which
22 allows the order of channel search to be specified, as
23 well as allowing the prohibition of certain claims.
24
25 struct s3c24xx_dma_order has a list of channels, and
26 each channel within has a slot for a list of dma
27 channel numbers. The slots are searched in order, for
28 the presence of a dma channel number with DMA_CH_VALID
29 orred in.
30
31 If the order has the flag DMA_CH_NEVER set, then after
32 checking the channel list, the system will return no
33 found channel, thus denying the request.
34
35 A board support file can call s3c24xx_dma_order_set()
36 to register an complete ordering set. The routine will
37 copy the data, so the original can be discared with
38 __initdata.
39
40
41Authour
42-------
43
44Ben Dooks,
45Copyright (c) 2007 Ben Dooks, Simtec Electronics
46Licensed under the GPL v2
diff --git a/Documentation/arm/Samsung-S3C24XX/Overview.txt b/Documentation/arm/Samsung-S3C24XX/Overview.txt
index 28d014714ab8..c31b76fa66c4 100644
--- a/Documentation/arm/Samsung-S3C24XX/Overview.txt
+++ b/Documentation/arm/Samsung-S3C24XX/Overview.txt
@@ -8,13 +8,10 @@ Introduction
8 8
9 The Samsung S3C24XX range of ARM9 System-on-Chip CPUs are supported 9 The Samsung S3C24XX range of ARM9 System-on-Chip CPUs are supported
10 by the 's3c2410' architecture of ARM Linux. Currently the S3C2410, 10 by the 's3c2410' architecture of ARM Linux. Currently the S3C2410,
11 S3C2440 and S3C2442 devices are supported. 11 S3C2412, S3C2413, S3C2440 and S3C2442 devices are supported.
12 12
13 Support for the S3C2400 series is in progress. 13 Support for the S3C2400 series is in progress.
14 14
15 Support for the S3C2412 and S3C2413 CPUs is being merged.
16
17
18Configuration 15Configuration
19------------- 16-------------
20 17
@@ -26,6 +23,22 @@ Configuration
26 please check the machine specific documentation. 23 please check the machine specific documentation.
27 24
28 25
26Layout
27------
28
29 The core support files are located in the platform code contained in
30 arch/arm/plat-s3c24xx with headers in include/asm-arm/plat-s3c24xx.
31 This directory should be kept to items shared between the platform
32 code (arch/arm/plat-s3c24xx) and the arch/arm/mach-s3c24* code.
33
34 Each cpu has a directory with the support files for it, and the
35 machines that carry the device. For example S3C2410 is contained
36 in arch/arm/mach-s3c2410 and S3C2440 in arch/arm/mach-s3c2440
37
38 Register, kernel and platform data definitions are held in the
39 include/asm-arm/arch-s3c2410 directory.
40
41
29Machines 42Machines
30-------- 43--------
31 44
diff --git a/Documentation/arm/Samsung-S3C24XX/Suspend.txt b/Documentation/arm/Samsung-S3C24XX/Suspend.txt
index e12bc3284a27..0dab6e32c130 100644
--- a/Documentation/arm/Samsung-S3C24XX/Suspend.txt
+++ b/Documentation/arm/Samsung-S3C24XX/Suspend.txt
@@ -5,10 +5,10 @@
5Introduction 5Introduction
6------------ 6------------
7 7
8 The S3C2410 supports a low-power suspend mode, where the SDRAM is kept 8 The S3C24XX supports a low-power suspend mode, where the SDRAM is kept
9 in Self-Refresh mode, and all but the essential peripheral blocks are 9 in Self-Refresh mode, and all but the essential peripheral blocks are
10 powered down. For more information on how this works, please look 10 powered down. For more information on how this works, please look
11 at the S3C2410 datasheets from Samsung. 11 at the relevant CPU datasheet from Samsung.
12 12
13 13
14Requirements 14Requirements
@@ -56,6 +56,27 @@ Machine Support
56 Note, the original method of adding an late_initcall() is wrong, 56 Note, the original method of adding an late_initcall() is wrong,
57 and will end up initialising all compiled machines' pm init! 57 and will end up initialising all compiled machines' pm init!
58 58
59 The following is an example of code used for testing wakeup from
60 an falling edge on IRQ_EINT0:
61
62
63static irqreturn_t button_irq(int irq, void *pw)
64{
65 return IRQ_HANDLED;
66}
67
68statuc void __init machine_init(void)
69{
70 ...
71
72 request_irq(IRQ_EINT0, button_irq, IRQF_TRIGGER_FALLING,
73 "button-irq-eint0", NULL);
74
75 enable_irq_wake(IRQ_EINT0);
76
77 s3c2410_pm_init();
78}
79
59 80
60Debugging 81Debugging
61--------- 82---------
@@ -70,6 +91,12 @@ Debugging
70 care should be taken that any external clock sources that the UARTs 91 care should be taken that any external clock sources that the UARTs
71 rely on are still enabled at that point. 92 rely on are still enabled at that point.
72 93
94 3) If any debugging is placed in the resume path, then it must have the
95 relevant clocks and peripherals setup before use (ie, bootloader).
96
97 For example, if you transmit a character from the UART, the baud
98 rate and uart controls must be setup beforehand.
99
73 100
74Configuration 101Configuration
75------------- 102-------------
@@ -89,6 +116,10 @@ Configuration
89 Allows the entire memory to be checksummed before and after the 116 Allows the entire memory to be checksummed before and after the
90 suspend to see if there has been any corruption of the contents. 117 suspend to see if there has been any corruption of the contents.
91 118
119 Note, the time to calculate the CRC is dependant on the CPU speed
120 and the size of memory. For an 64Mbyte RAM area on an 200MHz
121 S3C2410, this can take approximately 4 seconds to complete.
122
92 This support requires the CRC32 function to be enabled. 123 This support requires the CRC32 function to be enabled.
93 124
94 125
diff --git a/Documentation/auxdisplay/cfag12864b b/Documentation/auxdisplay/cfag12864b
new file mode 100644
index 000000000000..3572b98f45b8
--- /dev/null
+++ b/Documentation/auxdisplay/cfag12864b
@@ -0,0 +1,105 @@
1 ===================================
2 cfag12864b LCD Driver Documentation
3 ===================================
4
5License: GPLv2
6Author & Maintainer: Miguel Ojeda Sandonis <maxextreme@gmail.com>
7Date: 2006-10-27
8
9
10
11--------
120. INDEX
13--------
14
15 1. DRIVER INFORMATION
16 2. DEVICE INFORMATION
17 3. WIRING
18 4. USERSPACE PROGRAMMING
19
20
21---------------------
221. DRIVER INFORMATION
23---------------------
24
25This driver support one cfag12864b display at time.
26
27
28---------------------
292. DEVICE INFORMATION
30---------------------
31
32Manufacturer: Crystalfontz
33Device Name: Crystalfontz 12864b LCD Series
34Device Code: cfag12864b
35Webpage: http://www.crystalfontz.com
36Device Webpage: http://www.crystalfontz.com/products/12864b/
37Type: LCD (Liquid Crystal Display)
38Width: 128
39Height: 64
40Colors: 2 (B/N)
41Controller: ks0108
42Controllers: 2
43Pages: 8 each controller
44Addresses: 64 each page
45Data size: 1 byte each address
46Memory size: 2 * 8 * 64 * 1 = 1024 bytes = 1 Kbyte
47
48
49---------
503. WIRING
51---------
52
53The cfag12864b LCD Series don't have official wiring.
54
55The common wiring is done to the parallel port as shown:
56
57Parallel Port cfag12864b
58
59 Name Pin# Pin# Name
60
61Strobe ( 1)------------------------------(17) Enable
62Data 0 ( 2)------------------------------( 4) Data 0
63Data 1 ( 3)------------------------------( 5) Data 1
64Data 2 ( 4)------------------------------( 6) Data 2
65Data 3 ( 5)------------------------------( 7) Data 3
66Data 4 ( 6)------------------------------( 8) Data 4
67Data 5 ( 7)------------------------------( 9) Data 5
68Data 6 ( 8)------------------------------(10) Data 6
69Data 7 ( 9)------------------------------(11) Data 7
70 (10) [+5v]---( 1) Vdd
71 (11) [GND]---( 2) Ground
72 (12) [+5v]---(14) Reset
73 (13) [GND]---(15) Read / Write
74 Line (14)------------------------------(13) Controller Select 1
75 (15)
76 Init (16)------------------------------(12) Controller Select 2
77Select (17)------------------------------(16) Data / Instruction
78Ground (18)---[GND] [+5v]---(19) LED +
79Ground (19)---[GND]
80Ground (20)---[GND] E A Values:
81Ground (21)---[GND] [GND]---[P1]---(18) Vee · R = Resistor = 22 ohm
82Ground (22)---[GND] | · P1 = Preset = 10 Kohm
83Ground (23)---[GND] ---- S ------( 3) V0 · P2 = Preset = 1 Kohm
84Ground (24)---[GND] | |
85Ground (25)---[GND] [GND]---[P2]---[R]---(20) LED -
86
87
88------------------------
894. USERSPACE PROGRAMMING
90------------------------
91
92The cfag12864bfb describes a framebuffer device (/dev/fbX).
93
94It has a size of 1024 bytes = 1 Kbyte.
95Each bit represents one pixel. If the bit is high, the pixel will
96turn on. If the pixel is low, the pixel will turn off.
97
98You can use the framebuffer as a file: fopen, fwrite, fclose...
99Although the LCD won't get updated until the next refresh time arrives.
100
101Also, you can mmap the framebuffer: open & mmap, munmap & close...
102which is the best option for most uses.
103
104Check Documentation/auxdisplay/cfag12864b-example.c
105for a real working userspace complete program with usage examples.
diff --git a/Documentation/auxdisplay/cfag12864b-example.c b/Documentation/auxdisplay/cfag12864b-example.c
new file mode 100644
index 000000000000..7bfac354d4c9
--- /dev/null
+++ b/Documentation/auxdisplay/cfag12864b-example.c
@@ -0,0 +1,282 @@
1/*
2 * Filename: cfag12864b-example.c
3 * Version: 0.1.0
4 * Description: cfag12864b LCD userspace example program
5 * License: GPLv2
6 *
7 * Author: Copyright (C) Miguel Ojeda Sandonis <maxextreme@gmail.com>
8 * Date: 2006-10-31
9 *
10 * This program is free software; you can redistribute it and/or modify
11 * it under the terms of the GNU General Public License version 2 as
12 * published by the Free Software Foundation.
13 *
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU General Public License for more details.
18 *
19 * You should have received a copy of the GNU General Public License
20 * along with this program; if not, write to the Free Software
21 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
22 *
23 */
24
25/*
26 * ------------------------
27 * start of cfag12864b code
28 * ------------------------
29 */
30
31#include <string.h>
32#include <fcntl.h>
33#include <unistd.h>
34#include <sys/types.h>
35#include <sys/stat.h>
36#include <sys/mman.h>
37
38#define CFAG12864B_WIDTH (128)
39#define CFAG12864B_HEIGHT (64)
40#define CFAG12864B_SIZE (128 * 64 / 8)
41#define CFAG12864B_BPB (8)
42#define CFAG12864B_ADDRESS(x, y) ((y) * CFAG12864B_WIDTH / \
43 CFAG12864B_BPB + (x) / CFAG12864B_BPB)
44#define CFAG12864B_BIT(n) (((unsigned char) 1) << (n))
45
46#undef CFAG12864B_DOCHECK
47#ifdef CFAG12864B_DOCHECK
48 #define CFAG12864B_CHECK(x, y) ((x) < CFAG12864B_WIDTH && \
49 (y) < CFAG12864B_HEIGHT)
50#else
51 #define CFAG12864B_CHECK(x, y) (1)
52#endif
53
54int cfag12864b_fd;
55unsigned char * cfag12864b_mem;
56unsigned char cfag12864b_buffer[CFAG12864B_SIZE];
57
58/*
59 * init a cfag12864b framebuffer device
60 *
61 * No error: return = 0
62 * Unable to open: return = -1
63 * Unable to mmap: return = -2
64 */
65int cfag12864b_init(char *path)
66{
67 cfag12864b_fd = open(path, O_RDWR);
68 if (cfag12864b_fd == -1)
69 return -1;
70
71 cfag12864b_mem = mmap(0, CFAG12864B_SIZE, PROT_READ | PROT_WRITE,
72 MAP_SHARED, cfag12864b_fd, 0);
73 if (cfag12864b_mem == MAP_FAILED) {
74 close(cfag12864b_fd);
75 return -2;
76 }
77
78 return 0;
79}
80
81/*
82 * exit a cfag12864b framebuffer device
83 */
84void cfag12864b_exit(void)
85{
86 munmap(cfag12864b_mem, CFAG12864B_SIZE);
87 close(cfag12864b_fd);
88}
89
90/*
91 * set (x, y) pixel
92 */
93void cfag12864b_set(unsigned char x, unsigned char y)
94{
95 if (CFAG12864B_CHECK(x, y))
96 cfag12864b_buffer[CFAG12864B_ADDRESS(x, y)] |=
97 CFAG12864B_BIT(x % CFAG12864B_BPB);
98}
99
100/*
101 * unset (x, y) pixel
102 */
103void cfag12864b_unset(unsigned char x, unsigned char y)
104{
105 if (CFAG12864B_CHECK(x, y))
106 cfag12864b_buffer[CFAG12864B_ADDRESS(x, y)] &=
107 ~CFAG12864B_BIT(x % CFAG12864B_BPB);
108}
109
110/*
111 * is set (x, y) pixel?
112 *
113 * Pixel off: return = 0
114 * Pixel on: return = 1
115 */
116unsigned char cfag12864b_isset(unsigned char x, unsigned char y)
117{
118 if (CFAG12864B_CHECK(x, y))
119 if (cfag12864b_buffer[CFAG12864B_ADDRESS(x, y)] &
120 CFAG12864B_BIT(x % CFAG12864B_BPB))
121 return 1;
122
123 return 0;
124}
125
126/*
127 * not (x, y) pixel
128 */
129void cfag12864b_not(unsigned char x, unsigned char y)
130{
131 if (cfag12864b_isset(x, y))
132 cfag12864b_unset(x, y);
133 else
134 cfag12864b_set(x, y);
135}
136
137/*
138 * fill (set all pixels)
139 */
140void cfag12864b_fill(void)
141{
142 unsigned short i;
143
144 for (i = 0; i < CFAG12864B_SIZE; i++)
145 cfag12864b_buffer[i] = 0xFF;
146}
147
148/*
149 * clear (unset all pixels)
150 */
151void cfag12864b_clear(void)
152{
153 unsigned short i;
154
155 for (i = 0; i < CFAG12864B_SIZE; i++)
156 cfag12864b_buffer[i] = 0;
157}
158
159/*
160 * format a [128*64] matrix
161 *
162 * Pixel off: src[i] = 0
163 * Pixel on: src[i] > 0
164 */
165void cfag12864b_format(unsigned char * matrix)
166{
167 unsigned char i, j, n;
168
169 for (i = 0; i < CFAG12864B_HEIGHT; i++)
170 for (j = 0; j < CFAG12864B_WIDTH / CFAG12864B_BPB; j++) {
171 cfag12864b_buffer[i * CFAG12864B_WIDTH / CFAG12864B_BPB +
172 j] = 0;
173 for (n = 0; n < CFAG12864B_BPB; n++)
174 if (matrix[i * CFAG12864B_WIDTH +
175 j * CFAG12864B_BPB + n])
176 cfag12864b_buffer[i * CFAG12864B_WIDTH /
177 CFAG12864B_BPB + j] |=
178 CFAG12864B_BIT(n);
179 }
180}
181
182/*
183 * blit buffer to lcd
184 */
185void cfag12864b_blit(void)
186{
187 memcpy(cfag12864b_mem, cfag12864b_buffer, CFAG12864B_SIZE);
188}
189
190/*
191 * ----------------------
192 * end of cfag12864b code
193 * ----------------------
194 */
195
196#include <stdio.h>
197#include <string.h>
198
199#define EXAMPLES 6
200
201void example(unsigned char n)
202{
203 unsigned short i, j;
204 unsigned char matrix[CFAG12864B_WIDTH * CFAG12864B_HEIGHT];
205
206 if (n > EXAMPLES)
207 return;
208
209 printf("Example %i/%i - ", n, EXAMPLES);
210
211 switch (n) {
212 case 1:
213 printf("Draw points setting bits");
214 cfag12864b_clear();
215 for (i = 0; i < CFAG12864B_WIDTH; i += 2)
216 for (j = 0; j < CFAG12864B_HEIGHT; j += 2)
217 cfag12864b_set(i, j);
218 break;
219
220 case 2:
221 printf("Clear the LCD");
222 cfag12864b_clear();
223 break;
224
225 case 3:
226 printf("Draw rows formatting a [128*64] matrix");
227 memset(matrix, 0, CFAG12864B_WIDTH * CFAG12864B_HEIGHT);
228 for (i = 0; i < CFAG12864B_WIDTH; i++)
229 for (j = 0; j < CFAG12864B_HEIGHT; j += 2)
230 matrix[j * CFAG12864B_WIDTH + i] = 1;
231 cfag12864b_format(matrix);
232 break;
233
234 case 4:
235 printf("Fill the lcd");
236 cfag12864b_fill();
237 break;
238
239 case 5:
240 printf("Draw columns unsetting bits");
241 for (i = 0; i < CFAG12864B_WIDTH; i += 2)
242 for (j = 0; j < CFAG12864B_HEIGHT; j++)
243 cfag12864b_unset(i, j);
244 break;
245
246 case 6:
247 printf("Do negative not-ing all bits");
248 for (i = 0; i < CFAG12864B_WIDTH; i++)
249 for (j = 0; j < CFAG12864B_HEIGHT; j ++)
250 cfag12864b_not(i, j);
251 break;
252 }
253
254 puts(" - [Press Enter]");
255}
256
257int main(int argc, char *argv[])
258{
259 unsigned char n;
260
261 if (argc != 2) {
262 printf(
263 "Sintax: %s fbdev\n"
264 "Usually: /dev/fb0, /dev/fb1...\n", argv[0]);
265 return -1;
266 }
267
268 if (cfag12864b_init(argv[1])) {
269 printf("Can't init %s fbdev\n", argv[1]);
270 return -2;
271 }
272
273 for (n = 1; n <= EXAMPLES; n++) {
274 example(n);
275 cfag12864b_blit();
276 while (getchar() != '\n');
277 }
278
279 cfag12864b_exit();
280
281 return 0;
282}
diff --git a/Documentation/auxdisplay/ks0108 b/Documentation/auxdisplay/ks0108
new file mode 100644
index 000000000000..92b03b60c613
--- /dev/null
+++ b/Documentation/auxdisplay/ks0108
@@ -0,0 +1,55 @@
1 ==========================================
2 ks0108 LCD Controller Driver Documentation
3 ==========================================
4
5License: GPLv2
6Author & Maintainer: Miguel Ojeda Sandonis <maxextreme@gmail.com>
7Date: 2006-10-27
8
9
10
11--------
120. INDEX
13--------
14
15 1. DRIVER INFORMATION
16 2. DEVICE INFORMATION
17 3. WIRING
18
19
20---------------------
211. DRIVER INFORMATION
22---------------------
23
24This driver support the ks0108 LCD controller.
25
26
27---------------------
282. DEVICE INFORMATION
29---------------------
30
31Manufacturer: Samsung
32Device Name: KS0108 LCD Controller
33Device Code: ks0108
34Webpage: -
35Device Webpage: -
36Type: LCD Controller (Liquid Crystal Display Controller)
37Width: 64
38Height: 64
39Colors: 2 (B/N)
40Pages: 8
41Addresses: 64 each page
42Data size: 1 byte each address
43Memory size: 8 * 64 * 1 = 512 bytes
44
45
46---------
473. WIRING
48---------
49
50The driver supports data parallel port wiring.
51
52If you aren't building LCD related hardware, you should check
53your LCD specific wiring information in the same folder.
54
55For example, check Documentation/auxdisplay/cfag12864b.
diff --git a/Documentation/cdrom/packet-writing.txt b/Documentation/cdrom/packet-writing.txt
index 7715d2247c4d..cf1f8126991c 100644
--- a/Documentation/cdrom/packet-writing.txt
+++ b/Documentation/cdrom/packet-writing.txt
@@ -93,7 +93,7 @@ Notes
93Using the pktcdvd sysfs interface 93Using the pktcdvd sysfs interface
94--------------------------------- 94---------------------------------
95 95
96Since Linux 2.6.19, the pktcdvd module has a sysfs interface 96Since Linux 2.6.20, the pktcdvd module has a sysfs interface
97and can be controlled by it. For example the "pktcdvd" tool uses 97and can be controlled by it. For example the "pktcdvd" tool uses
98this interface. (see http://people.freenet.de/BalaGi#pktcdvd ) 98this interface. (see http://people.freenet.de/BalaGi#pktcdvd )
99 99
diff --git a/Documentation/cpu-load.txt b/Documentation/cpu-load.txt
new file mode 100644
index 000000000000..287224e57cfc
--- /dev/null
+++ b/Documentation/cpu-load.txt
@@ -0,0 +1,113 @@
1CPU load
2--------
3
4Linux exports various bits of information via `/proc/stat' and
5`/proc/uptime' that userland tools, such as top(1), use to calculate
6the average time system spent in a particular state, for example:
7
8 $ iostat
9 Linux 2.6.18.3-exp (linmac) 02/20/2007
10
11 avg-cpu: %user %nice %system %iowait %steal %idle
12 10.01 0.00 2.92 5.44 0.00 81.63
13
14 ...
15
16Here the system thinks that over the default sampling period the
17system spent 10.01% of the time doing work in user space, 2.92% in the
18kernel, and was overall 81.63% of the time idle.
19
20In most cases the `/proc/stat' information reflects the reality quite
21closely, however due to the nature of how/when the kernel collects
22this data sometimes it can not be trusted at all.
23
24So how is this information collected? Whenever timer interrupt is
25signalled the kernel looks what kind of task was running at this
26moment and increments the counter that corresponds to this tasks
27kind/state. The problem with this is that the system could have
28switched between various states multiple times between two timer
29interrupts yet the counter is incremented only for the last state.
30
31
32Example
33-------
34
35If we imagine the system with one task that periodically burns cycles
36in the following manner:
37
38 time line between two timer interrupts
39|--------------------------------------|
40 ^ ^
41 |_ something begins working |
42 |_ something goes to sleep
43 (only to be awaken quite soon)
44
45In the above situation the system will be 0% loaded according to the
46`/proc/stat' (since the timer interrupt will always happen when the
47system is executing the idle handler), but in reality the load is
48closer to 99%.
49
50One can imagine many more situations where this behavior of the kernel
51will lead to quite erratic information inside `/proc/stat'.
52
53
54/* gcc -o hog smallhog.c */
55#include <time.h>
56#include <limits.h>
57#include <signal.h>
58#include <sys/time.h>
59#define HIST 10
60
61static volatile sig_atomic_t stop;
62
63static void sighandler (int signr)
64{
65 (void) signr;
66 stop = 1;
67}
68static unsigned long hog (unsigned long niters)
69{
70 stop = 0;
71 while (!stop && --niters);
72 return niters;
73}
74int main (void)
75{
76 int i;
77 struct itimerval it = { .it_interval = { .tv_sec = 0, .tv_usec = 1 },
78 .it_value = { .tv_sec = 0, .tv_usec = 1 } };
79 sigset_t set;
80 unsigned long v[HIST];
81 double tmp = 0.0;
82 unsigned long n;
83 signal (SIGALRM, &sighandler);
84 setitimer (ITIMER_REAL, &it, NULL);
85
86 hog (ULONG_MAX);
87 for (i = 0; i < HIST; ++i) v[i] = ULONG_MAX - hog (ULONG_MAX);
88 for (i = 0; i < HIST; ++i) tmp += v[i];
89 tmp /= HIST;
90 n = tmp - (tmp / 3.0);
91
92 sigemptyset (&set);
93 sigaddset (&set, SIGALRM);
94
95 for (;;) {
96 hog (n);
97 sigwait (&set, &i);
98 }
99 return 0;
100}
101
102
103References
104----------
105
106http://lkml.org/lkml/2007/2/12/6
107Documentation/filesystems/proc.txt (1.8)
108
109
110Thanks
111------
112
113Con Kolivas, Pavel Machek
diff --git a/Documentation/cpusets.txt b/Documentation/cpusets.txt
index 842f0d1ab216..f2c0a6842930 100644
--- a/Documentation/cpusets.txt
+++ b/Documentation/cpusets.txt
@@ -557,6 +557,9 @@ Set some flags:
557Add some cpus: 557Add some cpus:
558# /bin/echo 0-7 > cpus 558# /bin/echo 0-7 > cpus
559 559
560Add some mems:
561# /bin/echo 0-7 > mems
562
560Now attach your shell to this cpuset: 563Now attach your shell to this cpuset:
561# /bin/echo $$ > tasks 564# /bin/echo $$ > tasks
562 565
diff --git a/Documentation/crypto/api-intro.txt b/Documentation/crypto/api-intro.txt
index 5a03a2801d67..9b84b805ab75 100644
--- a/Documentation/crypto/api-intro.txt
+++ b/Documentation/crypto/api-intro.txt
@@ -60,7 +60,7 @@ Here's an example of how to use the API:
60 desc.tfm = tfm; 60 desc.tfm = tfm;
61 desc.flags = 0; 61 desc.flags = 0;
62 62
63 if (crypto_hash_digest(&desc, &sg, 2, result)) 63 if (crypto_hash_digest(&desc, sg, 2, result))
64 fail(); 64 fail();
65 65
66 crypto_free_hash(tfm); 66 crypto_free_hash(tfm);
@@ -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/driver-model/platform.txt b/Documentation/driver-model/platform.txt
index 9f0bc3bfd776..f7c9262b2dc8 100644
--- a/Documentation/driver-model/platform.txt
+++ b/Documentation/driver-model/platform.txt
@@ -66,7 +66,7 @@ runtime memory footprint:
66 66
67Device Enumeration 67Device Enumeration
68~~~~~~~~~~~~~~~~~~ 68~~~~~~~~~~~~~~~~~~
69As a rule, platform specific (and often board-specific) setup code wil 69As a rule, platform specific (and often board-specific) setup code will
70register platform devices: 70register platform devices:
71 71
72 int platform_device_register(struct platform_device *pdev); 72 int platform_device_register(struct platform_device *pdev);
@@ -106,7 +106,7 @@ It's built from two components:
106 * platform_device.id ... the device instance number, or else "-1" 106 * platform_device.id ... the device instance number, or else "-1"
107 to indicate there's only one. 107 to indicate there's only one.
108 108
109These are catenated, so name/id "serial"/0 indicates bus_id "serial.0", and 109These are concatenated, so name/id "serial"/0 indicates bus_id "serial.0", and
110"serial/3" indicates bus_id "serial.3"; both would use the platform_driver 110"serial/3" indicates bus_id "serial.3"; both would use the platform_driver
111named "serial". While "my_rtc"/-1 would be bus_id "my_rtc" (no instance id) 111named "serial". While "my_rtc"/-1 would be bus_id "my_rtc" (no instance id)
112and use the platform_driver called "my_rtc". 112and use the platform_driver called "my_rtc".
diff --git a/Documentation/drivers/edac/edac.txt b/Documentation/drivers/edac/edac.txt
index 7b3d969d2964..3c5a9e4297b4 100644
--- a/Documentation/drivers/edac/edac.txt
+++ b/Documentation/drivers/edac/edac.txt
@@ -339,7 +339,21 @@ Device Symlink:
339 339
340 'device' 340 'device'
341 341
342 Symlink to the memory controller device 342 Symlink to the memory controller device.
343
344Sdram memory scrubbing rate:
345
346 'sdram_scrub_rate'
347
348 Read/Write attribute file that controls memory scrubbing. The scrubbing
349 rate is set by writing a minimum bandwith in bytes/sec to the attribute
350 file. The rate will be translated to an internal value that gives at
351 least the specified rate.
352
353 Reading the file will return the actual scrubbing rate employed.
354
355 If configuration fails or memory scrubbing is not implemented, the value
356 of the attribute file will be -1.
343 357
344 358
345 359
diff --git a/Documentation/fb/s3fb.txt b/Documentation/fb/s3fb.txt
new file mode 100644
index 000000000000..8a04c0da0c91
--- /dev/null
+++ b/Documentation/fb/s3fb.txt
@@ -0,0 +1,78 @@
1
2 s3fb - fbdev driver for S3 Trio/Virge chips
3 ===========================================
4
5
6Supported Hardware
7==================
8
9 S3 Trio32
10 S3 Trio64 (and variants V+, UV+, V2/DX, V2/GX)
11 S3 Virge (and variants VX, DX, GX and GX2+)
12 S3 Plato/PX (completely untested)
13 S3 Aurora64V+ (completely untested)
14
15 - only PCI bus supported
16 - only BIOS initialized VGA devices supported
17 - probably not working on big endian
18
19I tested s3fb on Trio64 (plain, V+ and V2/DX) and Virge (plain, VX, DX),
20all on i386.
21
22
23Supported Features
24==================
25
26 * 4 bpp pseudocolor modes (with 18bit palette, two variants)
27 * 8 bpp pseudocolor mode (with 18bit palette)
28 * 16 bpp truecolor modes (RGB 555 and RGB 565)
29 * 24 bpp truecolor mode (RGB 888) on (only on Virge VX)
30 * 32 bpp truecolor mode (RGB 888) on (not on Virge VX)
31 * text mode (activated by bpp = 0)
32 * interlaced mode variant (not available in text mode)
33 * doublescan mode variant (not available in text mode)
34 * panning in both directions
35 * suspend/resume support
36 * DPMS support
37
38Text mode is supported even in higher resolutions, but there is limitation
39to lower pixclocks (maximum between 50-60 MHz, depending on specific hardware).
40This limitation is not enforced by driver. Text mode supports 8bit wide fonts
41only (hardware limitation) and 16bit tall fonts (driver limitation).
42
43There are two 4 bpp modes. First mode (selected if nonstd == 0) is mode with
44packed pixels, high nibble first. Second mode (selected if nonstd == 1) is mode
45with interleaved planes (1 byte interleave), MSB first. Both modes support
468bit wide fonts only (driver limitation).
47
48Suspend/resume works on systems that initialize video card during resume and
49if device is active (for example used by fbcon).
50
51
52Missing Features
53================
54(alias TODO list)
55
56 * secondary (not initialized by BIOS) device support
57 * big endian support
58 * Zorro bus support
59 * MMIO support
60 * 24 bpp mode support on more cards
61 * support for fontwidths != 8 in 4 bpp modes
62 * support for fontheight != 16 in text mode
63 * composite and external sync (is anyone able to test this?)
64 * hardware cursor
65 * video overlay support
66 * vsync synchronization
67 * feature connector support
68 * acceleration support (8514-like 2D, Virge 3D, busmaster transfers)
69 * better values for some magic registers (performance issues)
70
71
72Known bugs
73==========
74
75 * cursor disable in text mode doesn't work
76
77--
78Ondrej Zajicek <santiago@crfreenet.org>
diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt
index 0ba6af02cdaf..5c88ba1ea262 100644
--- a/Documentation/feature-removal-schedule.txt
+++ b/Documentation/feature-removal-schedule.txt
@@ -6,6 +6,18 @@ be removed from this file.
6 6
7--------------------------- 7---------------------------
8 8
9What: V4L2 VIDIOC_G_MPEGCOMP and VIDIOC_S_MPEGCOMP
10When: October 2007
11Why: Broken attempt to set MPEG compression parameters. These ioctls are
12 not able to implement the wide variety of parameters that can be set
13 by hardware MPEG encoders. A new MPEG control mechanism was created
14 in kernel 2.6.18 that replaces these ioctls. See the V4L2 specification
15 (section 1.9: Extended controls) for more information on this topic.
16Who: Hans Verkuil <hverkuil@xs4all.nl> and
17 Mauro Carvalho Chehab <mchehab@infradead.org>
18
19---------------------------
20
9What: /sys/devices/.../power/state 21What: /sys/devices/.../power/state
10 dev->power.power_state 22 dev->power.power_state
11 dpm_runtime_{suspend,resume)() 23 dpm_runtime_{suspend,resume)()
@@ -39,33 +51,6 @@ Who: Dan Dennedy <dan@dennedy.org>, Stefan Richter <stefanr@s5r6.in-berlin.de>
39 51
40--------------------------- 52---------------------------
41 53
42What: dv1394 driver (CONFIG_IEEE1394_DV1394)
43When: June 2007
44Why: Replaced by raw1394 + userspace libraries, notably libiec61883. This
45 shift of application support has been indicated on www.linux1394.org
46 and developers' mailinglists for quite some time. Major applications
47 have been converted, with the exception of ffmpeg and hence xine.
48 Piped output of dvgrab2 is a partial equivalent to dv1394.
49Who: Dan Dennedy <dan@dennedy.org>, Stefan Richter <stefanr@s5r6.in-berlin.de>
50
51---------------------------
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. 54What: Video4Linux API 1 ioctls and video_decoder.h from Video devices.
70When: December 2006 55When: December 2006
71Why: V4L1 AP1 was replaced by V4L2 API. during migration from 2.4 to 2.6 56Why: V4L1 AP1 was replaced by V4L2 API. during migration from 2.4 to 2.6
@@ -161,15 +146,6 @@ Who: Arjan van de Ven <arjan@linux.intel.com>
161 146
162--------------------------- 147---------------------------
163 148
164What: mount/umount uevents
165When: February 2007
166Why: These events are not correct, and do not properly let userspace know
167 when a file system has been mounted or unmounted. Userspace should
168 poll the /proc/mounts file instead to detect this properly.
169Who: Greg Kroah-Hartman <gregkh@suse.de>
170
171---------------------------
172
173What: USB driver API moves to EXPORT_SYMBOL_GPL 149What: USB driver API moves to EXPORT_SYMBOL_GPL
174When: February 2008 150When: February 2008
175Files: include/linux/usb.h, drivers/usb/core/driver.c 151Files: include/linux/usb.h, drivers/usb/core/driver.c
@@ -186,18 +162,6 @@ Who: Greg Kroah-Hartman <gregkh@suse.de>
186 162
187--------------------------- 163---------------------------
188 164
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 165What: Interrupt only SA_* flags
202When: Januar 2007 166When: Januar 2007
203Why: The interrupt related SA_* flags are replaced by IRQF_* to move them 167Why: The interrupt related SA_* flags are replaced by IRQF_* to move them
@@ -243,12 +207,10 @@ Who: Jean Delvare <khali@linux-fr.org>,
243 207
244--------------------------- 208---------------------------
245 209
246What: IPv4 only connection tracking/NAT/helpers 210What: drivers depending on OBSOLETE_OSS
247When: 2.6.22 211When: options in 2.6.22, code in 2.6.24
248Why: The new layer 3 independant connection tracking replaces the old 212Why: OSS drivers with ALSA replacements
249 IPv4 only version. After some stabilization of the new code the 213Who: Adrian Bunk <bunk@stusta.de>
250 old one will be removed.
251Who: Patrick McHardy <kaber@trash.net>
252 214
253--------------------------- 215---------------------------
254 216
@@ -274,28 +236,6 @@ Who: Venkatesh Pallipadi <venkatesh.pallipadi@intel.com>
274 236
275--------------------------- 237---------------------------
276 238
277What: ACPI hotkey driver (CONFIG_ACPI_HOTKEY)
278When: 2.6.21
279Why: hotkey.c was an attempt to consolidate multiple drivers that use
280 ACPI to implement hotkeys. However, hotkeys are not documented
281 in the ACPI specification, so the drivers used undocumented
282 vendor-specific hooks and turned out to be more different than
283 the same.
284
285 Further, the keys and the features supplied by each platform
286 are different, so there will always be a need for
287 platform-specific drivers.
288
289 So the new plan is to delete hotkey.c and instead, work on the
290 platform specific drivers to try to make them look the same
291 to the user when they supply the same features.
292
293 hotkey.c has always depended on CONFIG_EXPERIMENTAL
294
295Who: Len Brown <len.brown@intel.com>
296
297---------------------------
298
299What: /sys/firmware/acpi/namespace 239What: /sys/firmware/acpi/namespace
300When: 2.6.21 240When: 2.6.21
301Why: The ACPI namespace is effectively the symbol list for 241Why: The ACPI namespace is effectively the symbol list for
@@ -306,11 +246,18 @@ Why: The ACPI namespace is effectively the symbol list for
306 the BIOS can be extracted and disassembled with acpidump 246 the BIOS can be extracted and disassembled with acpidump
307 and iasl as documented in the pmtools package here: 247 and iasl as documented in the pmtools package here:
308 http://ftp.kernel.org/pub/linux/kernel/people/lenb/acpi/utils 248 http://ftp.kernel.org/pub/linux/kernel/people/lenb/acpi/utils
309
310Who: Len Brown <len.brown@intel.com> 249Who: Len Brown <len.brown@intel.com>
311 250
312--------------------------- 251---------------------------
313 252
253What: ACPI procfs interface
254When: July 2007
255Why: After ACPI sysfs conversion, ACPI attributes will be duplicated
256 in sysfs and the ACPI procfs interface should be removed.
257Who: Zhang Rui <rui.zhang@intel.com>
258
259---------------------------
260
314What: /proc/acpi/button 261What: /proc/acpi/button
315When: August 2007 262When: August 2007
316Why: /proc/acpi/button has been replaced by events to the input layer 263Why: /proc/acpi/button has been replaced by events to the input layer
@@ -319,9 +266,51 @@ Who: Len Brown <len.brown@intel.com>
319 266
320--------------------------- 267---------------------------
321 268
322What: JFFS (version 1) 269What: sk98lin network driver
323When: 2.6.21 270When: July 2007
324Why: Unmaintained for years, superceded by JFFS2 for years. 271Why: In kernel tree version of driver is unmaintained. Sk98lin driver
325Who: Jeff Garzik <jeff@garzik.org> 272 replaced by the skge driver.
273Who: Stephen Hemminger <shemminger@osdl.org>
274
275---------------------------
276
277What: Compaq touchscreen device emulation
278When: Oct 2007
279Files: drivers/input/tsdev.c
280Why: The code says it was obsolete when it was written in 2001.
281 tslib is a userspace library which does anything tsdev can do and
282 much more besides in userspace where this code belongs. There is no
283 longer any need for tsdev and applications should have converted to
284 use tslib by now.
285 The name "tsdev" is also extremely confusing and lots of people have
286 it loaded when they don't need/use it.
287Who: Richard Purdie <rpurdie@rpsys.net>
288
289---------------------------
290
291What: i8xx_tco watchdog driver
292When: in 2.6.22
293Why: the i8xx_tco watchdog driver has been replaced by the iTCO_wdt
294 watchdog driver.
295Who: Wim Van Sebroeck <wim@iguana.be>
296
297---------------------------
298
299What: Multipath cached routing support in ipv4
300When: in 2.6.23
301Why: Code was merged, then submitter immediately disappeared leaving
302 us with no maintainer and lots of bugs. The code should not have
303 been merged in the first place, and many aspects of it's
304 implementation are blocking more critical core networking
305 development. It's marked EXPERIMENTAL and no distribution
306 enables it because it cause obscure crashes due to unfixable bugs
307 (interfaces don't return errors so memory allocation can't be
308 handled, calling contexts of these interfaces make handling
309 errors impossible too because they get called after we've
310 totally commited to creating a route object, for example).
311 This problem has existed for years and no forward progress
312 has ever been made, and nobody steps up to try and salvage
313 this code, so we're going to finally just get rid of it.
314Who: David S. Miller <davem@davemloft.net>
326 315
327--------------------------- 316---------------------------
diff --git a/Documentation/filesystems/00-INDEX b/Documentation/filesystems/00-INDEX
index 4dc28cc93503..571785887a4f 100644
--- a/Documentation/filesystems/00-INDEX
+++ b/Documentation/filesystems/00-INDEX
@@ -4,6 +4,8 @@ Exporting
4 - explanation of how to make filesystems exportable. 4 - explanation of how to make filesystems exportable.
5Locking 5Locking
6 - info on locking rules as they pertain to Linux VFS. 6 - info on locking rules as they pertain to Linux VFS.
79p.txt
8 - 9p (v9fs) is an implementation of the Plan 9 remote fs protocol.
7adfs.txt 9adfs.txt
8 - info and mount options for the Acorn Advanced Disc Filing System. 10 - info and mount options for the Acorn Advanced Disc Filing System.
9afs.txt 11afs.txt
@@ -82,8 +84,6 @@ udf.txt
82 - info and mount options for the UDF filesystem. 84 - info and mount options for the UDF filesystem.
83ufs.txt 85ufs.txt
84 - info on the ufs filesystem. 86 - info on the ufs filesystem.
85v9fs.txt
86 - v9fs is a Unix implementation of the Plan 9 9p remote fs protocol.
87vfat.txt 87vfat.txt
88 - info on using the VFAT filesystem used in Windows NT and Windows 95 88 - info on using the VFAT filesystem used in Windows NT and Windows 95
89vfs.txt 89vfs.txt
diff --git a/Documentation/filesystems/9p.txt b/Documentation/filesystems/9p.txt
index 4d075a4558f9..bbd8b28c13de 100644
--- a/Documentation/filesystems/9p.txt
+++ b/Documentation/filesystems/9p.txt
@@ -40,6 +40,10 @@ OPTIONS
40 aname=name aname specifies the file tree to access when the server is 40 aname=name aname specifies the file tree to access when the server is
41 offering several exported file systems. 41 offering several exported file systems.
42 42
43 cache=mode specifies a cacheing policy. By default, no caches are used.
44 loose = no attempts are made at consistency,
45 intended for exclusive, read-only mounts
46
43 debug=n specifies debug level. The debug level is a bitmask. 47 debug=n specifies debug level. The debug level is a bitmask.
44 0x01 = display verbose error messages 48 0x01 = display verbose error messages
45 0x02 = developer debug (DEBUG_CURRENT) 49 0x02 = developer debug (DEBUG_CURRENT)
diff --git a/Documentation/filesystems/afs.txt b/Documentation/filesystems/afs.txt
index 2f4237dfb8c7..12ad6c7f4e50 100644
--- a/Documentation/filesystems/afs.txt
+++ b/Documentation/filesystems/afs.txt
@@ -1,31 +1,82 @@
1 ====================
1 kAFS: AFS FILESYSTEM 2 kAFS: AFS FILESYSTEM
2 ==================== 3 ====================
3 4
4ABOUT 5Contents:
5===== 6
7 - Overview.
8 - Usage.
9 - Mountpoints.
10 - Proc filesystem.
11 - The cell database.
12 - Security.
13 - Examples.
14
15
16========
17OVERVIEW
18========
6 19
7This filesystem provides a fairly simple AFS filesystem driver. It is under 20This filesystem provides a fairly simple secure AFS filesystem driver. It is
8development and only provides very basic facilities. It does not yet support 21under development and does not yet provide the full feature set. The features
9the following AFS features: 22it does support include:
10 23
11 (*) Write support. 24 (*) Security (currently only AFS kaserver and KerberosIV tickets).
12 (*) Communications security.
13 (*) Local caching.
14 (*) pioctl() system call.
15 (*) Automatic mounting of embedded mountpoints.
16 25
26 (*) File reading.
17 27
28 (*) Automounting.
29
30It does not yet support the following AFS features:
31
32 (*) Write support.
33
34 (*) Local caching.
35
36 (*) pioctl() system call.
37
38
39===========
40COMPILATION
41===========
42
43The filesystem should be enabled by turning on the kernel configuration
44options:
45
46 CONFIG_AF_RXRPC - The RxRPC protocol transport
47 CONFIG_RXKAD - The RxRPC Kerberos security handler
48 CONFIG_AFS - The AFS filesystem
49
50Additionally, the following can be turned on to aid debugging:
51
52 CONFIG_AF_RXRPC_DEBUG - Permit AF_RXRPC debugging to be enabled
53 CONFIG_AFS_DEBUG - Permit AFS debugging to be enabled
54
55They permit the debugging messages to be turned on dynamically by manipulating
56the masks in the following files:
57
58 /sys/module/af_rxrpc/parameters/debug
59 /sys/module/afs/parameters/debug
60
61
62=====
18USAGE 63USAGE
19===== 64=====
20 65
21When inserting the driver modules the root cell must be specified along with a 66When inserting the driver modules the root cell must be specified along with a
22list of volume location server IP addresses: 67list of volume location server IP addresses:
23 68
24 insmod rxrpc.o 69 insmod af_rxrpc.o
70 insmod rxkad.o
25 insmod kafs.o rootcell=cambridge.redhat.com:172.16.18.73:172.16.18.91 71 insmod kafs.o rootcell=cambridge.redhat.com:172.16.18.73:172.16.18.91
26 72
27The first module is a driver for the RxRPC remote operation protocol, and the 73The first module is the AF_RXRPC network protocol driver. This provides the
28second is the actual filesystem driver for the AFS filesystem. 74RxRPC remote operation protocol and may also be accessed from userspace. See:
75
76 Documentation/networking/rxrpc.txt
77
78The second module is the kerberos RxRPC security driver, and the third module
79is the actual filesystem driver for the AFS filesystem.
29 80
30Once the module has been loaded, more modules can be added by the following 81Once the module has been loaded, more modules can be added by the following
31procedure: 82procedure:
@@ -33,7 +84,7 @@ procedure:
33 echo add grand.central.org 18.7.14.88:128.2.191.224 >/proc/fs/afs/cells 84 echo add grand.central.org 18.7.14.88:128.2.191.224 >/proc/fs/afs/cells
34 85
35Where the parameters to the "add" command are the name of a cell and a list of 86Where the parameters to the "add" command are the name of a cell and a list of
36volume location servers within that cell. 87volume location servers within that cell, with the latter separated by colons.
37 88
38Filesystems can be mounted anywhere by commands similar to the following: 89Filesystems can be mounted anywhere by commands similar to the following:
39 90
@@ -42,11 +93,6 @@ Filesystems can be mounted anywhere by commands similar to the following:
42 mount -t afs "#root.afs." /afs 93 mount -t afs "#root.afs." /afs
43 mount -t afs "#root.cell." /afs/cambridge 94 mount -t afs "#root.cell." /afs/cambridge
44 95
45 NB: When using this on Linux 2.4, the mount command has to be different,
46 since the filesystem doesn't have access to the device name argument:
47
48 mount -t afs none /afs -ovol="#root.afs."
49
50Where the initial character is either a hash or a percent symbol depending on 96Where the initial character is either a hash or a percent symbol depending on
51whether you definitely want a R/W volume (hash) or whether you'd prefer a R/O 97whether you definitely want a R/W volume (hash) or whether you'd prefer a R/O
52volume, but are willing to use a R/W volume instead (percent). 98volume, but are willing to use a R/W volume instead (percent).
@@ -60,55 +106,66 @@ named volume will be looked up in the cell specified during insmod.
60Additional cells can be added through /proc (see later section). 106Additional cells can be added through /proc (see later section).
61 107
62 108
109===========
63MOUNTPOINTS 110MOUNTPOINTS
64=========== 111===========
65 112
66AFS has a concept of mountpoints. These are specially formatted symbolic links 113AFS has a concept of mountpoints. In AFS terms, these are specially formatted
67(of the same form as the "device name" passed to mount). kAFS presents these 114symbolic links (of the same form as the "device name" passed to mount). kAFS
68to the user as directories that have special properties: 115presents these to the user as directories that have a follow-link capability
116(ie: symbolic link semantics). If anyone attempts to access them, they will
117automatically cause the target volume to be mounted (if possible) on that site.
69 118
70 (*) They cannot be listed. Running a program like "ls" on them will incur an 119Automatically mounted filesystems will be automatically unmounted approximately
71 EREMOTE error (Object is remote). 120twenty minutes after they were last used. Alternatively they can be unmounted
121directly with the umount() system call.
72 122
73 (*) Other objects can't be looked up inside of them. This also incurs an 123Manually unmounting an AFS volume will cause any idle submounts upon it to be
74 EREMOTE error. 124culled first. If all are culled, then the requested volume will also be
125unmounted, otherwise error EBUSY will be returned.
75 126
76 (*) They can be queried with the readlink() system call, which will return 127This can be used by the administrator to attempt to unmount the whole AFS tree
77 the name of the mountpoint to which they point. The "readlink" program 128mounted on /afs in one go by doing:
78 will also work.
79 129
80 (*) They can be mounted on (which symbolic links can't). 130 umount /afs
81 131
82 132
133===============
83PROC FILESYSTEM 134PROC FILESYSTEM
84=============== 135===============
85 136
86The rxrpc module creates a number of files in various places in the /proc
87filesystem:
88
89 (*) Firstly, some information files are made available in a directory called
90 "/proc/net/rxrpc/". These list the extant transport endpoint, peer,
91 connection and call records.
92
93 (*) Secondly, some control files are made available in a directory called
94 "/proc/sys/rxrpc/". Currently, all these files can be used for is to
95 turn on various levels of tracing.
96
97The AFS modules creates a "/proc/fs/afs/" directory and populates it: 137The AFS modules creates a "/proc/fs/afs/" directory and populates it:
98 138
99 (*) A "cells" file that lists cells currently known to the afs module. 139 (*) A "cells" file that lists cells currently known to the afs module and
140 their usage counts:
141
142 [root@andromeda ~]# cat /proc/fs/afs/cells
143 USE NAME
144 3 cambridge.redhat.com
100 145
101 (*) A directory per cell that contains files that list volume location 146 (*) A directory per cell that contains files that list volume location
102 servers, volumes, and active servers known within that cell. 147 servers, volumes, and active servers known within that cell.
103 148
149 [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/servers
150 USE ADDR STATE
151 4 172.16.18.91 0
152 [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/vlservers
153 ADDRESS
154 172.16.18.91
155 [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/volumes
156 USE STT VLID[0] VLID[1] VLID[2] NAME
157 1 Val 20000000 20000001 20000002 root.afs
104 158
159
160=================
105THE CELL DATABASE 161THE CELL DATABASE
106================= 162=================
107 163
108The filesystem maintains an internal database of all the cells it knows and 164The filesystem maintains an internal database of all the cells it knows and the
109the IP addresses of the volume location servers for those cells. The cell to 165IP addresses of the volume location servers for those cells. The cell to which
110which the computer belongs is added to the database when insmod is performed 166the system belongs is added to the database when insmod is performed by the
111by the "rootcell=" argument. 167"rootcell=" argument or, if compiled in, using a "kafs.rootcell=" argument on
168the kernel command line.
112 169
113Further cells can be added by commands similar to the following: 170Further cells can be added by commands similar to the following:
114 171
@@ -118,20 +175,65 @@ Further cells can be added by commands similar to the following:
118No other cell database operations are available at this time. 175No other cell database operations are available at this time.
119 176
120 177
178========
179SECURITY
180========
181
182Secure operations are initiated by acquiring a key using the klog program. A
183very primitive klog program is available at:
184
185 http://people.redhat.com/~dhowells/rxrpc/klog.c
186
187This should be compiled by:
188
189 make klog LDLIBS="-lcrypto -lcrypt -lkrb4 -lkeyutils"
190
191And then run as:
192
193 ./klog
194
195Assuming it's successful, this adds a key of type RxRPC, named for the service
196and cell, eg: "afs@<cellname>". This can be viewed with the keyctl program or
197by cat'ing /proc/keys:
198
199 [root@andromeda ~]# keyctl show
200 Session Keyring
201 -3 --alswrv 0 0 keyring: _ses.3268
202 2 --alswrv 0 0 \_ keyring: _uid.0
203 111416553 --als--v 0 0 \_ rxrpc: afs@CAMBRIDGE.REDHAT.COM
204
205Currently the username, realm, password and proposed ticket lifetime are
206compiled in to the program.
207
208It is not required to acquire a key before using AFS facilities, but if one is
209not acquired then all operations will be governed by the anonymous user parts
210of the ACLs.
211
212If a key is acquired, then all AFS operations, including mounts and automounts,
213made by a possessor of that key will be secured with that key.
214
215If a file is opened with a particular key and then the file descriptor is
216passed to a process that doesn't have that key (perhaps over an AF_UNIX
217socket), then the operations on the file will be made with key that was used to
218open the file.
219
220
221========
121EXAMPLES 222EXAMPLES
122======== 223========
123 224
124Here's what I use to test this. Some of the names and IP addresses are local 225Here's what I use to test this. Some of the names and IP addresses are local
125to my internal DNS. My "root.afs" partition has a mount point within it for 226to my internal DNS. My "root.afs" partition has a mount point within it for
126some public volumes volumes. 227some public volumes volumes.
127 228
128insmod -S /tmp/rxrpc.o 229insmod /tmp/rxrpc.o
129insmod -S /tmp/kafs.o rootcell=cambridge.redhat.com:172.16.18.73:172.16.18.91 230insmod /tmp/rxkad.o
231insmod /tmp/kafs.o rootcell=cambridge.redhat.com:172.16.18.91
130 232
131mount -t afs \%root.afs. /afs 233mount -t afs \%root.afs. /afs
132mount -t afs \%cambridge.redhat.com:root.cell. /afs/cambridge.redhat.com/ 234mount -t afs \%cambridge.redhat.com:root.cell. /afs/cambridge.redhat.com/
133 235
134echo add grand.central.org 18.7.14.88:128.2.191.224 > /proc/fs/afs/cells 236echo add grand.central.org 18.7.14.88:128.2.191.224 > /proc/fs/afs/cells
135mount -t afs "#grand.central.org:root.cell." /afs/grand.central.org/ 237mount -t afs "#grand.central.org:root.cell." /afs/grand.central.org/
136mount -t afs "#grand.central.org:root.archive." /afs/grand.central.org/archive 238mount -t afs "#grand.central.org:root.archive." /afs/grand.central.org/archive
137mount -t afs "#grand.central.org:root.contrib." /afs/grand.central.org/contrib 239mount -t afs "#grand.central.org:root.contrib." /afs/grand.central.org/contrib
@@ -141,15 +243,7 @@ mount -t afs "#grand.central.org:root.service." /afs/grand.central.org/service
141mount -t afs "#grand.central.org:root.software." /afs/grand.central.org/software 243mount -t afs "#grand.central.org:root.software." /afs/grand.central.org/software
142mount -t afs "#grand.central.org:root.user." /afs/grand.central.org/user 244mount -t afs "#grand.central.org:root.user." /afs/grand.central.org/user
143 245
144umount /afs/grand.central.org/user
145umount /afs/grand.central.org/software
146umount /afs/grand.central.org/service
147umount /afs/grand.central.org/project
148umount /afs/grand.central.org/doc
149umount /afs/grand.central.org/contrib
150umount /afs/grand.central.org/archive
151umount /afs/grand.central.org
152umount /afs/cambridge.redhat.com
153umount /afs 246umount /afs
154rmmod kafs 247rmmod kafs
248rmmod rxkad
155rmmod rxrpc 249rmmod rxrpc
diff --git a/Documentation/filesystems/proc.txt b/Documentation/filesystems/proc.txt
index 72af5de1effb..7aaf09b86a55 100644
--- a/Documentation/filesystems/proc.txt
+++ b/Documentation/filesystems/proc.txt
@@ -41,6 +41,7 @@ Table of Contents
41 2.11 /proc/sys/fs/mqueue - POSIX message queues filesystem 41 2.11 /proc/sys/fs/mqueue - POSIX message queues filesystem
42 2.12 /proc/<pid>/oom_adj - Adjust the oom-killer score 42 2.12 /proc/<pid>/oom_adj - Adjust the oom-killer score
43 2.13 /proc/<pid>/oom_score - Display current oom-killer score 43 2.13 /proc/<pid>/oom_score - Display current oom-killer score
44 2.14 /proc/<pid>/io - Display the IO accounting fields
44 45
45------------------------------------------------------------------------------ 46------------------------------------------------------------------------------
46Preface 47Preface
@@ -1420,6 +1421,15 @@ fewer messages that will be written. Message_burst controls when messages will
1420be dropped. The default settings limit warning messages to one every five 1421be dropped. The default settings limit warning messages to one every five
1421seconds. 1422seconds.
1422 1423
1424warnings
1425--------
1426
1427This controls console messages from the networking stack that can occur because
1428of problems on the network like duplicate address or bad checksums. Normally,
1429this should be enabled, but if the problem persists the messages can be
1430disabled.
1431
1432
1423netdev_max_backlog 1433netdev_max_backlog
1424------------------ 1434------------------
1425 1435
@@ -1990,3 +2000,107 @@ need to recompile the kernel, or even to reboot the system. The files in the
1990command to write value into these files, thereby changing the default settings 2000command to write value into these files, thereby changing the default settings
1991of the kernel. 2001of the kernel.
1992------------------------------------------------------------------------------ 2002------------------------------------------------------------------------------
2003
20042.14 /proc/<pid>/io - Display the IO accounting fields
2005-------------------------------------------------------
2006
2007This file contains IO statistics for each running process
2008
2009Example
2010-------
2011
2012test:/tmp # dd if=/dev/zero of=/tmp/test.dat &
2013[1] 3828
2014
2015test:/tmp # cat /proc/3828/io
2016rchar: 323934931
2017wchar: 323929600
2018syscr: 632687
2019syscw: 632675
2020read_bytes: 0
2021write_bytes: 323932160
2022cancelled_write_bytes: 0
2023
2024
2025Description
2026-----------
2027
2028rchar
2029-----
2030
2031I/O counter: chars read
2032The number of bytes which this task has caused to be read from storage. This
2033is simply the sum of bytes which this process passed to read() and pread().
2034It includes things like tty IO and it is unaffected by whether or not actual
2035physical disk IO was required (the read might have been satisfied from
2036pagecache)
2037
2038
2039wchar
2040-----
2041
2042I/O counter: chars written
2043The number of bytes which this task has caused, or shall cause to be written
2044to disk. Similar caveats apply here as with rchar.
2045
2046
2047syscr
2048-----
2049
2050I/O counter: read syscalls
2051Attempt to count the number of read I/O operations, i.e. syscalls like read()
2052and pread().
2053
2054
2055syscw
2056-----
2057
2058I/O counter: write syscalls
2059Attempt to count the number of write I/O operations, i.e. syscalls like
2060write() and pwrite().
2061
2062
2063read_bytes
2064----------
2065
2066I/O counter: bytes read
2067Attempt to count the number of bytes which this process really did cause to
2068be fetched from the storage layer. Done at the submit_bio() level, so it is
2069accurate for block-backed filesystems. <please add status regarding NFS and
2070CIFS at a later time>
2071
2072
2073write_bytes
2074-----------
2075
2076I/O counter: bytes written
2077Attempt to count the number of bytes which this process caused to be sent to
2078the storage layer. This is done at page-dirtying time.
2079
2080
2081cancelled_write_bytes
2082---------------------
2083
2084The big inaccuracy here is truncate. If a process writes 1MB to a file and
2085then deletes the file, it will in fact perform no writeout. But it will have
2086been accounted as having caused 1MB of write.
2087In other words: The number of bytes which this process caused to not happen,
2088by truncating pagecache. A task can cause "negative" IO too. If this task
2089truncates some dirty pagecache, some IO which another task has been accounted
2090for (in it's write_bytes) will not be happening. We _could_ just subtract that
2091from the truncating task's write_bytes, but there is information loss in doing
2092that.
2093
2094
2095Note
2096----
2097
2098At its current implementation state, this is a bit racy on 32-bit machines: if
2099process A reads process B's /proc/pid/io while process B is updating one of
2100those 64-bit counters, process A could see an intermediate result.
2101
2102
2103More information about this can be found within the taskstats documentation in
2104Documentation/accounting.
2105
2106------------------------------------------------------------------------------
diff --git a/Documentation/filesystems/relay.txt b/Documentation/filesystems/relay.txt
index d6788dae0349..7fbb6ffe5769 100644
--- a/Documentation/filesystems/relay.txt
+++ b/Documentation/filesystems/relay.txt
@@ -157,7 +157,7 @@ TBD(curr. line MT:/API/)
157 channel management functions: 157 channel management functions:
158 158
159 relay_open(base_filename, parent, subbuf_size, n_subbufs, 159 relay_open(base_filename, parent, subbuf_size, n_subbufs,
160 callbacks) 160 callbacks, private_data)
161 relay_close(chan) 161 relay_close(chan)
162 relay_flush(chan) 162 relay_flush(chan)
163 relay_reset(chan) 163 relay_reset(chan)
@@ -251,7 +251,7 @@ static struct rchan_callbacks relay_callbacks =
251 251
252And an example relay_open() invocation using them: 252And an example relay_open() invocation using them:
253 253
254 chan = relay_open("cpu", NULL, SUBBUF_SIZE, N_SUBBUFS, &relay_callbacks); 254 chan = relay_open("cpu", NULL, SUBBUF_SIZE, N_SUBBUFS, &relay_callbacks, NULL);
255 255
256If the create_buf_file() callback fails, or isn't defined, channel 256If the create_buf_file() callback fails, or isn't defined, channel
257creation and thus relay_open() will fail. 257creation and thus relay_open() will fail.
@@ -289,6 +289,11 @@ they use the proper locking for such a buffer, either by wrapping
289writes in a spinlock, or by copying a write function from relay.h and 289writes in a spinlock, or by copying a write function from relay.h and
290creating a local version that internally does the proper locking. 290creating a local version that internally does the proper locking.
291 291
292The private_data passed into relay_open() allows clients to associate
293user-defined data with a channel, and is immediately available
294(including in create_buf_file()) via chan->private_data or
295buf->chan->private_data.
296
292Channel 'modes' 297Channel 'modes'
293--------------- 298---------------
294 299
diff --git a/Documentation/filesystems/sysfs-pci.txt b/Documentation/filesystems/sysfs-pci.txt
index 7ba2baa165ff..5daa2aaec2c5 100644
--- a/Documentation/filesystems/sysfs-pci.txt
+++ b/Documentation/filesystems/sysfs-pci.txt
@@ -65,7 +65,7 @@ Accessing legacy resources through sysfs
65---------------------------------------- 65----------------------------------------
66 66
67Legacy I/O port and ISA memory resources are also provided in sysfs if the 67Legacy I/O port and ISA memory resources are also provided in sysfs if the
68underlying platform supports them. They're located in the PCI class heirarchy, 68underlying platform supports them. They're located in the PCI class hierarchy,
69e.g. 69e.g.
70 70
71 /sys/class/pci_bus/0000:17/ 71 /sys/class/pci_bus/0000:17/
diff --git a/Documentation/filesystems/ufs.txt b/Documentation/filesystems/ufs.txt
index 2b5a56a6a558..7a602adeca2b 100644
--- a/Documentation/filesystems/ufs.txt
+++ b/Documentation/filesystems/ufs.txt
@@ -21,7 +21,7 @@ ufstype=type_of_ufs
21 supported as read-write 21 supported as read-write
22 22
23 ufs2 used in FreeBSD 5.x 23 ufs2 used in FreeBSD 5.x
24 supported as read-only 24 supported as read-write
25 25
26 5xbsd synonym for ufs2 26 5xbsd synonym for ufs2
27 27
@@ -50,12 +50,11 @@ ufstype=type_of_ufs
50POSSIBLE PROBLEMS 50POSSIBLE PROBLEMS
51================= 51=================
52 52
53There is still bug in reallocation of fragment, in file fs/ufs/balloc.c, 53See next section, if you have any.
54line 364. But it seems working on current buffer cache configuration.
55 54
56 55
57BUG REPORTS 56BUG REPORTS
58=========== 57===========
59 58
60Any ufs bug report you can send to daniel.pirkl@email.cz (do not send 59Any ufs bug report you can send to daniel.pirkl@email.cz or
61partition tables bug reports.) 60to dushistov@mail.ru (do not send partition tables bug reports).
diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt
index 7737bfd03cf8..ea271f2d3954 100644
--- a/Documentation/filesystems/vfs.txt
+++ b/Documentation/filesystems/vfs.txt
@@ -617,6 +617,11 @@ struct address_space_operations {
617 In this case the prepare_write will be retried one the lock is 617 In this case the prepare_write will be retried one the lock is
618 regained. 618 regained.
619 619
620 Note: the page _must not_ be marked uptodate in this function
621 (or anywhere else) unless it actually is uptodate right now. As
622 soon as a page is marked uptodate, it is possible for a concurrent
623 read(2) to copy it to userspace.
624
620 commit_write: If prepare_write succeeds, new data will be copied 625 commit_write: If prepare_write succeeds, new data will be copied
621 into the page and then commit_write will be called. It will 626 into the page and then commit_write will be called. It will
622 typically update the size of the file (if appropriate) and 627 typically update the size of the file (if appropriate) and
diff --git a/Documentation/gpio.txt b/Documentation/gpio.txt
new file mode 100644
index 000000000000..f8528db967fa
--- /dev/null
+++ b/Documentation/gpio.txt
@@ -0,0 +1,306 @@
1GPIO Interfaces
2
3This provides an overview of GPIO access conventions on Linux.
4
5
6What is a GPIO?
7===============
8A "General Purpose Input/Output" (GPIO) is a flexible software-controlled
9digital signal. They are provided from many kinds of chip, and are familiar
10to Linux developers working with embedded and custom hardware. Each GPIO
11represents a bit connected to a particular pin, or "ball" on Ball Grid Array
12(BGA) packages. Board schematics show which external hardware connects to
13which GPIOs. Drivers can be written generically, so that board setup code
14passes such pin configuration data to drivers.
15
16System-on-Chip (SOC) processors heavily rely on GPIOs. In some cases, every
17non-dedicated pin can be configured as a GPIO; and most chips have at least
18several dozen of them. Programmable logic devices (like FPGAs) can easily
19provide GPIOs; multifunction chips like power managers, and audio codecs
20often have a few such pins to help with pin scarcity on SOCs; and there are
21also "GPIO Expander" chips that connect using the I2C or SPI serial busses.
22Most PC southbridges have a few dozen GPIO-capable pins (with only the BIOS
23firmware knowing how they're used).
24
25The exact capabilities of GPIOs vary between systems. Common options:
26
27 - Output values are writable (high=1, low=0). Some chips also have
28 options about how that value is driven, so that for example only one
29 value might be driven ... supporting "wire-OR" and similar schemes
30 for the other value (notably, "open drain" signaling).
31
32 - Input values are likewise readable (1, 0). Some chips support readback
33 of pins configured as "output", which is very useful in such "wire-OR"
34 cases (to support bidirectional signaling). GPIO controllers may have
35 input de-glitch logic, sometimes with software controls.
36
37 - Inputs can often be used as IRQ signals, often edge triggered but
38 sometimes level triggered. Such IRQs may be configurable as system
39 wakeup events, to wake the system from a low power state.
40
41 - Usually a GPIO will be configurable as either input or output, as needed
42 by different product boards; single direction ones exist too.
43
44 - Most GPIOs can be accessed while holding spinlocks, but those accessed
45 through a serial bus normally can't. Some systems support both types.
46
47On a given board each GPIO is used for one specific purpose like monitoring
48MMC/SD card insertion/removal, detecting card writeprotect status, driving
49a LED, configuring a transceiver, bitbanging a serial bus, poking a hardware
50watchdog, sensing a switch, and so on.
51
52
53GPIO conventions
54================
55Note that this is called a "convention" because you don't need to do it this
56way, and it's no crime if you don't. There **are** cases where portability
57is not the main issue; GPIOs are often used for the kind of board-specific
58glue logic that may even change between board revisions, and can't ever be
59used on a board that's wired differently. Only least-common-denominator
60functionality can be very portable. Other features are platform-specific,
61and that can be critical for glue logic.
62
63Plus, this doesn't define an implementation framework, just an interface.
64One platform might implement it as simple inline functions accessing chip
65registers; another might implement it by delegating through abstractions
66used for several very different kinds of GPIO controller.
67
68That said, if the convention is supported on their platform, drivers should
69use it when possible:
70
71 #include <asm/gpio.h>
72
73If you stick to this convention then it'll be easier for other developers to
74see what your code is doing, and help maintain it.
75
76
77Identifying GPIOs
78-----------------
79GPIOs are identified by unsigned integers in the range 0..MAX_INT. That
80reserves "negative" numbers for other purposes like marking signals as
81"not available on this board", or indicating faults. Code that doesn't
82touch the underlying hardware treats these integers as opaque cookies.
83
84Platforms define how they use those integers, and usually #define symbols
85for the GPIO lines so that board-specific setup code directly corresponds
86to the relevant schematics. In contrast, drivers should only use GPIO
87numbers passed to them from that setup code, using platform_data to hold
88board-specific pin configuration data (along with other board specific
89data they need). That avoids portability problems.
90
91So for example one platform uses numbers 32-159 for GPIOs; while another
92uses numbers 0..63 with one set of GPIO controllers, 64-79 with another
93type of GPIO controller, and on one particular board 80-95 with an FPGA.
94The numbers need not be contiguous; either of those platforms could also
95use numbers 2000-2063 to identify GPIOs in a bank of I2C GPIO expanders.
96
97Whether a platform supports multiple GPIO controllers is currently a
98platform-specific implementation issue.
99
100
101Using GPIOs
102-----------
103One of the first things to do with a GPIO, often in board setup code when
104setting up a platform_device using the GPIO, is mark its direction:
105
106 /* set as input or output, returning 0 or negative errno */
107 int gpio_direction_input(unsigned gpio);
108 int gpio_direction_output(unsigned gpio, int value);
109
110The return value is zero for success, else a negative errno. It should
111be checked, since the get/set calls don't have error returns and since
112misconfiguration is possible. (These calls could sleep.)
113
114For output GPIOs, the value provided becomes the initial output value.
115This helps avoid signal glitching during system startup.
116
117Setting the direction can fail if the GPIO number is invalid, or when
118that particular GPIO can't be used in that mode. It's generally a bad
119idea to rely on boot firmware to have set the direction correctly, since
120it probably wasn't validated to do more than boot Linux. (Similarly,
121that board setup code probably needs to multiplex that pin as a GPIO,
122and configure pullups/pulldowns appropriately.)
123
124
125Spinlock-Safe GPIO access
126-------------------------
127Most GPIO controllers can be accessed with memory read/write instructions.
128That doesn't need to sleep, and can safely be done from inside IRQ handlers.
129
130Use these calls to access such GPIOs:
131
132 /* GPIO INPUT: return zero or nonzero */
133 int gpio_get_value(unsigned gpio);
134
135 /* GPIO OUTPUT */
136 void gpio_set_value(unsigned gpio, int value);
137
138The values are boolean, zero for low, nonzero for high. When reading the
139value of an output pin, the value returned should be what's seen on the
140pin ... that won't always match the specified output value, because of
141issues including wire-OR and output latencies.
142
143The get/set calls have no error returns because "invalid GPIO" should have
144been reported earlier in gpio_set_direction(). However, note that not all
145platforms can read the value of output pins; those that can't should always
146return zero. Also, using these calls for GPIOs that can't safely be accessed
147without sleeping (see below) is an error.
148
149Platform-specific implementations are encouraged to optimize the two
150calls to access the GPIO value in cases where the GPIO number (and for
151output, value) are constant. It's normal for them to need only a couple
152of instructions in such cases (reading or writing a hardware register),
153and not to need spinlocks. Such optimized calls can make bitbanging
154applications a lot more efficient (in both space and time) than spending
155dozens of instructions on subroutine calls.
156
157
158GPIO access that may sleep
159--------------------------
160Some GPIO controllers must be accessed using message based busses like I2C
161or SPI. Commands to read or write those GPIO values require waiting to
162get to the head of a queue to transmit a command and get its response.
163This requires sleeping, which can't be done from inside IRQ handlers.
164
165Platforms that support this type of GPIO distinguish them from other GPIOs
166by returning nonzero from this call:
167
168 int gpio_cansleep(unsigned gpio);
169
170To access such GPIOs, a different set of accessors is defined:
171
172 /* GPIO INPUT: return zero or nonzero, might sleep */
173 int gpio_get_value_cansleep(unsigned gpio);
174
175 /* GPIO OUTPUT, might sleep */
176 void gpio_set_value_cansleep(unsigned gpio, int value);
177
178Other than the fact that these calls might sleep, and will not be ignored
179for GPIOs that can't be accessed from IRQ handlers, these calls act the
180same as the spinlock-safe calls.
181
182
183Claiming and Releasing GPIOs (OPTIONAL)
184---------------------------------------
185To help catch system configuration errors, two calls are defined.
186However, many platforms don't currently support this mechanism.
187
188 /* request GPIO, returning 0 or negative errno.
189 * non-null labels may be useful for diagnostics.
190 */
191 int gpio_request(unsigned gpio, const char *label);
192
193 /* release previously-claimed GPIO */
194 void gpio_free(unsigned gpio);
195
196Passing invalid GPIO numbers to gpio_request() will fail, as will requesting
197GPIOs that have already been claimed with that call. The return value of
198gpio_request() must be checked. (These calls could sleep.)
199
200These calls serve two basic purposes. One is marking the signals which
201are actually in use as GPIOs, for better diagnostics; systems may have
202several hundred potential GPIOs, but often only a dozen are used on any
203given board. Another is to catch conflicts between drivers, reporting
204errors when drivers wrongly think they have exclusive use of that signal.
205
206These two calls are optional because not not all current Linux platforms
207offer such functionality in their GPIO support; a valid implementation
208could return success for all gpio_request() calls. Unlike the other calls,
209the state they represent doesn't normally match anything from a hardware
210register; it's just a software bitmap which clearly is not necessary for
211correct operation of hardware or (bug free) drivers.
212
213Note that requesting a GPIO does NOT cause it to be configured in any
214way; it just marks that GPIO as in use. Separate code must handle any
215pin setup (e.g. controlling which pin the GPIO uses, pullup/pulldown).
216
217
218GPIOs mapped to IRQs
219--------------------
220GPIO numbers are unsigned integers; so are IRQ numbers. These make up
221two logically distinct namespaces (GPIO 0 need not use IRQ 0). You can
222map between them using calls like:
223
224 /* map GPIO numbers to IRQ numbers */
225 int gpio_to_irq(unsigned gpio);
226
227 /* map IRQ numbers to GPIO numbers */
228 int irq_to_gpio(unsigned irq);
229
230Those return either the corresponding number in the other namespace, or
231else a negative errno code if the mapping can't be done. (For example,
232some GPIOs can't used as IRQs.) It is an unchecked error to use a GPIO
233number that hasn't been marked as an input using gpio_set_direction(), or
234to use an IRQ number that didn't originally come from gpio_to_irq().
235
236These two mapping calls are expected to cost on the order of a single
237addition or subtraction. They're not allowed to sleep.
238
239Non-error values returned from gpio_to_irq() can be passed to request_irq()
240or free_irq(). They will often be stored into IRQ resources for platform
241devices, by the board-specific initialization code. Note that IRQ trigger
242options are part of the IRQ interface, e.g. IRQF_TRIGGER_FALLING, as are
243system wakeup capabilities.
244
245Non-error values returned from irq_to_gpio() would most commonly be used
246with gpio_get_value(), for example to initialize or update driver state
247when the IRQ is edge-triggered.
248
249
250Emulating Open Drain Signals
251----------------------------
252Sometimes shared signals need to use "open drain" signaling, where only the
253low signal level is actually driven. (That term applies to CMOS transistors;
254"open collector" is used for TTL.) A pullup resistor causes the high signal
255level. This is sometimes called a "wire-AND"; or more practically, from the
256negative logic (low=true) perspective this is a "wire-OR".
257
258One common example of an open drain signal is a shared active-low IRQ line.
259Also, bidirectional data bus signals sometimes use open drain signals.
260
261Some GPIO controllers directly support open drain outputs; many don't. When
262you need open drain signaling but your hardware doesn't directly support it,
263there's a common idiom you can use to emulate it with any GPIO pin that can
264be used as either an input or an output:
265
266 LOW: gpio_direction_output(gpio, 0) ... this drives the signal
267 and overrides the pullup.
268
269 HIGH: gpio_direction_input(gpio) ... this turns off the output,
270 so the pullup (or some other device) controls the signal.
271
272If you are "driving" the signal high but gpio_get_value(gpio) reports a low
273value (after the appropriate rise time passes), you know some other component
274is driving the shared signal low. That's not necessarily an error. As one
275common example, that's how I2C clocks are stretched: a slave that needs a
276slower clock delays the rising edge of SCK, and the I2C master adjusts its
277signaling rate accordingly.
278
279
280What do these conventions omit?
281===============================
282One of the biggest things these conventions omit is pin multiplexing, since
283this is highly chip-specific and nonportable. One platform might not need
284explicit multiplexing; another might have just two options for use of any
285given pin; another might have eight options per pin; another might be able
286to route a given GPIO to any one of several pins. (Yes, those examples all
287come from systems that run Linux today.)
288
289Related to multiplexing is configuration and enabling of the pullups or
290pulldowns integrated on some platforms. Not all platforms support them,
291or support them in the same way; and any given board might use external
292pullups (or pulldowns) so that the on-chip ones should not be used.
293
294There are other system-specific mechanisms that are not specified here,
295like the aforementioned options for input de-glitching and wire-OR output.
296Hardware may support reading or writing GPIOs in gangs, but that's usually
297configuration dependent: for GPIOs sharing the same bank. (GPIOs are
298commonly grouped in banks of 16 or 32, with a given SOC having several such
299banks.) Some systems can trigger IRQs from output GPIOs. Code relying on
300such mechanisms will necessarily be nonportable.
301
302Dynamic definition of GPIOs is not currently supported; for example, as
303a side effect of configuring an add-on board with some GPIO expanders.
304
305These calls are purely for kernel space, but a userspace API could be built
306on top of it.
diff --git a/Documentation/hrtimer/timer_stats.txt b/Documentation/hrtimer/timer_stats.txt
new file mode 100644
index 000000000000..27f782e3593f
--- /dev/null
+++ b/Documentation/hrtimer/timer_stats.txt
@@ -0,0 +1,68 @@
1timer_stats - timer usage statistics
2------------------------------------
3
4timer_stats is a debugging facility to make the timer (ab)usage in a Linux
5system visible to kernel and userspace developers. It is not intended for
6production usage as it adds significant overhead to the (hr)timer code and the
7(hr)timer data structures.
8
9timer_stats should be used by kernel and userspace developers to verify that
10their code does not make unduly use of timers. This helps to avoid unnecessary
11wakeups, which should be avoided to optimize power consumption.
12
13It can be enabled by CONFIG_TIMER_STATS in the "Kernel hacking" configuration
14section.
15
16timer_stats collects information about the timer events which are fired in a
17Linux system over a sample period:
18
19- the pid of the task(process) which initialized the timer
20- the name of the process which initialized the timer
21- the function where the timer was intialized
22- the callback function which is associated to the timer
23- the number of events (callbacks)
24
25timer_stats adds an entry to /proc: /proc/timer_stats
26
27This entry is used to control the statistics functionality and to read out the
28sampled information.
29
30The timer_stats functionality is inactive on bootup.
31
32To activate a sample period issue:
33# echo 1 >/proc/timer_stats
34
35To stop a sample period issue:
36# echo 0 >/proc/timer_stats
37
38The statistics can be retrieved by:
39# cat /proc/timer_stats
40
41The readout of /proc/timer_stats automatically disables sampling. The sampled
42information is kept until a new sample period is started. This allows multiple
43readouts.
44
45Sample output of /proc/timer_stats:
46
47Timerstats sample period: 3.888770 s
48 12, 0 swapper hrtimer_stop_sched_tick (hrtimer_sched_tick)
49 15, 1 swapper hcd_submit_urb (rh_timer_func)
50 4, 959 kedac schedule_timeout (process_timeout)
51 1, 0 swapper page_writeback_init (wb_timer_fn)
52 28, 0 swapper hrtimer_stop_sched_tick (hrtimer_sched_tick)
53 22, 2948 IRQ 4 tty_flip_buffer_push (delayed_work_timer_fn)
54 3, 3100 bash schedule_timeout (process_timeout)
55 1, 1 swapper queue_delayed_work_on (delayed_work_timer_fn)
56 1, 1 swapper queue_delayed_work_on (delayed_work_timer_fn)
57 1, 1 swapper neigh_table_init_no_netlink (neigh_periodic_timer)
58 1, 2292 ip __netdev_watchdog_up (dev_watchdog)
59 1, 23 events/1 do_cache_clean (delayed_work_timer_fn)
6090 total events, 30.0 events/sec
61
62The first column is the number of events, the second column the pid, the third
63column is the name of the process. The forth column shows the function which
64initialized the timer and in parantheses the callback function which was
65executed on expiry.
66
67 Thomas, Ingo
68
diff --git a/Documentation/hrtimers/highres.txt b/Documentation/hrtimers/highres.txt
new file mode 100644
index 000000000000..ce0e9a91e157
--- /dev/null
+++ b/Documentation/hrtimers/highres.txt
@@ -0,0 +1,249 @@
1High resolution timers and dynamic ticks design notes
2-----------------------------------------------------
3
4Further information can be found in the paper of the OLS 2006 talk "hrtimers
5and beyond". The paper is part of the OLS 2006 Proceedings Volume 1, which can
6be found on the OLS website:
7http://www.linuxsymposium.org/2006/linuxsymposium_procv1.pdf
8
9The slides to this talk are available from:
10http://tglx.de/projects/hrtimers/ols2006-hrtimers.pdf
11
12The slides contain five figures (pages 2, 15, 18, 20, 22), which illustrate the
13changes in the time(r) related Linux subsystems. Figure #1 (p. 2) shows the
14design of the Linux time(r) system before hrtimers and other building blocks
15got merged into mainline.
16
17Note: the paper and the slides are talking about "clock event source", while we
18switched to the name "clock event devices" in meantime.
19
20The design contains the following basic building blocks:
21
22- hrtimer base infrastructure
23- timeofday and clock source management
24- clock event management
25- high resolution timer functionality
26- dynamic ticks
27
28
29hrtimer base infrastructure
30---------------------------
31
32The hrtimer base infrastructure was merged into the 2.6.16 kernel. Details of
33the base implementation are covered in Documentation/hrtimers/hrtimer.txt. See
34also figure #2 (OLS slides p. 15)
35
36The main differences to the timer wheel, which holds the armed timer_list type
37timers are:
38 - time ordered enqueueing into a rb-tree
39 - independent of ticks (the processing is based on nanoseconds)
40
41
42timeofday and clock source management
43-------------------------------------
44
45John Stultz's Generic Time Of Day (GTOD) framework moves a large portion of
46code out of the architecture-specific areas into a generic management
47framework, as illustrated in figure #3 (OLS slides p. 18). The architecture
48specific portion is reduced to the low level hardware details of the clock
49sources, which are registered in the framework and selected on a quality based
50decision. The low level code provides hardware setup and readout routines and
51initializes data structures, which are used by the generic time keeping code to
52convert the clock ticks to nanosecond based time values. All other time keeping
53related functionality is moved into the generic code. The GTOD base patch got
54merged into the 2.6.18 kernel.
55
56Further information about the Generic Time Of Day framework is available in the
57OLS 2005 Proceedings Volume 1:
58http://www.linuxsymposium.org/2005/linuxsymposium_procv1.pdf
59
60The paper "We Are Not Getting Any Younger: A New Approach to Time and
61Timers" was written by J. Stultz, D.V. Hart, & N. Aravamudan.
62
63Figure #3 (OLS slides p.18) illustrates the transformation.
64
65
66clock event management
67----------------------
68
69While clock sources provide read access to the monotonically increasing time
70value, clock event devices are used to schedule the next event
71interrupt(s). The next event is currently defined to be periodic, with its
72period defined at compile time. The setup and selection of the event device
73for various event driven functionalities is hardwired into the architecture
74dependent code. This results in duplicated code across all architectures and
75makes it extremely difficult to change the configuration of the system to use
76event interrupt devices other than those already built into the
77architecture. Another implication of the current design is that it is necessary
78to touch all the architecture-specific implementations in order to provide new
79functionality like high resolution timers or dynamic ticks.
80
81The clock events subsystem tries to address this problem by providing a generic
82solution to manage clock event devices and their usage for the various clock
83event driven kernel functionalities. The goal of the clock event subsystem is
84to minimize the clock event related architecture dependent code to the pure
85hardware related handling and to allow easy addition and utilization of new
86clock event devices. It also minimizes the duplicated code across the
87architectures as it provides generic functionality down to the interrupt
88service handler, which is almost inherently hardware dependent.
89
90Clock event devices are registered either by the architecture dependent boot
91code or at module insertion time. Each clock event device fills a data
92structure with clock-specific property parameters and callback functions. The
93clock event management decides, by using the specified property parameters, the
94set of system functions a clock event device will be used to support. This
95includes the distinction of per-CPU and per-system global event devices.
96
97System-level global event devices are used for the Linux periodic tick. Per-CPU
98event devices are used to provide local CPU functionality such as process
99accounting, profiling, and high resolution timers.
100
101The management layer assignes one or more of the folliwing functions to a clock
102event device:
103 - system global periodic tick (jiffies update)
104 - cpu local update_process_times
105 - cpu local profiling
106 - cpu local next event interrupt (non periodic mode)
107
108The clock event device delegates the selection of those timer interrupt related
109functions completely to the management layer. The clock management layer stores
110a function pointer in the device description structure, which has to be called
111from the hardware level handler. This removes a lot of duplicated code from the
112architecture specific timer interrupt handlers and hands the control over the
113clock event devices and the assignment of timer interrupt related functionality
114to the core code.
115
116The clock event layer API is rather small. Aside from the clock event device
117registration interface it provides functions to schedule the next event
118interrupt, clock event device notification service and support for suspend and
119resume.
120
121The framework adds about 700 lines of code which results in a 2KB increase of
122the kernel binary size. The conversion of i386 removes about 100 lines of
123code. The binary size decrease is in the range of 400 byte. We believe that the
124increase of flexibility and the avoidance of duplicated code across
125architectures justifies the slight increase of the binary size.
126
127The conversion of an architecture has no functional impact, but allows to
128utilize the high resolution and dynamic tick functionalites without any change
129to the clock event device and timer interrupt code. After the conversion the
130enabling of high resolution timers and dynamic ticks is simply provided by
131adding the kernel/time/Kconfig file to the architecture specific Kconfig and
132adding the dynamic tick specific calls to the idle routine (a total of 3 lines
133added to the idle function and the Kconfig file)
134
135Figure #4 (OLS slides p.20) illustrates the transformation.
136
137
138high resolution timer functionality
139-----------------------------------
140
141During system boot it is not possible to use the high resolution timer
142functionality, while making it possible would be difficult and would serve no
143useful function. The initialization of the clock event device framework, the
144clock source framework (GTOD) and hrtimers itself has to be done and
145appropriate clock sources and clock event devices have to be registered before
146the high resolution functionality can work. Up to the point where hrtimers are
147initialized, the system works in the usual low resolution periodic mode. The
148clock source and the clock event device layers provide notification functions
149which inform hrtimers about availability of new hardware. hrtimers validates
150the usability of the registered clock sources and clock event devices before
151switching to high resolution mode. This ensures also that a kernel which is
152configured for high resolution timers can run on a system which lacks the
153necessary hardware support.
154
155The high resolution timer code does not support SMP machines which have only
156global clock event devices. The support of such hardware would involve IPI
157calls when an interrupt happens. The overhead would be much larger than the
158benefit. This is the reason why we currently disable high resolution and
159dynamic ticks on i386 SMP systems which stop the local APIC in C3 power
160state. A workaround is available as an idea, but the problem has not been
161tackled yet.
162
163The time ordered insertion of timers provides all the infrastructure to decide
164whether the event device has to be reprogrammed when a timer is added. The
165decision is made per timer base and synchronized across per-cpu timer bases in
166a support function. The design allows the system to utilize separate per-CPU
167clock event devices for the per-CPU timer bases, but currently only one
168reprogrammable clock event device per-CPU is utilized.
169
170When the timer interrupt happens, the next event interrupt handler is called
171from the clock event distribution code and moves expired timers from the
172red-black tree to a separate double linked list and invokes the softirq
173handler. An additional mode field in the hrtimer structure allows the system to
174execute callback functions directly from the next event interrupt handler. This
175is restricted to code which can safely be executed in the hard interrupt
176context. This applies, for example, to the common case of a wakeup function as
177used by nanosleep. The advantage of executing the handler in the interrupt
178context is the avoidance of up to two context switches - from the interrupted
179context to the softirq and to the task which is woken up by the expired
180timer.
181
182Once a system has switched to high resolution mode, the periodic tick is
183switched off. This disables the per system global periodic clock event device -
184e.g. the PIT on i386 SMP systems.
185
186The periodic tick functionality is provided by an per-cpu hrtimer. The callback
187function is executed in the next event interrupt context and updates jiffies
188and calls update_process_times and profiling. The implementation of the hrtimer
189based periodic tick is designed to be extended with dynamic tick functionality.
190This allows to use a single clock event device to schedule high resolution
191timer and periodic events (jiffies tick, profiling, process accounting) on UP
192systems. This has been proved to work with the PIT on i386 and the Incrementer
193on PPC.
194
195The softirq for running the hrtimer queues and executing the callbacks has been
196separated from the tick bound timer softirq to allow accurate delivery of high
197resolution timer signals which are used by itimer and POSIX interval
198timers. The execution of this softirq can still be delayed by other softirqs,
199but the overall latencies have been significantly improved by this separation.
200
201Figure #5 (OLS slides p.22) illustrates the transformation.
202
203
204dynamic ticks
205-------------
206
207Dynamic ticks are the logical consequence of the hrtimer based periodic tick
208replacement (sched_tick). The functionality of the sched_tick hrtimer is
209extended by three functions:
210
211- hrtimer_stop_sched_tick
212- hrtimer_restart_sched_tick
213- hrtimer_update_jiffies
214
215hrtimer_stop_sched_tick() is called when a CPU goes into idle state. The code
216evaluates the next scheduled timer event (from both hrtimers and the timer
217wheel) and in case that the next event is further away than the next tick it
218reprograms the sched_tick to this future event, to allow longer idle sleeps
219without worthless interruption by the periodic tick. The function is also
220called when an interrupt happens during the idle period, which does not cause a
221reschedule. The call is necessary as the interrupt handler might have armed a
222new timer whose expiry time is before the time which was identified as the
223nearest event in the previous call to hrtimer_stop_sched_tick.
224
225hrtimer_restart_sched_tick() is called when the CPU leaves the idle state before
226it calls schedule(). hrtimer_restart_sched_tick() resumes the periodic tick,
227which is kept active until the next call to hrtimer_stop_sched_tick().
228
229hrtimer_update_jiffies() is called from irq_enter() when an interrupt happens
230in the idle period to make sure that jiffies are up to date and the interrupt
231handler has not to deal with an eventually stale jiffy value.
232
233The dynamic tick feature provides statistical values which are exported to
234userspace via /proc/stats and can be made available for enhanced power
235management control.
236
237The implementation leaves room for further development like full tickless
238systems, where the time slice is controlled by the scheduler, variable
239frequency profiling, and a complete removal of jiffies in the future.
240
241
242Aside the current initial submission of i386 support, the patchset has been
243extended to x86_64 and ARM already. Initial (work in progress) support is also
244available for MIPS and PowerPC.
245
246 Thomas, Ingo
247
248
249
diff --git a/Documentation/hrtimers.txt b/Documentation/hrtimers/hrtimers.txt
index ce31f65e12e7..ce31f65e12e7 100644
--- a/Documentation/hrtimers.txt
+++ b/Documentation/hrtimers/hrtimers.txt
diff --git a/Documentation/hwmon/it87 b/Documentation/hwmon/it87
index 74a80992d237..c0528d6f9ace 100644
--- a/Documentation/hwmon/it87
+++ b/Documentation/hwmon/it87
@@ -135,6 +135,16 @@ Give 0 for unused sensor. Any other value is invalid. To configure this at
135startup, consult lm_sensors's /etc/sensors.conf. (2 = thermistor; 135startup, consult lm_sensors's /etc/sensors.conf. (2 = thermistor;
1363 = thermal diode) 1363 = thermal diode)
137 137
138
139Fan speed control
140-----------------
141
138The fan speed control features are limited to manual PWM mode. Automatic 142The fan speed control features are limited to manual PWM mode. Automatic
139"Smart Guardian" mode control handling is not implemented. However 143"Smart Guardian" mode control handling is not implemented. However
140if you want to go for "manual mode" just write 1 to pwmN_enable. 144if you want to go for "manual mode" just write 1 to pwmN_enable.
145
146If you are only able to control the fan speed with very small PWM values,
147try lowering the PWM base frequency (pwm1_freq). Depending on the fan,
148it may give you a somewhat greater control range. The same frequency is
149used to drive all fan outputs, which is why pwm2_freq and pwm3_freq are
150read-only.
diff --git a/Documentation/hwmon/sysfs-interface b/Documentation/hwmon/sysfs-interface
index efef3b962cd3..d73d2e8c7534 100644
--- a/Documentation/hwmon/sysfs-interface
+++ b/Documentation/hwmon/sysfs-interface
@@ -166,16 +166,21 @@ pwm[1-*] Pulse width modulation fan control.
166 166
167pwm[1-*]_enable 167pwm[1-*]_enable
168 Switch PWM on and off. 168 Switch PWM on and off.
169 Not always present even if fan*_pwm is. 169 Not always present even if pwmN is.
170 0: turn off 170 0: turn off
171 1: turn on in manual mode 171 1: turn on in manual mode
172 2+: turn on in automatic mode 172 2+: turn on in automatic mode
173 Check individual chip documentation files for automatic mode details. 173 Check individual chip documentation files for automatic mode
174 details.
174 RW 175 RW
175 176
176pwm[1-*]_mode 177pwm[1-*]_mode 0: DC mode (direct current)
177 0: DC mode 178 1: PWM mode (pulse-width modulation)
178 1: PWM mode 179 RW
180
181pwm[1-*]_freq Base PWM frequency in Hz.
182 Only possibly available when pwmN_mode is PWM, but not always
183 present even then.
179 RW 184 RW
180 185
181pwm[1-*]_auto_channels_temp 186pwm[1-*]_auto_channels_temp
diff --git a/Documentation/hwmon/w83627ehf b/Documentation/hwmon/w83627ehf
index 8a15a7408753..030fac6cec7a 100644
--- a/Documentation/hwmon/w83627ehf
+++ b/Documentation/hwmon/w83627ehf
@@ -2,26 +2,29 @@ Kernel driver w83627ehf
2======================= 2=======================
3 3
4Supported chips: 4Supported chips:
5 * Winbond W83627EHF/EHG (ISA access ONLY) 5 * Winbond W83627EHF/EHG/DHG (ISA access ONLY)
6 Prefix: 'w83627ehf' 6 Prefix: 'w83627ehf'
7 Addresses scanned: ISA address retrieved from Super I/O registers 7 Addresses scanned: ISA address retrieved from Super I/O registers
8 Datasheet: http://www.winbond-usa.com/products/winbond_products/pdfs/PCIC/W83627EHF_%20W83627EHGb.pdf 8 Datasheet:
9 http://www.winbond-usa.com/products/winbond_products/pdfs/PCIC/W83627EHF_%20W83627EHGb.pdf
10 DHG datasheet confidential.
9 11
10Authors: 12Authors:
11 Jean Delvare <khali@linux-fr.org> 13 Jean Delvare <khali@linux-fr.org>
12 Yuan Mu (Winbond) 14 Yuan Mu (Winbond)
13 Rudolf Marek <r.marek@assembler.cz> 15 Rudolf Marek <r.marek@assembler.cz>
16 David Hubbard <david.c.hubbard@gmail.com>
14 17
15Description 18Description
16----------- 19-----------
17 20
18This driver implements support for the Winbond W83627EHF and W83627EHG 21This driver implements support for the Winbond W83627EHF, W83627EHG, and
19super I/O chips. We will refer to them collectively as Winbond chips. 22W83627DHG super I/O chips. We will refer to them collectively as Winbond chips.
20 23
21The chips implement three temperature sensors, five fan rotation 24The chips implement three temperature sensors, five fan rotation
22speed sensors, ten analog voltage sensors, alarms with beep warnings (control 25speed sensors, ten analog voltage sensors (only nine for the 627DHG), alarms
23unimplemented), and some automatic fan regulation strategies (plus manual 26with beep warnings (control unimplemented), and some automatic fan regulation
24fan control mode). 27strategies (plus manual fan control mode).
25 28
26Temperatures are measured in degrees Celsius and measurement resolution is 1 29Temperatures are measured in degrees Celsius and measurement resolution is 1
27degC for temp1 and 0.5 degC for temp2 and temp3. An alarm is triggered when 30degC for temp1 and 0.5 degC for temp2 and temp3. An alarm is triggered when
@@ -55,6 +58,9 @@ prog -> pwm4 (the programmable setting is not supported by the driver)
55/sys files 58/sys files
56---------- 59----------
57 60
61name - this is a standard hwmon device entry. For the W83627EHF and W83627EHG,
62 it is set to "w83627ehf" and for the W83627DHG it is set to "w83627dhg"
63
58pwm[1-4] - this file stores PWM duty cycle or DC value (fan speed) in range: 64pwm[1-4] - this file stores PWM duty cycle or DC value (fan speed) in range:
59 0 (stop) to 255 (full) 65 0 (stop) to 255 (full)
60 66
@@ -83,3 +89,37 @@ pwm[1-4]_stop_time - how many milliseconds [ms] must elapse to switch
83 89
84Note: last two functions are influenced by other control bits, not yet exported 90Note: last two functions are influenced by other control bits, not yet exported
85 by the driver, so a change might not have any effect. 91 by the driver, so a change might not have any effect.
92
93Implementation Details
94----------------------
95
96Future driver development should bear in mind that the following registers have
97different functions on the 627EHF and the 627DHG. Some registers also have
98different power-on default values, but BIOS should already be loading
99appropriate defaults. Note that bank selection must be performed as is currently
100done in the driver for all register addresses.
101
1020x49: only on DHG, selects temperature source for AUX fan, CPU fan0
1030x4a: not completely documented for the EHF and the DHG documentation assigns
104 different behavior to bits 7 and 6, including extending the temperature
105 input selection to SmartFan I, not just SmartFan III. Testing on the EHF
106 will reveal whether they are compatible or not.
107
1080x58: Chip ID: 0xa1=EHF 0xc1=DHG
1090x5e: only on DHG, has bits to enable "current mode" temperature detection and
110 critical temperature protection
1110x45b: only on EHF, bit 3, vin4 alarm (EHF supports 10 inputs, only 9 on DHG)
1120x552: only on EHF, vin4
1130x558: only on EHF, vin4 high limit
1140x559: only on EHF, vin4 low limit
1150x6b: only on DHG, SYS fan critical temperature
1160x6c: only on DHG, CPU fan0 critical temperature
1170x6d: only on DHG, AUX fan critical temperature
1180x6e: only on DHG, CPU fan1 critical temperature
119
1200x50-0x55 and 0x650-0x657 are marked "Test Register" for the EHF, but "Reserved
121 Register" for the DHG
122
123The DHG also supports PECI, where the DHG queries Intel CPU temperatures, and
124the ICH8 southbridge gets that data via PECI from the DHG, so that the
125southbridge drives the fans. And the DHG supports SST, a one-wire serial bus.
diff --git a/Documentation/i2c/busses/i2c-i801 b/Documentation/i2c/busses/i2c-i801
index 3db69a086c41..c34f0db78a30 100644
--- a/Documentation/i2c/busses/i2c-i801
+++ b/Documentation/i2c/busses/i2c-i801
@@ -48,14 +48,9 @@ following:
48The SMBus controller is function 3 in device 1f. Class 0c05 is SMBus Serial 48The SMBus controller is function 3 in device 1f. Class 0c05 is SMBus Serial
49Controller. 49Controller.
50 50
51If you do NOT see the 24x3 device at function 3, and you can't figure out
52any way in the BIOS to enable it,
53
54The ICH chips are quite similar to Intel's PIIX4 chip, at least in the 51The ICH chips are quite similar to Intel's PIIX4 chip, at least in the
55SMBus controller. 52SMBus controller.
56 53
57See the file i2c-piix4 for some additional information.
58
59 54
60Process Call Support 55Process Call Support
61-------------------- 56--------------------
@@ -74,6 +69,61 @@ SMBus 2.0 Support
74 69
75The 82801DB (ICH4) and later chips support several SMBus 2.0 features. 70The 82801DB (ICH4) and later chips support several SMBus 2.0 features.
76 71
72
73Hidden ICH SMBus
74----------------
75
76If your system has an Intel ICH south bridge, but you do NOT see the
77SMBus device at 00:1f.3 in lspci, and you can't figure out any way in the
78BIOS to enable it, it means it has been hidden by the BIOS code. Asus is
79well known for first doing this on their P4B motherboard, and many other
80boards after that. Some vendor machines are affected as well.
81
82The first thing to try is the "i2c_ec" ACPI driver. It could be that the
83SMBus was hidden on purpose because it'll be driven by ACPI. If the
84i2c_ec driver works for you, just forget about the i2c-i801 driver and
85don't try to unhide the ICH SMBus. Even if i2c_ec doesn't work, you
86better make sure that the SMBus isn't used by the ACPI code. Try loading
87the "fan" and "thermal" drivers, and check in /proc/acpi/fan and
88/proc/acpi/thermal_zone. If you find anything there, it's likely that
89the ACPI is accessing the SMBus and it's safer not to unhide it. Only
90once you are certain that ACPI isn't using the SMBus, you can attempt
91to unhide it.
92
93In order to unhide the SMBus, we need to change the value of a PCI
94register before the kernel enumerates the PCI devices. This is done in
95drivers/pci/quirks.c, where all affected boards must be listed (see
96function asus_hides_smbus_hostbridge.) If the SMBus device is missing,
97and you think there's something interesting on the SMBus (e.g. a
98hardware monitoring chip), you need to add your board to the list.
99
100The motherboard is identified using the subvendor and subdevice IDs of the
101host bridge PCI device. Get yours with "lspci -n -v -s 00:00.0":
102
10300:00.0 Class 0600: 8086:2570 (rev 02)
104 Subsystem: 1043:80f2
105 Flags: bus master, fast devsel, latency 0
106 Memory at fc000000 (32-bit, prefetchable) [size=32M]
107 Capabilities: [e4] #09 [2106]
108 Capabilities: [a0] AGP version 3.0
109
110Here the host bridge ID is 2570 (82865G/PE/P), the subvendor ID is 1043
111(Asus) and the subdevice ID is 80f2 (P4P800-X). You can find the symbolic
112names for the bridge ID and the subvendor ID in include/linux/pci_ids.h,
113and then add a case for your subdevice ID at the right place in
114drivers/pci/quirks.c. Then please give it very good testing, to make sure
115that the unhidden SMBus doesn't conflict with e.g. ACPI.
116
117If it works, proves useful (i.e. there are usable chips on the SMBus)
118and seems safe, please submit a patch for inclusion into the kernel.
119
120Note: There's a useful script in lm_sensors 2.10.2 and later, named
121unhide_ICH_SMBus (in prog/hotplug), which uses the fakephp driver to
122temporarily unhide the SMBus without having to patch and recompile your
123kernel. It's very convenient if you just want to check if there's
124anything interesting on your hidden ICH SMBus.
125
126
77********************** 127**********************
78The lm_sensors project gratefully acknowledges the support of Texas 128The lm_sensors project gratefully acknowledges the support of Texas
79Instruments in the initial development of this driver. 129Instruments in the initial development of this driver.
diff --git a/Documentation/i2c/busses/i2c-parport b/Documentation/i2c/busses/i2c-parport
index 77b995dfca22..dceaba1ad930 100644
--- a/Documentation/i2c/busses/i2c-parport
+++ b/Documentation/i2c/busses/i2c-parport
@@ -19,6 +19,7 @@ It currently supports the following devices:
19 * (type=4) Analog Devices ADM1032 evaluation board 19 * (type=4) Analog Devices ADM1032 evaluation board
20 * (type=5) Analog Devices evaluation boards: ADM1025, ADM1030, ADM1031 20 * (type=5) Analog Devices evaluation boards: ADM1025, ADM1030, ADM1031
21 * (type=6) Barco LPT->DVI (K5800236) adapter 21 * (type=6) Barco LPT->DVI (K5800236) adapter
22 * (type=7) One For All JP1 parallel port adapter
22 23
23These devices use different pinout configurations, so you have to tell 24These devices use different pinout configurations, so you have to tell
24the driver what you have, using the type module parameter. There is no 25the driver what you have, using the type module parameter. There is no
@@ -157,3 +158,17 @@ many more, using /dev/velleman.
157 http://home.wanadoo.nl/hihihi/libk8005.htm 158 http://home.wanadoo.nl/hihihi/libk8005.htm
158 http://struyve.mine.nu:8080/index.php?block=k8000 159 http://struyve.mine.nu:8080/index.php?block=k8000
159 http://sourceforge.net/projects/libk8005/ 160 http://sourceforge.net/projects/libk8005/
161
162
163One For All JP1 parallel port adapter
164-------------------------------------
165
166The JP1 project revolves around a set of remote controls which expose
167the I2C bus their internal configuration EEPROM lives on via a 6 pin
168jumper in the battery compartment. More details can be found at:
169
170http://www.hifi-remote.com/jp1/
171
172Details of the simple parallel port hardware can be found at:
173
174http://www.hifi-remote.com/jp1/hardware.shtml
diff --git a/Documentation/i2c/busses/i2c-piix4 b/Documentation/i2c/busses/i2c-piix4
index 921476333235..7cbe43fa2701 100644
--- a/Documentation/i2c/busses/i2c-piix4
+++ b/Documentation/i2c/busses/i2c-piix4
@@ -6,7 +6,7 @@ Supported adapters:
6 Datasheet: Publicly available at the Intel website 6 Datasheet: Publicly available at the Intel website
7 * ServerWorks OSB4, CSB5, CSB6 and HT-1000 southbridges 7 * ServerWorks OSB4, CSB5, CSB6 and HT-1000 southbridges
8 Datasheet: Only available via NDA from ServerWorks 8 Datasheet: Only available via NDA from ServerWorks
9 * ATI IXP southbridges IXP200, IXP300, IXP400 9 * ATI IXP200, IXP300, IXP400 and SB600 southbridges
10 Datasheet: Not publicly available 10 Datasheet: Not publicly available
11 * Standard Microsystems (SMSC) SLC90E66 (Victory66) southbridge 11 * Standard Microsystems (SMSC) SLC90E66 (Victory66) southbridge
12 Datasheet: Publicly available at the SMSC website http://www.smsc.com 12 Datasheet: Publicly available at the SMSC website http://www.smsc.com
diff --git a/Documentation/i2c/busses/i2c-viapro b/Documentation/i2c/busses/i2c-viapro
index 25680346e0ac..775f489e86f6 100644
--- a/Documentation/i2c/busses/i2c-viapro
+++ b/Documentation/i2c/busses/i2c-viapro
@@ -13,6 +13,9 @@ Supported adapters:
13 * VIA Technologies, Inc. VT8235, VT8237R, VT8237A, VT8251 13 * VIA Technologies, Inc. VT8235, VT8237R, VT8237A, VT8251
14 Datasheet: available on request and under NDA from VIA 14 Datasheet: available on request and under NDA from VIA
15 15
16 * VIA Technologies, Inc. CX700
17 Datasheet: available on request and under NDA from VIA
18
16Authors: 19Authors:
17 Kyösti Mälkki <kmalkki@cc.hut.fi>, 20 Kyösti Mälkki <kmalkki@cc.hut.fi>,
18 Mark D. Studebaker <mdsxyz123@yahoo.com>, 21 Mark D. Studebaker <mdsxyz123@yahoo.com>,
@@ -44,6 +47,7 @@ Your lspci -n listing must show one of these :
44 device 1106:3227 (VT8237R) 47 device 1106:3227 (VT8237R)
45 device 1106:3337 (VT8237A) 48 device 1106:3337 (VT8237A)
46 device 1106:3287 (VT8251) 49 device 1106:3287 (VT8251)
50 device 1106:8324 (CX700)
47 51
48If none of these show up, you should look in the BIOS for settings like 52If none of these show up, you should look in the BIOS for settings like
49enable ACPI / SMBus or even USB. 53enable ACPI / SMBus or even USB.
@@ -51,3 +55,6 @@ enable ACPI / SMBus or even USB.
51Except for the oldest chips (VT82C596A/B, VT82C686A and most probably 55Except for the oldest chips (VT82C596A/B, VT82C686A and most probably
52VT8231), this driver supports I2C block transactions. Such transactions 56VT8231), this driver supports I2C block transactions. Such transactions
53are mainly useful to read from and write to EEPROMs. 57are mainly useful to read from and write to EEPROMs.
58
59The CX700 additionally appears to support SMBus PEC, although this driver
60doesn't implement it yet.
diff --git a/Documentation/i2c/porting-clients b/Documentation/i2c/porting-clients
index f03c2a02f806..ca272b263a92 100644
--- a/Documentation/i2c/porting-clients
+++ b/Documentation/i2c/porting-clients
@@ -129,6 +129,12 @@ Technical changes:
129 structure, those name member should be initialized to a driver name 129 structure, those name member should be initialized to a driver name
130 string. i2c_driver itself has no name member anymore. 130 string. i2c_driver itself has no name member anymore.
131 131
132* [Driver model] Instead of shutdown or reboot notifiers, provide a
133 shutdown() method in your driver.
134
135* [Power management] Use the driver model suspend() and resume()
136 callbacks instead of the obsolete pm_register() calls.
137
132Coding policy: 138Coding policy:
133 139
134* [Copyright] Use (C), not (c), for copyright. 140* [Copyright] Use (C), not (c), for copyright.
diff --git a/Documentation/i2c/smbus-protocol b/Documentation/i2c/smbus-protocol
index 09f5e5ca4927..8a653c60d25a 100644
--- a/Documentation/i2c/smbus-protocol
+++ b/Documentation/i2c/smbus-protocol
@@ -97,7 +97,7 @@ SMBus Write Word Data
97===================== 97=====================
98 98
99This is the opposite operation of the Read Word Data command. 16 bits 99This is the opposite operation of the Read Word Data command. 16 bits
100of data is read from a device, from a designated register that is 100of data is written to a device, to the designated register that is
101specified through the Comm byte. 101specified through the Comm byte.
102 102
103S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P 103S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P
diff --git a/Documentation/i2c/writing-clients b/Documentation/i2c/writing-clients
index 3a057c8e5507..fbcff96f4ca1 100644
--- a/Documentation/i2c/writing-clients
+++ b/Documentation/i2c/writing-clients
@@ -21,20 +21,26 @@ The driver structure
21 21
22Usually, you will implement a single driver structure, and instantiate 22Usually, you will implement a single driver structure, and instantiate
23all clients from it. Remember, a driver structure contains general access 23all clients from it. Remember, a driver structure contains general access
24routines, a client structure specific information like the actual I2C 24routines, and should be zero-initialized except for fields with data you
25address. 25provide. A client structure holds device-specific information like the
26driver model device node, and its I2C address.
26 27
27static struct i2c_driver foo_driver = { 28static struct i2c_driver foo_driver = {
28 .driver = { 29 .driver = {
29 .name = "foo", 30 .name = "foo",
30 }, 31 },
31 .attach_adapter = &foo_attach_adapter, 32 .attach_adapter = foo_attach_adapter,
32 .detach_client = &foo_detach_client, 33 .detach_client = foo_detach_client,
33 .command = &foo_command /* may be NULL */ 34 .shutdown = foo_shutdown, /* optional */
35 .suspend = foo_suspend, /* optional */
36 .resume = foo_resume, /* optional */
37 .command = foo_command, /* optional */
34} 38}
35 39
36The name field must match the driver name, including the case. It must not 40The name field is the driver name, and must not contain spaces. It
37contain spaces, and may be up to 31 characters long. 41should match the module name (if the driver can be compiled as a module),
42although you can use MODULE_ALIAS (passing "foo" in this example) to add
43another name for the module.
38 44
39All other fields are for call-back functions which will be explained 45All other fields are for call-back functions which will be explained
40below. 46below.
@@ -43,11 +49,18 @@ below.
43Extra client data 49Extra client data
44================= 50=================
45 51
46The client structure has a special `data' field that can point to any 52Each client structure has a special `data' field that can point to any
47structure at all. You can use this to keep client-specific data. You 53structure at all. You should use this to keep device-specific data,
54especially in drivers that handle multiple I2C or SMBUS devices. You
48do not always need this, but especially for `sensors' drivers, it can 55do not always need this, but especially for `sensors' drivers, it can
49be very useful. 56be very useful.
50 57
58 /* store the value */
59 void i2c_set_clientdata(struct i2c_client *client, void *data);
60
61 /* retrieve the value */
62 void *i2c_get_clientdata(struct i2c_client *client);
63
51An example structure is below. 64An example structure is below.
52 65
53 struct foo_data { 66 struct foo_data {
@@ -493,6 +506,33 @@ by `__init_data'. Hose functions and structures can be removed after
493kernel booting (or module loading) is completed. 506kernel booting (or module loading) is completed.
494 507
495 508
509Power Management
510================
511
512If your I2C device needs special handling when entering a system low
513power state -- like putting a transceiver into a low power mode, or
514activating a system wakeup mechanism -- do that in the suspend() method.
515The resume() method should reverse what the suspend() method does.
516
517These are standard driver model calls, and they work just like they
518would for any other driver stack. The calls can sleep, and can use
519I2C messaging to the device being suspended or resumed (since their
520parent I2C adapter is active when these calls are issued, and IRQs
521are still enabled).
522
523
524System Shutdown
525===============
526
527If your I2C device needs special handling when the system shuts down
528or reboots (including kexec) -- like turning something off -- use a
529shutdown() method.
530
531Again, this is a standard driver model call, working just like it
532would for any other driver stack: the calls can sleep, and can use
533I2C messaging.
534
535
496Command function 536Command function
497================ 537================
498 538
diff --git a/Documentation/ia64/err_inject.txt b/Documentation/ia64/err_inject.txt
new file mode 100644
index 000000000000..6449a7090dbb
--- /dev/null
+++ b/Documentation/ia64/err_inject.txt
@@ -0,0 +1,1068 @@
1
2IPF Machine Check (MC) error inject tool
3========================================
4
5IPF Machine Check (MC) error inject tool is used to inject MC
6errors from Linux. The tool is a test bed for IPF MC work flow including
7hardware correctable error handling, OS recoverable error handling, MC
8event logging, etc.
9
10The tool includes two parts: a kernel driver and a user application
11sample. The driver provides interface to PAL to inject error
12and query error injection capabilities. The driver code is in
13arch/ia64/kernel/err_inject.c. The application sample (shown below)
14provides a combination of various errors and calls the driver's interface
15(sysfs interface) to inject errors or query error injection capabilities.
16
17The tool can be used to test Intel IPF machine MC handling capabilities.
18It's especially useful for people who can not access hardware MC injection
19tool to inject error. It's also very useful to integrate with other
20software test suits to do stressful testing on IPF.
21
22Below is a sample application as part of the whole tool. The sample
23can be used as a working test tool. Or it can be expanded to include
24more features. It also can be a integrated into a libary or other user
25application to have more thorough test.
26
27The sample application takes err.conf as error configuation input. Gcc
28compiles the code. After you install err_inject driver, you can run
29this sample application to inject errors.
30
31Errata: Itanium 2 Processors Specification Update lists some errata against
32the pal_mc_error_inject PAL procedure. The following err.conf has been tested
33on latest Montecito PAL.
34
35err.conf:
36
37#This is configuration file for err_inject_tool.
38#The format of the each line is:
39#cpu, loop, interval, err_type_info, err_struct_info, err_data_buffer
40#where
41# cpu: logical cpu number the error will be inject in.
42# loop: times the error will be injected.
43# interval: In second. every so often one error is injected.
44# err_type_info, err_struct_info: PAL parameters.
45#
46#Note: All values are hex w/o or w/ 0x prefix.
47
48
49#On cpu2, inject only total 0x10 errors, interval 5 seconds
50#corrected, data cache, hier-2, physical addr(assigned by tool code).
51#working on Montecito latest PAL.
522, 10, 5, 4101, 95
53
54#On cpu4, inject and consume total 0x10 errors, interval 5 seconds
55#corrected, data cache, hier-2, physical addr(assigned by tool code).
56#working on Montecito latest PAL.
574, 10, 5, 4109, 95
58
59#On cpu15, inject and consume total 0x10 errors, interval 5 seconds
60#recoverable, DTR0, hier-2.
61#working on Montecito latest PAL.
620xf, 0x10, 5, 4249, 15
63
64The sample application source code:
65
66err_injection_tool.c:
67
68/*
69 * This program is free software; you can redistribute it and/or modify
70 * it under the terms of the GNU General Public License as published by
71 * the Free Software Foundation; either version 2 of the License, or
72 * (at your option) any later version.
73 *
74 * This program is distributed in the hope that it will be useful, but
75 * WITHOUT ANY WARRANTY; without even the implied warranty of
76 * MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, GOOD TITLE or
77 * NON INFRINGEMENT. See the GNU General Public License for more
78 * details.
79 *
80 * You should have received a copy of the GNU General Public License
81 * along with this program; if not, write to the Free Software
82 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
83 *
84 * Copyright (C) 2006 Intel Co
85 * Fenghua Yu <fenghua.yu@intel.com>
86 *
87 */
88#include <sys/types.h>
89#include <sys/stat.h>
90#include <fcntl.h>
91#include <stdio.h>
92#include <sched.h>
93#include <unistd.h>
94#include <stdlib.h>
95#include <stdarg.h>
96#include <string.h>
97#include <errno.h>
98#include <time.h>
99#include <sys/ipc.h>
100#include <sys/sem.h>
101#include <sys/wait.h>
102#include <sys/mman.h>
103#include <sys/shm.h>
104
105#define MAX_FN_SIZE 256
106#define MAX_BUF_SIZE 256
107#define DATA_BUF_SIZE 256
108#define NR_CPUS 512
109#define MAX_TASK_NUM 2048
110#define MIN_INTERVAL 5 // seconds
111#define ERR_DATA_BUFFER_SIZE 3 // Three 8-byte.
112#define PARA_FIELD_NUM 5
113#define MASK_SIZE (NR_CPUS/64)
114#define PATH_FORMAT "/sys/devices/system/cpu/cpu%d/err_inject/"
115
116int sched_setaffinity(pid_t pid, unsigned int len, unsigned long *mask);
117
118int verbose;
119#define vbprintf if (verbose) printf
120
121int log_info(int cpu, const char *fmt, ...)
122{
123 FILE *log;
124 char fn[MAX_FN_SIZE];
125 char buf[MAX_BUF_SIZE];
126 va_list args;
127
128 sprintf(fn, "%d.log", cpu);
129 log=fopen(fn, "a+");
130 if (log==NULL) {
131 perror("Error open:");
132 return -1;
133 }
134
135 va_start(args, fmt);
136 vprintf(fmt, args);
137 memset(buf, 0, MAX_BUF_SIZE);
138 vsprintf(buf, fmt, args);
139 va_end(args);
140
141 fwrite(buf, sizeof(buf), 1, log);
142 fclose(log);
143
144 return 0;
145}
146
147typedef unsigned long u64;
148typedef unsigned int u32;
149
150typedef union err_type_info_u {
151 struct {
152 u64 mode : 3, /* 0-2 */
153 err_inj : 3, /* 3-5 */
154 err_sev : 2, /* 6-7 */
155 err_struct : 5, /* 8-12 */
156 struct_hier : 3, /* 13-15 */
157 reserved : 48; /* 16-63 */
158 } err_type_info_u;
159 u64 err_type_info;
160} err_type_info_t;
161
162typedef union err_struct_info_u {
163 struct {
164 u64 siv : 1, /* 0 */
165 c_t : 2, /* 1-2 */
166 cl_p : 3, /* 3-5 */
167 cl_id : 3, /* 6-8 */
168 cl_dp : 1, /* 9 */
169 reserved1 : 22, /* 10-31 */
170 tiv : 1, /* 32 */
171 trigger : 4, /* 33-36 */
172 trigger_pl : 3, /* 37-39 */
173 reserved2 : 24; /* 40-63 */
174 } err_struct_info_cache;
175 struct {
176 u64 siv : 1, /* 0 */
177 tt : 2, /* 1-2 */
178 tc_tr : 2, /* 3-4 */
179 tr_slot : 8, /* 5-12 */
180 reserved1 : 19, /* 13-31 */
181 tiv : 1, /* 32 */
182 trigger : 4, /* 33-36 */
183 trigger_pl : 3, /* 37-39 */
184 reserved2 : 24; /* 40-63 */
185 } err_struct_info_tlb;
186 struct {
187 u64 siv : 1, /* 0 */
188 regfile_id : 4, /* 1-4 */
189 reg_num : 7, /* 5-11 */
190 reserved1 : 20, /* 12-31 */
191 tiv : 1, /* 32 */
192 trigger : 4, /* 33-36 */
193 trigger_pl : 3, /* 37-39 */
194 reserved2 : 24; /* 40-63 */
195 } err_struct_info_register;
196 struct {
197 u64 reserved;
198 } err_struct_info_bus_processor_interconnect;
199 u64 err_struct_info;
200} err_struct_info_t;
201
202typedef union err_data_buffer_u {
203 struct {
204 u64 trigger_addr; /* 0-63 */
205 u64 inj_addr; /* 64-127 */
206 u64 way : 5, /* 128-132 */
207 index : 20, /* 133-152 */
208 : 39; /* 153-191 */
209 } err_data_buffer_cache;
210 struct {
211 u64 trigger_addr; /* 0-63 */
212 u64 inj_addr; /* 64-127 */
213 u64 way : 5, /* 128-132 */
214 index : 20, /* 133-152 */
215 reserved : 39; /* 153-191 */
216 } err_data_buffer_tlb;
217 struct {
218 u64 trigger_addr; /* 0-63 */
219 } err_data_buffer_register;
220 struct {
221 u64 reserved; /* 0-63 */
222 } err_data_buffer_bus_processor_interconnect;
223 u64 err_data_buffer[ERR_DATA_BUFFER_SIZE];
224} err_data_buffer_t;
225
226typedef union capabilities_u {
227 struct {
228 u64 i : 1,
229 d : 1,
230 rv : 1,
231 tag : 1,
232 data : 1,
233 mesi : 1,
234 dp : 1,
235 reserved1 : 3,
236 pa : 1,
237 va : 1,
238 wi : 1,
239 reserved2 : 20,
240 trigger : 1,
241 trigger_pl : 1,
242 reserved3 : 30;
243 } capabilities_cache;
244 struct {
245 u64 d : 1,
246 i : 1,
247 rv : 1,
248 tc : 1,
249 tr : 1,
250 reserved1 : 27,
251 trigger : 1,
252 trigger_pl : 1,
253 reserved2 : 30;
254 } capabilities_tlb;
255 struct {
256 u64 gr_b0 : 1,
257 gr_b1 : 1,
258 fr : 1,
259 br : 1,
260 pr : 1,
261 ar : 1,
262 cr : 1,
263 rr : 1,
264 pkr : 1,
265 dbr : 1,
266 ibr : 1,
267 pmc : 1,
268 pmd : 1,
269 reserved1 : 3,
270 regnum : 1,
271 reserved2 : 15,
272 trigger : 1,
273 trigger_pl : 1,
274 reserved3 : 30;
275 } capabilities_register;
276 struct {
277 u64 reserved;
278 } capabilities_bus_processor_interconnect;
279} capabilities_t;
280
281typedef struct resources_s {
282 u64 ibr0 : 1,
283 ibr2 : 1,
284 ibr4 : 1,
285 ibr6 : 1,
286 dbr0 : 1,
287 dbr2 : 1,
288 dbr4 : 1,
289 dbr6 : 1,
290 reserved : 48;
291} resources_t;
292
293
294long get_page_size(void)
295{
296 long page_size=sysconf(_SC_PAGESIZE);
297 return page_size;
298}
299
300#define PAGE_SIZE (get_page_size()==-1?0x4000:get_page_size())
301#define SHM_SIZE (2*PAGE_SIZE*NR_CPUS)
302#define SHM_VA 0x2000000100000000
303
304int shmid;
305void *shmaddr;
306
307int create_shm(void)
308{
309 key_t key;
310 char fn[MAX_FN_SIZE];
311
312 /* cpu0 is always existing */
313 sprintf(fn, PATH_FORMAT, 0);
314 if ((key = ftok(fn, 's')) == -1) {
315 perror("ftok");
316 return -1;
317 }
318
319 shmid = shmget(key, SHM_SIZE, 0644 | IPC_CREAT);
320 if (shmid == -1) {
321 if (errno==EEXIST) {
322 shmid = shmget(key, SHM_SIZE, 0);
323 if (shmid == -1) {
324 perror("shmget");
325 return -1;
326 }
327 }
328 else {
329 perror("shmget");
330 return -1;
331 }
332 }
333 vbprintf("shmid=%d", shmid);
334
335 /* connect to the segment: */
336 shmaddr = shmat(shmid, (void *)SHM_VA, 0);
337 if (shmaddr == (void*)-1) {
338 perror("shmat");
339 return -1;
340 }
341
342 memset(shmaddr, 0, SHM_SIZE);
343 mlock(shmaddr, SHM_SIZE);
344
345 return 0;
346}
347
348int free_shm()
349{
350 munlock(shmaddr, SHM_SIZE);
351 shmdt(shmaddr);
352 semctl(shmid, 0, IPC_RMID);
353
354 return 0;
355}
356
357#ifdef _SEM_SEMUN_UNDEFINED
358union semun
359{
360 int val;
361 struct semid_ds *buf;
362 unsigned short int *array;
363 struct seminfo *__buf;
364};
365#endif
366
367u32 mode=1; /* 1: physical mode; 2: virtual mode. */
368int one_lock=1;
369key_t key[NR_CPUS];
370int semid[NR_CPUS];
371
372int create_sem(int cpu)
373{
374 union semun arg;
375 char fn[MAX_FN_SIZE];
376 int sid;
377
378 sprintf(fn, PATH_FORMAT, cpu);
379 sprintf(fn, "%s/%s", fn, "err_type_info");
380 if ((key[cpu] = ftok(fn, 'e')) == -1) {
381 perror("ftok");
382 return -1;
383 }
384
385 if (semid[cpu]!=0)
386 return 0;
387
388 /* clear old semaphore */
389 if ((sid = semget(key[cpu], 1, 0)) != -1)
390 semctl(sid, 0, IPC_RMID);
391
392 /* get one semaphore */
393 if ((semid[cpu] = semget(key[cpu], 1, IPC_CREAT | IPC_EXCL)) == -1) {
394 perror("semget");
395 printf("Please remove semaphore with key=0x%lx, then run the tool.\n",
396 (u64)key[cpu]);
397 return -1;
398 }
399
400 vbprintf("semid[%d]=0x%lx, key[%d]=%lx\n",cpu,(u64)semid[cpu],cpu,
401 (u64)key[cpu]);
402 /* initialize the semaphore to 1: */
403 arg.val = 1;
404 if (semctl(semid[cpu], 0, SETVAL, arg) == -1) {
405 perror("semctl");
406 return -1;
407 }
408
409 return 0;
410}
411
412static int lock(int cpu)
413{
414 struct sembuf lock;
415
416 lock.sem_num = cpu;
417 lock.sem_op = 1;
418 semop(semid[cpu], &lock, 1);
419
420 return 0;
421}
422
423static int unlock(int cpu)
424{
425 struct sembuf unlock;
426
427 unlock.sem_num = cpu;
428 unlock.sem_op = -1;
429 semop(semid[cpu], &unlock, 1);
430
431 return 0;
432}
433
434void free_sem(int cpu)
435{
436 semctl(semid[cpu], 0, IPC_RMID);
437}
438
439int wr_multi(char *fn, unsigned long *data, int size)
440{
441 int fd;
442 char buf[MAX_BUF_SIZE];
443 int ret;
444
445 if (size==1)
446 sprintf(buf, "%lx", *data);
447 else if (size==3)
448 sprintf(buf, "%lx,%lx,%lx", data[0], data[1], data[2]);
449 else {
450 fprintf(stderr,"write to file with wrong size!\n");
451 return -1;
452 }
453
454 fd=open(fn, O_RDWR);
455 if (!fd) {
456 perror("Error:");
457 return -1;
458 }
459 ret=write(fd, buf, sizeof(buf));
460 close(fd);
461 return ret;
462}
463
464int wr(char *fn, unsigned long data)
465{
466 return wr_multi(fn, &data, 1);
467}
468
469int rd(char *fn, unsigned long *data)
470{
471 int fd;
472 char buf[MAX_BUF_SIZE];
473
474 fd=open(fn, O_RDONLY);
475 if (fd<0) {
476 perror("Error:");
477 return -1;
478 }
479 read(fd, buf, MAX_BUF_SIZE);
480 *data=strtoul(buf, NULL, 16);
481 close(fd);
482 return 0;
483}
484
485int rd_status(char *path, int *status)
486{
487 char fn[MAX_FN_SIZE];
488 sprintf(fn, "%s/status", path);
489 if (rd(fn, (u64*)status)<0) {
490 perror("status reading error.\n");
491 return -1;
492 }
493
494 return 0;
495}
496
497int rd_capabilities(char *path, u64 *capabilities)
498{
499 char fn[MAX_FN_SIZE];
500 sprintf(fn, "%s/capabilities", path);
501 if (rd(fn, capabilities)<0) {
502 perror("capabilities reading error.\n");
503 return -1;
504 }
505
506 return 0;
507}
508
509int rd_all(char *path)
510{
511 unsigned long err_type_info, err_struct_info, err_data_buffer;
512 int status;
513 unsigned long capabilities, resources;
514 char fn[MAX_FN_SIZE];
515
516 sprintf(fn, "%s/err_type_info", path);
517 if (rd(fn, &err_type_info)<0) {
518 perror("err_type_info reading error.\n");
519 return -1;
520 }
521 printf("err_type_info=%lx\n", err_type_info);
522
523 sprintf(fn, "%s/err_struct_info", path);
524 if (rd(fn, &err_struct_info)<0) {
525 perror("err_struct_info reading error.\n");
526 return -1;
527 }
528 printf("err_struct_info=%lx\n", err_struct_info);
529
530 sprintf(fn, "%s/err_data_buffer", path);
531 if (rd(fn, &err_data_buffer)<0) {
532 perror("err_data_buffer reading error.\n");
533 return -1;
534 }
535 printf("err_data_buffer=%lx\n", err_data_buffer);
536
537 sprintf(fn, "%s/status", path);
538 if (rd("status", (u64*)&status)<0) {
539 perror("status reading error.\n");
540 return -1;
541 }
542 printf("status=%d\n", status);
543
544 sprintf(fn, "%s/capabilities", path);
545 if (rd(fn,&capabilities)<0) {
546 perror("capabilities reading error.\n");
547 return -1;
548 }
549 printf("capabilities=%lx\n", capabilities);
550
551 sprintf(fn, "%s/resources", path);
552 if (rd(fn, &resources)<0) {
553 perror("resources reading error.\n");
554 return -1;
555 }
556 printf("resources=%lx\n", resources);
557
558 return 0;
559}
560
561int query_capabilities(char *path, err_type_info_t err_type_info,
562 u64 *capabilities)
563{
564 char fn[MAX_FN_SIZE];
565 err_struct_info_t err_struct_info;
566 err_data_buffer_t err_data_buffer;
567
568 err_struct_info.err_struct_info=0;
569 memset(err_data_buffer.err_data_buffer, -1, ERR_DATA_BUFFER_SIZE*8);
570
571 sprintf(fn, "%s/err_type_info", path);
572 wr(fn, err_type_info.err_type_info);
573 sprintf(fn, "%s/err_struct_info", path);
574 wr(fn, 0x0);
575 sprintf(fn, "%s/err_data_buffer", path);
576 wr_multi(fn, err_data_buffer.err_data_buffer, ERR_DATA_BUFFER_SIZE);
577
578 // Fire pal_mc_error_inject procedure.
579 sprintf(fn, "%s/call_start", path);
580 wr(fn, mode);
581
582 if (rd_capabilities(path, capabilities)<0)
583 return -1;
584
585 return 0;
586}
587
588int query_all_capabilities()
589{
590 int status;
591 err_type_info_t err_type_info;
592 int err_sev, err_struct, struct_hier;
593 int cap=0;
594 u64 capabilities;
595 char path[MAX_FN_SIZE];
596
597 err_type_info.err_type_info=0; // Initial
598 err_type_info.err_type_info_u.mode=0; // Query mode;
599 err_type_info.err_type_info_u.err_inj=0;
600
601 printf("All capabilities implemented in pal_mc_error_inject:\n");
602 sprintf(path, PATH_FORMAT ,0);
603 for (err_sev=0;err_sev<3;err_sev++)
604 for (err_struct=0;err_struct<5;err_struct++)
605 for (struct_hier=0;struct_hier<5;struct_hier++)
606 {
607 status=-1;
608 capabilities=0;
609 err_type_info.err_type_info_u.err_sev=err_sev;
610 err_type_info.err_type_info_u.err_struct=err_struct;
611 err_type_info.err_type_info_u.struct_hier=struct_hier;
612
613 if (query_capabilities(path, err_type_info, &capabilities)<0)
614 continue;
615
616 if (rd_status(path, &status)<0)
617 continue;
618
619 if (status==0) {
620 cap=1;
621 printf("For err_sev=%d, err_struct=%d, struct_hier=%d: ",
622 err_sev, err_struct, struct_hier);
623 printf("capabilities 0x%lx\n", capabilities);
624 }
625 }
626 if (!cap) {
627 printf("No capabilities supported.\n");
628 return 0;
629 }
630
631 return 0;
632}
633
634int err_inject(int cpu, char *path, err_type_info_t err_type_info,
635 err_struct_info_t err_struct_info,
636 err_data_buffer_t err_data_buffer)
637{
638 int status;
639 char fn[MAX_FN_SIZE];
640
641 log_info(cpu, "err_type_info=%lx, err_struct_info=%lx, ",
642 err_type_info.err_type_info,
643 err_struct_info.err_struct_info);
644 log_info(cpu,"err_data_buffer=[%lx,%lx,%lx]\n",
645 err_data_buffer.err_data_buffer[0],
646 err_data_buffer.err_data_buffer[1],
647 err_data_buffer.err_data_buffer[2]);
648 sprintf(fn, "%s/err_type_info", path);
649 wr(fn, err_type_info.err_type_info);
650 sprintf(fn, "%s/err_struct_info", path);
651 wr(fn, err_struct_info.err_struct_info);
652 sprintf(fn, "%s/err_data_buffer", path);
653 wr_multi(fn, err_data_buffer.err_data_buffer, ERR_DATA_BUFFER_SIZE);
654
655 // Fire pal_mc_error_inject procedure.
656 sprintf(fn, "%s/call_start", path);
657 wr(fn,mode);
658
659 if (rd_status(path, &status)<0) {
660 vbprintf("fail: read status\n");
661 return -100;
662 }
663
664 if (status!=0) {
665 log_info(cpu, "fail: status=%d\n", status);
666 return status;
667 }
668
669 return status;
670}
671
672static int construct_data_buf(char *path, err_type_info_t err_type_info,
673 err_struct_info_t err_struct_info,
674 err_data_buffer_t *err_data_buffer,
675 void *va1)
676{
677 char fn[MAX_FN_SIZE];
678 u64 virt_addr=0, phys_addr=0;
679
680 vbprintf("va1=%lx\n", (u64)va1);
681 memset(&err_data_buffer->err_data_buffer_cache, 0, ERR_DATA_BUFFER_SIZE*8);
682
683 switch (err_type_info.err_type_info_u.err_struct) {
684 case 1: // Cache
685 switch (err_struct_info.err_struct_info_cache.cl_id) {
686 case 1: //Virtual addr
687 err_data_buffer->err_data_buffer_cache.inj_addr=(u64)va1;
688 break;
689 case 2: //Phys addr
690 sprintf(fn, "%s/virtual_to_phys", path);
691 virt_addr=(u64)va1;
692 if (wr(fn,virt_addr)<0)
693 return -1;
694 rd(fn, &phys_addr);
695 err_data_buffer->err_data_buffer_cache.inj_addr=phys_addr;
696 break;
697 default:
698 printf("Not supported cl_id\n");
699 break;
700 }
701 break;
702 case 2: // TLB
703 break;
704 case 3: // Register file
705 break;
706 case 4: // Bus/system interconnect
707 default:
708 printf("Not supported err_struct\n");
709 break;
710 }
711
712 return 0;
713}
714
715typedef struct {
716 u64 cpu;
717 u64 loop;
718 u64 interval;
719 u64 err_type_info;
720 u64 err_struct_info;
721 u64 err_data_buffer[ERR_DATA_BUFFER_SIZE];
722} parameters_t;
723
724parameters_t line_para;
725int para;
726
727static int empty_data_buffer(u64 *err_data_buffer)
728{
729 int empty=1;
730 int i;
731
732 for (i=0;i<ERR_DATA_BUFFER_SIZE; i++)
733 if (err_data_buffer[i]!=-1)
734 empty=0;
735
736 return empty;
737}
738
739int err_inj()
740{
741 err_type_info_t err_type_info;
742 err_struct_info_t err_struct_info;
743 err_data_buffer_t err_data_buffer;
744 int count;
745 FILE *fp;
746 unsigned long cpu, loop, interval, err_type_info_conf, err_struct_info_conf;
747 u64 err_data_buffer_conf[ERR_DATA_BUFFER_SIZE];
748 int num;
749 int i;
750 char path[MAX_FN_SIZE];
751 parameters_t parameters[MAX_TASK_NUM]={};
752 pid_t child_pid[MAX_TASK_NUM];
753 time_t current_time;
754 int status;
755
756 if (!para) {
757 fp=fopen("err.conf", "r");
758 if (fp==NULL) {
759 perror("Error open err.conf");
760 return -1;
761 }
762
763 num=0;
764 while (!feof(fp)) {
765 char buf[256];
766 memset(buf,0,256);
767 fgets(buf, 256, fp);
768 count=sscanf(buf, "%lx, %lx, %lx, %lx, %lx, %lx, %lx, %lx\n",
769 &cpu, &loop, &interval,&err_type_info_conf,
770 &err_struct_info_conf,
771 &err_data_buffer_conf[0],
772 &err_data_buffer_conf[1],
773 &err_data_buffer_conf[2]);
774 if (count!=PARA_FIELD_NUM+3) {
775 err_data_buffer_conf[0]=-1;
776 err_data_buffer_conf[1]=-1;
777 err_data_buffer_conf[2]=-1;
778 count=sscanf(buf, "%lx, %lx, %lx, %lx, %lx\n",
779 &cpu, &loop, &interval,&err_type_info_conf,
780 &err_struct_info_conf);
781 if (count!=PARA_FIELD_NUM)
782 continue;
783 }
784
785 parameters[num].cpu=cpu;
786 parameters[num].loop=loop;
787 parameters[num].interval= interval>MIN_INTERVAL
788 ?interval:MIN_INTERVAL;
789 parameters[num].err_type_info=err_type_info_conf;
790 parameters[num].err_struct_info=err_struct_info_conf;
791 memcpy(parameters[num++].err_data_buffer,
792 err_data_buffer_conf,ERR_DATA_BUFFER_SIZE*8) ;
793
794 if (num>=MAX_TASK_NUM)
795 break;
796 }
797 }
798 else {
799 parameters[0].cpu=line_para.cpu;
800 parameters[0].loop=line_para.loop;
801 parameters[0].interval= line_para.interval>MIN_INTERVAL
802 ?line_para.interval:MIN_INTERVAL;
803 parameters[0].err_type_info=line_para.err_type_info;
804 parameters[0].err_struct_info=line_para.err_struct_info;
805 memcpy(parameters[0].err_data_buffer,
806 line_para.err_data_buffer,ERR_DATA_BUFFER_SIZE*8) ;
807
808 num=1;
809 }
810
811 /* Create semaphore: If one_lock, one semaphore for all processors.
812 Otherwise, one sempaphore for each processor. */
813 if (one_lock) {
814 if (create_sem(0)) {
815 printf("Can not create semaphore...exit\n");
816 free_sem(0);
817 return -1;
818 }
819 }
820 else {
821 for (i=0;i<num;i++) {
822 if (create_sem(parameters[i].cpu)) {
823 printf("Can not create semaphore for cpu%d...exit\n",i);
824 free_sem(parameters[num].cpu);
825 return -1;
826 }
827 }
828 }
829
830 /* Create a shm segment which will be used to inject/consume errors on.*/
831 if (create_shm()==-1) {
832 printf("Error to create shm...exit\n");
833 return -1;
834 }
835
836 for (i=0;i<num;i++) {
837 pid_t pid;
838
839 current_time=time(NULL);
840 log_info(parameters[i].cpu, "\nBegine at %s", ctime(&current_time));
841 log_info(parameters[i].cpu, "Configurations:\n");
842 log_info(parameters[i].cpu,"On cpu%ld: loop=%lx, interval=%lx(s)",
843 parameters[i].cpu,
844 parameters[i].loop,
845 parameters[i].interval);
846 log_info(parameters[i].cpu," err_type_info=%lx,err_struct_info=%lx\n",
847 parameters[i].err_type_info,
848 parameters[i].err_struct_info);
849
850 sprintf(path, PATH_FORMAT, (int)parameters[i].cpu);
851 err_type_info.err_type_info=parameters[i].err_type_info;
852 err_struct_info.err_struct_info=parameters[i].err_struct_info;
853 memcpy(err_data_buffer.err_data_buffer,
854 parameters[i].err_data_buffer,
855 ERR_DATA_BUFFER_SIZE*8);
856
857 pid=fork();
858 if (pid==0) {
859 unsigned long mask[MASK_SIZE];
860 int j, k;
861
862 void *va1, *va2;
863
864 /* Allocate two memory areas va1 and va2 in shm */
865 va1=shmaddr+parameters[i].cpu*PAGE_SIZE;
866 va2=shmaddr+parameters[i].cpu*PAGE_SIZE+PAGE_SIZE;
867
868 vbprintf("va1=%lx, va2=%lx\n", (u64)va1, (u64)va2);
869 memset(va1, 0x1, PAGE_SIZE);
870 memset(va2, 0x2, PAGE_SIZE);
871
872 if (empty_data_buffer(err_data_buffer.err_data_buffer))
873 /* If not specified yet, construct data buffer
874 * with va1
875 */
876 construct_data_buf(path, err_type_info,
877 err_struct_info, &err_data_buffer,va1);
878
879 for (j=0;j<MASK_SIZE;j++)
880 mask[j]=0;
881
882 cpu=parameters[i].cpu;
883 k = cpu%64;
884 j = cpu/64;
885 mask[j]=1<<k;
886
887 if (sched_setaffinity(0, MASK_SIZE*8, mask)==-1) {
888 perror("Error sched_setaffinity:");
889 return -1;
890 }
891
892 for (j=0; j<parameters[i].loop; j++) {
893 log_info(parameters[i].cpu,"Injection ");
894 log_info(parameters[i].cpu,"on cpu%ld: #%d/%ld ",
895
896 parameters[i].cpu,j+1, parameters[i].loop);
897
898 /* Hold the lock */
899 if (one_lock)
900 lock(0);
901 else
902 /* Hold lock on this cpu */
903 lock(parameters[i].cpu);
904
905 if ((status=err_inject(parameters[i].cpu,
906 path, err_type_info,
907 err_struct_info, err_data_buffer))
908 ==0) {
909 /* consume the error for "inject only"*/
910 memcpy(va2, va1, PAGE_SIZE);
911 memcpy(va1, va2, PAGE_SIZE);
912 log_info(parameters[i].cpu,
913 "successful\n");
914 }
915 else {
916 log_info(parameters[i].cpu,"fail:");
917 log_info(parameters[i].cpu,
918 "status=%d\n", status);
919 unlock(parameters[i].cpu);
920 break;
921 }
922 if (one_lock)
923 /* Release the lock */
924 unlock(0);
925 /* Release lock on this cpu */
926 else
927 unlock(parameters[i].cpu);
928
929 if (j < parameters[i].loop-1)
930 sleep(parameters[i].interval);
931 }
932 current_time=time(NULL);
933 log_info(parameters[i].cpu, "Done at %s", ctime(&current_time));
934 return 0;
935 }
936 else if (pid<0) {
937 perror("Error fork:");
938 continue;
939 }
940 child_pid[i]=pid;
941 }
942 for (i=0;i<num;i++)
943 waitpid(child_pid[i], NULL, 0);
944
945 if (one_lock)
946 free_sem(0);
947 else
948 for (i=0;i<num;i++)
949 free_sem(parameters[i].cpu);
950
951 printf("All done.\n");
952
953 return 0;
954}
955
956void help()
957{
958 printf("err_inject_tool:\n");
959 printf("\t-q: query all capabilities. default: off\n");
960 printf("\t-m: procedure mode. 1: physical 2: virtual. default: 1\n");
961 printf("\t-i: inject errors. default: off\n");
962 printf("\t-l: one lock per cpu. default: one lock for all\n");
963 printf("\t-e: error parameters:\n");
964 printf("\t\tcpu,loop,interval,err_type_info,err_struct_info[,err_data_buffer[0],err_data_buffer[1],err_data_buffer[2]]\n");
965 printf("\t\t cpu: logical cpu number the error will be inject in.\n");
966 printf("\t\t loop: times the error will be injected.\n");
967 printf("\t\t interval: In second. every so often one error is injected.\n");
968 printf("\t\t err_type_info, err_struct_info: PAL parameters.\n");
969 printf("\t\t err_data_buffer: PAL parameter. Optional. If not present,\n");
970 printf("\t\t it's constructed by tool automatically. Be\n");
971 printf("\t\t careful to provide err_data_buffer and make\n");
972 printf("\t\t sure it's working with the environment.\n");
973 printf("\t Note:no space between error parameters.\n");
974 printf("\t default: Take error parameters from err.conf instead of command line.\n");
975 printf("\t-v: verbose. default: off\n");
976 printf("\t-h: help\n\n");
977 printf("The tool will take err.conf file as ");
978 printf("input to inject single or multiple errors ");
979 printf("on one or multiple cpus in parallel.\n");
980}
981
982int main(int argc, char **argv)
983{
984 char c;
985 int do_err_inj=0;
986 int do_query_all=0;
987 int count;
988 u32 m;
989
990 /* Default one lock for all cpu's */
991 one_lock=1;
992 while ((c = getopt(argc, argv, "m:iqvhle:")) != EOF)
993 switch (c) {
994 case 'm': /* Procedure mode. 1: phys 2: virt */
995 count=sscanf(optarg, "%x", &m);
996 if (count!=1 || (m!=1 && m!=2)) {
997 printf("Wrong mode number.\n");
998 help();
999 return -1;
1000 }
1001 mode=m;
1002 break;
1003 case 'i': /* Inject errors */
1004 do_err_inj=1;
1005 break;
1006 case 'q': /* Query */
1007 do_query_all=1;
1008 break;
1009 case 'v': /* Verbose */
1010 verbose=1;
1011 break;
1012 case 'l': /* One lock per cpu */
1013 one_lock=0;
1014 break;
1015 case 'e': /* error arguments */
1016 /* Take parameters:
1017 * #cpu, loop, interval, err_type_info, err_struct_info[, err_data_buffer]
1018 * err_data_buffer is optional. Recommend not to specify
1019 * err_data_buffer. Better to use tool to generate it.
1020 */
1021 count=sscanf(optarg,
1022 "%lx, %lx, %lx, %lx, %lx, %lx, %lx, %lx\n",
1023 &line_para.cpu,
1024 &line_para.loop,
1025 &line_para.interval,
1026 &line_para.err_type_info,
1027 &line_para.err_struct_info,
1028 &line_para.err_data_buffer[0],
1029 &line_para.err_data_buffer[1],
1030 &line_para.err_data_buffer[2]);
1031 if (count!=PARA_FIELD_NUM+3) {
1032 line_para.err_data_buffer[0]=-1,
1033 line_para.err_data_buffer[1]=-1,
1034 line_para.err_data_buffer[2]=-1;
1035 count=sscanf(optarg, "%lx, %lx, %lx, %lx, %lx\n",
1036 &line_para.cpu,
1037 &line_para.loop,
1038 &line_para.interval,
1039 &line_para.err_type_info,
1040 &line_para.err_struct_info);
1041 if (count!=PARA_FIELD_NUM) {
1042 printf("Wrong error arguments.\n");
1043 help();
1044 return -1;
1045 }
1046 }
1047 para=1;
1048 break;
1049 continue;
1050 break;
1051 case 'h':
1052 help();
1053 return 0;
1054 default:
1055 break;
1056 }
1057
1058 if (do_query_all)
1059 query_all_capabilities();
1060 if (do_err_inj)
1061 err_inj();
1062
1063 if (!do_query_all && !do_err_inj)
1064 help();
1065
1066 return 0;
1067}
1068
diff --git a/Documentation/ide.txt b/Documentation/ide.txt
index 786c3a766995..3bb9f9c98611 100644
--- a/Documentation/ide.txt
+++ b/Documentation/ide.txt
@@ -232,7 +232,9 @@ Summary of ide driver parameters for kernel command line
232 232
233 "hdx=remap63" : remap the drive: add 63 to all sector numbers 233 "hdx=remap63" : remap the drive: add 63 to all sector numbers
234 (for DM OnTrack) 234 (for DM OnTrack)
235 235
236 "idex=noautotune" : driver will NOT attempt to tune interface speed
237
236 "hdx=autotune" : driver will attempt to tune interface speed 238 "hdx=autotune" : driver will attempt to tune interface speed
237 to the fastest PIO mode supported, 239 to the fastest PIO mode supported,
238 if possible for this drive only. 240 if possible for this drive only.
@@ -267,17 +269,6 @@ Summary of ide driver parameters for kernel command line
267 "idex=base,ctl" : specify both base and ctl 269 "idex=base,ctl" : specify both base and ctl
268 270
269 "idex=base,ctl,irq" : specify base, ctl, and irq number 271 "idex=base,ctl,irq" : specify base, ctl, and irq number
270
271 "idex=autotune" : driver will attempt to tune interface speed
272 to the fastest PIO mode supported,
273 for all drives on this interface.
274 Not fully supported by all chipset types,
275 and quite likely to cause trouble with
276 older/odd IDE drives.
277
278 "idex=noautotune" : driver will NOT attempt to tune interface speed
279 This is the default for most chipsets,
280 except the cmd640.
281 272
282 "idex=serialize" : do not overlap operations on idex. Please note 273 "idex=serialize" : do not overlap operations on idex. Please note
283 that you will have to specify this option for 274 that you will have to specify this option for
@@ -303,13 +294,8 @@ The following are valid ONLY on ide0, which usually corresponds
303to the first ATA interface found on the particular host, and the defaults for 294to the first ATA interface found on the particular host, and the defaults for
304the base,ctl ports must not be altered. 295the base,ctl ports must not be altered.
305 296
306 "ide0=dtc2278" : probe/support DTC2278 interface
307 "ide0=ht6560b" : probe/support HT6560B interface
308 "ide0=cmd640_vlb" : *REQUIRED* for VLB cards with the CMD640 chip 297 "ide0=cmd640_vlb" : *REQUIRED* for VLB cards with the CMD640 chip
309 (not for PCI -- automatically detected) 298 (not for PCI -- automatically detected)
310 "ide0=qd65xx" : probe/support qd65xx interface
311 "ide0=ali14xx" : probe/support ali14xx chipsets (ALI M1439/M1443/M1445)
312 "ide0=umc8672" : probe/support umc8672 chipsets
313 299
314 "ide=doubler" : probe/support IDE doublers on Amiga 300 "ide=doubler" : probe/support IDE doublers on Amiga
315 301
@@ -317,6 +303,15 @@ There may be more options than shown -- use the source, Luke!
317 303
318Everything else is rejected with a "BAD OPTION" message. 304Everything else is rejected with a "BAD OPTION" message.
319 305
306For legacy IDE VLB host drivers (ali14xx/dtc2278/ht6560b/qd65xx/umc8672)
307you need to explicitly enable probing by using "probe" kernel parameter,
308i.e. to enable probing for ALI M14xx chipsets (ali14xx host driver) use:
309
310* "ali14xx.probe" boot option when ali14xx driver is built-in the kernel
311
312* "probe" module parameter when ali14xx driver is compiled as module
313 ("modprobe ali14xx probe")
314
320================================================================================ 315================================================================================
321 316
322IDE ATAPI streaming tape driver 317IDE ATAPI streaming tape driver
diff --git a/Documentation/infiniband/user_mad.txt b/Documentation/infiniband/user_mad.txt
index 750fe5e80ebc..8ec54b974b67 100644
--- a/Documentation/infiniband/user_mad.txt
+++ b/Documentation/infiniband/user_mad.txt
@@ -91,6 +91,14 @@ Sending MADs
91 if (ret != sizeof *mad + mad_length) 91 if (ret != sizeof *mad + mad_length)
92 perror("write"); 92 perror("write");
93 93
94Transaction IDs
95
96 Users of the umad devices can use the lower 32 bits of the
97 transaction ID field (that is, the least significant half of the
98 field in network byte order) in MADs being sent to match
99 request/response pairs. The upper 32 bits are reserved for use by
100 the kernel and will be overwritten before a MAD is sent.
101
94Setting IsSM Capability Bit 102Setting IsSM Capability Bit
95 103
96 To set the IsSM capability bit for a port, simply open the 104 To set the IsSM capability bit for a port, simply open the
diff --git a/Documentation/ioctl-number.txt b/Documentation/ioctl-number.txt
index 5a8bd5bd88ef..8f750c0efed5 100644
--- a/Documentation/ioctl-number.txt
+++ b/Documentation/ioctl-number.txt
@@ -94,8 +94,7 @@ Code Seq# Include File Comments
94'L' 00-1F linux/loop.h 94'L' 00-1F linux/loop.h
95'L' E0-FF linux/ppdd.h encrypted disk device driver 95'L' E0-FF linux/ppdd.h encrypted disk device driver
96 <http://linux01.gwdg.de/~alatham/ppdd.html> 96 <http://linux01.gwdg.de/~alatham/ppdd.html>
97'M' all linux/soundcard.h conflict! 97'M' all linux/soundcard.h
98'M' 00-1F linux/isicom.h conflict!
99'N' 00-1F drivers/usb/scanner.h 98'N' 00-1F drivers/usb/scanner.h
100'P' all linux/soundcard.h 99'P' all linux/soundcard.h
101'Q' all linux/soundcard.h 100'Q' all linux/soundcard.h
diff --git a/Documentation/isdn/README.gigaset b/Documentation/isdn/README.gigaset
index fa0d4cca964a..55b2852904a4 100644
--- a/Documentation/isdn/README.gigaset
+++ b/Documentation/isdn/README.gigaset
@@ -8,29 +8,33 @@ GigaSet 307x Device Driver
8 This release supports the connection of the Gigaset 307x/417x family of 8 This release supports the connection of the Gigaset 307x/417x family of
9 ISDN DECT bases via Gigaset M101 Data, Gigaset M105 Data or direct USB 9 ISDN DECT bases via Gigaset M101 Data, Gigaset M105 Data or direct USB
10 connection. The following devices are reported to be compatible: 10 connection. The following devices are reported to be compatible:
11 307x/417x: 11
12 Gigaset SX255isdn 12 Bases:
13 Gigaset SX353isdn 13 Siemens Gigaset 3070/3075 isdn
14 Sinus 45 [AB] isdn (Deutsche Telekom) 14 Siemens Gigaset 4170/4175 isdn
15 Sinus 721X/XA 15 Siemens Gigaset SX205/255
16 Siemens Gigaset SX353
17 T-Com Sinus 45 [AB] isdn
18 T-Com Sinus 721X[A] [SE]
16 Vox Chicago 390 ISDN (KPN Telecom) 19 Vox Chicago 390 ISDN (KPN Telecom)
17 M101: 20
18 Sinus 45 Data 1 (Telekom) 21 RS232 data boxes:
19 M105: 22 Siemens Gigaset M101 Data
20 Gigaset USB Adapter DECT 23 T-Com Sinus 45 Data 1
21 Sinus 45 Data 2 (Telekom) 24
22 Sinus 721 data 25 USB data boxes:
26 Siemens Gigaset M105 Data
27 Siemens Gigaset USB Adapter DECT
28 T-Com Sinus 45 Data 2
29 T-Com Sinus 721 data
23 Chicago 390 USB (KPN) 30 Chicago 390 USB (KPN)
31
24 See also http://www.erbze.info/sinus_gigaset.htm and 32 See also http://www.erbze.info/sinus_gigaset.htm and
25 http://gigaset307x.sourceforge.net/ 33 http://gigaset307x.sourceforge.net/
26 34
27 We had also reports from users of Gigaset M105 who could use the drivers 35 We had also reports from users of Gigaset M105 who could use the drivers
28 with SX 100 and CX 100 ISDN bases (only in unimodem mode, see section 2.4.) 36 with SX 100 and CX 100 ISDN bases (only in unimodem mode, see section 2.4.)
29 If you have another device that works with our driver, please let us know. 37 If you have another device that works with our driver, please let us know.
30 For example, Gigaset SX205isdn/Sinus 721 X SE and Gigaset SX303isdn bases
31 are just versions without answering machine of models known to work, so
32 they should work just as well; but so far we are lacking positive reports
33 on these.
34 38
35 Chances of getting an USB device to work are good if the output of 39 Chances of getting an USB device to work are good if the output of
36 lsusb 40 lsusb
@@ -60,14 +64,28 @@ GigaSet 307x Device Driver
60 To get the device working, you have to load the proper kernel module. You 64 To get the device working, you have to load the proper kernel module. You
61 can do this using 65 can do this using
62 modprobe modulename 66 modprobe modulename
63 where modulename is usb_gigaset (M105) or bas_gigaset (direct USB 67 where modulename is ser_gigaset (M101), usb_gigaset (M105), or
64 connection to the base). 68 bas_gigaset (direct USB connection to the base).
69
70 The module ser_gigaset provides a serial line discipline N_GIGASET_M101
71 which drives the device through the regular serial line driver. To use it,
72 run the Gigaset M101 daemon "gigasetm101d" (also available from
73 http://sourceforge.net/projects/gigaset307x/) with the device file of the
74 RS232 port to the M101 as an argument, for example:
75 gigasetm101d /dev/ttyS1
76 This will open the device file, set its line discipline to N_GIGASET_M101,
77 and then sleep in the background, keeping the device open so that the
78 line discipline remains active. To deactivate it, kill the daemon, for
79 example with
80 killall gigasetm101d
81 before disconnecting the device.
65 82
662.2. Device nodes for user space programs 832.2. Device nodes for user space programs
67 ------------------------------------ 84 ------------------------------------
68 The device can be accessed from user space (eg. by the user space tools 85 The device can be accessed from user space (eg. by the user space tools
69 mentioned in 1.2.) through the device nodes: 86 mentioned in 1.2.) through the device nodes:
70 87
88 - /dev/ttyGS0 for M101 (RS232 data boxes)
71 - /dev/ttyGU0 for M105 (USB data boxes) 89 - /dev/ttyGU0 for M105 (USB data boxes)
72 - /dev/ttyGB0 for the base driver (direct USB connection) 90 - /dev/ttyGB0 for the base driver (direct USB connection)
73 91
@@ -168,6 +186,19 @@ GigaSet 307x Device Driver
168 You can also use /sys/class/tty/ttyGxy/cidmode for changing the CID mode 186 You can also use /sys/class/tty/ttyGxy/cidmode for changing the CID mode
169 setting (ttyGxy is ttyGU0 or ttyGB0). 187 setting (ttyGxy is ttyGU0 or ttyGB0).
170 188
1892.6. M105 Undocumented USB Requests
190 ------------------------------
191
192 The Gigaset M105 USB data box understands a couple of useful, but
193 undocumented USB commands. These requests are not used in normal
194 operation (for wireless access to the base), but are needed for access
195 to the M105's own configuration mode (registration to the base, baudrate
196 and line format settings, device status queries) via the gigacontr
197 utility. Their use is disabled in the driver by default for safety
198 reasons but can be enabled by setting the kernel configuration option
199 "Support for undocumented USB requests" (GIGASET_UNDOCREQ) to "Y" and
200 recompiling.
201
171 202
1723. Troubleshooting 2033. Troubleshooting
173 --------------- 204 ---------------
diff --git a/Documentation/kbuild/makefiles.txt b/Documentation/kbuild/makefiles.txt
index 4b3d6710c504..bb5306e9a5c3 100644
--- a/Documentation/kbuild/makefiles.txt
+++ b/Documentation/kbuild/makefiles.txt
@@ -34,7 +34,7 @@ This document describes the Linux kernel Makefiles.
34 --- 6.1 Set variables to tweak the build to the architecture 34 --- 6.1 Set variables to tweak the build to the architecture
35 --- 6.2 Add prerequisites to archprepare: 35 --- 6.2 Add prerequisites to archprepare:
36 --- 6.3 List directories to visit when descending 36 --- 6.3 List directories to visit when descending
37 --- 6.4 Architecture specific boot images 37 --- 6.4 Architecture-specific boot images
38 --- 6.5 Building non-kbuild targets 38 --- 6.5 Building non-kbuild targets
39 --- 6.6 Commands useful for building a boot image 39 --- 6.6 Commands useful for building a boot image
40 --- 6.7 Custom kbuild commands 40 --- 6.7 Custom kbuild commands
@@ -124,7 +124,7 @@ more details, with real examples.
124 Example: 124 Example:
125 obj-y += foo.o 125 obj-y += foo.o
126 126
127 This tell kbuild that there is one object in that directory, named 127 This tells kbuild that there is one object in that directory, named
128 foo.o. foo.o will be built from foo.c or foo.S. 128 foo.o. foo.o will be built from foo.c or foo.S.
129 129
130 If foo.o shall be built as a module, the variable obj-m is used. 130 If foo.o shall be built as a module, the variable obj-m is used.
@@ -353,7 +353,7 @@ more details, with real examples.
353 Special rules are used when the kbuild infrastructure does 353 Special rules are used when the kbuild infrastructure does
354 not provide the required support. A typical example is 354 not provide the required support. A typical example is
355 header files generated during the build process. 355 header files generated during the build process.
356 Another example are the architecture specific Makefiles which 356 Another example are the architecture-specific Makefiles which
357 need special rules to prepare boot images etc. 357 need special rules to prepare boot images etc.
358 358
359 Special rules are written as normal Make rules. 359 Special rules are written as normal Make rules.
@@ -416,7 +416,7 @@ more details, with real examples.
416 #arch/i386/kernel/Makefile 416 #arch/i386/kernel/Makefile
417 vsyscall-flags += $(call ld-option, -Wl$(comma)--hash-style=sysv) 417 vsyscall-flags += $(call ld-option, -Wl$(comma)--hash-style=sysv)
418 418
419 In the above example vsyscall-flags will be assigned the option 419 In the above example, vsyscall-flags will be assigned the option
420 -Wl$(comma)--hash-style=sysv if it is supported by $(CC). 420 -Wl$(comma)--hash-style=sysv if it is supported by $(CC).
421 The second argument is optional, and if supplied will be used 421 The second argument is optional, and if supplied will be used
422 if first argument is not supported. 422 if first argument is not supported.
@@ -434,7 +434,7 @@ more details, with real examples.
434 #arch/i386/Makefile 434 #arch/i386/Makefile
435 cflags-y += $(call cc-option,-march=pentium-mmx,-march=i586) 435 cflags-y += $(call cc-option,-march=pentium-mmx,-march=i586)
436 436
437 In the above example cflags-y will be assigned the option 437 In the above example, cflags-y will be assigned the option
438 -march=pentium-mmx if supported by $(CC), otherwise -march=i586. 438 -march=pentium-mmx if supported by $(CC), otherwise -march=i586.
439 The second argument to cc-option is optional, and if omitted, 439 The second argument to cc-option is optional, and if omitted,
440 cflags-y will be assigned no value if first option is not supported. 440 cflags-y will be assigned no value if first option is not supported.
@@ -750,10 +750,10 @@ When kbuild executes, the following steps are followed (roughly):
750 located at the root of the obj tree. 750 located at the root of the obj tree.
751 The very first objects linked are listed in head-y, assigned by 751 The very first objects linked are listed in head-y, assigned by
752 arch/$(ARCH)/Makefile. 752 arch/$(ARCH)/Makefile.
7537) Finally, the architecture specific part does any required post processing 7537) Finally, the architecture-specific part does any required post processing
754 and builds the final bootimage. 754 and builds the final bootimage.
755 - This includes building boot records 755 - This includes building boot records
756 - Preparing initrd images and thelike 756 - Preparing initrd images and the like
757 757
758 758
759--- 6.1 Set variables to tweak the build to the architecture 759--- 6.1 Set variables to tweak the build to the architecture
@@ -880,7 +880,7 @@ When kbuild executes, the following steps are followed (roughly):
880 880
881 $(head-y) lists objects to be linked first in vmlinux. 881 $(head-y) lists objects to be linked first in vmlinux.
882 $(libs-y) lists directories where a lib.a archive can be located. 882 $(libs-y) lists directories where a lib.a archive can be located.
883 The rest lists directories where a built-in.o object file can be 883 The rest list directories where a built-in.o object file can be
884 located. 884 located.
885 885
886 $(init-y) objects will be located after $(head-y). 886 $(init-y) objects will be located after $(head-y).
@@ -888,7 +888,7 @@ When kbuild executes, the following steps are followed (roughly):
888 $(core-y), $(libs-y), $(drivers-y) and $(net-y). 888 $(core-y), $(libs-y), $(drivers-y) and $(net-y).
889 889
890 The top level Makefile defines values for all generic directories, 890 The top level Makefile defines values for all generic directories,
891 and arch/$(ARCH)/Makefile only adds architecture specific directories. 891 and arch/$(ARCH)/Makefile only adds architecture-specific directories.
892 892
893 Example: 893 Example:
894 #arch/sparc64/Makefile 894 #arch/sparc64/Makefile
@@ -897,7 +897,7 @@ When kbuild executes, the following steps are followed (roughly):
897 drivers-$(CONFIG_OPROFILE) += arch/sparc64/oprofile/ 897 drivers-$(CONFIG_OPROFILE) += arch/sparc64/oprofile/
898 898
899 899
900--- 6.4 Architecture specific boot images 900--- 6.4 Architecture-specific boot images
901 901
902 An arch Makefile specifies goals that take the vmlinux file, compress 902 An arch Makefile specifies goals that take the vmlinux file, compress
903 it, wrap it in bootstrapping code, and copy the resulting files 903 it, wrap it in bootstrapping code, and copy the resulting files
@@ -924,7 +924,7 @@ When kbuild executes, the following steps are followed (roughly):
924 "$(Q)$(MAKE) $(build)=<dir>" is the recommended way to invoke 924 "$(Q)$(MAKE) $(build)=<dir>" is the recommended way to invoke
925 make in a subdirectory. 925 make in a subdirectory.
926 926
927 There are no rules for naming architecture specific targets, 927 There are no rules for naming architecture-specific targets,
928 but executing "make help" will list all relevant targets. 928 but executing "make help" will list all relevant targets.
929 To support this, $(archhelp) must be defined. 929 To support this, $(archhelp) must be defined.
930 930
@@ -982,7 +982,7 @@ When kbuild executes, the following steps are followed (roughly):
982 $(call if_changed,ld/objcopy/gzip) 982 $(call if_changed,ld/objcopy/gzip)
983 983
984 When the rule is evaluated, it is checked to see if any files 984 When the rule is evaluated, it is checked to see if any files
985 needs an update, or the command line has changed since the last 985 need an update, or the command line has changed since the last
986 invocation. The latter will force a rebuild if any options 986 invocation. The latter will force a rebuild if any options
987 to the executable have changed. 987 to the executable have changed.
988 Any target that utilises if_changed must be listed in $(targets), 988 Any target that utilises if_changed must be listed in $(targets),
@@ -1089,7 +1089,7 @@ When kbuild executes, the following steps are followed (roughly):
1089 assignment. 1089 assignment.
1090 1090
1091 The kbuild infrastructure for *lds file are used in several 1091 The kbuild infrastructure for *lds file are used in several
1092 architecture specific files. 1092 architecture-specific files.
1093 1093
1094 1094
1095=== 7 Kbuild Variables 1095=== 7 Kbuild Variables
@@ -1133,7 +1133,7 @@ The top Makefile exports the following variables:
1133 1133
1134 This variable defines a place for the arch Makefiles to install 1134 This variable defines a place for the arch Makefiles to install
1135 the resident kernel image and System.map file. 1135 the resident kernel image and System.map file.
1136 Use this for architecture specific install targets. 1136 Use this for architecture-specific install targets.
1137 1137
1138 INSTALL_MOD_PATH, MODLIB 1138 INSTALL_MOD_PATH, MODLIB
1139 1139
diff --git a/Documentation/kdump/kdump.txt b/Documentation/kdump/kdump.txt
index 073306818347..2fedc081b4c8 100644
--- a/Documentation/kdump/kdump.txt
+++ b/Documentation/kdump/kdump.txt
@@ -30,6 +30,10 @@ On x86 machines, the first 640 KB of physical memory is needed to boot,
30regardless of where the kernel loads. Therefore, kexec backs up this 30regardless of where the kernel loads. Therefore, kexec backs up this
31region just before rebooting into the dump-capture kernel. 31region just before rebooting into the dump-capture kernel.
32 32
33Similarly on PPC64 machines first 32KB of physical memory is needed for
34booting regardless of where the kernel is loaded and to support 64K page
35size kexec backs up the first 64KB memory.
36
33All of the necessary information about the system kernel's core image is 37All of the necessary information about the system kernel's core image is
34encoded in the ELF format, and stored in a reserved area of memory 38encoded in the ELF format, and stored in a reserved area of memory
35before a crash. The physical address of the start of the ELF header is 39before a crash. The physical address of the start of the ELF header is
@@ -224,7 +228,7 @@ Dump-capture kernel config options (Arch Dependent, x86_64)
224Dump-capture kernel config options (Arch Dependent, ppc64) 228Dump-capture kernel config options (Arch Dependent, ppc64)
225---------------------------------------------------------- 229----------------------------------------------------------
226 230
227- Make and install the kernel and its modules. DO NOT add this kernel 231* Make and install the kernel and its modules. DO NOT add this kernel
228 to the boot loader configuration files. 232 to the boot loader configuration files.
229 233
230Dump-capture kernel config options (Arch Dependent, ia64) 234Dump-capture kernel config options (Arch Dependent, ia64)
@@ -251,8 +255,8 @@ Dump-capture kernel config options (Arch Dependent, ia64)
251Boot into System Kernel 255Boot into System Kernel
252======================= 256=======================
253 257
2541) Make and install the kernel and its modules. Update the boot loader 2581) Update the boot loader (such as grub, yaboot, or lilo) configuration
255 (such as grub, yaboot, or lilo) configuration files as necessary. 259 files as necessary.
256 260
2572) Boot the system kernel with the boot parameter "crashkernel=Y@X", 2612) Boot the system kernel with the boot parameter "crashkernel=Y@X",
258 where Y specifies how much memory to reserve for the dump-capture kernel 262 where Y specifies how much memory to reserve for the dump-capture kernel
@@ -311,10 +315,10 @@ Following are the arch specific command line options to be used while
311loading dump-capture kernel. 315loading dump-capture kernel.
312 316
313For i386, x86_64 and ia64: 317For i386, x86_64 and ia64:
314 "init 1 irqpoll maxcpus=1" 318 "1 irqpoll maxcpus=1"
315 319
316For ppc64: 320For ppc64:
317 "init 1 maxcpus=1 noirqdistrib" 321 "1 maxcpus=1 noirqdistrib"
318 322
319 323
320Notes on loading the dump-capture kernel: 324Notes on loading the dump-capture kernel:
@@ -332,8 +336,8 @@ Notes on loading the dump-capture kernel:
332* You must specify <root-dev> in the format corresponding to the root 336* You must specify <root-dev> in the format corresponding to the root
333 device name in the output of mount command. 337 device name in the output of mount command.
334 338
335* "init 1" boots the dump-capture kernel into single-user mode without 339* Boot parameter "1" boots the dump-capture kernel into single-user
336 networking. If you want networking, use "init 3." 340 mode without networking. If you want networking, use "3".
337 341
338* We generally don' have to bring up a SMP kernel just to capture the 342* We generally don' have to bring up a SMP kernel just to capture the
339 dump. Hence generally it is useful either to build a UP dump-capture 343 dump. Hence generally it is useful either to build a UP dump-capture
@@ -356,10 +360,11 @@ If die() is called, and it happens to be a thread with pid 0 or 1, or die()
356is called inside interrupt context or die() is called and panic_on_oops is set, 360is called inside interrupt context or die() is called and panic_on_oops is set,
357the system will boot into the dump-capture kernel. 361the system will boot into the dump-capture kernel.
358 362
359On powererpc systems when a soft-reset is generated, die() is called by all cpus and the system will boot into the dump-capture kernel. 363On powererpc systems when a soft-reset is generated, die() is called by all cpus
364and the system will boot into the dump-capture kernel.
360 365
361For testing purposes, you can trigger a crash by using "ALT-SysRq-c", 366For testing purposes, you can trigger a crash by using "ALT-SysRq-c",
362"echo c > /proc/sysrq-trigger or write a module to force the panic. 367"echo c > /proc/sysrq-trigger" or write a module to force the panic.
363 368
364Write Out the Dump File 369Write Out the Dump File
365======================= 370=======================
@@ -410,12 +415,9 @@ format. Crash is available on Dave Anderson's site at the following URL:
410To Do 415To Do
411===== 416=====
412 417
4131) Provide a kernel pages filtering mechanism, so core file size is not 4181) Provide relocatable kernels for all architectures to help in maintaining
414 extreme on systems with huge memory banks. 419 multiple kernels for crash_dump, and the same kernel as the system kernel
415 420 can be used to capture the dump.
4162) Relocatable kernel can help in maintaining multiple kernels for
417 crash_dump, and the same kernel as the system kernel can be used to
418 capture the dump.
419 421
420 422
421Contact 423Contact
diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt
index 284e7e198e93..2075c0658bf5 100644
--- a/Documentation/kernel-doc-nano-HOWTO.txt
+++ b/Documentation/kernel-doc-nano-HOWTO.txt
@@ -101,16 +101,20 @@ The format of the block comment is like this:
101 101
102/** 102/**
103 * function_name(:)? (- short description)? 103 * function_name(:)? (- short description)?
104(* @parameterx: (description of parameter x)?)* 104(* @parameterx(space)*: (description of parameter x)?)*
105(* a blank line)? 105(* a blank line)?
106 * (Description:)? (Description of function)? 106 * (Description:)? (Description of function)?
107 * (section header: (section description)? )* 107 * (section header: (section description)? )*
108(*)?*/ 108(*)?*/
109 109
110The short function description cannot be multiline, but the other 110The short function description ***cannot be multiline***, but the other
111descriptions can be (and they can contain blank lines). Avoid putting a 111descriptions can be (and they can contain blank lines). If you continue
112spurious blank line after the function name, or else the description will 112that initial short description onto a second line, that second line will
113be repeated! 113appear further down at the beginning of the description section, which is
114almost certainly not what you had in mind.
115
116Avoid putting a spurious blank line after the function name, or else the
117description will be repeated!
114 118
115All descriptive text is further processed, scanning for the following special 119All descriptive text is further processed, scanning for the following special
116patterns, which are highlighted appropriately. 120patterns, which are highlighted appropriately.
@@ -121,6 +125,31 @@ patterns, which are highlighted appropriately.
121'@parameter' - name of a parameter 125'@parameter' - name of a parameter
122'%CONST' - name of a constant. 126'%CONST' - name of a constant.
123 127
128NOTE 1: The multi-line descriptive text you provide does *not* recognize
129line breaks, so if you try to format some text nicely, as in:
130
131 Return codes
132 0 - cool
133 1 - invalid arg
134 2 - out of memory
135
136this will all run together and produce:
137
138 Return codes 0 - cool 1 - invalid arg 2 - out of memory
139
140NOTE 2: If the descriptive text you provide has lines that begin with
141some phrase followed by a colon, each of those phrases will be taken as
142a new section heading, which means you should similarly try to avoid text
143like:
144
145 Return codes:
146 0: cool
147 1: invalid arg
148 2: out of memory
149
150every line of which would start a new section. Again, probably not
151what you were after.
152
124Take a look around the source tree for examples. 153Take a look around the source tree for examples.
125 154
126 155
diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt
index b53bccbd9727..c68dafeda7a7 100644
--- a/Documentation/kernel-docs.txt
+++ b/Documentation/kernel-docs.txt
@@ -1,10 +1,10 @@
1 1
2 Index of Documentation for People Interested in Writing and/or 2 Index of Documentation for People Interested in Writing and/or
3 3
4 Understanding the Linux Kernel. 4 Understanding the Linux Kernel.
5 5
6 Juan-Mariano de Goyeneche <jmseyas@dit.upm.es> 6 Juan-Mariano de Goyeneche <jmseyas@dit.upm.es>
7 7
8/* 8/*
9 * The latest version of this document may be found at: 9 * The latest version of this document may be found at:
10 * http://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html 10 * http://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html
@@ -61,18 +61,18 @@
61 13.-The Linux Kernel Sources, A.-Linux Data Structures, B.-The 61 13.-The Linux Kernel Sources, A.-Linux Data Structures, B.-The
62 Alpha AXP Processor, C.-Useful Web and FTP Sites, D.-The GNU 62 Alpha AXP Processor, C.-Useful Web and FTP Sites, D.-The GNU
63 General Public License, Glossary". In short: a must have. 63 General Public License, Glossary". In short: a must have.
64 64
65 * Title: "The Linux Kernel Hackers' Guide" 65 * Title: "Linux Device Drivers, 2nd Edition"
66 Author: Michael K.Johnson and others. 66 Author: Alessandro Rubini and Jonathan Corbet.
67 URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html 67 URL: http://www.xml.com/ldd/chapter/book/index.html
68 Keywords: everything! 68 Keywords: device drivers, modules, debugging, memory, hardware,
69 Description: No more Postscript book-like version. Only HTML now. 69 interrupt handling, char drivers, block drivers, kmod, mmap, DMA,
70 Many people have contributed. The interface is similar to web 70 buses.
71 available mailing lists archives. You can find some articles and 71 Description: O'Reilly's popular book, now also on-line under the
72 then some mails asking questions about them and/or complementing 72 GNU Free Documentation License.
73 previous contributions. A little bit anarchic in this aspect, but 73 Notes: You can also buy it in paper-form from O'Reilly. See below
74 with some valuable information in some cases. 74 under BOOKS (Not on-line).
75 75
76 * Title: "Conceptual Architecture of the Linux Kernel" 76 * Title: "Conceptual Architecture of the Linux Kernel"
77 Author: Ivan T. Bowman. 77 Author: Ivan T. Bowman.
78 URL: http://plg.uwaterloo.ca/~itbowman/papers/CS746G-a1.html 78 URL: http://plg.uwaterloo.ca/~itbowman/papers/CS746G-a1.html
@@ -81,17 +81,17 @@
81 Description: Conceptual software arquitecture of the Linux kernel, 81 Description: Conceptual software arquitecture of the Linux kernel,
82 automatically extracted from the source code. Very detailed. Good 82 automatically extracted from the source code. Very detailed. Good
83 figures. Gives good overall kernel understanding. 83 figures. Gives good overall kernel understanding.
84 84
85 * Title: "Concrete Architecture of the Linux Kernel" 85 * Title: "Concrete Architecture of the Linux Kernel"
86 Author: Ivan T. Bowman, Saheem Siddiqi, and Meyer C. Tanuan. 86 Author: Ivan T. Bowman, Saheem Siddiqi, and Meyer C. Tanuan.
87 URL: http://plg.uwaterloo.ca/~itbowman/papers/CS746G-a2.html 87 URL: http://plg.uwaterloo.ca/~itbowman/papers/CS746G-a2.html
88 Keywords: concrete arquitecture, extracted design, reverse 88 Keywords: concrete architecture, extracted design, reverse
89 engineering, system structure, dependencies. 89 engineering, system structure, dependencies.
90 Description: Concrete arquitecture of the Linux kernel, 90 Description: Concrete architecture of the Linux kernel,
91 automatically extracted from the source code. Very detailed. Good 91 automatically extracted from the source code. Very detailed. Good
92 figures. Gives good overall kernel understanding. This papers 92 figures. Gives good overall kernel understanding. This papers
93 focus on lower details than its predecessor (files, variables...). 93 focus on lower details than its predecessor (files, variables...).
94 94
95 * Title: "Linux as a Case Study: Its Extracted Software 95 * Title: "Linux as a Case Study: Its Extracted Software
96 Architecture" 96 Architecture"
97 Author: Ivan T. Bowman, Richard C. Holt and Neil V. Brewster. 97 Author: Ivan T. Bowman, Richard C. Holt and Neil V. Brewster.
@@ -101,7 +101,7 @@
101 Description: Paper appeared at ICSE'99, Los Angeles, May 16-22, 101 Description: Paper appeared at ICSE'99, Los Angeles, May 16-22,
102 1999. A mixture of the previous two documents from the same 102 1999. A mixture of the previous two documents from the same
103 author. 103 author.
104 104
105 * Title: "Overview of the Virtual File System" 105 * Title: "Overview of the Virtual File System"
106 Author: Richard Gooch. 106 Author: Richard Gooch.
107 URL: http://www.atnf.csiro.au/~rgooch/linux/vfs.txt 107 URL: http://www.atnf.csiro.au/~rgooch/linux/vfs.txt
@@ -111,20 +111,20 @@
111 What is it, how it works, operations taken when opening a file or 111 What is it, how it works, operations taken when opening a file or
112 mounting a file system and description of important data 112 mounting a file system and description of important data
113 structures explaining the purpose of each of their entries. 113 structures explaining the purpose of each of their entries.
114 114
115 * Title: "The Linux RAID-1, 4, 5 Code" 115 * Title: "The Linux RAID-1, 4, 5 Code"
116 Author: Ingo Molnar, Gadi Oxman and Miguel de Icaza. 116 Author: Ingo Molnar, Gadi Oxman and Miguel de Icaza.
117 URL: http://www2.linuxjournal.com/lj-issues/issue44/2391.html 117 URL: http://www.linuxjournal.com/article.php?sid=2391
118 Keywords: RAID, MD driver. 118 Keywords: RAID, MD driver.
119 Description: Linux Journal Kernel Korner article. Here is it's 119 Description: Linux Journal Kernel Korner article. Here is it's
120 abstract: "A description of the implementation of the RAID-1, 120 abstract: "A description of the implementation of the RAID-1,
121 RAID-4 and RAID-5 personalities of the MD device driver in the 121 RAID-4 and RAID-5 personalities of the MD device driver in the
122 Linux kernel, providing users with high performance and reliable, 122 Linux kernel, providing users with high performance and reliable,
123 secondary-storage capability using software". 123 secondary-storage capability using software".
124 124
125 * Title: "Dynamic Kernels: Modularized Device Drivers" 125 * Title: "Dynamic Kernels: Modularized Device Drivers"
126 Author: Alessandro Rubini. 126 Author: Alessandro Rubini.
127 URL: http://www2.linuxjournal.com/lj-issues/issue23/1219.html 127 URL: http://www.linuxjournal.com/article.php?sid=1219
128 Keywords: device driver, module, loading/unloading modules, 128 Keywords: device driver, module, loading/unloading modules,
129 allocating resources. 129 allocating resources.
130 Description: Linux Journal Kernel Korner article. Here is it's 130 Description: Linux Journal Kernel Korner article. Here is it's
@@ -134,10 +134,10 @@
134 loadable modules. This installment presents an introduction to the 134 loadable modules. This installment presents an introduction to the
135 topic, preparing the reader to understand next month's 135 topic, preparing the reader to understand next month's
136 installment". 136 installment".
137 137
138 * Title: "Dynamic Kernels: Discovery" 138 * Title: "Dynamic Kernels: Discovery"
139 Author: Alessandro Rubini. 139 Author: Alessandro Rubini.
140 URL: http://www2.linuxjournal.com/lj-issues/issue24/1220.html 140 URL: http://www.linuxjournal.com/article.php?sid=1220
141 Keywords: character driver, init_module, clean_up module, 141 Keywords: character driver, init_module, clean_up module,
142 autodetection, mayor number, minor number, file operations, 142 autodetection, mayor number, minor number, file operations,
143 open(), close(). 143 open(), close().
@@ -146,20 +146,20 @@
146 the actual code to create custom module implementing a character 146 the actual code to create custom module implementing a character
147 device driver. It describes the code for module initialization and 147 device driver. It describes the code for module initialization and
148 cleanup, as well as the open() and close() system calls". 148 cleanup, as well as the open() and close() system calls".
149 149
150 * Title: "The Devil's in the Details" 150 * Title: "The Devil's in the Details"
151 Author: Georg v. Zezschwitz and Alessandro Rubini. 151 Author: Georg v. Zezschwitz and Alessandro Rubini.
152 URL: http://www2.linuxjournal.com/lj-issues/issue25/1221.html 152 URL: http://www.linuxjournal.com/article.php?sid=1221
153 Keywords: read(), write(), select(), ioctl(), blocking/non 153 Keywords: read(), write(), select(), ioctl(), blocking/non
154 blocking mode, interrupt handler. 154 blocking mode, interrupt handler.
155 Description: Linux Journal Kernel Korner article. Here is it's 155 Description: Linux Journal Kernel Korner article. Here is it's
156 abstract: "This article, the third of four on writing character 156 abstract: "This article, the third of four on writing character
157 device drivers, introduces concepts of reading, writing, and using 157 device drivers, introduces concepts of reading, writing, and using
158 ioctl-calls". 158 ioctl-calls".
159 159
160 * Title: "Dissecting Interrupts and Browsing DMA" 160 * Title: "Dissecting Interrupts and Browsing DMA"
161 Author: Alessandro Rubini and Georg v. Zezschwitz. 161 Author: Alessandro Rubini and Georg v. Zezschwitz.
162 URL: http://www2.linuxjournal.com/lj-issues/issue26/1222.html 162 URL: http://www.linuxjournal.com/article.php?sid=1222
163 Keywords: interrupts, irqs, DMA, bottom halves, task queues. 163 Keywords: interrupts, irqs, DMA, bottom halves, task queues.
164 Description: Linux Journal Kernel Korner article. Here is it's 164 Description: Linux Journal Kernel Korner article. Here is it's
165 abstract: "This is the fourth in a series of articles about 165 abstract: "This is the fourth in a series of articles about
@@ -170,10 +170,10 @@
170 writing, and several different facilities have been provided for 170 writing, and several different facilities have been provided for
171 different situations. We also investigate the complex topic of 171 different situations. We also investigate the complex topic of
172 DMA". 172 DMA".
173 173
174 * Title: "Device Drivers Concluded" 174 * Title: "Device Drivers Concluded"
175 Author: Georg v. Zezschwitz. 175 Author: Georg v. Zezschwitz.
176 URL: http://www2.linuxjournal.com/lj-issues/issue28/1287.html 176 URL: http://www.linuxjournal.com/article.php?sid=1287
177 Keywords: address spaces, pages, pagination, page management, 177 Keywords: address spaces, pages, pagination, page management,
178 demand loading, swapping, memory protection, memory mapping, mmap, 178 demand loading, swapping, memory protection, memory mapping, mmap,
179 virtual memory areas (VMAs), vremap, PCI. 179 virtual memory areas (VMAs), vremap, PCI.
@@ -182,10 +182,10 @@
182 five articles about character device drivers. In this final 182 five articles about character device drivers. In this final
183 section, Georg deals with memory mapping devices, beginning with 183 section, Georg deals with memory mapping devices, beginning with
184 an overall description of the Linux memory management concepts". 184 an overall description of the Linux memory management concepts".
185 185
186 * Title: "Network Buffers And Memory Management" 186 * Title: "Network Buffers And Memory Management"
187 Author: Alan Cox. 187 Author: Alan Cox.
188 URL: http://www2.linuxjournal.com/lj-issues/issue30/1312.html 188 URL: http://www.linuxjournal.com/article.php?sid=1312
189 Keywords: sk_buffs, network devices, protocol/link layer 189 Keywords: sk_buffs, network devices, protocol/link layer
190 variables, network devices flags, transmit, receive, 190 variables, network devices flags, transmit, receive,
191 configuration, multicast. 191 configuration, multicast.
@@ -214,28 +214,26 @@
214 of the Coda filesystem. This version document is meant to describe 214 of the Coda filesystem. This version document is meant to describe
215 the current interface (version 1.0) as well as improvements we 215 the current interface (version 1.0) as well as improvements we
216 envisage". 216 envisage".
217 217
218 * Title: "Programming PCI-Devices under Linux" 218 * Title: "Programming PCI-Devices under Linux"
219 Author: Claus Schroeter. 219 Author: Claus Schroeter.
220 URL: 220 URL:
221 ftp://ftp.llp.fu-berlin.de/pub/linux/LINUX-LAB/whitepapers/pcip.ps 221 ftp://ftp.llp.fu-berlin.de/pub/linux/LINUX-LAB/whitepapers/pcip.ps.gz
222 .gz
223 Keywords: PCI, device, busmastering. 222 Keywords: PCI, device, busmastering.
224 Description: 6 pages tutorial on PCI programming under Linux. 223 Description: 6 pages tutorial on PCI programming under Linux.
225 Gives the basic concepts on the architecture of the PCI subsystem, 224 Gives the basic concepts on the architecture of the PCI subsystem,
226 as long as basic functions and macros to read/write the devices 225 as long as basic functions and macros to read/write the devices
227 and perform busmastering. 226 and perform busmastering.
228 227
229 * Title: "Writing Character Device Driver for Linux" 228 * Title: "Writing Character Device Driver for Linux"
230 Author: R. Baruch and C. Schroeter. 229 Author: R. Baruch and C. Schroeter.
231 URL: 230 URL:
232 ftp://ftp.llp.fu-berlin.de/pub/linux/LINUX-LAB/whitepapers/drivers 231 ftp://ftp.llp.fu-berlin.de/pub/linux/LINUX-LAB/whitepapers/drivers.ps.gz
233 .ps.gz
234 Keywords: character device drivers, I/O, signals, DMA, accessing 232 Keywords: character device drivers, I/O, signals, DMA, accessing
235 ports in user space, kernel environment. 233 ports in user space, kernel environment.
236 Description: 68 pages paper on writing character drivers. A little 234 Description: 68 pages paper on writing character drivers. A little
237 bit old (1.993, 1.994) although still useful. 235 bit old (1.993, 1.994) although still useful.
238 236
239 * Title: "Design and Implementation of the Second Extended 237 * Title: "Design and Implementation of the Second Extended
240 Filesystem" 238 Filesystem"
241 Author: Rémy Card, Theodore Ts'o, Stephen Tweedie. 239 Author: Rémy Card, Theodore Ts'o, Stephen Tweedie.
@@ -249,14 +247,14 @@
249 e2fsck's passes description... A must read! 247 e2fsck's passes description... A must read!
250 Notes: This paper was first published in the Proceedings of the 248 Notes: This paper was first published in the Proceedings of the
251 First Dutch International Symposium on Linux, ISBN 90-367-0385-9. 249 First Dutch International Symposium on Linux, ISBN 90-367-0385-9.
252 250
253 * Title: "Analysis of the Ext2fs structure" 251 * Title: "Analysis of the Ext2fs structure"
254 Author: Louis-Dominique Dubeau. 252 Author: Louis-Dominique Dubeau.
255 URL: http://step.polymtl.ca/~ldd/ext2fs/ext2fs_toc.html 253 URL: http://www.nondot.org/sabre/os/files/FileSystems/ext2fs/
256 Keywords: ext2, filesystem, ext2fs. 254 Keywords: ext2, filesystem, ext2fs.
257 Description: Description of ext2's blocks, directories, inodes, 255 Description: Description of ext2's blocks, directories, inodes,
258 bitmaps, invariants... 256 bitmaps, invariants...
259 257
260 * Title: "Journaling the Linux ext2fs Filesystem" 258 * Title: "Journaling the Linux ext2fs Filesystem"
261 Author: Stephen C. Tweedie. 259 Author: Stephen C. Tweedie.
262 URL: 260 URL:
@@ -265,7 +263,7 @@
265 Description: Excellent 8-pages paper explaining the journaling 263 Description: Excellent 8-pages paper explaining the journaling
266 capabilities added to ext2 by the author, showing different 264 capabilities added to ext2 by the author, showing different
267 problems faced and the alternatives chosen. 265 problems faced and the alternatives chosen.
268 266
269 * Title: "Kernel API changes from 2.0 to 2.2" 267 * Title: "Kernel API changes from 2.0 to 2.2"
270 Author: Richard Gooch. 268 Author: Richard Gooch.
271 URL: 269 URL:
@@ -273,7 +271,7 @@
273 Keywords: 2.2, changes. 271 Keywords: 2.2, changes.
274 Description: Kernel functions/structures/variables which changed 272 Description: Kernel functions/structures/variables which changed
275 from 2.0.x to 2.2.x. 273 from 2.0.x to 2.2.x.
276 274
277 * Title: "Kernel API changes from 2.2 to 2.4" 275 * Title: "Kernel API changes from 2.2 to 2.4"
278 Author: Richard Gooch. 276 Author: Richard Gooch.
279 URL: 277 URL:
@@ -345,17 +343,7 @@
345 Notes: Beware: the main page states: "This document may not be 343 Notes: Beware: the main page states: "This document may not be
346 published, printed or used in excerpts without explicit permission 344 published, printed or used in excerpts without explicit permission
347 of the author". Fortunately, it may still be read... 345 of the author". Fortunately, it may still be read...
348 346
349 * Title: "Tour Of the Linux Kernel Source"
350 Author: Vijo Cherian.
351 URL: http://www.geocities.com/vijoc/tolks/tolks.html
352 Keywords: .
353 Description: A classic of this page! Was lost for a while and is
354 back again. Thanks Vijo! TOLKS: the name says it all. A tour of
355 the sources, describing directories, files, variables, data
356 structures... It covers general stuff, device drivers,
357 filesystems, IPC and Networking Code.
358
359 * Title: "Linux Kernel Mailing List Glossary" 347 * Title: "Linux Kernel Mailing List Glossary"
360 Author: various 348 Author: various
361 URL: http://kernelnewbies.org/glossary/ 349 URL: http://kernelnewbies.org/glossary/
@@ -377,7 +365,17 @@
377 kernels, but most of it applies to 2.2 too; 2.0 is slightly 365 kernels, but most of it applies to 2.2 too; 2.0 is slightly
378 different". Freely redistributable under the conditions of the GNU 366 different". Freely redistributable under the conditions of the GNU
379 General Public License. 367 General Public License.
380 368
369 * Title: "Global spinlock list and usage"
370 Author: Rick Lindsley.
371 URL: http://lse.sourceforge.net/lockhier/global-spin-lock
372 Keywords: spinlock.
373 Description: This is an attempt to document both the existence and
374 usage of the spinlocks in the Linux 2.4.5 kernel. Comprehensive
375 list of spinlocks showing when they are used, which functions
376 access them, how each lock is acquired, under what conditions it
377 is held, whether interrupts can occur or not while it is held...
378
381 * Title: "Porting Linux 2.0 Drivers To Linux 2.2: Changes and New 379 * Title: "Porting Linux 2.0 Drivers To Linux 2.2: Changes and New
382 Features " 380 Features "
383 Author: Alan Cox. 381 Author: Alan Cox.
@@ -385,70 +383,70 @@
385 Keywords: ports, porting. 383 Keywords: ports, porting.
386 Description: Article from Linux Magazine on porting from 2.0 to 384 Description: Article from Linux Magazine on porting from 2.0 to
387 2.2 kernels. 385 2.2 kernels.
388 386
389 * Title: "Porting Device Drivers To Linux 2.2: part II" 387 * Title: "Porting Device Drivers To Linux 2.2: part II"
390 Author: Alan Cox. 388 Author: Alan Cox.
391 URL: http://www.linux-mag.com/1999-06/gear_01.html 389 URL: http://www.linux-mag.com/1999-06/gear_01.html
392 Keywords: ports, porting. 390 Keywords: ports, porting.
393 Description: Second part on porting from 2.0 to 2.2 kernels. 391 Description: Second part on porting from 2.0 to 2.2 kernels.
394 392
395 * Title: "How To Make Sure Your Driver Will Work On The Power 393 * Title: "How To Make Sure Your Driver Will Work On The Power
396 Macintosh" 394 Macintosh"
397 Author: Paul Mackerras. 395 Author: Paul Mackerras.
398 URL: http://www.linux-mag.com/1999-07/gear_01.html 396 URL: http://www.linux-mag.com/1999-07/gear_01.html
399 Keywords: Mac, Power Macintosh, porting, drivers, compatibility. 397 Keywords: Mac, Power Macintosh, porting, drivers, compatibility.
400 Description: The title says it all. 398 Description: The title says it all.
401 399
402 * Title: "An Introduction to SCSI Drivers" 400 * Title: "An Introduction to SCSI Drivers"
403 Author: Alan Cox. 401 Author: Alan Cox.
404 URL: http://www.linux-mag.com/1999-08/gear_01.html 402 URL: http://www.linux-mag.com/1999-08/gear_01.html
405 Keywords: SCSI, device, driver. 403 Keywords: SCSI, device, driver.
406 Description: The title says it all. 404 Description: The title says it all.
407 405
408 * Title: "Advanced SCSI Drivers And Other Tales" 406 * Title: "Advanced SCSI Drivers And Other Tales"
409 Author: Alan Cox. 407 Author: Alan Cox.
410 URL: http://www.linux-mag.com/1999-09/gear_01.html 408 URL: http://www.linux-mag.com/1999-09/gear_01.html
411 Keywords: SCSI, device, driver, advanced. 409 Keywords: SCSI, device, driver, advanced.
412 Description: The title says it all. 410 Description: The title says it all.
413 411
414 * Title: "Writing Linux Mouse Drivers" 412 * Title: "Writing Linux Mouse Drivers"
415 Author: Alan Cox. 413 Author: Alan Cox.
416 URL: http://www.linux-mag.com/1999-10/gear_01.html 414 URL: http://www.linux-mag.com/1999-10/gear_01.html
417 Keywords: mouse, driver, gpm. 415 Keywords: mouse, driver, gpm.
418 Description: The title says it all. 416 Description: The title says it all.
419 417
420 * Title: "More on Mouse Drivers" 418 * Title: "More on Mouse Drivers"
421 Author: Alan Cox. 419 Author: Alan Cox.
422 URL: http://www.linux-mag.com/1999-11/gear_01.html 420 URL: http://www.linux-mag.com/1999-11/gear_01.html
423 Keywords: mouse, driver, gpm, races, asynchronous I/O. 421 Keywords: mouse, driver, gpm, races, asynchronous I/O.
424 Description: The title still says it all. 422 Description: The title still says it all.
425 423
426 * Title: "Writing Video4linux Radio Driver" 424 * Title: "Writing Video4linux Radio Driver"
427 Author: Alan Cox. 425 Author: Alan Cox.
428 URL: http://www.linux-mag.com/1999-12/gear_01.html 426 URL: http://www.linux-mag.com/1999-12/gear_01.html
429 Keywords: video4linux, driver, radio, radio devices. 427 Keywords: video4linux, driver, radio, radio devices.
430 Description: The title says it all. 428 Description: The title says it all.
431 429
432 * Title: "Video4linux Drivers, Part 1: Video-Capture Device" 430 * Title: "Video4linux Drivers, Part 1: Video-Capture Device"
433 Author: Alan Cox. 431 Author: Alan Cox.
434 URL: http://www.linux-mag.com/2000-01/gear_01.html 432 URL: http://www.linux-mag.com/2000-01/gear_01.html
435 Keywords: video4linux, driver, video capture, capture devices, 433 Keywords: video4linux, driver, video capture, capture devices,
436 camera driver. 434 camera driver.
437 Description: The title says it all. 435 Description: The title says it all.
438 436
439 * Title: "Video4linux Drivers, Part 2: Video-capture Devices" 437 * Title: "Video4linux Drivers, Part 2: Video-capture Devices"
440 Author: Alan Cox. 438 Author: Alan Cox.
441 URL: http://www.linux-mag.com/2000-02/gear_01.html 439 URL: http://www.linux-mag.com/2000-02/gear_01.html
442 Keywords: video4linux, driver, video capture, capture devices, 440 Keywords: video4linux, driver, video capture, capture devices,
443 camera driver, control, query capabilities, capability, facility. 441 camera driver, control, query capabilities, capability, facility.
444 Description: The title says it all. 442 Description: The title says it all.
445 443
446 * Title: "PCI Management in Linux 2.2" 444 * Title: "PCI Management in Linux 2.2"
447 Author: Alan Cox. 445 Author: Alan Cox.
448 URL: http://www.linux-mag.com/2000-03/gear_01.html 446 URL: http://www.linux-mag.com/2000-03/gear_01.html
449 Keywords: PCI, bus, bus-mastering. 447 Keywords: PCI, bus, bus-mastering.
450 Description: The title says it all. 448 Description: The title says it all.
451 449
452 * Title: "Linux 2.4 Kernel Internals" 450 * Title: "Linux 2.4 Kernel Internals"
453 Author: Tigran Aivazian and Christoph Hellwig. 451 Author: Tigran Aivazian and Christoph Hellwig.
454 URL: http://www.moses.uklinux.net/patches/lki.html 452 URL: http://www.moses.uklinux.net/patches/lki.html
@@ -456,13 +454,11 @@
456 Description: A little book used for a short training course. 454 Description: A little book used for a short training course.
457 Covers building the kernel image, booting (including SMP bootup), 455 Covers building the kernel image, booting (including SMP bootup),
458 process management, VFS and more. 456 process management, VFS and more.
459 457
460 * Title: "Linux IP Networking. A Guide to the Implementation and 458 * Title: "Linux IP Networking. A Guide to the Implementation and
461 Modification of the Linux Protocol Stack." 459 Modification of the Linux Protocol Stack."
462 Author: Glenn Herrin. 460 Author: Glenn Herrin.
463 URL: 461 URL: http://www.cs.unh.edu/cnrg/gherrin
464 http://kernelnewbies.org/documents/ipnetworking/linuxipnetworking.
465 html
466 Keywords: network, networking, protocol, IP, UDP, TCP, connection, 462 Keywords: network, networking, protocol, IP, UDP, TCP, connection,
467 socket, receiving, transmitting, forwarding, routing, packets, 463 socket, receiving, transmitting, forwarding, routing, packets,
468 modules, /proc, sk_buff, FIB, tags. 464 modules, /proc, sk_buff, FIB, tags.
@@ -495,7 +491,7 @@
495 drivers for the Linux PCMCIA Card Services interface. It also 491 drivers for the Linux PCMCIA Card Services interface. It also
496 describes how to write user-mode utilities for communicating with 492 describes how to write user-mode utilities for communicating with
497 Card Services. 493 Card Services.
498 494
499 * Title: "The Linux Kernel NFSD Implementation" 495 * Title: "The Linux Kernel NFSD Implementation"
500 Author: Neil Brown. 496 Author: Neil Brown.
501 URL: 497 URL:
@@ -591,47 +587,22 @@
591 Pages: 520. 587 Pages: 520.
592 ISBN: 2-212-08932-5 588 ISBN: 2-212-08932-5
593 Notes: French. 589 Notes: French.
594 590
595 * Title: "The Linux Kernel Book"
596 Author: Remy Card, Eric Dumas, Franck Mevel.
597 Publisher: John Wiley & Sons.
598 Date: 1998.
599 ISBN: 0-471-98141-9
600 Notes: English translation.
601
602 * Title: "Linux 2.0"
603 Author: Remy Card, Eric Dumas, Franck Mevel.
604 Publisher: Gestión 2000.
605 Date: 1997.
606 Pages: 501.
607 ISBN: 8-480-88208-5
608 Notes: Spanish translation.
609
610 * Title: "Unix internals -- the new frontiers" 591 * Title: "Unix internals -- the new frontiers"
611 Author: Uresh Vahalia. 592 Author: Uresh Vahalia.
612 Publisher: Prentice Hall. 593 Publisher: Prentice Hall.
613 Date: 1996. 594 Date: 1996.
614 Pages: 600. 595 Pages: 600.
615 ISBN: 0-13-101908-2 596 ISBN: 0-13-101908-2
616 597
617 * Title: "Linux Core Kernel Commentary. Guide to Insider's Knowledge 598 * Title: "The Design and Implementation of the 4.4 BSD UNIX
618 on the Core Kernel of the Linux Code" 599 Operating System"
619 Author: Scott Maxwell. 600 Author: Marshall Kirk McKusick, Keith Bostic, Michael J. Karels,
620 Publisher: Coriolis. 601 John S. Quarterman.
621 Date: 1999. 602 Publisher: Addison-Wesley.
622 Pages: 592. 603 Date: 1996.
623 ISBN: 1-57610-469-9 604 ISBN: 0-201-54979-4
624 Notes: CD-ROM included. Line by line commentary of the kernel 605
625 code.
626
627 * Title: "Linux IP Stacks Commentary"
628 Author: Stephen Satchell and HBJ Clifford.
629 Publisher: Coriolis.
630 Date: 2000.
631 Pages: ???.
632 ISBN: 1-57610-470-2
633 Notes: Line by line source code commentary book.
634
635 * Title: "Programming for the real world - POSIX.4" 606 * Title: "Programming for the real world - POSIX.4"
636 Author: Bill O. Gallmeister. 607 Author: Bill O. Gallmeister.
637 Publisher: O'Reilly & Associates, Inc.. 608 Publisher: O'Reilly & Associates, Inc..
@@ -640,18 +611,32 @@
640 ISBN: I-56592-074-0 611 ISBN: I-56592-074-0
641 Notes: Though not being directly about Linux, Linux aims to be 612 Notes: Though not being directly about Linux, Linux aims to be
642 POSIX. Good reference. 613 POSIX. Good reference.
643 614
644 * Title: "Understanding the Linux Kernel" 615 * Title: "UNIX Systems for Modern Architectures: Symmetric
645 Author: Daniel P. Bovet and Marco Cesati. 616 Multiprocesssing and Caching for Kernel Programmers"
646 Publisher: O'Reilly & Associates, Inc.. 617 Author: Curt Schimmel.
647 Date: 2000. 618 Publisher: Addison Wesley.
648 Pages: 702. 619 Date: June, 1994.
649 ISBN: 0-596-00002-2 620 Pages: 432.
650 Notes: Further information in 621 ISBN: 0-201-63338-8
651 http://www.oreilly.com/catalog/linuxkernel/ 622
652 623 * Title: "The Design and Implementation of the 4.3 BSD UNIX
624 Operating System"
625 Author: Samuel J. Leffler, Marshall Kirk McKusick, Michael J.
626 Karels, John S. Quarterman.
627 Publisher: Addison-Wesley.
628 Date: 1989 (reprinted with corrections on October, 1990).
629 ISBN: 0-201-06196-1
630
631 * Title: "The Design of the UNIX Operating System"
632 Author: Maurice J. Bach.
633 Publisher: Prentice Hall.
634 Date: 1986.
635 Pages: 471.
636 ISBN: 0-13-201757-1
637
653 MISCELLANEOUS: 638 MISCELLANEOUS:
654 639
655 * Name: linux/Documentation 640 * Name: linux/Documentation
656 Author: Many. 641 Author: Many.
657 URL: Just look inside your kernel sources. 642 URL: Just look inside your kernel sources.
@@ -660,7 +645,7 @@
660 inside the Documentation directory. Some pages from this document 645 inside the Documentation directory. Some pages from this document
661 (including this document itself) have been moved there, and might 646 (including this document itself) have been moved there, and might
662 be more up to date than the web version. 647 be more up to date than the web version.
663 648
664 * Name: "Linux Source Driver" 649 * Name: "Linux Source Driver"
665 URL: http://lsd.linux.cz 650 URL: http://lsd.linux.cz
666 Keywords: Browsing source code. 651 Keywords: Browsing source code.
@@ -671,7 +656,7 @@
671 you can search Linux kernel (fulltext, macros, types, functions 656 you can search Linux kernel (fulltext, macros, types, functions
672 and variables) and LSD can generate patches for you on the fly 657 and variables) and LSD can generate patches for you on the fly
673 (files, directories or kernel)". 658 (files, directories or kernel)".
674 659
675 * Name: "Linux Kernel Source Reference" 660 * Name: "Linux Kernel Source Reference"
676 Author: Thomas Graichen. 661 Author: Thomas Graichen.
677 URL: http://innominate.org/~graichen/projects/lksr/ 662 URL: http://innominate.org/~graichen/projects/lksr/
@@ -681,27 +666,27 @@
681 sources of any version starting from 1.0 up to the (daily updated) 666 sources of any version starting from 1.0 up to the (daily updated)
682 current version available. Also you can check the differences 667 current version available. Also you can check the differences
683 between two versions of a file". 668 between two versions of a file".
684 669
685 * Name: "Cross-Referencing Linux" 670 * Name: "Cross-Referencing Linux"
686 URL: http://lxr.linux.no/source/ 671 URL: http://lxr.linux.no/source/
687 Keywords: Browsing source code. 672 Keywords: Browsing source code.
688 Description: Another web-based Linux kernel source code browser. 673 Description: Another web-based Linux kernel source code browser.
689 Lots of cross references to variables and functions. You can see 674 Lots of cross references to variables and functions. You can see
690 where they are defined and where they are used. 675 where they are defined and where they are used.
691 676
692 * Name: "Linux Weekly News" 677 * Name: "Linux Weekly News"
693 URL: http://lwn.net 678 URL: http://lwn.net
694 Keywords: latest kernel news. 679 Keywords: latest kernel news.
695 Description: The title says it all. There's a fixed kernel section 680 Description: The title says it all. There's a fixed kernel section
696 summarizing developers' work, bug fixes, new features and versions 681 summarizing developers' work, bug fixes, new features and versions
697 produced during the week. Published every Thursday. 682 produced during the week. Published every Thursday.
698 683
699 * Name: "Kernel Traffic" 684 * Name: "Kernel Traffic"
700 URL: http://www.kerneltraffic.org/kernel-traffic/ 685 URL: http://kt.zork.net/kernel-traffic/
701 Keywords: linux-kernel mailing list, weekly kernel news. 686 Keywords: linux-kernel mailing list, weekly kernel news.
702 Description: Weekly newsletter covering the most relevant 687 Description: Weekly newsletter covering the most relevant
703 discussions of the linux-kernel mailing list. 688 discussions of the linux-kernel mailing list.
704 689
705 * Name: "CuTTiNG.eDGe.LiNuX" 690 * Name: "CuTTiNG.eDGe.LiNuX"
706 URL: http://edge.kernelnotes.org 691 URL: http://edge.kernelnotes.org
707 Keywords: changelist. 692 Keywords: changelist.
@@ -709,7 +694,7 @@
709 release. What's new, what's better, what's changed. Myrdraal reads 694 release. What's new, what's better, what's changed. Myrdraal reads
710 the patches and describes them. Pointers to the patches are there, 695 the patches and describes them. Pointers to the patches are there,
711 too. 696 too.
712 697
713 * Name: "New linux-kernel Mailing List FAQ" 698 * Name: "New linux-kernel Mailing List FAQ"
714 URL: http://www.tux.org/lkml/ 699 URL: http://www.tux.org/lkml/
715 Keywords: linux-kernel mailing list FAQ. 700 Keywords: linux-kernel mailing list FAQ.
@@ -719,7 +704,7 @@
719 it. Read it to see how to join the mailing list. Dozens of 704 it. Read it to see how to join the mailing list. Dozens of
720 interesting questions regarding the list, Linux, developers (who 705 interesting questions regarding the list, Linux, developers (who
721 is ...?), terms (what is...?) are answered here too. Just read it. 706 is ...?), terms (what is...?) are answered here too. Just read it.
722 707
723 * Name: "Linux Virtual File System" 708 * Name: "Linux Virtual File System"
724 Author: Peter J. Braam. 709 Author: Peter J. Braam.
725 URL: http://www.coda.cs.cmu.edu/doc/talks/linuxvfs/ 710 URL: http://www.coda.cs.cmu.edu/doc/talks/linuxvfs/
@@ -727,10 +712,10 @@
727 Description: Set of slides, presumably from a presentation on the 712 Description: Set of slides, presumably from a presentation on the
728 Linux VFS layer. Covers version 2.1.x, with dentries and the 713 Linux VFS layer. Covers version 2.1.x, with dentries and the
729 dcache. 714 dcache.
730 715
731 * Name: "Gary's Encyclopedia - The Linux Kernel" 716 * Name: "Gary's Encyclopedia - The Linux Kernel"
732 Author: Gary (I suppose...). 717 Author: Gary (I suppose...).
733 URL: http://members.aa.net/~swear/pedia/kernel.html 718 URL: http://www.lisoleg.net/cgi-bin/lisoleg.pl?view=kernel.htm
734 Keywords: links, not found here?. 719 Keywords: links, not found here?.
735 Description: Gary's Encyclopedia exists to allow the rapid finding 720 Description: Gary's Encyclopedia exists to allow the rapid finding
736 of documentation and other information of interest to GNU/Linux 721 of documentation and other information of interest to GNU/Linux
@@ -738,7 +723,7 @@
738 categories. This link is for kernel-specific links, documents, 723 categories. This link is for kernel-specific links, documents,
739 sites... Look there if you could not find here what you were 724 sites... Look there if you could not find here what you were
740 looking for. 725 looking for.
741 726
742 * Name: "The home page of Linux-MM" 727 * Name: "The home page of Linux-MM"
743 Author: The Linux-MM team. 728 Author: The Linux-MM team.
744 URL: http://linux-mm.org/ 729 URL: http://linux-mm.org/
@@ -747,7 +732,7 @@
747 Description: Site devoted to Linux Memory Management development. 732 Description: Site devoted to Linux Memory Management development.
748 Memory related patches, HOWTOs, links, mm developers... Don't miss 733 Memory related patches, HOWTOs, links, mm developers... Don't miss
749 it if you are interested in memory management development! 734 it if you are interested in memory management development!
750 735
751 * Name: "Kernel Newbies IRC Channel" 736 * Name: "Kernel Newbies IRC Channel"
752 URL: http://www.kernelnewbies.org 737 URL: http://www.kernelnewbies.org
753 Keywords: IRC, newbies, channel, asking doubts. 738 Keywords: IRC, newbies, channel, asking doubts.
diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt
index 25d298517104..84c3bd05c639 100644
--- a/Documentation/kernel-parameters.txt
+++ b/Documentation/kernel-parameters.txt
@@ -48,6 +48,7 @@ parameter is applicable:
48 ISAPNP ISA PnP code is enabled. 48 ISAPNP ISA PnP code is enabled.
49 ISDN Appropriate ISDN support is enabled. 49 ISDN Appropriate ISDN support is enabled.
50 JOY Appropriate joystick support is enabled. 50 JOY Appropriate joystick support is enabled.
51 LIBATA Libata driver is enabled
51 LP Printer support is enabled. 52 LP Printer support is enabled.
52 LOOP Loopback device support is enabled. 53 LOOP Loopback device support is enabled.
53 M68k M68k architecture is enabled. 54 M68k M68k architecture is enabled.
@@ -78,6 +79,7 @@ parameter is applicable:
78 Documentation/scsi/. 79 Documentation/scsi/.
79 SELINUX SELinux support is enabled. 80 SELINUX SELinux support is enabled.
80 SERIAL Serial support is enabled. 81 SERIAL Serial support is enabled.
82 SH SuperH architecture is enabled.
81 SMP The kernel is an SMP kernel. 83 SMP The kernel is an SMP kernel.
82 SPARC Sparc architecture is enabled. 84 SPARC Sparc architecture is enabled.
83 SWSUSP Software suspend is enabled. 85 SWSUSP Software suspend is enabled.
@@ -104,6 +106,9 @@ loader, and have no meaning to the kernel directly.
104Do not modify the syntax of boot loader parameters without extreme 106Do not modify the syntax of boot loader parameters without extreme
105need or coordination with <Documentation/i386/boot.txt>. 107need or coordination with <Documentation/i386/boot.txt>.
106 108
109There are also arch-specific kernel-parameters not documented here.
110See for example <Documentation/x86_64/boot-options.txt>.
111
107Note that ALL kernel parameters listed below are CASE SENSITIVE, and that 112Note that ALL kernel parameters listed below are CASE SENSITIVE, and that
108a trailing = on the name of any parameter states that that parameter will 113a trailing = on the name of any parameter states that that parameter will
109be entered as an environment variable, whereas its absence indicates that 114be entered as an environment variable, whereas its absence indicates that
@@ -121,7 +126,8 @@ and is between 256 and 4096 characters. It is defined in the file
121 See header of drivers/scsi/53c7xx.c. 126 See header of drivers/scsi/53c7xx.c.
122 See also Documentation/scsi/ncr53c7xx.txt. 127 See also Documentation/scsi/ncr53c7xx.txt.
123 128
124 acpi= [HW,ACPI] Advanced Configuration and Power Interface 129 acpi= [HW,ACPI,X86-64,i386]
130 Advanced Configuration and Power Interface
125 Format: { force | off | ht | strict | noirq } 131 Format: { force | off | ht | strict | noirq }
126 force -- enable ACPI if default was off 132 force -- enable ACPI if default was off
127 off -- disable ACPI if default was on 133 off -- disable ACPI if default was on
@@ -132,6 +138,12 @@ and is between 256 and 4096 characters. It is defined in the file
132 138
133 See also Documentation/pm.txt, pci=noacpi 139 See also Documentation/pm.txt, pci=noacpi
134 140
141 acpi_apic_instance= [ACPI, IOAPIC]
142 Format: <int>
143 2: use 2nd APIC table, if available
144 1,0: use 1st APIC table
145 default: 0
146
135 acpi_sleep= [HW,ACPI] Sleep options 147 acpi_sleep= [HW,ACPI] Sleep options
136 Format: { s3_bios, s3_mode } 148 Format: { s3_bios, s3_mode }
137 See Documentation/power/video.txt 149 See Documentation/power/video.txt
@@ -169,19 +181,41 @@ and is between 256 and 4096 characters. It is defined in the file
169 that require a timer override, but don't have 181 that require a timer override, but don't have
170 HPET 182 HPET
171 183
172 acpi_dbg_layer= [HW,ACPI] 184 acpi.debug_layer= [HW,ACPI]
173 Format: <int> 185 Format: <int>
174 Each bit of the <int> indicates an ACPI debug layer, 186 Each bit of the <int> indicates an ACPI debug layer,
175 1: enable, 0: disable. It is useful for boot time 187 1: enable, 0: disable. It is useful for boot time
176 debugging. After system has booted up, it can be set 188 debugging. After system has booted up, it can be set
177 via /proc/acpi/debug_layer. 189 via /sys/module/acpi/parameters/debug_layer.
178 190 CONFIG_ACPI_DEBUG must be enabled for this to produce any output.
179 acpi_dbg_level= [HW,ACPI] 191 Available bits (add the numbers together) to enable debug output
192 for specific parts of the ACPI subsystem:
193 0x01 utilities 0x02 hardware 0x04 events 0x08 tables
194 0x10 namespace 0x20 parser 0x40 dispatcher
195 0x80 executer 0x100 resources 0x200 acpica debugger
196 0x400 os services 0x800 acpica disassembler.
197 The number can be in decimal or prefixed with 0x in hex.
198 Warning: Many of these options can produce a lot of
199 output and make your system unusable. Be very careful.
200
201 acpi.debug_level= [HW,ACPI]
180 Format: <int> 202 Format: <int>
181 Each bit of the <int> indicates an ACPI debug level, 203 Each bit of the <int> indicates an ACPI debug level,
182 1: enable, 0: disable. It is useful for boot time 204 1: enable, 0: disable. It is useful for boot time
183 debugging. After system has booted up, it can be set 205 debugging. After system has booted up, it can be set
184 via /proc/acpi/debug_level. 206 via /sys/module/acpi/parameters/debug_level.
207 CONFIG_ACPI_DEBUG must be enabled for this to produce any output.
208 Available bits (add the numbers together) to enable different
209 debug output levels of the ACPI subsystem:
210 0x01 error 0x02 warn 0x04 init 0x08 debug object
211 0x10 info 0x20 init names 0x40 parse 0x80 load
212 0x100 dispatch 0x200 execute 0x400 names 0x800 operation region
213 0x1000 bfield 0x2000 tables 0x4000 values 0x8000 objects
214 0x10000 resources 0x20000 user requests 0x40000 package.
215 The number can be in decimal or prefixed with 0x in hex.
216 Warning: Many of these options can produce a lot of
217 output and make your system unusable. Be very careful.
218
185 219
186 acpi_fake_ecdt [HW,ACPI] Workaround failure due to BIOS lacking ECDT 220 acpi_fake_ecdt [HW,ACPI] Workaround failure due to BIOS lacking ECDT
187 221
@@ -361,6 +395,11 @@ and is between 256 and 4096 characters. It is defined in the file
361 clocksource is not available, it defaults to PIT. 395 clocksource is not available, it defaults to PIT.
362 Format: { pit | tsc | cyclone | pmtmr } 396 Format: { pit | tsc | cyclone | pmtmr }
363 397
398 code_bytes [IA32] How many bytes of object code to print in an
399 oops report.
400 Range: 0 - 8192
401 Default: 64
402
364 disable_8254_timer 403 disable_8254_timer
365 enable_8254_timer 404 enable_8254_timer
366 [IA32/X86_64] Disable/Enable interrupt 0 timer routing 405 [IA32/X86_64] Disable/Enable interrupt 0 timer routing
@@ -476,7 +515,7 @@ and is between 256 and 4096 characters. It is defined in the file
476 515
477 dtc3181e= [HW,SCSI] 516 dtc3181e= [HW,SCSI]
478 517
479 earlyprintk= [IA-32,X86-64] 518 earlyprintk= [IA-32,X86-64,SH]
480 earlyprintk=vga 519 earlyprintk=vga
481 earlyprintk=serial[,ttySn[,baudrate]] 520 earlyprintk=serial[,ttySn[,baudrate]]
482 521
@@ -601,6 +640,10 @@ and is between 256 and 4096 characters. It is defined in the file
601 highmem otherwise. This also works to reduce highmem 640 highmem otherwise. This also works to reduce highmem
602 size on bigger boxes. 641 size on bigger boxes.
603 642
643 highres= [KNL] Enable/disable high resolution timer mode.
644 Valid parameters: "on", "off"
645 Default: "on"
646
604 hisax= [HW,ISDN] 647 hisax= [HW,ISDN]
605 See Documentation/isdn/README.HiSax. 648 See Documentation/isdn/README.HiSax.
606 649
@@ -759,6 +802,9 @@ and is between 256 and 4096 characters. It is defined in the file
759 lapic [IA-32,APIC] Enable the local APIC even if BIOS 802 lapic [IA-32,APIC] Enable the local APIC even if BIOS
760 disabled it. 803 disabled it.
761 804
805 lapic_timer_c2_ok [IA-32,x86-64,APIC] trust the local apic timer in
806 C2 power state.
807
762 lasi= [HW,SCSI] PARISC LASI driver for the 53c700 chip 808 lasi= [HW,SCSI] PARISC LASI driver for the 53c700 chip
763 Format: addr:<io>,irq:<irq> 809 Format: addr:<io>,irq:<irq>
764 810
@@ -851,7 +897,14 @@ and is between 256 and 4096 characters. It is defined in the file
851 Format: <1-256> 897 Format: <1-256>
852 898
853 maxcpus= [SMP] Maximum number of processors that an SMP kernel 899 maxcpus= [SMP] Maximum number of processors that an SMP kernel
854 should make use of 900 should make use of.
901 Using "nosmp" or "maxcpus=0" will disable SMP
902 entirely (the MPS table probe still happens, though).
903 A command-line option of "maxcpus=<NUM>", where <NUM>
904 is an integer greater than 0, limits the maximum number
905 of CPUs activated in SMP mode to <NUM>.
906 Using "maxcpus=1" on an SMP kernel is the trivial
907 case of an SMP kernel with only one CPU.
855 908
856 max_addr=[KMG] [KNL,BOOT,ia64] All physical memory greater than or 909 max_addr=[KMG] [KNL,BOOT,ia64] All physical memory greater than or
857 equal to this physical address is ignored. 910 equal to this physical address is ignored.
@@ -1026,6 +1079,10 @@ and is between 256 and 4096 characters. It is defined in the file
1026 emulation library even if a 387 maths coprocessor 1079 emulation library even if a 387 maths coprocessor
1027 is present. 1080 is present.
1028 1081
1082 noacpi [LIBATA] Disables use of ACPI in libata suspend/resume
1083 when set.
1084 Format: <int>
1085
1029 noaliencache [MM, NUMA] Disables the allcoation of alien caches in 1086 noaliencache [MM, NUMA] Disables the allcoation of alien caches in
1030 the slab allocator. Saves per-node memory, but will 1087 the slab allocator. Saves per-node memory, but will
1031 impact performance on real NUMA hardware. 1088 impact performance on real NUMA hardware.
@@ -1070,6 +1127,10 @@ and is between 256 and 4096 characters. It is defined in the file
1070 in certain environments such as networked servers or 1127 in certain environments such as networked servers or
1071 real-time systems. 1128 real-time systems.
1072 1129
1130 nohz= [KNL] Boottime enable/disable dynamic ticks
1131 Valid arguments: on, off
1132 Default: on
1133
1073 noirqbalance [IA-32,SMP,KNL] Disable kernel irq balancing 1134 noirqbalance [IA-32,SMP,KNL] Disable kernel irq balancing
1074 1135
1075 noirqdebug [IA-32] Disables the code which attempts to detect and 1136 noirqdebug [IA-32] Disables the code which attempts to detect and
@@ -1087,6 +1148,8 @@ and is between 256 and 4096 characters. It is defined in the file
1087 1148
1088 nolapic [IA-32,APIC] Do not enable or use the local APIC. 1149 nolapic [IA-32,APIC] Do not enable or use the local APIC.
1089 1150
1151 nolapic_timer [IA-32,APIC] Do not use the local APIC timer.
1152
1090 noltlbs [PPC] Do not use large page/tlb entries for kernel 1153 noltlbs [PPC] Do not use large page/tlb entries for kernel
1091 lowmem mapping on PPC40x. 1154 lowmem mapping on PPC40x.
1092 1155
@@ -1259,6 +1322,12 @@ and is between 256 and 4096 characters. It is defined in the file
1259 This sorting is done to get a device 1322 This sorting is done to get a device
1260 order compatible with older (<= 2.4) kernels. 1323 order compatible with older (<= 2.4) kernels.
1261 nobfsort Don't sort PCI devices into breadth-first order. 1324 nobfsort Don't sort PCI devices into breadth-first order.
1325 cbiosize=nn[KMG] The fixed amount of bus space which is
1326 reserved for the CardBus bridge's IO window.
1327 The default value is 256 bytes.
1328 cbmemsize=nn[KMG] The fixed amount of bus space which is
1329 reserved for the CardBus bridge's memory
1330 window. The default value is 64 megabytes.
1262 1331
1263 pcmv= [HW,PCMCIA] BadgePAD 4 1332 pcmv= [HW,PCMCIA] BadgePAD 4
1264 1333
@@ -1396,6 +1465,8 @@ and is between 256 and 4096 characters. It is defined in the file
1396 in <PAGE_SIZE> units (needed only for swap files). 1465 in <PAGE_SIZE> units (needed only for swap files).
1397 See Documentation/power/swsusp-and-swap-files.txt 1466 See Documentation/power/swsusp-and-swap-files.txt
1398 1467
1468 retain_initrd [RAM] Keep initrd memory after extraction
1469
1399 rhash_entries= [KNL,NET] 1470 rhash_entries= [KNL,NET]
1400 Set number of hash buckets for route cache 1471 Set number of hash buckets for route cache
1401 1472
@@ -1649,6 +1720,22 @@ and is between 256 and 4096 characters. It is defined in the file
1649 stifb= [HW] 1720 stifb= [HW]
1650 Format: bpp:<bpp1>[:<bpp2>[:<bpp3>...]] 1721 Format: bpp:<bpp1>[:<bpp2>[:<bpp3>...]]
1651 1722
1723 sunrpc.pool_mode=
1724 [NFS]
1725 Control how the NFS server code allocates CPUs to
1726 service thread pools. Depending on how many NICs
1727 you have and where their interrupts are bound, this
1728 option will affect which CPUs will do NFS serving.
1729 Note: this parameter cannot be changed while the
1730 NFS server is running.
1731
1732 auto the server chooses an appropriate mode
1733 automatically using heuristics
1734 global a single global pool contains all CPUs
1735 percpu one pool for each CPU
1736 pernode one pool for each NUMA node (equivalent
1737 to global on non-NUMA machines)
1738
1652 swiotlb= [IA-64] Number of I/O TLB slabs 1739 swiotlb= [IA-64] Number of I/O TLB slabs
1653 1740
1654 switches= [HW,M68k] 1741 switches= [HW,M68k]
@@ -1722,10 +1809,17 @@ and is between 256 and 4096 characters. It is defined in the file
1722 Note that genuine overcurrent events won't be 1809 Note that genuine overcurrent events won't be
1723 reported either. 1810 reported either.
1724 1811
1812 usbcore.autosuspend=
1813 [USB] The autosuspend time delay (in seconds) used
1814 for newly-detected USB devices (default 2). This
1815 is the time required before an idle device will be
1816 autosuspended. Devices for which the delay is set
1817 to a negative value won't be autosuspended at all.
1818
1725 usbhid.mousepoll= 1819 usbhid.mousepoll=
1726 [USBHID] The interval which mice are to be polled at. 1820 [USBHID] The interval which mice are to be polled at.
1727 1821
1728 vdso= [IA-32] 1822 vdso= [IA-32,SH]
1729 vdso=1: enable VDSO (default) 1823 vdso=1: enable VDSO (default)
1730 vdso=0: disable VDSO mapping 1824 vdso=0: disable VDSO mapping
1731 1825
diff --git a/Documentation/keys.txt b/Documentation/keys.txt
index 60c665d9cfaa..81d9aa097298 100644
--- a/Documentation/keys.txt
+++ b/Documentation/keys.txt
@@ -859,6 +859,18 @@ payload contents" for more information.
859 void unregister_key_type(struct key_type *type); 859 void unregister_key_type(struct key_type *type);
860 860
861 861
862Under some circumstances, it may be desirable to desirable to deal with a
863bundle of keys. The facility provides access to the keyring type for managing
864such a bundle:
865
866 struct key_type key_type_keyring;
867
868This can be used with a function such as request_key() to find a specific
869keyring in a process's keyrings. A keyring thus found can then be searched
870with keyring_search(). Note that it is not possible to use request_key() to
871search a specific keyring, so using keyrings in this way is of limited utility.
872
873
862=================================== 874===================================
863NOTES ON ACCESSING PAYLOAD CONTENTS 875NOTES ON ACCESSING PAYLOAD CONTENTS
864=================================== 876===================================
diff --git a/Documentation/local_ops.txt b/Documentation/local_ops.txt
new file mode 100644
index 000000000000..b0aca0705d1e
--- /dev/null
+++ b/Documentation/local_ops.txt
@@ -0,0 +1,163 @@
1 Semantics and Behavior of Local Atomic Operations
2
3 Mathieu Desnoyers
4
5
6 This document explains the purpose of the local atomic operations, how
7to implement them for any given architecture and shows how they can be used
8properly. It also stresses on the precautions that must be taken when reading
9those local variables across CPUs when the order of memory writes matters.
10
11
12
13* Purpose of local atomic operations
14
15Local atomic operations are meant to provide fast and highly reentrant per CPU
16counters. They minimize the performance cost of standard atomic operations by
17removing the LOCK prefix and memory barriers normally required to synchronize
18across CPUs.
19
20Having fast per CPU atomic counters is interesting in many cases : it does not
21require disabling interrupts to protect from interrupt handlers and it permits
22coherent counters in NMI handlers. It is especially useful for tracing purposes
23and for various performance monitoring counters.
24
25Local atomic operations only guarantee variable modification atomicity wrt the
26CPU which owns the data. Therefore, care must taken to make sure that only one
27CPU writes to the local_t data. This is done by using per cpu data and making
28sure that we modify it from within a preemption safe context. It is however
29permitted to read local_t data from any CPU : it will then appear to be written
30out of order wrt other memory writes on the owner CPU.
31
32
33* Implementation for a given architecture
34
35It can be done by slightly modifying the standard atomic operations : only
36their UP variant must be kept. It typically means removing LOCK prefix (on
37i386 and x86_64) and any SMP sychronization barrier. If the architecture does
38not have a different behavior between SMP and UP, including asm-generic/local.h
39in your archtecture's local.h is sufficient.
40
41The local_t type is defined as an opaque signed long by embedding an
42atomic_long_t inside a structure. This is made so a cast from this type to a
43long fails. The definition looks like :
44
45typedef struct { atomic_long_t a; } local_t;
46
47
48* How to use local atomic operations
49
50#include <linux/percpu.h>
51#include <asm/local.h>
52
53static DEFINE_PER_CPU(local_t, counters) = LOCAL_INIT(0);
54
55
56* Counting
57
58Counting is done on all the bits of a signed long.
59
60In preemptible context, use get_cpu_var() and put_cpu_var() around local atomic
61operations : it makes sure that preemption is disabled around write access to
62the per cpu variable. For instance :
63
64 local_inc(&get_cpu_var(counters));
65 put_cpu_var(counters);
66
67If you are already in a preemption-safe context, you can directly use
68__get_cpu_var() instead.
69
70 local_inc(&__get_cpu_var(counters));
71
72
73
74* Reading the counters
75
76Those local counters can be read from foreign CPUs to sum the count. Note that
77the data seen by local_read across CPUs must be considered to be out of order
78relatively to other memory writes happening on the CPU that owns the data.
79
80 long sum = 0;
81 for_each_online_cpu(cpu)
82 sum += local_read(&per_cpu(counters, cpu));
83
84If you want to use a remote local_read to synchronize access to a resource
85between CPUs, explicit smp_wmb() and smp_rmb() memory barriers must be used
86respectively on the writer and the reader CPUs. It would be the case if you use
87the local_t variable as a counter of bytes written in a buffer : there should
88be a smp_wmb() between the buffer write and the counter increment and also a
89smp_rmb() between the counter read and the buffer read.
90
91
92Here is a sample module which implements a basic per cpu counter using local.h.
93
94--- BEGIN ---
95/* test-local.c
96 *
97 * Sample module for local.h usage.
98 */
99
100
101#include <asm/local.h>
102#include <linux/module.h>
103#include <linux/timer.h>
104
105static DEFINE_PER_CPU(local_t, counters) = LOCAL_INIT(0);
106
107static struct timer_list test_timer;
108
109/* IPI called on each CPU. */
110static void test_each(void *info)
111{
112 /* Increment the counter from a non preemptible context */
113 printk("Increment on cpu %d\n", smp_processor_id());
114 local_inc(&__get_cpu_var(counters));
115
116 /* This is what incrementing the variable would look like within a
117 * preemptible context (it disables preemption) :
118 *
119 * local_inc(&get_cpu_var(counters));
120 * put_cpu_var(counters);
121 */
122}
123
124static void do_test_timer(unsigned long data)
125{
126 int cpu;
127
128 /* Increment the counters */
129 on_each_cpu(test_each, NULL, 0, 1);
130 /* Read all the counters */
131 printk("Counters read from CPU %d\n", smp_processor_id());
132 for_each_online_cpu(cpu) {
133 printk("Read : CPU %d, count %ld\n", cpu,
134 local_read(&per_cpu(counters, cpu)));
135 }
136 del_timer(&test_timer);
137 test_timer.expires = jiffies + 1000;
138 add_timer(&test_timer);
139}
140
141static int __init test_init(void)
142{
143 /* initialize the timer that will increment the counter */
144 init_timer(&test_timer);
145 test_timer.function = do_test_timer;
146 test_timer.expires = jiffies + 1;
147 add_timer(&test_timer);
148
149 return 0;
150}
151
152static void __exit test_exit(void)
153{
154 del_timer_sync(&test_timer);
155}
156
157module_init(test_init);
158module_exit(test_exit);
159
160MODULE_LICENSE("GPL");
161MODULE_AUTHOR("Mathieu Desnoyers");
162MODULE_DESCRIPTION("Local Atomic Ops");
163--- END ---
diff --git a/Documentation/magic-number.txt b/Documentation/magic-number.txt
index af67faccf4de..0e740c812d12 100644
--- a/Documentation/magic-number.txt
+++ b/Documentation/magic-number.txt
@@ -65,7 +65,6 @@ CMAGIC 0x0111 user include/linux/a.out.h
65MKISS_DRIVER_MAGIC 0x04bf mkiss_channel drivers/net/mkiss.h 65MKISS_DRIVER_MAGIC 0x04bf mkiss_channel drivers/net/mkiss.h
66RISCOM8_MAGIC 0x0907 riscom_port drivers/char/riscom8.h 66RISCOM8_MAGIC 0x0907 riscom_port drivers/char/riscom8.h
67SPECIALIX_MAGIC 0x0907 specialix_port drivers/char/specialix_io8.h 67SPECIALIX_MAGIC 0x0907 specialix_port drivers/char/specialix_io8.h
68AURORA_MAGIC 0x0A18 Aurora_port drivers/sbus/char/aurora.h
69HDLC_MAGIC 0x239e n_hdlc drivers/char/n_hdlc.c 68HDLC_MAGIC 0x239e n_hdlc drivers/char/n_hdlc.c
70APM_BIOS_MAGIC 0x4101 apm_user arch/i386/kernel/apm.c 69APM_BIOS_MAGIC 0x4101 apm_user arch/i386/kernel/apm.c
71CYCLADES_MAGIC 0x4359 cyclades_port include/linux/cyclades.h 70CYCLADES_MAGIC 0x4359 cyclades_port include/linux/cyclades.h
diff --git a/Documentation/networking/ax25.txt b/Documentation/networking/ax25.txt
index 37c25b0925f0..8257dbf9be57 100644
--- a/Documentation/networking/ax25.txt
+++ b/Documentation/networking/ax25.txt
@@ -1,16 +1,10 @@
1To use the amateur radio protocols within Linux you will need to get a 1To use the amateur radio protocols within Linux you will need to get a
2suitable copy of the AX.25 Utilities. More detailed information about these 2suitable copy of the AX.25 Utilities. More detailed information about
3and associated programs can be found on http://zone.pspt.fi/~jsn/. 3AX.25, NET/ROM and ROSE, associated programs and and utilities can be
4 4found on http://www.linux-ax25.org.
5For more information about the AX.25, NET/ROM and ROSE protocol stacks, see
6the AX25-HOWTO written by Terry Dawson <terry@perf.no.itg.telstra.com.au>
7who is also the AX.25 Utilities maintainer.
8 5
9There is an active mailing list for discussing Linux amateur radio matters 6There is an active mailing list for discussing Linux amateur radio matters
10called linux-hams. To subscribe to it, send a message to 7called linux-hams@vger.kernel.org. To subscribe to it, send a message to
11majordomo@vger.kernel.org with the words "subscribe linux-hams" in the body 8majordomo@vger.kernel.org with the words "subscribe linux-hams" in the body
12of the message, the subject field is ignored. 9of the message, the subject field is ignored. You don't need to be
13 10subscribed to post but of course that means you might miss an answer.
14Jonathan G4KLX
15
16g4klx@g4klx.demon.co.uk
diff --git a/Documentation/networking/bcm43xx.txt b/Documentation/networking/bcm43xx.txt
index 28541d2bee1e..a136721499bf 100644
--- a/Documentation/networking/bcm43xx.txt
+++ b/Documentation/networking/bcm43xx.txt
@@ -2,35 +2,88 @@
2 BCM43xx Linux Driver Project 2 BCM43xx Linux Driver Project
3 ============================ 3 ============================
4 4
5About this software 5Introduction
6------------------- 6------------
7 7
8The goal of this project is to develop a linux driver for Broadcom 8Many of the wireless devices found in modern notebook computers are
9BCM43xx chips, based on the specification at 9based on the wireless chips produced by Broadcom. These devices have
10http://bcm-specs.sipsolutions.net/ 10been a problem for Linux users as there is no open-source driver
11available. In addition, Broadcom has not released specifications
12for the device, and driver availability has been limited to the
13binary-only form used in the GPL versions of AP hardware such as the
14Linksys WRT54G, and the Windows and OS X drivers. Before this project
15began, the only way to use these devices were to use the Windows or
16OS X drivers with either the Linuxant or ndiswrapper modules. There
17is a strong penalty if this method is used as loading the binary-only
18module "taints" the kernel, and no kernel developer will help diagnose
19any kernel problems.
11 20
12The project page is http://bcm43xx.berlios.de/ 21Development
22-----------
13 23
24This driver has been developed using
25a clean-room technique that is described at
26http://bcm-specs.sipsolutions.net/ReverseEngineeringProcess. For legal
27reasons, none of the clean-room crew works on the on the Linux driver,
28and none of the Linux developers sees anything but the specifications,
29which are the ultimate product of the reverse-engineering group.
14 30
15Requirements 31Software
16------------ 32--------
33
34Since the release of the 2.6.17 kernel, the bcm43xx driver has been
35distributed with the kernel source, and is prebuilt in most, if not
36all, distributions. There is, however, additional software that is
37required. The firmware used by the chip is the intellectual property
38of Broadcom and they have not given the bcm43xx team redistribution
39rights to this firmware. Since we cannot legally redistribute
40the firwmare we cannot include it with the driver. Furthermore, it
41cannot be placed in the downloadable archives of any distributing
42organization; therefore, the user is responsible for obtaining the
43firmware and placing it in the appropriate location so that the driver
44can find it when initializing.
45
46To help with this process, the bcm43xx developers provide a separate
47program named bcm43xx-fwcutter to "cut" the firmware out of a
48Windows or OS X driver and write the extracted files to the proper
49location. This program is usually provided with the distribution;
50however, it may be downloaded from
51
52http://developer.berlios.de/project/showfiles.php?group_id=4547
17 53
181) Linux Kernel 2.6.16 or later 54The firmware is available in two versions. V3 firmware is used with
19 http://www.kernel.org/ 55the in-kernel bcm43xx driver that uses a software MAC layer called
56SoftMAC, and will have a microcode revision of 0x127 or smaller. The
57V4 firmware is used by an out-of-kernel driver employing a variation of
58the Devicescape MAC layer known as d80211. Once bcm43xx-d80211 reaches
59a satisfactory level of development, it will replace bcm43xx-softmac
60in the kernel as it is much more flexible and powerful.
20 61
21 You may want to configure your kernel with: 62A source for the latest V3 firmware is
22 63
23 CONFIG_DEBUG_FS (optional): 64http://downloads.openwrt.org/sources/wl_apsta-3.130.20.0.o
24 -> Kernel hacking
25 -> Debug Filesystem
26 65
272) SoftMAC IEEE 802.11 Networking Stack extension and patched ieee80211 66Once this file is downloaded, the command
28 modules: 67'bcm43xx-fwcutter -w <dir> <filename>'
29 http://softmac.sipsolutions.net/ 68will extract the microcode and write it to directory
69<dir>. The correct directory will depend on your distribution;
70however, most use '/lib/firmware'. Once this step is completed,
71the bcm3xx driver should load when the system is booted. To see
72any messages relating to the driver, issue the command 'dmesg |
73grep bcm43xx' from a terminal window. If there are any problems,
74please send that output to Bcm43xx-dev@lists.berlios.de.
30 75
313) Firmware Files 76Although the driver has been in-kernel since 2.6.17, the earliest
77version is quite limited in its capability. Patches that include
78all features of later versions are available for the stable kernel
79versions from 2.6.18. These will be needed if you use a BCM4318,
80or a PCI Express version (BCM4311 and BCM4312). In addition, if you
81have an early BCM4306 and more than 1 GB RAM, your kernel will need
82to be patched. These patches, which are being updated regularly,
83are available at ftp://lwfinger.dynalias.org/patches. Look for
84combined_2.6.YY.patch. Of course you will need kernel source downloaded
85from kernel.org, or the source from your distribution.
32 86
33 Please try fwcutter. Fwcutter can extract the firmware from various 87If you build your own kernel, please enable CONFIG_BCM43XX_DEBUG
34 binary driver files. It supports driver files from Windows, MacOS and 88and CONFIG_IEEE80211_SOFTMAC_DEBUG. The log information provided is
35 Linux. You can get fwcutter from http://bcm43xx.berlios.de/. 89essential for solving any problems.
36 Also, fwcutter comes with a README file for further instructions.
diff --git a/Documentation/networking/bonding.txt b/Documentation/networking/bonding.txt
index de809e58092f..1da566630831 100644
--- a/Documentation/networking/bonding.txt
+++ b/Documentation/networking/bonding.txt
@@ -920,40 +920,9 @@ options, you may wish to use the "max_bonds" module parameter,
920documented above. 920documented above.
921 921
922 To create multiple bonding devices with differing options, it 922 To create multiple bonding devices with differing options, it
923is necessary to load the bonding driver multiple times. Note that 923is necessary to use bonding parameters exported by sysfs, documented
924current versions of the sysconfig network initialization scripts 924in the section below.
925handle this automatically; if your distro uses these scripts, no
926special action is needed. See the section Configuring Bonding
927Devices, above, if you're not sure about your network initialization
928scripts.
929
930 To load multiple instances of the module, it is necessary to
931specify a different name for each instance (the module loading system
932requires that every loaded module, even multiple instances of the same
933module, have a unique name). This is accomplished by supplying
934multiple sets of bonding options in /etc/modprobe.conf, for example:
935
936alias bond0 bonding
937options bond0 -o bond0 mode=balance-rr miimon=100
938
939alias bond1 bonding
940options bond1 -o bond1 mode=balance-alb miimon=50
941
942 will load the bonding module two times. The first instance is
943named "bond0" and creates the bond0 device in balance-rr mode with an
944miimon of 100. The second instance is named "bond1" and creates the
945bond1 device in balance-alb mode with an miimon of 50.
946
947 In some circumstances (typically with older distributions),
948the above does not work, and the second bonding instance never sees
949its options. In that case, the second options line can be substituted
950as follows:
951
952install bond1 /sbin/modprobe --ignore-install bonding -o bond1 \
953 mode=balance-alb miimon=50
954 925
955 This may be repeated any number of times, specifying a new and
956unique name in place of bond1 for each subsequent instance.
957 926
9583.4 Configuring Bonding Manually via Sysfs 9273.4 Configuring Bonding Manually via Sysfs
959------------------------------------------ 928------------------------------------------
diff --git a/Documentation/networking/dccp.txt b/Documentation/networking/dccp.txt
index 387482e46c47..4504cc59e405 100644
--- a/Documentation/networking/dccp.txt
+++ b/Documentation/networking/dccp.txt
@@ -57,6 +57,16 @@ DCCP_SOCKOPT_SEND_CSCOV is for the receiver and has a different meaning: it
57 coverage value are also acceptable. The higher the number, the more 57 coverage value are also acceptable. The higher the number, the more
58 restrictive this setting (see [RFC 4340, sec. 9.2.1]). 58 restrictive this setting (see [RFC 4340, sec. 9.2.1]).
59 59
60The following two options apply to CCID 3 exclusively and are getsockopt()-only.
61In either case, a TFRC info struct (defined in <linux/tfrc.h>) is returned.
62DCCP_SOCKOPT_CCID_RX_INFO
63 Returns a `struct tfrc_rx_info' in optval; the buffer for optval and
64 optlen must be set to at least sizeof(struct tfrc_rx_info).
65DCCP_SOCKOPT_CCID_TX_INFO
66 Returns a `struct tfrc_tx_info' in optval; the buffer for optval and
67 optlen must be set to at least sizeof(struct tfrc_tx_info).
68
69
60Sysctl variables 70Sysctl variables
61================ 71================
62Several DCCP default parameters can be managed by the following sysctls 72Several DCCP default parameters can be managed by the following sysctls
diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt
index a0f6842368c3..af6a63ab9026 100644
--- a/Documentation/networking/ip-sysctl.txt
+++ b/Documentation/networking/ip-sysctl.txt
@@ -147,6 +147,11 @@ tcp_available_congestion_control - STRING
147 More congestion control algorithms may be available as modules, 147 More congestion control algorithms may be available as modules,
148 but not loaded. 148 but not loaded.
149 149
150tcp_base_mss - INTEGER
151 The initial value of search_low to be used by Packetization Layer
152 Path MTU Discovery (MTU probing). If MTU probing is enabled,
153 this is the inital MSS used by the connection.
154
150tcp_congestion_control - STRING 155tcp_congestion_control - STRING
151 Set the congestion control algorithm to be used for new 156 Set the congestion control algorithm to be used for new
152 connections. The algorithm "reno" is always available, but 157 connections. The algorithm "reno" is always available, but
@@ -174,11 +179,31 @@ tcp_fin_timeout - INTEGER
174 because they eat maximum 1.5K of memory, but they tend 179 because they eat maximum 1.5K of memory, but they tend
175 to live longer. Cf. tcp_max_orphans. 180 to live longer. Cf. tcp_max_orphans.
176 181
177tcp_frto - BOOLEAN 182tcp_frto - INTEGER
178 Enables F-RTO, an enhanced recovery algorithm for TCP retransmission 183 Enables F-RTO, an enhanced recovery algorithm for TCP retransmission
179 timeouts. It is particularly beneficial in wireless environments 184 timeouts. It is particularly beneficial in wireless environments
180 where packet loss is typically due to random radio interference 185 where packet loss is typically due to random radio interference
181 rather than intermediate router congestion. 186 rather than intermediate router congestion. If set to 1, basic
187 version is enabled. 2 enables SACK enhanced F-RTO, which is
188 EXPERIMENTAL. The basic version can be used also when SACK is
189 enabled for a flow through tcp_sack sysctl.
190
191tcp_frto_response - INTEGER
192 When F-RTO has detected that a TCP retransmission timeout was
193 spurious (i.e, the timeout would have been avoided had TCP set a
194 longer retransmission timeout), TCP has several options what to do
195 next. Possible values are:
196 0 Rate halving based; a smooth and conservative response,
197 results in halved cwnd and ssthresh after one RTT
198 1 Very conservative response; not recommended because even
199 though being valid, it interacts poorly with the rest of
200 Linux TCP, halves cwnd and ssthresh immediately
201 2 Aggressive response; undoes congestion control measures
202 that are now known to be unnecessary (ignoring the
203 possibility of a lost retransmission that would require
204 TCP to be more cautious), cwnd and ssthresh are restored
205 to the values prior timeout
206 Default: 0 (rate halving based)
182 207
183tcp_keepalive_time - INTEGER 208tcp_keepalive_time - INTEGER
184 How often TCP sends out keepalive messages when keepalive is enabled. 209 How often TCP sends out keepalive messages when keepalive is enabled.
@@ -243,6 +268,27 @@ tcp_mem - vector of 3 INTEGERs: min, pressure, max
243 Defaults are calculated at boot time from amount of available 268 Defaults are calculated at boot time from amount of available
244 memory. 269 memory.
245 270
271tcp_moderate_rcvbuf - BOOLEAN
272 If set, TCP performs receive buffer autotuning, attempting to
273 automatically size the buffer (no greater than tcp_rmem[2]) to
274 match the size required by the path for full throughput. Enabled by
275 default.
276
277tcp_mtu_probing - INTEGER
278 Controls TCP Packetization-Layer Path MTU Discovery. Takes three
279 values:
280 0 - Disabled
281 1 - Disabled by default, enabled when an ICMP black hole detected
282 2 - Always enabled, use initial MSS of tcp_base_mss.
283
284tcp_no_metrics_save - BOOLEAN
285 By default, TCP saves various connection metrics in the route cache
286 when the connection closes, so that connections established in the
287 near future can use these to set initial conditions. Usually, this
288 increases overall performance, but may sometimes cause performance
289 degredation. If set, TCP will not cache metrics on closing
290 connections.
291
246tcp_orphan_retries - INTEGER 292tcp_orphan_retries - INTEGER
247 How may times to retry before killing TCP connection, closed 293 How may times to retry before killing TCP connection, closed
248 by our side. Default value 7 corresponds to ~50sec-16min 294 by our side. Default value 7 corresponds to ~50sec-16min
@@ -825,6 +871,15 @@ accept_redirects - BOOLEAN
825 Functional default: enabled if local forwarding is disabled. 871 Functional default: enabled if local forwarding is disabled.
826 disabled if local forwarding is enabled. 872 disabled if local forwarding is enabled.
827 873
874accept_source_route - INTEGER
875 Accept source routing (routing extension header).
876
877 > 0: Accept routing header.
878 = 0: Accept only routing header type 2.
879 < 0: Do not accept routing header.
880
881 Default: 0
882
828autoconf - BOOLEAN 883autoconf - BOOLEAN
829 Autoconfigure addresses using Prefix Information in Router 884 Autoconfigure addresses using Prefix Information in Router
830 Advertisements. 885 Advertisements.
@@ -960,7 +1015,12 @@ bridge-nf-call-ip6tables - BOOLEAN
960 Default: 1 1015 Default: 1
961 1016
962bridge-nf-filter-vlan-tagged - BOOLEAN 1017bridge-nf-filter-vlan-tagged - BOOLEAN
963 1 : pass bridged vlan-tagged ARP/IP traffic to arptables/iptables. 1018 1 : pass bridged vlan-tagged ARP/IP/IPv6 traffic to {arp,ip,ip6}tables.
1019 0 : disable this.
1020 Default: 1
1021
1022bridge-nf-filter-pppoe-tagged - BOOLEAN
1023 1 : pass bridged pppoe-tagged IP/IPv6 traffic to {ip,ip6}tables.
964 0 : disable this. 1024 0 : disable this.
965 Default: 1 1025 Default: 1
966 1026
diff --git a/Documentation/networking/rxrpc.txt b/Documentation/networking/rxrpc.txt
new file mode 100644
index 000000000000..cae231b1c134
--- /dev/null
+++ b/Documentation/networking/rxrpc.txt
@@ -0,0 +1,859 @@
1 ======================
2 RxRPC NETWORK PROTOCOL
3 ======================
4
5The RxRPC protocol driver provides a reliable two-phase transport on top of UDP
6that can be used to perform RxRPC remote operations. This is done over sockets
7of AF_RXRPC family, using sendmsg() and recvmsg() with control data to send and
8receive data, aborts and errors.
9
10Contents of this document:
11
12 (*) Overview.
13
14 (*) RxRPC protocol summary.
15
16 (*) AF_RXRPC driver model.
17
18 (*) Control messages.
19
20 (*) Socket options.
21
22 (*) Security.
23
24 (*) Example client usage.
25
26 (*) Example server usage.
27
28 (*) AF_RXRPC kernel interface.
29
30
31========
32OVERVIEW
33========
34
35RxRPC is a two-layer protocol. There is a session layer which provides
36reliable virtual connections using UDP over IPv4 (or IPv6) as the transport
37layer, but implements a real network protocol; and there's the presentation
38layer which renders structured data to binary blobs and back again using XDR
39(as does SunRPC):
40
41 +-------------+
42 | Application |
43 +-------------+
44 | XDR | Presentation
45 +-------------+
46 | RxRPC | Session
47 +-------------+
48 | UDP | Transport
49 +-------------+
50
51
52AF_RXRPC provides:
53
54 (1) Part of an RxRPC facility for both kernel and userspace applications by
55 making the session part of it a Linux network protocol (AF_RXRPC).
56
57 (2) A two-phase protocol. The client transmits a blob (the request) and then
58 receives a blob (the reply), and the server receives the request and then
59 transmits the reply.
60
61 (3) Retention of the reusable bits of the transport system set up for one call
62 to speed up subsequent calls.
63
64 (4) A secure protocol, using the Linux kernel's key retention facility to
65 manage security on the client end. The server end must of necessity be
66 more active in security negotiations.
67
68AF_RXRPC does not provide XDR marshalling/presentation facilities. That is
69left to the application. AF_RXRPC only deals in blobs. Even the operation ID
70is just the first four bytes of the request blob, and as such is beyond the
71kernel's interest.
72
73
74Sockets of AF_RXRPC family are:
75
76 (1) created as type SOCK_DGRAM;
77
78 (2) provided with a protocol of the type of underlying transport they're going
79 to use - currently only PF_INET is supported.
80
81
82The Andrew File System (AFS) is an example of an application that uses this and
83that has both kernel (filesystem) and userspace (utility) components.
84
85
86======================
87RXRPC PROTOCOL SUMMARY
88======================
89
90An overview of the RxRPC protocol:
91
92 (*) RxRPC sits on top of another networking protocol (UDP is the only option
93 currently), and uses this to provide network transport. UDP ports, for
94 example, provide transport endpoints.
95
96 (*) RxRPC supports multiple virtual "connections" from any given transport
97 endpoint, thus allowing the endpoints to be shared, even to the same
98 remote endpoint.
99
100 (*) Each connection goes to a particular "service". A connection may not go
101 to multiple services. A service may be considered the RxRPC equivalent of
102 a port number. AF_RXRPC permits multiple services to share an endpoint.
103
104 (*) Client-originating packets are marked, thus a transport endpoint can be
105 shared between client and server connections (connections have a
106 direction).
107
108 (*) Up to a billion connections may be supported concurrently between one
109 local transport endpoint and one service on one remote endpoint. An RxRPC
110 connection is described by seven numbers:
111
112 Local address }
113 Local port } Transport (UDP) address
114 Remote address }
115 Remote port }
116 Direction
117 Connection ID
118 Service ID
119
120 (*) Each RxRPC operation is a "call". A connection may make up to four
121 billion calls, but only up to four calls may be in progress on a
122 connection at any one time.
123
124 (*) Calls are two-phase and asymmetric: the client sends its request data,
125 which the service receives; then the service transmits the reply data
126 which the client receives.
127
128 (*) The data blobs are of indefinite size, the end of a phase is marked with a
129 flag in the packet. The number of packets of data making up one blob may
130 not exceed 4 billion, however, as this would cause the sequence number to
131 wrap.
132
133 (*) The first four bytes of the request data are the service operation ID.
134
135 (*) Security is negotiated on a per-connection basis. The connection is
136 initiated by the first data packet on it arriving. If security is
137 requested, the server then issues a "challenge" and then the client
138 replies with a "response". If the response is successful, the security is
139 set for the lifetime of that connection, and all subsequent calls made
140 upon it use that same security. In the event that the server lets a
141 connection lapse before the client, the security will be renegotiated if
142 the client uses the connection again.
143
144 (*) Calls use ACK packets to handle reliability. Data packets are also
145 explicitly sequenced per call.
146
147 (*) There are two types of positive acknowledgement: hard-ACKs and soft-ACKs.
148 A hard-ACK indicates to the far side that all the data received to a point
149 has been received and processed; a soft-ACK indicates that the data has
150 been received but may yet be discarded and re-requested. The sender may
151 not discard any transmittable packets until they've been hard-ACK'd.
152
153 (*) Reception of a reply data packet implicitly hard-ACK's all the data
154 packets that make up the request.
155
156 (*) An call is complete when the request has been sent, the reply has been
157 received and the final hard-ACK on the last packet of the reply has
158 reached the server.
159
160 (*) An call may be aborted by either end at any time up to its completion.
161
162
163=====================
164AF_RXRPC DRIVER MODEL
165=====================
166
167About the AF_RXRPC driver:
168
169 (*) The AF_RXRPC protocol transparently uses internal sockets of the transport
170 protocol to represent transport endpoints.
171
172 (*) AF_RXRPC sockets map onto RxRPC connection bundles. Actual RxRPC
173 connections are handled transparently. One client socket may be used to
174 make multiple simultaneous calls to the same service. One server socket
175 may handle calls from many clients.
176
177 (*) Additional parallel client connections will be initiated to support extra
178 concurrent calls, up to a tunable limit.
179
180 (*) Each connection is retained for a certain amount of time [tunable] after
181 the last call currently using it has completed in case a new call is made
182 that could reuse it.
183
184 (*) Each internal UDP socket is retained [tunable] for a certain amount of
185 time [tunable] after the last connection using it discarded, in case a new
186 connection is made that could use it.
187
188 (*) A client-side connection is only shared between calls if they have have
189 the same key struct describing their security (and assuming the calls
190 would otherwise share the connection). Non-secured calls would also be
191 able to share connections with each other.
192
193 (*) A server-side connection is shared if the client says it is.
194
195 (*) ACK'ing is handled by the protocol driver automatically, including ping
196 replying.
197
198 (*) SO_KEEPALIVE automatically pings the other side to keep the connection
199 alive [TODO].
200
201 (*) If an ICMP error is received, all calls affected by that error will be
202 aborted with an appropriate network error passed through recvmsg().
203
204
205Interaction with the user of the RxRPC socket:
206
207 (*) A socket is made into a server socket by binding an address with a
208 non-zero service ID.
209
210 (*) In the client, sending a request is achieved with one or more sendmsgs,
211 followed by the reply being received with one or more recvmsgs.
212
213 (*) The first sendmsg for a request to be sent from a client contains a tag to
214 be used in all other sendmsgs or recvmsgs associated with that call. The
215 tag is carried in the control data.
216
217 (*) connect() is used to supply a default destination address for a client
218 socket. This may be overridden by supplying an alternate address to the
219 first sendmsg() of a call (struct msghdr::msg_name).
220
221 (*) If connect() is called on an unbound client, a random local port will
222 bound before the operation takes place.
223
224 (*) A server socket may also be used to make client calls. To do this, the
225 first sendmsg() of the call must specify the target address. The server's
226 transport endpoint is used to send the packets.
227
228 (*) Once the application has received the last message associated with a call,
229 the tag is guaranteed not to be seen again, and so it can be used to pin
230 client resources. A new call can then be initiated with the same tag
231 without fear of interference.
232
233 (*) In the server, a request is received with one or more recvmsgs, then the
234 the reply is transmitted with one or more sendmsgs, and then the final ACK
235 is received with a last recvmsg.
236
237 (*) When sending data for a call, sendmsg is given MSG_MORE if there's more
238 data to come on that call.
239
240 (*) When receiving data for a call, recvmsg flags MSG_MORE if there's more
241 data to come for that call.
242
243 (*) When receiving data or messages for a call, MSG_EOR is flagged by recvmsg
244 to indicate the terminal message for that call.
245
246 (*) A call may be aborted by adding an abort control message to the control
247 data. Issuing an abort terminates the kernel's use of that call's tag.
248 Any messages waiting in the receive queue for that call will be discarded.
249
250 (*) Aborts, busy notifications and challenge packets are delivered by recvmsg,
251 and control data messages will be set to indicate the context. Receiving
252 an abort or a busy message terminates the kernel's use of that call's tag.
253
254 (*) The control data part of the msghdr struct is used for a number of things:
255
256 (*) The tag of the intended or affected call.
257
258 (*) Sending or receiving errors, aborts and busy notifications.
259
260 (*) Notifications of incoming calls.
261
262 (*) Sending debug requests and receiving debug replies [TODO].
263
264 (*) When the kernel has received and set up an incoming call, it sends a
265 message to server application to let it know there's a new call awaiting
266 its acceptance [recvmsg reports a special control message]. The server
267 application then uses sendmsg to assign a tag to the new call. Once that
268 is done, the first part of the request data will be delivered by recvmsg.
269
270 (*) The server application has to provide the server socket with a keyring of
271 secret keys corresponding to the security types it permits. When a secure
272 connection is being set up, the kernel looks up the appropriate secret key
273 in the keyring and then sends a challenge packet to the client and
274 receives a response packet. The kernel then checks the authorisation of
275 the packet and either aborts the connection or sets up the security.
276
277 (*) The name of the key a client will use to secure its communications is
278 nominated by a socket option.
279
280
281Notes on recvmsg:
282
283 (*) If there's a sequence of data messages belonging to a particular call on
284 the receive queue, then recvmsg will keep working through them until:
285
286 (a) it meets the end of that call's received data,
287
288 (b) it meets a non-data message,
289
290 (c) it meets a message belonging to a different call, or
291
292 (d) it fills the user buffer.
293
294 If recvmsg is called in blocking mode, it will keep sleeping, awaiting the
295 reception of further data, until one of the above four conditions is met.
296
297 (2) MSG_PEEK operates similarly, but will return immediately if it has put any
298 data in the buffer rather than sleeping until it can fill the buffer.
299
300 (3) If a data message is only partially consumed in filling a user buffer,
301 then the remainder of that message will be left on the front of the queue
302 for the next taker. MSG_TRUNC will never be flagged.
303
304 (4) If there is more data to be had on a call (it hasn't copied the last byte
305 of the last data message in that phase yet), then MSG_MORE will be
306 flagged.
307
308
309================
310CONTROL MESSAGES
311================
312
313AF_RXRPC makes use of control messages in sendmsg() and recvmsg() to multiplex
314calls, to invoke certain actions and to report certain conditions. These are:
315
316 MESSAGE ID SRT DATA MEANING
317 ======================= === =========== ===============================
318 RXRPC_USER_CALL_ID sr- User ID App's call specifier
319 RXRPC_ABORT srt Abort code Abort code to issue/received
320 RXRPC_ACK -rt n/a Final ACK received
321 RXRPC_NET_ERROR -rt error num Network error on call
322 RXRPC_BUSY -rt n/a Call rejected (server busy)
323 RXRPC_LOCAL_ERROR -rt error num Local error encountered
324 RXRPC_NEW_CALL -r- n/a New call received
325 RXRPC_ACCEPT s-- n/a Accept new call
326
327 (SRT = usable in Sendmsg / delivered by Recvmsg / Terminal message)
328
329 (*) RXRPC_USER_CALL_ID
330
331 This is used to indicate the application's call ID. It's an unsigned long
332 that the app specifies in the client by attaching it to the first data
333 message or in the server by passing it in association with an RXRPC_ACCEPT
334 message. recvmsg() passes it in conjunction with all messages except
335 those of the RXRPC_NEW_CALL message.
336
337 (*) RXRPC_ABORT
338
339 This is can be used by an application to abort a call by passing it to
340 sendmsg, or it can be delivered by recvmsg to indicate a remote abort was
341 received. Either way, it must be associated with an RXRPC_USER_CALL_ID to
342 specify the call affected. If an abort is being sent, then error EBADSLT
343 will be returned if there is no call with that user ID.
344
345 (*) RXRPC_ACK
346
347 This is delivered to a server application to indicate that the final ACK
348 of a call was received from the client. It will be associated with an
349 RXRPC_USER_CALL_ID to indicate the call that's now complete.
350
351 (*) RXRPC_NET_ERROR
352
353 This is delivered to an application to indicate that an ICMP error message
354 was encountered in the process of trying to talk to the peer. An
355 errno-class integer value will be included in the control message data
356 indicating the problem, and an RXRPC_USER_CALL_ID will indicate the call
357 affected.
358
359 (*) RXRPC_BUSY
360
361 This is delivered to a client application to indicate that a call was
362 rejected by the server due to the server being busy. It will be
363 associated with an RXRPC_USER_CALL_ID to indicate the rejected call.
364
365 (*) RXRPC_LOCAL_ERROR
366
367 This is delivered to an application to indicate that a local error was
368 encountered and that a call has been aborted because of it. An
369 errno-class integer value will be included in the control message data
370 indicating the problem, and an RXRPC_USER_CALL_ID will indicate the call
371 affected.
372
373 (*) RXRPC_NEW_CALL
374
375 This is delivered to indicate to a server application that a new call has
376 arrived and is awaiting acceptance. No user ID is associated with this,
377 as a user ID must subsequently be assigned by doing an RXRPC_ACCEPT.
378
379 (*) RXRPC_ACCEPT
380
381 This is used by a server application to attempt to accept a call and
382 assign it a user ID. It should be associated with an RXRPC_USER_CALL_ID
383 to indicate the user ID to be assigned. If there is no call to be
384 accepted (it may have timed out, been aborted, etc.), then sendmsg will
385 return error ENODATA. If the user ID is already in use by another call,
386 then error EBADSLT will be returned.
387
388
389==============
390SOCKET OPTIONS
391==============
392
393AF_RXRPC sockets support a few socket options at the SOL_RXRPC level:
394
395 (*) RXRPC_SECURITY_KEY
396
397 This is used to specify the description of the key to be used. The key is
398 extracted from the calling process's keyrings with request_key() and
399 should be of "rxrpc" type.
400
401 The optval pointer points to the description string, and optlen indicates
402 how long the string is, without the NUL terminator.
403
404 (*) RXRPC_SECURITY_KEYRING
405
406 Similar to above but specifies a keyring of server secret keys to use (key
407 type "keyring"). See the "Security" section.
408
409 (*) RXRPC_EXCLUSIVE_CONNECTION
410
411 This is used to request that new connections should be used for each call
412 made subsequently on this socket. optval should be NULL and optlen 0.
413
414 (*) RXRPC_MIN_SECURITY_LEVEL
415
416 This is used to specify the minimum security level required for calls on
417 this socket. optval must point to an int containing one of the following
418 values:
419
420 (a) RXRPC_SECURITY_PLAIN
421
422 Encrypted checksum only.
423
424 (b) RXRPC_SECURITY_AUTH
425
426 Encrypted checksum plus packet padded and first eight bytes of packet
427 encrypted - which includes the actual packet length.
428
429 (c) RXRPC_SECURITY_ENCRYPTED
430
431 Encrypted checksum plus entire packet padded and encrypted, including
432 actual packet length.
433
434
435========
436SECURITY
437========
438
439Currently, only the kerberos 4 equivalent protocol has been implemented
440(security index 2 - rxkad). This requires the rxkad module to be loaded and,
441on the client, tickets of the appropriate type to be obtained from the AFS
442kaserver or the kerberos server and installed as "rxrpc" type keys. This is
443normally done using the klog program. An example simple klog program can be
444found at:
445
446 http://people.redhat.com/~dhowells/rxrpc/klog.c
447
448The payload provided to add_key() on the client should be of the following
449form:
450
451 struct rxrpc_key_sec2_v1 {
452 uint16_t security_index; /* 2 */
453 uint16_t ticket_length; /* length of ticket[] */
454 uint32_t expiry; /* time at which expires */
455 uint8_t kvno; /* key version number */
456 uint8_t __pad[3];
457 uint8_t session_key[8]; /* DES session key */
458 uint8_t ticket[0]; /* the encrypted ticket */
459 };
460
461Where the ticket blob is just appended to the above structure.
462
463
464For the server, keys of type "rxrpc_s" must be made available to the server.
465They have a description of "<serviceID>:<securityIndex>" (eg: "52:2" for an
466rxkad key for the AFS VL service). When such a key is created, it should be
467given the server's secret key as the instantiation data (see the example
468below).
469
470 add_key("rxrpc_s", "52:2", secret_key, 8, keyring);
471
472A keyring is passed to the server socket by naming it in a sockopt. The server
473socket then looks the server secret keys up in this keyring when secure
474incoming connections are made. This can be seen in an example program that can
475be found at:
476
477 http://people.redhat.com/~dhowells/rxrpc/listen.c
478
479
480====================
481EXAMPLE CLIENT USAGE
482====================
483
484A client would issue an operation by:
485
486 (1) An RxRPC socket is set up by:
487
488 client = socket(AF_RXRPC, SOCK_DGRAM, PF_INET);
489
490 Where the third parameter indicates the protocol family of the transport
491 socket used - usually IPv4 but it can also be IPv6 [TODO].
492
493 (2) A local address can optionally be bound:
494
495 struct sockaddr_rxrpc srx = {
496 .srx_family = AF_RXRPC,
497 .srx_service = 0, /* we're a client */
498 .transport_type = SOCK_DGRAM, /* type of transport socket */
499 .transport.sin_family = AF_INET,
500 .transport.sin_port = htons(7000), /* AFS callback */
501 .transport.sin_address = 0, /* all local interfaces */
502 };
503 bind(client, &srx, sizeof(srx));
504
505 This specifies the local UDP port to be used. If not given, a random
506 non-privileged port will be used. A UDP port may be shared between
507 several unrelated RxRPC sockets. Security is handled on a basis of
508 per-RxRPC virtual connection.
509
510 (3) The security is set:
511
512 const char *key = "AFS:cambridge.redhat.com";
513 setsockopt(client, SOL_RXRPC, RXRPC_SECURITY_KEY, key, strlen(key));
514
515 This issues a request_key() to get the key representing the security
516 context. The minimum security level can be set:
517
518 unsigned int sec = RXRPC_SECURITY_ENCRYPTED;
519 setsockopt(client, SOL_RXRPC, RXRPC_MIN_SECURITY_LEVEL,
520 &sec, sizeof(sec));
521
522 (4) The server to be contacted can then be specified (alternatively this can
523 be done through sendmsg):
524
525 struct sockaddr_rxrpc srx = {
526 .srx_family = AF_RXRPC,
527 .srx_service = VL_SERVICE_ID,
528 .transport_type = SOCK_DGRAM, /* type of transport socket */
529 .transport.sin_family = AF_INET,
530 .transport.sin_port = htons(7005), /* AFS volume manager */
531 .transport.sin_address = ...,
532 };
533 connect(client, &srx, sizeof(srx));
534
535 (5) The request data should then be posted to the server socket using a series
536 of sendmsg() calls, each with the following control message attached:
537
538 RXRPC_USER_CALL_ID - specifies the user ID for this call
539
540 MSG_MORE should be set in msghdr::msg_flags on all but the last part of
541 the request. Multiple requests may be made simultaneously.
542
543 If a call is intended to go to a destination other then the default
544 specified through connect(), then msghdr::msg_name should be set on the
545 first request message of that call.
546
547 (6) The reply data will then be posted to the server socket for recvmsg() to
548 pick up. MSG_MORE will be flagged by recvmsg() if there's more reply data
549 for a particular call to be read. MSG_EOR will be set on the terminal
550 read for a call.
551
552 All data will be delivered with the following control message attached:
553
554 RXRPC_USER_CALL_ID - specifies the user ID for this call
555
556 If an abort or error occurred, this will be returned in the control data
557 buffer instead, and MSG_EOR will be flagged to indicate the end of that
558 call.
559
560
561====================
562EXAMPLE SERVER USAGE
563====================
564
565A server would be set up to accept operations in the following manner:
566
567 (1) An RxRPC socket is created by:
568
569 server = socket(AF_RXRPC, SOCK_DGRAM, PF_INET);
570
571 Where the third parameter indicates the address type of the transport
572 socket used - usually IPv4.
573
574 (2) Security is set up if desired by giving the socket a keyring with server
575 secret keys in it:
576
577 keyring = add_key("keyring", "AFSkeys", NULL, 0,
578 KEY_SPEC_PROCESS_KEYRING);
579
580 const char secret_key[8] = {
581 0xa7, 0x83, 0x8a, 0xcb, 0xc7, 0x83, 0xec, 0x94 };
582 add_key("rxrpc_s", "52:2", secret_key, 8, keyring);
583
584 setsockopt(server, SOL_RXRPC, RXRPC_SECURITY_KEYRING, "AFSkeys", 7);
585
586 The keyring can be manipulated after it has been given to the socket. This
587 permits the server to add more keys, replace keys, etc. whilst it is live.
588
589 (2) A local address must then be bound:
590
591 struct sockaddr_rxrpc srx = {
592 .srx_family = AF_RXRPC,
593 .srx_service = VL_SERVICE_ID, /* RxRPC service ID */
594 .transport_type = SOCK_DGRAM, /* type of transport socket */
595 .transport.sin_family = AF_INET,
596 .transport.sin_port = htons(7000), /* AFS callback */
597 .transport.sin_address = 0, /* all local interfaces */
598 };
599 bind(server, &srx, sizeof(srx));
600
601 (3) The server is then set to listen out for incoming calls:
602
603 listen(server, 100);
604
605 (4) The kernel notifies the server of pending incoming connections by sending
606 it a message for each. This is received with recvmsg() on the server
607 socket. It has no data, and has a single dataless control message
608 attached:
609
610 RXRPC_NEW_CALL
611
612 The address that can be passed back by recvmsg() at this point should be
613 ignored since the call for which the message was posted may have gone by
614 the time it is accepted - in which case the first call still on the queue
615 will be accepted.
616
617 (5) The server then accepts the new call by issuing a sendmsg() with two
618 pieces of control data and no actual data:
619
620 RXRPC_ACCEPT - indicate connection acceptance
621 RXRPC_USER_CALL_ID - specify user ID for this call
622
623 (6) The first request data packet will then be posted to the server socket for
624 recvmsg() to pick up. At that point, the RxRPC address for the call can
625 be read from the address fields in the msghdr struct.
626
627 Subsequent request data will be posted to the server socket for recvmsg()
628 to collect as it arrives. All but the last piece of the request data will
629 be delivered with MSG_MORE flagged.
630
631 All data will be delivered with the following control message attached:
632
633 RXRPC_USER_CALL_ID - specifies the user ID for this call
634
635 (8) The reply data should then be posted to the server socket using a series
636 of sendmsg() calls, each with the following control messages attached:
637
638 RXRPC_USER_CALL_ID - specifies the user ID for this call
639
640 MSG_MORE should be set in msghdr::msg_flags on all but the last message
641 for a particular call.
642
643 (9) The final ACK from the client will be posted for retrieval by recvmsg()
644 when it is received. It will take the form of a dataless message with two
645 control messages attached:
646
647 RXRPC_USER_CALL_ID - specifies the user ID for this call
648 RXRPC_ACK - indicates final ACK (no data)
649
650 MSG_EOR will be flagged to indicate that this is the final message for
651 this call.
652
653(10) Up to the point the final packet of reply data is sent, the call can be
654 aborted by calling sendmsg() with a dataless message with the following
655 control messages attached:
656
657 RXRPC_USER_CALL_ID - specifies the user ID for this call
658 RXRPC_ABORT - indicates abort code (4 byte data)
659
660 Any packets waiting in the socket's receive queue will be discarded if
661 this is issued.
662
663Note that all the communications for a particular service take place through
664the one server socket, using control messages on sendmsg() and recvmsg() to
665determine the call affected.
666
667
668=========================
669AF_RXRPC KERNEL INTERFACE
670=========================
671
672The AF_RXRPC module also provides an interface for use by in-kernel utilities
673such as the AFS filesystem. This permits such a utility to:
674
675 (1) Use different keys directly on individual client calls on one socket
676 rather than having to open a whole slew of sockets, one for each key it
677 might want to use.
678
679 (2) Avoid having RxRPC call request_key() at the point of issue of a call or
680 opening of a socket. Instead the utility is responsible for requesting a
681 key at the appropriate point. AFS, for instance, would do this during VFS
682 operations such as open() or unlink(). The key is then handed through
683 when the call is initiated.
684
685 (3) Request the use of something other than GFP_KERNEL to allocate memory.
686
687 (4) Avoid the overhead of using the recvmsg() call. RxRPC messages can be
688 intercepted before they get put into the socket Rx queue and the socket
689 buffers manipulated directly.
690
691To use the RxRPC facility, a kernel utility must still open an AF_RXRPC socket,
692bind an addess as appropriate and listen if it's to be a server socket, but
693then it passes this to the kernel interface functions.
694
695The kernel interface functions are as follows:
696
697 (*) Begin a new client call.
698
699 struct rxrpc_call *
700 rxrpc_kernel_begin_call(struct socket *sock,
701 struct sockaddr_rxrpc *srx,
702 struct key *key,
703 unsigned long user_call_ID,
704 gfp_t gfp);
705
706 This allocates the infrastructure to make a new RxRPC call and assigns
707 call and connection numbers. The call will be made on the UDP port that
708 the socket is bound to. The call will go to the destination address of a
709 connected client socket unless an alternative is supplied (srx is
710 non-NULL).
711
712 If a key is supplied then this will be used to secure the call instead of
713 the key bound to the socket with the RXRPC_SECURITY_KEY sockopt. Calls
714 secured in this way will still share connections if at all possible.
715
716 The user_call_ID is equivalent to that supplied to sendmsg() in the
717 control data buffer. It is entirely feasible to use this to point to a
718 kernel data structure.
719
720 If this function is successful, an opaque reference to the RxRPC call is
721 returned. The caller now holds a reference on this and it must be
722 properly ended.
723
724 (*) End a client call.
725
726 void rxrpc_kernel_end_call(struct rxrpc_call *call);
727
728 This is used to end a previously begun call. The user_call_ID is expunged
729 from AF_RXRPC's knowledge and will not be seen again in association with
730 the specified call.
731
732 (*) Send data through a call.
733
734 int rxrpc_kernel_send_data(struct rxrpc_call *call, struct msghdr *msg,
735 size_t len);
736
737 This is used to supply either the request part of a client call or the
738 reply part of a server call. msg.msg_iovlen and msg.msg_iov specify the
739 data buffers to be used. msg_iov may not be NULL and must point
740 exclusively to in-kernel virtual addresses. msg.msg_flags may be given
741 MSG_MORE if there will be subsequent data sends for this call.
742
743 The msg must not specify a destination address, control data or any flags
744 other than MSG_MORE. len is the total amount of data to transmit.
745
746 (*) Abort a call.
747
748 void rxrpc_kernel_abort_call(struct rxrpc_call *call, u32 abort_code);
749
750 This is used to abort a call if it's still in an abortable state. The
751 abort code specified will be placed in the ABORT message sent.
752
753 (*) Intercept received RxRPC messages.
754
755 typedef void (*rxrpc_interceptor_t)(struct sock *sk,
756 unsigned long user_call_ID,
757 struct sk_buff *skb);
758
759 void
760 rxrpc_kernel_intercept_rx_messages(struct socket *sock,
761 rxrpc_interceptor_t interceptor);
762
763 This installs an interceptor function on the specified AF_RXRPC socket.
764 All messages that would otherwise wind up in the socket's Rx queue are
765 then diverted to this function. Note that care must be taken to process
766 the messages in the right order to maintain DATA message sequentiality.
767
768 The interceptor function itself is provided with the address of the socket
769 and handling the incoming message, the ID assigned by the kernel utility
770 to the call and the socket buffer containing the message.
771
772 The skb->mark field indicates the type of message:
773
774 MARK MEANING
775 =============================== =======================================
776 RXRPC_SKB_MARK_DATA Data message
777 RXRPC_SKB_MARK_FINAL_ACK Final ACK received for an incoming call
778 RXRPC_SKB_MARK_BUSY Client call rejected as server busy
779 RXRPC_SKB_MARK_REMOTE_ABORT Call aborted by peer
780 RXRPC_SKB_MARK_NET_ERROR Network error detected
781 RXRPC_SKB_MARK_LOCAL_ERROR Local error encountered
782 RXRPC_SKB_MARK_NEW_CALL New incoming call awaiting acceptance
783
784 The remote abort message can be probed with rxrpc_kernel_get_abort_code().
785 The two error messages can be probed with rxrpc_kernel_get_error_number().
786 A new call can be accepted with rxrpc_kernel_accept_call().
787
788 Data messages can have their contents extracted with the usual bunch of
789 socket buffer manipulation functions. A data message can be determined to
790 be the last one in a sequence with rxrpc_kernel_is_data_last(). When a
791 data message has been used up, rxrpc_kernel_data_delivered() should be
792 called on it..
793
794 Non-data messages should be handled to rxrpc_kernel_free_skb() to dispose
795 of. It is possible to get extra refs on all types of message for later
796 freeing, but this may pin the state of a call until the message is finally
797 freed.
798
799 (*) Accept an incoming call.
800
801 struct rxrpc_call *
802 rxrpc_kernel_accept_call(struct socket *sock,
803 unsigned long user_call_ID);
804
805 This is used to accept an incoming call and to assign it a call ID. This
806 function is similar to rxrpc_kernel_begin_call() and calls accepted must
807 be ended in the same way.
808
809 If this function is successful, an opaque reference to the RxRPC call is
810 returned. The caller now holds a reference on this and it must be
811 properly ended.
812
813 (*) Reject an incoming call.
814
815 int rxrpc_kernel_reject_call(struct socket *sock);
816
817 This is used to reject the first incoming call on the socket's queue with
818 a BUSY message. -ENODATA is returned if there were no incoming calls.
819 Other errors may be returned if the call had been aborted (-ECONNABORTED)
820 or had timed out (-ETIME).
821
822 (*) Record the delivery of a data message and free it.
823
824 void rxrpc_kernel_data_delivered(struct sk_buff *skb);
825
826 This is used to record a data message as having been delivered and to
827 update the ACK state for the call. The socket buffer will be freed.
828
829 (*) Free a message.
830
831 void rxrpc_kernel_free_skb(struct sk_buff *skb);
832
833 This is used to free a non-DATA socket buffer intercepted from an AF_RXRPC
834 socket.
835
836 (*) Determine if a data message is the last one on a call.
837
838 bool rxrpc_kernel_is_data_last(struct sk_buff *skb);
839
840 This is used to determine if a socket buffer holds the last data message
841 to be received for a call (true will be returned if it does, false
842 if not).
843
844 The data message will be part of the reply on a client call and the
845 request on an incoming call. In the latter case there will be more
846 messages, but in the former case there will not.
847
848 (*) Get the abort code from an abort message.
849
850 u32 rxrpc_kernel_get_abort_code(struct sk_buff *skb);
851
852 This is used to extract the abort code from a remote abort message.
853
854 (*) Get the error number from a local or network error message.
855
856 int rxrpc_kernel_get_error_number(struct sk_buff *skb);
857
858 This is used to extract the error number from a message indicating either
859 a local error occurred or a network error occurred.
diff --git a/Documentation/networking/wan-router.txt b/Documentation/networking/wan-router.txt
index 653978dcea7f..07dd6d9930a1 100644
--- a/Documentation/networking/wan-router.txt
+++ b/Documentation/networking/wan-router.txt
@@ -250,7 +250,6 @@ PRODUCT COMPONENTS AND RELATED FILES
250 sdladrv.h SDLA support module API definitions 250 sdladrv.h SDLA support module API definitions
251 sdlasfm.h SDLA firmware module definitions 251 sdlasfm.h SDLA firmware module definitions
252 if_wanpipe.h WANPIPE Socket definitions 252 if_wanpipe.h WANPIPE Socket definitions
253 if_wanpipe_common.h WANPIPE Socket/Driver common definitions.
254 sdlapci.h WANPIPE PCI definitions 253 sdlapci.h WANPIPE PCI definitions
255 254
256 255
diff --git a/Documentation/nfsroot.txt b/Documentation/nfsroot.txt
index 719f9a9d60c0..16a7cae2721d 100644
--- a/Documentation/nfsroot.txt
+++ b/Documentation/nfsroot.txt
@@ -67,8 +67,8 @@ nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>]
67 <nfs-options> Standard NFS options. All options are separated by commas. 67 <nfs-options> Standard NFS options. All options are separated by commas.
68 The following defaults are used: 68 The following defaults are used:
69 port = as given by server portmap daemon 69 port = as given by server portmap daemon
70 rsize = 1024 70 rsize = 4096
71 wsize = 1024 71 wsize = 4096
72 timeo = 7 72 timeo = 7
73 retrans = 3 73 retrans = 3
74 acregmin = 3 74 acregmin = 3
diff --git a/Documentation/oops-tracing.txt b/Documentation/oops-tracing.txt
index 2503404ae5c2..ea55ea8bc8ef 100644
--- a/Documentation/oops-tracing.txt
+++ b/Documentation/oops-tracing.txt
@@ -234,6 +234,12 @@ characters, each representing a particular tainted value.
234 6: 'B' if a page-release function has found a bad page reference or 234 6: 'B' if a page-release function has found a bad page reference or
235 some unexpected page flags. 235 some unexpected page flags.
236 236
237 7: 'U' if a user specifically requested that the Tainted flag be set,
238 ' ' otherwise.
239
240 7: 'U' if a user or user application specifically requested that the
241 Tainted flag be set, ' ' otherwise.
242
237The primary reason for the 'Tainted: ' string is to tell kernel 243The primary reason for the 'Tainted: ' string is to tell kernel
238debuggers if this is a clean kernel or if anything unusual has 244debuggers if this is a clean kernel or if anything unusual has
239occurred. Tainting is permanent: even if an offending module is 245occurred. Tainting is permanent: even if an offending module is
diff --git a/Documentation/pci.txt b/Documentation/pci.txt
index fd5028eca13e..cdf2f3c0ab14 100644
--- a/Documentation/pci.txt
+++ b/Documentation/pci.txt
@@ -205,8 +205,8 @@ Tips on when/where to use the above attributes:
205 exclusively called by the probe() routine, can be marked __devinit. 205 exclusively called by the probe() routine, can be marked __devinit.
206 Ditto for remove() and __devexit. 206 Ditto for remove() and __devexit.
207 207
208 o If mydriver_probe() is marked with __devinit(), then all address 208 o If mydriver_remove() is marked with __devexit(), then all address
209 references to mydriver_probe must use __devexit_p(mydriver_probe) 209 references to mydriver_remove must use __devexit_p(mydriver_remove)
210 (in the struct pci_driver declaration for example). 210 (in the struct pci_driver declaration for example).
211 __devexit_p() will generate the function name _or_ NULL if the 211 __devexit_p() will generate the function name _or_ NULL if the
212 function will be discarded. For an example, see drivers/net/tg3.c. 212 function will be discarded. For an example, see drivers/net/tg3.c.
diff --git a/Documentation/power/pci.txt b/Documentation/power/pci.txt
index c750f9f2e76e..b6a3cbf7e846 100644
--- a/Documentation/power/pci.txt
+++ b/Documentation/power/pci.txt
@@ -102,31 +102,28 @@ pci_save_state
102-------------- 102--------------
103 103
104Usage: 104Usage:
105 pci_save_state(dev, buffer); 105 pci_save_state(struct pci_dev *dev);
106 106
107Description: 107Description:
108 Save first 64 bytes of PCI config space. Buffer must be allocated by 108 Save first 64 bytes of PCI config space, along with any additional
109 caller. 109 PCI-Express or PCI-X information.
110 110
111 111
112pci_restore_state 112pci_restore_state
113----------------- 113-----------------
114 114
115Usage: 115Usage:
116 pci_restore_state(dev, buffer); 116 pci_restore_state(struct pci_dev *dev);
117 117
118Description: 118Description:
119 Restore previously saved config space. (First 64 bytes only); 119 Restore previously saved config space.
120
121 If buffer is NULL, then restore what information we know about the
122 device from bootup: BARs and interrupt line.
123 120
124 121
125pci_set_power_state 122pci_set_power_state
126------------------- 123-------------------
127 124
128Usage: 125Usage:
129 pci_set_power_state(dev, state); 126 pci_set_power_state(struct pci_dev *dev, pci_power_t state);
130 127
131Description: 128Description:
132 Transition device to low power state using PCI PM Capabilities 129 Transition device to low power state using PCI PM Capabilities
@@ -142,7 +139,7 @@ pci_enable_wake
142--------------- 139---------------
143 140
144Usage: 141Usage:
145 pci_enable_wake(dev, state, enable); 142 pci_enable_wake(struct pci_dev *dev, pci_power_t state, int enable);
146 143
147Description: 144Description:
148 Enable device to generate PME# during low power state using PCI PM 145 Enable device to generate PME# during low power state using PCI PM
diff --git a/Documentation/powerpc/booting-without-of.txt b/Documentation/powerpc/booting-without-of.txt
index 33994271cb3b..033a3f3b3ab7 100644
--- a/Documentation/powerpc/booting-without-of.txt
+++ b/Documentation/powerpc/booting-without-of.txt
@@ -39,7 +39,7 @@
39 and property data. The old style variable 39 and property data. The old style variable
40 alignment would make it impossible to do 40 alignment would make it impossible to do
41 "simple" insertion of properties using 41 "simple" insertion of properties using
42 memove (thanks Milton for 42 memmove (thanks Milton for
43 noticing). Updated kernel patch as well 43 noticing). Updated kernel patch as well
44 - Correct a few more alignment constraints 44 - Correct a few more alignment constraints
45 - Add a chapter about the device-tree 45 - Add a chapter about the device-tree
@@ -55,7 +55,7 @@
55 55
56 ToDo: 56 ToDo:
57 - Add some definitions of interrupt tree (simple/complex) 57 - Add some definitions of interrupt tree (simple/complex)
58 - Add some definitions for pci host bridges 58 - Add some definitions for PCI host bridges
59 - Add some common address format examples 59 - Add some common address format examples
60 - Add definitions for standard properties and "compatible" 60 - Add definitions for standard properties and "compatible"
61 names for cells that are not already defined by the existing 61 names for cells that are not already defined by the existing
@@ -114,7 +114,7 @@ it with special cases.
114 forth words isn't required), you can enter the kernel with: 114 forth words isn't required), you can enter the kernel with:
115 115
116 r5 : OF callback pointer as defined by IEEE 1275 116 r5 : OF callback pointer as defined by IEEE 1275
117 bindings to powerpc. Only the 32 bit client interface 117 bindings to powerpc. Only the 32-bit client interface
118 is currently supported 118 is currently supported
119 119
120 r3, r4 : address & length of an initrd if any or 0 120 r3, r4 : address & length of an initrd if any or 0
@@ -194,7 +194,7 @@ it with special cases.
194 for this is to keep kernels on embedded systems small and efficient; 194 for this is to keep kernels on embedded systems small and efficient;
195 part of this is due to the fact the code is already that way. In the 195 part of this is due to the fact the code is already that way. In the
196 future, a kernel may support multiple platforms, but only if the 196 future, a kernel may support multiple platforms, but only if the
197 platforms feature the same core architectire. A single kernel build 197 platforms feature the same core architecture. A single kernel build
198 cannot support both configurations with Book E and configurations 198 cannot support both configurations with Book E and configurations
199 with classic Powerpc architectures. 199 with classic Powerpc architectures.
200 200
@@ -215,7 +215,7 @@ of the boot sequences.... someone speak up if this is wrong!
215 enable another config option to select the specific board 215 enable another config option to select the specific board
216 supported. 216 supported.
217 217
218NOTE: If ben doesn't merge the setup files, may need to change this to 218NOTE: If Ben doesn't merge the setup files, may need to change this to
219point to setup_32.c 219point to setup_32.c
220 220
221 221
@@ -256,7 +256,7 @@ struct boot_param_header {
256 u32 off_dt_struct; /* offset to structure */ 256 u32 off_dt_struct; /* offset to structure */
257 u32 off_dt_strings; /* offset to strings */ 257 u32 off_dt_strings; /* offset to strings */
258 u32 off_mem_rsvmap; /* offset to memory reserve map 258 u32 off_mem_rsvmap; /* offset to memory reserve map
259*/ 259 */
260 u32 version; /* format version */ 260 u32 version; /* format version */
261 u32 last_comp_version; /* last compatible version */ 261 u32 last_comp_version; /* last compatible version */
262 262
@@ -265,6 +265,9 @@ struct boot_param_header {
265 booting on */ 265 booting on */
266 /* version 3 fields below */ 266 /* version 3 fields below */
267 u32 size_dt_strings; /* size of the strings block */ 267 u32 size_dt_strings; /* size of the strings block */
268
269 /* version 17 fields below */
270 u32 size_dt_struct; /* size of the DT structure block */
268}; 271};
269 272
270 Along with the constants: 273 Along with the constants:
@@ -273,7 +276,7 @@ struct boot_param_header {
273#define OF_DT_HEADER 0xd00dfeed /* 4: version, 276#define OF_DT_HEADER 0xd00dfeed /* 4: version,
274 4: total size */ 277 4: total size */
275#define OF_DT_BEGIN_NODE 0x1 /* Start node: full name 278#define OF_DT_BEGIN_NODE 0x1 /* Start node: full name
276*/ 279 */
277#define OF_DT_END_NODE 0x2 /* End node */ 280#define OF_DT_END_NODE 0x2 /* End node */
278#define OF_DT_PROP 0x3 /* Property: name off, 281#define OF_DT_PROP 0x3 /* Property: name off,
279 size, content */ 282 size, content */
@@ -310,9 +313,8 @@ struct boot_param_header {
310 - off_mem_rsvmap 313 - off_mem_rsvmap
311 314
312 This is an offset from the beginning of the header to the start 315 This is an offset from the beginning of the header to the start
313 of the reserved memory map. This map is a list of pairs of 64 316 of the reserved memory map. This map is a list of pairs of 64-
314 bit integers. Each pair is a physical address and a size. The 317 bit integers. Each pair is a physical address and a size. The
315
316 list is terminated by an entry of size 0. This map provides the 318 list is terminated by an entry of size 0. This map provides the
317 kernel with a list of physical memory areas that are "reserved" 319 kernel with a list of physical memory areas that are "reserved"
318 and thus not to be used for memory allocations, especially during 320 and thus not to be used for memory allocations, especially during
@@ -325,7 +327,7 @@ struct boot_param_header {
325 contain _at least_ this DT block itself (header,total_size). If 327 contain _at least_ this DT block itself (header,total_size). If
326 you are passing an initrd to the kernel, you should reserve it as 328 you are passing an initrd to the kernel, you should reserve it as
327 well. You do not need to reserve the kernel image itself. The map 329 well. You do not need to reserve the kernel image itself. The map
328 should be 64 bit aligned. 330 should be 64-bit aligned.
329 331
330 - version 332 - version
331 333
@@ -335,10 +337,13 @@ struct boot_param_header {
335 to reallocate it easily at boot and free up the unused flattened 337 to reallocate it easily at boot and free up the unused flattened
336 structure after expansion. Version 16 introduces a new more 338 structure after expansion. Version 16 introduces a new more
337 "compact" format for the tree itself that is however not backward 339 "compact" format for the tree itself that is however not backward
338 compatible. You should always generate a structure of the highest 340 compatible. Version 17 adds an additional field, size_dt_struct,
339 version defined at the time of your implementation. Currently 341 allowing it to be reallocated or moved more easily (this is
340 that is version 16, unless you explicitly aim at being backward 342 particularly useful for bootloaders which need to make
341 compatible. 343 adjustments to a device tree based on probed information). You
344 should always generate a structure of the highest version defined
345 at the time of your implementation. Currently that is version 17,
346 unless you explicitly aim at being backward compatible.
342 347
343 - last_comp_version 348 - last_comp_version
344 349
@@ -347,7 +352,7 @@ struct boot_param_header {
347 is backward compatible with version 1 (that is, a kernel build 352 is backward compatible with version 1 (that is, a kernel build
348 for version 1 will be able to boot with a version 2 format). You 353 for version 1 will be able to boot with a version 2 format). You
349 should put a 1 in this field if you generate a device tree of 354 should put a 1 in this field if you generate a device tree of
350 version 1 to 3, or 0x10 if you generate a tree of version 0x10 355 version 1 to 3, or 16 if you generate a tree of version 16 or 17
351 using the new unit name format. 356 using the new unit name format.
352 357
353 - boot_cpuid_phys 358 - boot_cpuid_phys
@@ -360,6 +365,17 @@ struct boot_param_header {
360 point (see further chapters for more informations on the required 365 point (see further chapters for more informations on the required
361 device-tree contents) 366 device-tree contents)
362 367
368 - size_dt_strings
369
370 This field only exists on version 3 and later headers. It
371 gives the size of the "strings" section of the device tree (which
372 starts at the offset given by off_dt_strings).
373
374 - size_dt_struct
375
376 This field only exists on version 17 and later headers. It gives
377 the size of the "structure" section of the device tree (which
378 starts at the offset given by off_dt_struct).
363 379
364 So the typical layout of a DT block (though the various parts don't 380 So the typical layout of a DT block (though the various parts don't
365 need to be in that order) looks like this (addresses go from top to 381 need to be in that order) looks like this (addresses go from top to
@@ -417,7 +433,7 @@ root node who has no parent.
417A node has 2 names. The actual node name is generally contained in a 433A node has 2 names. The actual node name is generally contained in a
418property of type "name" in the node property list whose value is a 434property of type "name" in the node property list whose value is a
419zero terminated string and is mandatory for version 1 to 3 of the 435zero terminated string and is mandatory for version 1 to 3 of the
420format definition (as it is in Open Firmware). Version 0x10 makes it 436format definition (as it is in Open Firmware). Version 16 makes it
421optional as it can generate it from the unit name defined below. 437optional as it can generate it from the unit name defined below.
422 438
423There is also a "unit name" that is used to differentiate nodes with 439There is also a "unit name" that is used to differentiate nodes with
@@ -461,7 +477,7 @@ referencing another node via "phandle" is when laying out the
461interrupt tree which will be described in a further version of this 477interrupt tree which will be described in a further version of this
462document. 478document.
463 479
464This "linux, phandle" property is a 32 bit value that uniquely 480This "linux, phandle" property is a 32-bit value that uniquely
465identifies a node. You are free to use whatever values or system of 481identifies a node. You are free to use whatever values or system of
466values, internal pointers, or whatever to generate these, the only 482values, internal pointers, or whatever to generate these, the only
467requirement is that every node for which you provide that property has 483requirement is that every node for which you provide that property has
@@ -471,7 +487,7 @@ Here is an example of a simple device-tree. In this example, an "o"
471designates a node followed by the node unit name. Properties are 487designates a node followed by the node unit name. Properties are
472presented with their name followed by their content. "content" 488presented with their name followed by their content. "content"
473represents an ASCII string (zero terminated) value, while <content> 489represents an ASCII string (zero terminated) value, while <content>
474represents a 32 bit hexadecimal value. The various nodes in this 490represents a 32-bit hexadecimal value. The various nodes in this
475example will be discussed in a later chapter. At this point, it is 491example will be discussed in a later chapter. At this point, it is
476only meant to give you a idea of what a device-tree looks like. I have 492only meant to give you a idea of what a device-tree looks like. I have
477purposefully kept the "name" and "linux,phandle" properties which 493purposefully kept the "name" and "linux,phandle" properties which
@@ -497,7 +513,7 @@ looks like in practice.
497 | |- device_type = "cpu" 513 | |- device_type = "cpu"
498 | |- reg = <0> 514 | |- reg = <0>
499 | |- clock-frequency = <5f5e1000> 515 | |- clock-frequency = <5f5e1000>
500 | |- linux,boot-cpu 516 | |- 64-bit
501 | |- linux,phandle = <2> 517 | |- linux,phandle = <2>
502 | 518 |
503 o memory@0 519 o memory@0
@@ -509,7 +525,6 @@ looks like in practice.
509 o chosen 525 o chosen
510 |- name = "chosen" 526 |- name = "chosen"
511 |- bootargs = "root=/dev/sda2" 527 |- bootargs = "root=/dev/sda2"
512 |- linux,platform = <00000600>
513 |- linux,phandle = <4> 528 |- linux,phandle = <4>
514 529
515This tree is almost a minimal tree. It pretty much contains the 530This tree is almost a minimal tree. It pretty much contains the
@@ -519,7 +534,7 @@ physical memory layout. It also includes misc information passed
519through /chosen, like in this example, the platform type (mandatory) 534through /chosen, like in this example, the platform type (mandatory)
520and the kernel command line arguments (optional). 535and the kernel command line arguments (optional).
521 536
522The /cpus/PowerPC,970@0/linux,boot-cpu property is an example of a 537The /cpus/PowerPC,970@0/64-bit property is an example of a
523property without a value. All other properties have a value. The 538property without a value. All other properties have a value. The
524significance of the #address-cells and #size-cells properties will be 539significance of the #address-cells and #size-cells properties will be
525explained in chapter IV which defines precisely the required nodes and 540explained in chapter IV which defines precisely the required nodes and
@@ -544,15 +559,15 @@ Here's the basic structure of a single node:
544 * [align gap to next 4 bytes boundary] 559 * [align gap to next 4 bytes boundary]
545 * for each property: 560 * for each property:
546 * token OF_DT_PROP (that is 0x00000003) 561 * token OF_DT_PROP (that is 0x00000003)
547 * 32 bit value of property value size in bytes (or 0 of no 562 * 32-bit value of property value size in bytes (or 0 if no
548 * value) 563 value)
549 * 32 bit value of offset in string block of property name 564 * 32-bit value of offset in string block of property name
550 * property value data if any 565 * property value data if any
551 * [align gap to next 4 bytes boundary] 566 * [align gap to next 4 bytes boundary]
552 * [child nodes if any] 567 * [child nodes if any]
553 * token OF_DT_END_NODE (that is 0x00000002) 568 * token OF_DT_END_NODE (that is 0x00000002)
554 569
555So the node content can be summarised as a start token, a full path, 570So the node content can be summarized as a start token, a full path,
556a list of properties, a list of child nodes, and an end token. Every 571a list of properties, a list of child nodes, and an end token. Every
557child node is a full node structure itself as defined above. 572child node is a full node structure itself as defined above.
558 573
@@ -584,7 +599,7 @@ provide those properties yourself.
584---------------------------------------------- 599----------------------------------------------
585 600
586The general rule is documented in the various Open Firmware 601The general rule is documented in the various Open Firmware
587documentations. If you chose to describe a bus with the device-tree 602documentations. If you choose to describe a bus with the device-tree
588and there exist an OF bus binding, then you should follow the 603and there exist an OF bus binding, then you should follow the
589specification. However, the kernel does not require every single 604specification. However, the kernel does not require every single
590device or bus to be described by the device tree. 605device or bus to be described by the device tree.
@@ -597,9 +612,9 @@ those properties defining addresses format for devices directly mapped
597on the processor bus. 612on the processor bus.
598 613
599Those 2 properties define 'cells' for representing an address and a 614Those 2 properties define 'cells' for representing an address and a
600size. A "cell" is a 32 bit number. For example, if both contain 2 615size. A "cell" is a 32-bit number. For example, if both contain 2
601like the example tree given above, then an address and a size are both 616like the example tree given above, then an address and a size are both
602composed of 2 cells, and each is a 64 bit number (cells are 617composed of 2 cells, and each is a 64-bit number (cells are
603concatenated and expected to be in big endian format). Another example 618concatenated and expected to be in big endian format). Another example
604is the way Apple firmware defines them, with 2 cells for an address 619is the way Apple firmware defines them, with 2 cells for an address
605and one cell for a size. Most 32-bit implementations should define 620and one cell for a size. Most 32-bit implementations should define
@@ -633,7 +648,7 @@ prom_parse.c file of the recent kernels for your bus type.
633 648
634The "reg" property only defines addresses and sizes (if #size-cells 649The "reg" property only defines addresses and sizes (if #size-cells
635is non-0) within a given bus. In order to translate addresses upward 650is non-0) within a given bus. In order to translate addresses upward
636(that is into parent bus addresses, and possibly into cpu physical 651(that is into parent bus addresses, and possibly into CPU physical
637addresses), all busses must contain a "ranges" property. If the 652addresses), all busses must contain a "ranges" property. If the
638"ranges" property is missing at a given level, it's assumed that 653"ranges" property is missing at a given level, it's assumed that
639translation isn't possible. The format of the "ranges" property for a 654translation isn't possible. The format of the "ranges" property for a
@@ -649,9 +664,9 @@ example, for a PCI host controller, that would be a CPU address. For a
649PCI<->ISA bridge, that would be a PCI address. It defines the base 664PCI<->ISA bridge, that would be a PCI address. It defines the base
650address in the parent bus where the beginning of that range is mapped. 665address in the parent bus where the beginning of that range is mapped.
651 666
652For a new 64 bit powerpc board, I recommend either the 2/2 format or 667For a new 64-bit powerpc board, I recommend either the 2/2 format or
653Apple's 2/1 format which is slightly more compact since sizes usually 668Apple's 2/1 format which is slightly more compact since sizes usually
654fit in a single 32 bit word. New 32 bit powerpc boards should use a 669fit in a single 32-bit word. New 32-bit powerpc boards should use a
6551/1 format, unless the processor supports physical addresses greater 6701/1 format, unless the processor supports physical addresses greater
656than 32-bits, in which case a 2/1 format is recommended. 671than 32-bits, in which case a 2/1 format is recommended.
657 672
@@ -733,8 +748,7 @@ address which can extend beyond that limit.
733 that typically get driven by the same platform code in the 748 that typically get driven by the same platform code in the
734 kernel, you would use a different "model" property but put a 749 kernel, you would use a different "model" property but put a
735 value in "compatible". The kernel doesn't directly use that 750 value in "compatible". The kernel doesn't directly use that
736 value (see /chosen/linux,platform for how the kernel chooses a 751 value but it is generally useful.
737 platform type) but it is generally useful.
738 752
739 The root node is also generally where you add additional properties 753 The root node is also generally where you add additional properties
740 specific to your board like the serial number if any, that sort of 754 specific to your board like the serial number if any, that sort of
@@ -766,7 +780,7 @@ address which can extend beyond that limit.
766 Required properties: 780 Required properties:
767 781
768 - device_type : has to be "cpu" 782 - device_type : has to be "cpu"
769 - reg : This is the physical cpu number, it's a single 32 bit cell 783 - reg : This is the physical CPU number, it's a single 32-bit cell
770 and is also used as-is as the unit number for constructing the 784 and is also used as-is as the unit number for constructing the
771 unit name in the full path. For example, with 2 CPUs, you would 785 unit name in the full path. For example, with 2 CPUs, you would
772 have the full path: 786 have the full path:
@@ -778,7 +792,6 @@ address which can extend beyond that limit.
778 bytes 792 bytes
779 - d-cache-size : one cell, size of L1 data cache in bytes 793 - d-cache-size : one cell, size of L1 data cache in bytes
780 - i-cache-size : one cell, size of L1 instruction cache in bytes 794 - i-cache-size : one cell, size of L1 instruction cache in bytes
781 - linux, boot-cpu : Should be defined if this cpu is the boot cpu.
782 795
783 Recommended properties: 796 Recommended properties:
784 797
@@ -788,7 +801,7 @@ address which can extend beyond that limit.
788 the kernel timebase/decrementer calibration based on this 801 the kernel timebase/decrementer calibration based on this
789 value. 802 value.
790 - clock-frequency : a cell indicating the CPU core clock frequency 803 - clock-frequency : a cell indicating the CPU core clock frequency
791 in Hz. A new property will be defined for 64 bit values, but if 804 in Hz. A new property will be defined for 64-bit values, but if
792 your frequency is < 4Ghz, one cell is enough. Here as well as 805 your frequency is < 4Ghz, one cell is enough. Here as well as
793 for the above, the common code doesn't use that property, but 806 for the above, the common code doesn't use that property, but
794 you are welcome to re-use the pSeries or Maple one. A future 807 you are welcome to re-use the pSeries or Maple one. A future
@@ -835,19 +848,13 @@ address which can extend beyond that limit.
835 848
836 This node is a bit "special". Normally, that's where open firmware 849 This node is a bit "special". Normally, that's where open firmware
837 puts some variable environment information, like the arguments, or 850 puts some variable environment information, like the arguments, or
838 phandle pointers to nodes like the main interrupt controller, or the 851 the default input/output devices.
839 default input/output devices.
840 852
841 This specification makes a few of these mandatory, but also defines 853 This specification makes a few of these mandatory, but also defines
842 some linux-specific properties that would be normally constructed by 854 some linux-specific properties that would be normally constructed by
843 the prom_init() trampoline when booting with an OF client interface, 855 the prom_init() trampoline when booting with an OF client interface,
844 but that you have to provide yourself when using the flattened format. 856 but that you have to provide yourself when using the flattened format.
845 857
846 Required properties:
847
848 - linux,platform : This is your platform number as assigned by the
849 architecture maintainers
850
851 Recommended properties: 858 Recommended properties:
852 859
853 - bootargs : This zero-terminated string is passed as the kernel 860 - bootargs : This zero-terminated string is passed as the kernel
@@ -861,14 +868,14 @@ address which can extend beyond that limit.
861 that the kernel tries to find out the default console and has 868 that the kernel tries to find out the default console and has
862 knowledge of various types like 8250 serial ports. You may want 869 knowledge of various types like 8250 serial ports. You may want
863 to extend this function to add your own. 870 to extend this function to add your own.
864 - interrupt-controller : This is one cell containing a phandle
865 value that matches the "linux,phandle" property of your main
866 interrupt controller node. May be used for interrupt routing.
867
868 871
869 Note that u-boot creates and fills in the chosen node for platforms 872 Note that u-boot creates and fills in the chosen node for platforms
870 that use it. 873 that use it.
871 874
875 (Note: a practice that is now obsolete was to include a property
876 under /chosen called interrupt-controller which had a phandle value
877 that pointed to the main interrupt controller)
878
872 f) the /soc<SOCname> node 879 f) the /soc<SOCname> node
873 880
874 This node is used to represent a system-on-a-chip (SOC) and must be 881 This node is used to represent a system-on-a-chip (SOC) and must be
@@ -916,8 +923,7 @@ address which can extend beyond that limit.
916 The SOC node may contain child nodes for each SOC device that the 923 The SOC node may contain child nodes for each SOC device that the
917 platform uses. Nodes should not be created for devices which exist 924 platform uses. Nodes should not be created for devices which exist
918 on the SOC but are not used by a particular platform. See chapter VI 925 on the SOC but are not used by a particular platform. See chapter VI
919 for more information on how to specify devices that are part of an 926 for more information on how to specify devices that are part of a SOC.
920SOC.
921 927
922 Example SOC node for the MPC8540: 928 Example SOC node for the MPC8540:
923 929
@@ -980,7 +986,7 @@ The syntax of the dtc tool is
980 [-o output-filename] [-V output_version] input_filename 986 [-o output-filename] [-V output_version] input_filename
981 987
982 988
983The "output_version" defines what versio of the "blob" format will be 989The "output_version" defines what version of the "blob" format will be
984generated. Supported versions are 1,2,3 and 16. The default is 990generated. Supported versions are 1,2,3 and 16. The default is
985currently version 3 but that may change in the future to version 16. 991currently version 3 but that may change in the future to version 16.
986 992
@@ -1002,12 +1008,12 @@ supported currently at the toplevel.
1002 */ 1008 */
1003 1009
1004 property2 = <1234abcd>; /* define a property containing a 1010 property2 = <1234abcd>; /* define a property containing a
1005 * numerical 32 bits value (hexadecimal) 1011 * numerical 32-bit value (hexadecimal)
1006 */ 1012 */
1007 1013
1008 property3 = <12345678 12345678 deadbeef>; 1014 property3 = <12345678 12345678 deadbeef>;
1009 /* define a property containing 3 1015 /* define a property containing 3
1010 * numerical 32 bits values (cells) in 1016 * numerical 32-bit values (cells) in
1011 * hexadecimal 1017 * hexadecimal
1012 */ 1018 */
1013 property4 = [0a 0b 0c 0d de ea ad be ef]; 1019 property4 = [0a 0b 0c 0d de ea ad be ef];
@@ -1076,7 +1082,7 @@ while all this has been defined and implemented.
1076 its usage in early_init_devtree(), and the corresponding various 1082 its usage in early_init_devtree(), and the corresponding various
1077 early_init_dt_scan_*() callbacks. That code can be re-used in a 1083 early_init_dt_scan_*() callbacks. That code can be re-used in a
1078 GPL bootloader, and as the author of that code, I would be happy 1084 GPL bootloader, and as the author of that code, I would be happy
1079 to discuss possible free licencing to any vendor who wishes to 1085 to discuss possible free licensing to any vendor who wishes to
1080 integrate all or part of this code into a non-GPL bootloader. 1086 integrate all or part of this code into a non-GPL bootloader.
1081 1087
1082 1088
@@ -1085,7 +1091,7 @@ VI - System-on-a-chip devices and nodes
1085======================================= 1091=======================================
1086 1092
1087Many companies are now starting to develop system-on-a-chip 1093Many companies are now starting to develop system-on-a-chip
1088processors, where the processor core (cpu) and many peripheral devices 1094processors, where the processor core (CPU) and many peripheral devices
1089exist on a single piece of silicon. For these SOCs, an SOC node 1095exist on a single piece of silicon. For these SOCs, an SOC node
1090should be used that defines child nodes for the devices that make 1096should be used that defines child nodes for the devices that make
1091up the SOC. While platforms are not required to use this model in 1097up the SOC. While platforms are not required to use this model in
@@ -1117,42 +1123,7 @@ See appendix A for an example partial SOC node definition for the
1117MPC8540. 1123MPC8540.
1118 1124
1119 1125
11202) Specifying interrupt information for SOC devices 11262) Representing devices without a current OF specification
1121---------------------------------------------------
1122
1123Each device that is part of an SOC and which generates interrupts
1124should have the following properties:
1125
1126 - interrupt-parent : contains the phandle of the interrupt
1127 controller which handles interrupts for this device
1128 - interrupts : a list of tuples representing the interrupt
1129 number and the interrupt sense and level for each interrupt
1130 for this device.
1131
1132This information is used by the kernel to build the interrupt table
1133for the interrupt controllers in the system.
1134
1135Sense and level information should be encoded as follows:
1136
1137 Devices connected to openPIC-compatible controllers should encode
1138 sense and polarity as follows:
1139
1140 0 = low to high edge sensitive type enabled
1141 1 = active low level sensitive type enabled
1142 2 = active high level sensitive type enabled
1143 3 = high to low edge sensitive type enabled
1144
1145 ISA PIC interrupt controllers should adhere to the ISA PIC
1146 encodings listed below:
1147
1148 0 = active low level sensitive type enabled
1149 1 = active high level sensitive type enabled
1150 2 = high to low edge sensitive type enabled
1151 3 = low to high edge sensitive type enabled
1152
1153
1154
11553) Representing devices without a current OF specification
1156---------------------------------------------------------- 1127----------------------------------------------------------
1157 1128
1158Currently, there are many devices on SOCs that do not have a standard 1129Currently, there are many devices on SOCs that do not have a standard
@@ -1209,6 +1180,13 @@ platforms are moved over to use the flattened-device-tree model.
1209 - phy-handle : The phandle for the PHY connected to this ethernet 1180 - phy-handle : The phandle for the PHY connected to this ethernet
1210 controller. 1181 controller.
1211 1182
1183 Recommended properties:
1184
1185 - linux,network-index : This is the intended "index" of this
1186 network device. This is used by the bootwrapper to interpret
1187 MAC addresses passed by the firmware when no information other
1188 than indices is available to associate an address with a device.
1189
1212 Example: 1190 Example:
1213 1191
1214 ethernet@24000 { 1192 ethernet@24000 {
@@ -1320,10 +1298,10 @@ platforms are moved over to use the flattened-device-tree model.
1320 and additions : 1298 and additions :
1321 1299
1322 Required properties : 1300 Required properties :
1323 - compatible : Should be "fsl-usb2-mph" for multi port host usb 1301 - compatible : Should be "fsl-usb2-mph" for multi port host USB
1324 controllers, or "fsl-usb2-dr" for dual role usb controllers 1302 controllers, or "fsl-usb2-dr" for dual role USB controllers
1325 - phy_type : For multi port host usb controllers, should be one of 1303 - phy_type : For multi port host USB controllers, should be one of
1326 "ulpi", or "serial". For dual role usb controllers, should be 1304 "ulpi", or "serial". For dual role USB controllers, should be
1327 one of "ulpi", "utmi", "utmi_wide", or "serial". 1305 one of "ulpi", "utmi", "utmi_wide", or "serial".
1328 - reg : Offset and length of the register set for the device 1306 - reg : Offset and length of the register set for the device
1329 - port0 : boolean; if defined, indicates port0 is connected for 1307 - port0 : boolean; if defined, indicates port0 is connected for
@@ -1334,6 +1312,9 @@ platforms are moved over to use the flattened-device-tree model.
1334 fsl-usb2-mph compatible controllers. Either this property or 1312 fsl-usb2-mph compatible controllers. Either this property or
1335 "port0" (or both) must be defined for "fsl-usb2-mph" compatible 1313 "port0" (or both) must be defined for "fsl-usb2-mph" compatible
1336 controllers. 1314 controllers.
1315 - dr_mode : indicates the working mode for "fsl-usb2-dr" compatible
1316 controllers. Can be "host", "peripheral", or "otg". Default to
1317 "host" if not defined for backward compatibility.
1337 1318
1338 Recommended properties : 1319 Recommended properties :
1339 - interrupts : <a b> where a is the interrupt number and b is a 1320 - interrupts : <a b> where a is the interrupt number and b is a
@@ -1344,7 +1325,7 @@ platforms are moved over to use the flattened-device-tree model.
1344 - interrupt-parent : the phandle for the interrupt controller that 1325 - interrupt-parent : the phandle for the interrupt controller that
1345 services interrupts for this device. 1326 services interrupts for this device.
1346 1327
1347 Example multi port host usb controller device node : 1328 Example multi port host USB controller device node :
1348 usb@22000 { 1329 usb@22000 {
1349 device_type = "usb"; 1330 device_type = "usb";
1350 compatible = "fsl-usb2-mph"; 1331 compatible = "fsl-usb2-mph";
@@ -1358,7 +1339,7 @@ platforms are moved over to use the flattened-device-tree model.
1358 port1; 1339 port1;
1359 }; 1340 };
1360 1341
1361 Example dual role usb controller device node : 1342 Example dual role USB controller device node :
1362 usb@23000 { 1343 usb@23000 {
1363 device_type = "usb"; 1344 device_type = "usb";
1364 compatible = "fsl-usb2-dr"; 1345 compatible = "fsl-usb2-dr";
@@ -1367,6 +1348,7 @@ platforms are moved over to use the flattened-device-tree model.
1367 #size-cells = <0>; 1348 #size-cells = <0>;
1368 interrupt-parent = <700>; 1349 interrupt-parent = <700>;
1369 interrupts = <26 1>; 1350 interrupts = <26 1>;
1351 dr_mode = "otg";
1370 phy = "ulpi"; 1352 phy = "ulpi";
1371 }; 1353 };
1372 1354
@@ -1391,7 +1373,7 @@ platforms are moved over to use the flattened-device-tree model.
1391 - channel-fifo-len : An integer representing the number of 1373 - channel-fifo-len : An integer representing the number of
1392 descriptor pointers each channel fetch fifo can hold. 1374 descriptor pointers each channel fetch fifo can hold.
1393 - exec-units-mask : The bitmask representing what execution units 1375 - exec-units-mask : The bitmask representing what execution units
1394 (EUs) are available. It's a single 32 bit cell. EU information 1376 (EUs) are available. It's a single 32-bit cell. EU information
1395 should be encoded following the SEC's Descriptor Header Dword 1377 should be encoded following the SEC's Descriptor Header Dword
1396 EU_SEL0 field documentation, i.e. as follows: 1378 EU_SEL0 field documentation, i.e. as follows:
1397 1379
@@ -1407,7 +1389,7 @@ platforms are moved over to use the flattened-device-tree model.
1407 bits 8 through 31 are reserved for future SEC EUs. 1389 bits 8 through 31 are reserved for future SEC EUs.
1408 1390
1409 - descriptor-types-mask : The bitmask representing what descriptors 1391 - descriptor-types-mask : The bitmask representing what descriptors
1410 are available. It's a single 32 bit cell. Descriptor type 1392 are available. It's a single 32-bit cell. Descriptor type
1411 information should be encoded following the SEC's Descriptor 1393 information should be encoded following the SEC's Descriptor
1412 Header Dword DESC_TYPE field documentation, i.e. as follows: 1394 Header Dword DESC_TYPE field documentation, i.e. as follows:
1413 1395
@@ -1496,7 +1478,7 @@ platforms are moved over to use the flattened-device-tree model.
1496 Required properties: 1478 Required properties:
1497 - device_type : should be "spi". 1479 - device_type : should be "spi".
1498 - compatible : should be "fsl_spi". 1480 - compatible : should be "fsl_spi".
1499 - mode : the spi operation mode, it can be "cpu" or "qe". 1481 - mode : the SPI operation mode, it can be "cpu" or "qe".
1500 - reg : Offset and length of the register set for the device 1482 - reg : Offset and length of the register set for the device
1501 - interrupts : <a b> where a is the interrupt number and b is a 1483 - interrupts : <a b> where a is the interrupt number and b is a
1502 field that represents an encoding of the sense and level 1484 field that represents an encoding of the sense and level
@@ -1573,6 +1555,12 @@ platforms are moved over to use the flattened-device-tree model.
1573 - mac-address : list of bytes representing the ethernet address. 1555 - mac-address : list of bytes representing the ethernet address.
1574 - phy-handle : The phandle for the PHY connected to this controller. 1556 - phy-handle : The phandle for the PHY connected to this controller.
1575 1557
1558 Recommended properties:
1559 - linux,network-index : This is the intended "index" of this
1560 network device. This is used by the bootwrapper to interpret
1561 MAC addresses passed by the firmware when no information other
1562 than indices is available to associate an address with a device.
1563
1576 Example: 1564 Example:
1577 ucc@2000 { 1565 ucc@2000 {
1578 device_type = "network"; 1566 device_type = "network";
@@ -1716,7 +1704,7 @@ platforms are moved over to use the flattened-device-tree model.
1716 - partitions : Several pairs of 32-bit values where the first value is 1704 - partitions : Several pairs of 32-bit values where the first value is
1717 partition's offset from the start of the device and the second one is 1705 partition's offset from the start of the device and the second one is
1718 partition size in bytes with LSB used to signify a read only 1706 partition size in bytes with LSB used to signify a read only
1719 partition (so, the parition size should always be an even number). 1707 partition (so, the partition size should always be an even number).
1720 - partition-names : The list of concatenated zero terminated strings 1708 - partition-names : The list of concatenated zero terminated strings
1721 representing the partition names. 1709 representing the partition names.
1722 - probe-type : The type of probe which should be done for the chip 1710 - probe-type : The type of probe which should be done for the chip
@@ -1737,6 +1725,92 @@ platforms are moved over to use the flattened-device-tree model.
1737 1725
1738 More devices will be defined as this spec matures. 1726 More devices will be defined as this spec matures.
1739 1727
1728VII - Specifying interrupt information for devices
1729===================================================
1730
1731The device tree represents the busses and devices of a hardware
1732system in a form similar to the physical bus topology of the
1733hardware.
1734
1735In addition, a logical 'interrupt tree' exists which represents the
1736hierarchy and routing of interrupts in the hardware.
1737
1738The interrupt tree model is fully described in the
1739document "Open Firmware Recommended Practice: Interrupt
1740Mapping Version 0.9". The document is available at:
1741<http://playground.sun.com/1275/practice>.
1742
17431) interrupts property
1744----------------------
1745
1746Devices that generate interrupts to a single interrupt controller
1747should use the conventional OF representation described in the
1748OF interrupt mapping documentation.
1749
1750Each device which generates interrupts must have an 'interrupt'
1751property. The interrupt property value is an arbitrary number of
1752of 'interrupt specifier' values which describe the interrupt or
1753interrupts for the device.
1754
1755The encoding of an interrupt specifier is determined by the
1756interrupt domain in which the device is located in the
1757interrupt tree. The root of an interrupt domain specifies in
1758its #interrupt-cells property the number of 32-bit cells
1759required to encode an interrupt specifier. See the OF interrupt
1760mapping documentation for a detailed description of domains.
1761
1762For example, the binding for the OpenPIC interrupt controller
1763specifies an #interrupt-cells value of 2 to encode the interrupt
1764number and level/sense information. All interrupt children in an
1765OpenPIC interrupt domain use 2 cells per interrupt in their interrupts
1766property.
1767
1768The PCI bus binding specifies a #interrupt-cell value of 1 to encode
1769which interrupt pin (INTA,INTB,INTC,INTD) is used.
1770
17712) interrupt-parent property
1772----------------------------
1773
1774The interrupt-parent property is specified to define an explicit
1775link between a device node and its interrupt parent in
1776the interrupt tree. The value of interrupt-parent is the
1777phandle of the parent node.
1778
1779If the interrupt-parent property is not defined for a node, it's
1780interrupt parent is assumed to be an ancestor in the node's
1781_device tree_ hierarchy.
1782
17833) OpenPIC Interrupt Controllers
1784--------------------------------
1785
1786OpenPIC interrupt controllers require 2 cells to encode
1787interrupt information. The first cell defines the interrupt
1788number. The second cell defines the sense and level
1789information.
1790
1791Sense and level information should be encoded as follows:
1792
1793 0 = low to high edge sensitive type enabled
1794 1 = active low level sensitive type enabled
1795 2 = active high level sensitive type enabled
1796 3 = high to low edge sensitive type enabled
1797
17984) ISA Interrupt Controllers
1799----------------------------
1800
1801ISA PIC interrupt controllers require 2 cells to encode
1802interrupt information. The first cell defines the interrupt
1803number. The second cell defines the sense and level
1804information.
1805
1806ISA PIC interrupt controllers should adhere to the ISA PIC
1807encodings listed below:
1808
1809 0 = active low level sensitive type enabled
1810 1 = active high level sensitive type enabled
1811 2 = high to low edge sensitive type enabled
1812 3 = low to high edge sensitive type enabled
1813
1740 1814
1741Appendix A - Sample SOC node for MPC8540 1815Appendix A - Sample SOC node for MPC8540
1742======================================== 1816========================================
diff --git a/Documentation/powerpc/mpc52xx-device-tree-bindings.txt b/Documentation/powerpc/mpc52xx-device-tree-bindings.txt
index 69f016f02bb0..e59fcbbe338c 100644
--- a/Documentation/powerpc/mpc52xx-device-tree-bindings.txt
+++ b/Documentation/powerpc/mpc52xx-device-tree-bindings.txt
@@ -1,7 +1,7 @@
1MPC52xx Device Tree Bindings 1MPC5200 Device Tree Bindings
2---------------------------- 2----------------------------
3 3
4(c) 2006 Secret Lab Technologies Ltd 4(c) 2006-2007 Secret Lab Technologies Ltd
5Grant Likely <grant.likely at secretlab.ca> 5Grant Likely <grant.likely at secretlab.ca>
6 6
7********** DRAFT *********** 7********** DRAFT ***********
@@ -20,11 +20,11 @@ described in Documentation/powerpc/booting-without-of.txt), or passed
20by Open Firmare (IEEE 1275) compatible firmware using an OF compatible 20by Open Firmare (IEEE 1275) compatible firmware using an OF compatible
21client interface API. 21client interface API.
22 22
23This document specifies the requirements on the device-tree for mpc52xx 23This document specifies the requirements on the device-tree for mpc5200
24based boards. These requirements are above and beyond the details 24based boards. These requirements are above and beyond the details
25specified in either the OpenFirmware spec or booting-without-of.txt 25specified in either the OpenFirmware spec or booting-without-of.txt
26 26
27All new mpc52xx-based boards are expected to match this document. In 27All new mpc5200-based boards are expected to match this document. In
28cases where this document is not sufficient to support a new board port, 28cases where this document is not sufficient to support a new board port,
29this document should be updated as part of adding the new board support. 29this document should be updated as part of adding the new board support.
30 30
@@ -32,26 +32,26 @@ II - Philosophy
32=============== 32===============
33The core of this document is naming convention. The whole point of 33The core of this document is naming convention. The whole point of
34defining this convention is to reduce or eliminate the number of 34defining this convention is to reduce or eliminate the number of
35special cases required to support a 52xx board. If all 52xx boards 35special cases required to support a 5200 board. If all 5200 boards
36follow the same convention, then generic 52xx support code will work 36follow the same convention, then generic 5200 support code will work
37rather than coding special cases for each new board. 37rather than coding special cases for each new board.
38 38
39This section tries to capture the thought process behind why the naming 39This section tries to capture the thought process behind why the naming
40convention is what it is. 40convention is what it is.
41 41
421. Node names 421. names
43------------- 43---------
44There is strong convention/requirements already established for children 44There is strong convention/requirements already established for children
45of the root node. 'cpus' describes the processor cores, 'memory' 45of the root node. 'cpus' describes the processor cores, 'memory'
46describes memory, and 'chosen' provides boot configuration. Other nodes 46describes memory, and 'chosen' provides boot configuration. Other nodes
47are added to describe devices attached to the processor local bus. 47are added to describe devices attached to the processor local bus.
48
48Following convention already established with other system-on-chip 49Following convention already established with other system-on-chip
49processors, MPC52xx boards must have an 'soc5200' node as a child of the 50processors, 5200 device trees should use the name 'soc5200' for the
50root node. 51parent node of on chip devices, and the root node should be its parent.
51 52
52The soc5200 node holds child nodes for all on chip devices. Child nodes 53Child nodes are typically named after the configured function. ie.
53are typically named after the configured function. ie. the FEC node is 54the FEC node is named 'ethernet', and a PSC in uart mode is named 'serial'.
54named 'ethernet', and a PSC in uart mode is named 'serial'.
55 55
562. device_type property 562. device_type property
57----------------------- 57-----------------------
@@ -66,28 +66,47 @@ exactly.
66Since device_type isn't enough to match devices to drivers, there also 66Since device_type isn't enough to match devices to drivers, there also
67needs to be a naming convention for the compatible property. Compatible 67needs to be a naming convention for the compatible property. Compatible
68is an list of device descriptions sorted from specific to generic. For 68is an list of device descriptions sorted from specific to generic. For
69the mpc52xx, the required format for each compatible value is 69the mpc5200, the required format for each compatible value is
70<chip>-<device>[-<mode>]. At the minimum, the list shall contain two 70<chip>-<device>[-<mode>]. The OS should be able to match a device driver
71items; the first specifying the exact chip, and the second specifying 71to the device based solely on the compatible value. If two drivers
72mpc52xx for the chip. 72match on the compatible list; the 'most compatible' driver should be
73 73selected.
74ie. ethernet on mpc5200b: compatible = "mpc5200b-ethernet\0mpc52xx-ethernet" 74
75 75The split between the MPC5200 and the MPC5200B leaves a bit of a
76The idea here is that most drivers will match to the most generic field 76connundrum. How should the compatible property be set up to provide
77in the compatible list (mpc52xx-*), but can also test the more specific 77maximum compatability information; but still acurately describe the
78field for enabling bug fixes or extra features. 78chip? For the MPC5200; the answer is easy. Most of the SoC devices
79originally appeared on the MPC5200. Since they didn't exist anywhere
80else; the 5200 compatible properties will contain only one item;
81"mpc5200-<device>".
82
83The 5200B is almost the same as the 5200, but not quite. It fixes
84silicon bugs and it adds a small number of enhancements. Most of the
85devices either provide exactly the same interface as on the 5200. A few
86devices have extra functions but still have a backwards compatible mode.
87To express this infomation as completely as possible, 5200B device trees
88should have two items in the compatible list;
89"mpc5200b-<device>\0mpc5200-<device>". It is *strongly* recommended
90that 5200B device trees follow this convention (instead of only listing
91the base mpc5200 item).
92
93If another chip appear on the market with one of the mpc5200 SoC
94devices, then the compatible list should include mpc5200-<device>.
95
96ie. ethernet on mpc5200: compatible = "mpc5200-ethernet"
97 ethernet on mpc5200b: compatible = "mpc5200b-ethernet\0mpc5200-ethernet"
79 98
80Modal devices, like PSCs, also append the configured function to the 99Modal devices, like PSCs, also append the configured function to the
81end of the compatible field. ie. A PSC in i2s mode would specify 100end of the compatible field. ie. A PSC in i2s mode would specify
82"mpc52xx-psc-i2s", not "mpc52xx-i2s". This convention is chosen to 101"mpc5200-psc-i2s", not "mpc5200-i2s". This convention is chosen to
83avoid naming conflicts with non-psc devices providing the same 102avoid naming conflicts with non-psc devices providing the same
84function. For example, "mpc52xx-spi" and "mpc52xx-psc-spi" describe 103function. For example, "mpc5200-spi" and "mpc5200-psc-spi" describe
85the mpc5200 simple spi device and a PSC spi mode respectively. 104the mpc5200 simple spi device and a PSC spi mode respectively.
86 105
87If the soc device is more generic and present on other SOCs, the 106If the soc device is more generic and present on other SOCs, the
88compatible property can specify the more generic device type also. 107compatible property can specify the more generic device type also.
89 108
90ie. mscan: compatible = "mpc5200-mscan\0mpc52xx-mscan\0fsl,mscan"; 109ie. mscan: compatible = "mpc5200-mscan\0fsl,mscan";
91 110
92At the time of writing, exact chip may be either 'mpc5200' or 111At the time of writing, exact chip may be either 'mpc5200' or
93'mpc5200b'. 112'mpc5200b'.
@@ -96,7 +115,7 @@ Device drivers should always try to match as generically as possible.
96 115
97III - Structure 116III - Structure
98=============== 117===============
99The device tree for an mpc52xx board follows the structure defined in 118The device tree for an mpc5200 board follows the structure defined in
100booting-without-of.txt with the following additional notes: 119booting-without-of.txt with the following additional notes:
101 120
1020) the root node 1210) the root node
@@ -115,7 +134,7 @@ Typical memory description node; see booting-without-of.
115 134
1163) The soc5200 node 1353) The soc5200 node
117------------------- 136-------------------
118This node describes the on chip SOC peripherals. Every mpc52xx based 137This node describes the on chip SOC peripherals. Every mpc5200 based
119board will have this node, and as such there is a common naming 138board will have this node, and as such there is a common naming
120convention for SOC devices. 139convention for SOC devices.
121 140
@@ -125,71 +144,111 @@ name type description
125device_type string must be "soc" 144device_type string must be "soc"
126ranges int should be <0 baseaddr baseaddr+10000> 145ranges int should be <0 baseaddr baseaddr+10000>
127reg int must be <baseaddr 10000> 146reg int must be <baseaddr 10000>
147compatible string mpc5200: "mpc5200-soc"
148 mpc5200b: "mpc5200b-soc\0mpc5200-soc"
149system-frequency int Fsystem frequency; source of all
150 other clocks.
151bus-frequency int IPB bus frequency in HZ. Clock rate
152 used by most of the soc devices.
153#interrupt-cells int must be <3>.
128 154
129Recommended properties: 155Recommended properties:
130name type description 156name type description
131---- ---- ----------- 157---- ---- -----------
132compatible string should be "<chip>-soc\0mpc52xx-soc" 158model string Exact model of the chip;
133 ie. "mpc5200b-soc\0mpc52xx-soc" 159 ie: model="fsl,mpc5200"
134#interrupt-cells int must be <3>. If it is not defined 160revision string Silicon revision of chip
135 here then it must be defined in every 161 ie: revision="M08A"
136 soc device node. 162
137bus-frequency int IPB bus frequency in HZ. Clock rate 163The 'model' and 'revision' properties are *strongly* recommended. Having
138 used by most of the soc devices. 164them presence acts as a bit of a safety net for working around as yet
139 Defining it here avoids needing it 165undiscovered bugs on one version of silicon. For example, device drivers
140 added to every device node. 166can use the model and revision properties to decide if a bug fix should
167be turned on.
141 168
1424) soc5200 child nodes 1694) soc5200 child nodes
143---------------------- 170----------------------
144Any on chip SOC devices available to Linux must appear as soc5200 child nodes. 171Any on chip SOC devices available to Linux must appear as soc5200 child nodes.
145 172
146Note: in the tables below, '*' matches all <chip> values. ie. 173Note: The tables below show the value for the mpc5200. A mpc5200b device
147*-pic would translate to "mpc5200-pic\0mpc52xx-pic" 174tree should use the "mpc5200b-<device>\0mpc5200-<device> form.
148 175
149Required soc5200 child nodes: 176Required soc5200 child nodes:
150name device_type compatible Description 177name device_type compatible Description
151---- ----------- ---------- ----------- 178---- ----------- ---------- -----------
152cdm@<addr> cdm *-cmd Clock Distribution 179cdm@<addr> cdm mpc5200-cmd Clock Distribution
153pic@<addr> interrupt-controller *-pic need an interrupt 180pic@<addr> interrupt-controller mpc5200-pic need an interrupt
154 controller to boot 181 controller to boot
155bestcomm@<addr> dma-controller *-bestcomm 52xx pic also requires 182bestcomm@<addr> dma-controller mpc5200-bestcomm 5200 pic also requires
156 the bestcomm device 183 the bestcomm device
157 184
158Recommended soc5200 child nodes; populate as needed for your board 185Recommended soc5200 child nodes; populate as needed for your board
159name device_type compatible Description 186name device_type compatible Description
160---- ----------- ---------- ----------- 187---- ----------- ---------- -----------
161gpt@<addr> gpt *-gpt General purpose timers 188gpt@<addr> gpt mpc5200-gpt General purpose timers
162rtc@<addr> rtc *-rtc Real time clock 189rtc@<addr> rtc mpc5200-rtc Real time clock
163mscan@<addr> mscan *-mscan CAN bus controller 190mscan@<addr> mscan mpc5200-mscan CAN bus controller
164pci@<addr> pci *-pci PCI bridge 191pci@<addr> pci mpc5200-pci PCI bridge
165serial@<addr> serial *-psc-uart PSC in serial mode 192serial@<addr> serial mpc5200-psc-uart PSC in serial mode
166i2s@<addr> sound *-psc-i2s PSC in i2s mode 193i2s@<addr> sound mpc5200-psc-i2s PSC in i2s mode
167ac97@<addr> sound *-psc-ac97 PSC in ac97 mode 194ac97@<addr> sound mpc5200-psc-ac97 PSC in ac97 mode
168spi@<addr> spi *-psc-spi PSC in spi mode 195spi@<addr> spi mpc5200-psc-spi PSC in spi mode
169irda@<addr> irda *-psc-irda PSC in IrDA mode 196irda@<addr> irda mpc5200-psc-irda PSC in IrDA mode
170spi@<addr> spi *-spi MPC52xx spi device 197spi@<addr> spi mpc5200-spi MPC5200 spi device
171ethernet@<addr> network *-fec MPC52xx ethernet device 198ethernet@<addr> network mpc5200-fec MPC5200 ethernet device
172ata@<addr> ata *-ata IDE ATA interface 199ata@<addr> ata mpc5200-ata IDE ATA interface
173i2c@<addr> i2c *-i2c I2C controller 200i2c@<addr> i2c mpc5200-i2c I2C controller
174usb@<addr> usb-ohci-be *-ohci,ohci-be USB controller 201usb@<addr> usb-ohci-be mpc5200-ohci,ohci-be USB controller
175xlb@<addr> xlb *-xlb XLB arbritrator 202xlb@<addr> xlb mpc5200-xlb XLB arbritrator
203
204Important child node properties
205name type description
206---- ---- -----------
207cell-index int When multiple devices are present, is the
208 index of the device in the hardware (ie. There
209 are 6 PSC on the 5200 numbered PSC1 to PSC6)
210 PSC1 has 'cell-index = <0>'
211 PSC4 has 'cell-index = <3>'
212
2135) General Purpose Timer nodes (child of soc5200 node)
214On the mpc5200 and 5200b, GPT0 has a watchdog timer function. If the board
215design supports the internal wdt, then the device node for GPT0 should
216include the empty property 'has-wdt'.
217
2186) PSC nodes (child of soc5200 node)
219PSC nodes can define the optional 'port-number' property to force assignment
220order of serial ports. For example, PSC5 might be physically connected to
221the port labeled 'COM1' and PSC1 wired to 'COM1'. In this case, PSC5 would
222have a "port-number = <0>" property, and PSC1 would have "port-number = <1>".
223
224PSC in i2s mode: The mpc5200 and mpc5200b PSCs are not compatible when in
225i2s mode. An 'mpc5200b-psc-i2s' node cannot include 'mpc5200-psc-i2s' in the
226compatible field.
176 227
177IV - Extra Notes 228IV - Extra Notes
178================ 229================
179 230
1801. Interrupt mapping 2311. Interrupt mapping
181-------------------- 232--------------------
182The mpc52xx pic driver splits hardware IRQ numbers into two levels. The 233The mpc5200 pic driver splits hardware IRQ numbers into two levels. The
183split reflects the layout of the PIC hardware itself, which groups 234split reflects the layout of the PIC hardware itself, which groups
184interrupts into one of three groups; CRIT, MAIN or PERP. Also, the 235interrupts into one of three groups; CRIT, MAIN or PERP. Also, the
185Bestcomm dma engine has it's own set of interrupt sources which are 236Bestcomm dma engine has it's own set of interrupt sources which are
186cascaded off of peripheral interrupt 0, which the driver interprets as a 237cascaded off of peripheral interrupt 0, which the driver interprets as a
187fourth group, SDMA. 238fourth group, SDMA.
188 239
189The interrupts property for device nodes using the mpc52xx pic consists 240The interrupts property for device nodes using the mpc5200 pic consists
190of three cells; <L1 L2 level> 241of three cells; <L1 L2 level>
191 242
192 L1 := [CRIT=0, MAIN=1, PERP=2, SDMA=3] 243 L1 := [CRIT=0, MAIN=1, PERP=2, SDMA=3]
193 L2 := interrupt number; directly mapped from the value in the 244 L2 := interrupt number; directly mapped from the value in the
194 "ICTL PerStat, MainStat, CritStat Encoded Register" 245 "ICTL PerStat, MainStat, CritStat Encoded Register"
195 level := [LEVEL_HIGH=0, EDGE_RISING=1, EDGE_FALLING=2, LEVEL_LOW=3] 246 level := [LEVEL_HIGH=0, EDGE_RISING=1, EDGE_FALLING=2, LEVEL_LOW=3]
247
2482. Shared registers
249-------------------
250Some SoC devices share registers between them. ie. the i2c devices use
251a single clock control register, and almost all device are affected by
252the port_config register. Devices which need to manipulate shared regs
253should look to the parent SoC node. The soc node is responsible
254for arbitrating all shared register access.
diff --git a/Documentation/rbtree.txt b/Documentation/rbtree.txt
new file mode 100644
index 000000000000..7224459b469e
--- /dev/null
+++ b/Documentation/rbtree.txt
@@ -0,0 +1,192 @@
1Red-black Trees (rbtree) in Linux
2January 18, 2007
3Rob Landley <rob@landley.net>
4=============================
5
6What are red-black trees, and what are they for?
7------------------------------------------------
8
9Red-black trees are a type of self-balancing binary search tree, used for
10storing sortable key/value data pairs. This differs from radix trees (which
11are used to efficiently store sparse arrays and thus use long integer indexes
12to insert/access/delete nodes) and hash tables (which are not kept sorted to
13be easily traversed in order, and must be tuned for a specific size and
14hash function where rbtrees scale gracefully storing arbitrary keys).
15
16Red-black trees are similar to AVL trees, but provide faster real-time bounded
17worst case performance for insertion and deletion (at most two rotations and
18three rotations, respectively, to balance the tree), with slightly slower
19(but still O(log n)) lookup time.
20
21To quote Linux Weekly News:
22
23 There are a number of red-black trees in use in the kernel.
24 The anticipatory, deadline, and CFQ I/O schedulers all employ
25 rbtrees to track requests; the packet CD/DVD driver does the same.
26 The high-resolution timer code uses an rbtree to organize outstanding
27 timer requests. The ext3 filesystem tracks directory entries in a
28 red-black tree. Virtual memory areas (VMAs) are tracked with red-black
29 trees, as are epoll file descriptors, cryptographic keys, and network
30 packets in the "hierarchical token bucket" scheduler.
31
32This document covers use of the Linux rbtree implementation. For more
33information on the nature and implementation of Red Black Trees, see:
34
35 Linux Weekly News article on red-black trees
36 http://lwn.net/Articles/184495/
37
38 Wikipedia entry on red-black trees
39 http://en.wikipedia.org/wiki/Red-black_tree
40
41Linux implementation of red-black trees
42---------------------------------------
43
44Linux's rbtree implementation lives in the file "lib/rbtree.c". To use it,
45"#include <linux/rbtree.h>".
46
47The Linux rbtree implementation is optimized for speed, and thus has one
48less layer of indirection (and better cache locality) than more traditional
49tree implementations. Instead of using pointers to separate rb_node and data
50structures, each instance of struct rb_node is embedded in the data structure
51it organizes. And instead of using a comparison callback function pointer,
52users are expected to write their own tree search and insert functions
53which call the provided rbtree functions. Locking is also left up to the
54user of the rbtree code.
55
56Creating a new rbtree
57---------------------
58
59Data nodes in an rbtree tree are structures containing a struct rb_node member:
60
61 struct mytype {
62 struct rb_node node;
63 char *keystring;
64 };
65
66When dealing with a pointer to the embedded struct rb_node, the containing data
67structure may be accessed with the standard container_of() macro. In addition,
68individual members may be accessed directly via rb_entry(node, type, member).
69
70At the root of each rbtree is an rb_root structure, which is initialized to be
71empty via:
72
73 struct rb_root mytree = RB_ROOT;
74
75Searching for a value in an rbtree
76----------------------------------
77
78Writing a search function for your tree is fairly straightforward: start at the
79root, compare each value, and follow the left or right branch as necessary.
80
81Example:
82
83 struct mytype *my_search(struct rb_root *root, char *string)
84 {
85 struct rb_node *node = root->rb_node;
86
87 while (node) {
88 struct mytype *data = container_of(node, struct mytype, node);
89 int result;
90
91 result = strcmp(string, data->keystring);
92
93 if (result < 0)
94 node = node->rb_left;
95 else if (result > 0)
96 node = node->rb_right;
97 else
98 return data;
99 }
100 return NULL;
101 }
102
103Inserting data into an rbtree
104-----------------------------
105
106Inserting data in the tree involves first searching for the place to insert the
107new node, then inserting the node and rebalancing ("recoloring") the tree.
108
109The search for insertion differs from the previous search by finding the
110location of the pointer on which to graft the new node. The new node also
111needs a link to its parent node for rebalancing purposes.
112
113Example:
114
115 int my_insert(struct rb_root *root, struct mytype *data)
116 {
117 struct rb_node **new = &(root->rb_node), *parent = NULL;
118
119 /* Figure out where to put new node */
120 while (*new) {
121 struct mytype *this = container_of(*new, struct mytype, node);
122 int result = strcmp(data->keystring, this->keystring);
123
124 parent = *new;
125 if (result < 0)
126 new = &((*new)->rb_left);
127 else if (result > 0)
128 new = &((*new)->rb_right);
129 else
130 return FALSE;
131 }
132
133 /* Add new node and rebalance tree. */
134 rb_link_node(data->node, parent, new);
135 rb_insert_color(data->node, root);
136
137 return TRUE;
138 }
139
140Removing or replacing existing data in an rbtree
141------------------------------------------------
142
143To remove an existing node from a tree, call:
144
145 void rb_erase(struct rb_node *victim, struct rb_root *tree);
146
147Example:
148
149 struct mytype *data = mysearch(mytree, "walrus");
150
151 if (data) {
152 rb_erase(data->node, mytree);
153 myfree(data);
154 }
155
156To replace an existing node in a tree with a new one with the same key, call:
157
158 void rb_replace_node(struct rb_node *old, struct rb_node *new,
159 struct rb_root *tree);
160
161Replacing a node this way does not re-sort the tree: If the new node doesn't
162have the same key as the old node, the rbtree will probably become corrupted.
163
164Iterating through the elements stored in an rbtree (in sort order)
165------------------------------------------------------------------
166
167Four functions are provided for iterating through an rbtree's contents in
168sorted order. These work on arbitrary trees, and should not need to be
169modified or wrapped (except for locking purposes):
170
171 struct rb_node *rb_first(struct rb_root *tree);
172 struct rb_node *rb_last(struct rb_root *tree);
173 struct rb_node *rb_next(struct rb_node *node);
174 struct rb_node *rb_prev(struct rb_node *node);
175
176To start iterating, call rb_first() or rb_last() with a pointer to the root
177of the tree, which will return a pointer to the node structure contained in
178the first or last element in the tree. To continue, fetch the next or previous
179node by calling rb_next() or rb_prev() on the current node. This will return
180NULL when there are no more nodes left.
181
182The iterator functions return a pointer to the embedded struct rb_node, from
183which the containing data structure may be accessed with the container_of()
184macro, and individual members may be accessed directly via
185rb_entry(node, type, member).
186
187Example:
188
189 struct rb_node *node;
190 for (node = rb_first(&mytree); node; node = rb_next(node))
191 printk("key=%s\n", rb_entry(node, int, keystring));
192
diff --git a/Documentation/rtc.txt b/Documentation/rtc.txt
index 7cf1ec5bcdd3..1ef6bb88cd00 100644
--- a/Documentation/rtc.txt
+++ b/Documentation/rtc.txt
@@ -149,7 +149,7 @@ RTC class framework, but can't be supported by the older driver.
149 is connected to an IRQ line, it can often issue an alarm IRQ up to 149 is connected to an IRQ line, it can often issue an alarm IRQ up to
150 24 hours in the future. 150 24 hours in the future.
151 151
152 * RTC_WKALM_SET, RTC_WKALM_READ ... RTCs that can issue alarms beyond 152 * RTC_WKALM_SET, RTC_WKALM_RD ... RTCs that can issue alarms beyond
153 the next 24 hours use a slightly more powerful API, which supports 153 the next 24 hours use a slightly more powerful API, which supports
154 setting the longer alarm time and enabling its IRQ using a single 154 setting the longer alarm time and enabling its IRQ using a single
155 request (using the same model as EFI firmware). 155 request (using the same model as EFI firmware).
@@ -167,6 +167,28 @@ Linux out of a low power sleep state (or hibernation) back to a fully
167operational state. For example, a system could enter a deep power saving 167operational state. For example, a system could enter a deep power saving
168state until it's time to execute some scheduled tasks. 168state until it's time to execute some scheduled tasks.
169 169
170Note that many of these ioctls need not actually be implemented by your
171driver. The common rtc-dev interface handles many of these nicely if your
172driver returns ENOIOCTLCMD. Some common examples:
173
174 * RTC_RD_TIME, RTC_SET_TIME: the read_time/set_time functions will be
175 called with appropriate values.
176
177 * RTC_ALM_SET, RTC_ALM_READ, RTC_WKALM_SET, RTC_WKALM_RD: the
178 set_alarm/read_alarm functions will be called. To differentiate
179 between the ALM and WKALM, check the larger fields of the rtc_wkalrm
180 struct (like tm_year). These will be set to -1 when using ALM and
181 will be set to proper values when using WKALM.
182
183 * RTC_IRQP_SET, RTC_IRQP_READ: the irq_set_freq function will be called
184 to set the frequency while the framework will handle the read for you
185 since the frequency is stored in the irq_freq member of the rtc_device
186 structure. Also make sure you set the max_user_freq member in your
187 initialization routines so the framework can sanity check the user
188 input for you.
189
190If all else fails, check out the rtc-test.c driver!
191
170 192
171-------------------- 8< ---------------- 8< ----------------------------- 193-------------------- 8< ---------------- 8< -----------------------------
172 194
@@ -237,7 +259,7 @@ int main(int argc, char **argv)
237 "\n...Update IRQs not supported.\n"); 259 "\n...Update IRQs not supported.\n");
238 goto test_READ; 260 goto test_READ;
239 } 261 }
240 perror("ioctl"); 262 perror("RTC_UIE_ON ioctl");
241 exit(errno); 263 exit(errno);
242 } 264 }
243 265
@@ -284,7 +306,7 @@ int main(int argc, char **argv)
284 /* Turn off update interrupts */ 306 /* Turn off update interrupts */
285 retval = ioctl(fd, RTC_UIE_OFF, 0); 307 retval = ioctl(fd, RTC_UIE_OFF, 0);
286 if (retval == -1) { 308 if (retval == -1) {
287 perror("ioctl"); 309 perror("RTC_UIE_OFF ioctl");
288 exit(errno); 310 exit(errno);
289 } 311 }
290 312
@@ -292,7 +314,7 @@ test_READ:
292 /* Read the RTC time/date */ 314 /* Read the RTC time/date */
293 retval = ioctl(fd, RTC_RD_TIME, &rtc_tm); 315 retval = ioctl(fd, RTC_RD_TIME, &rtc_tm);
294 if (retval == -1) { 316 if (retval == -1) {
295 perror("ioctl"); 317 perror("RTC_RD_TIME ioctl");
296 exit(errno); 318 exit(errno);
297 } 319 }
298 320
@@ -320,14 +342,14 @@ test_READ:
320 "\n...Alarm IRQs not supported.\n"); 342 "\n...Alarm IRQs not supported.\n");
321 goto test_PIE; 343 goto test_PIE;
322 } 344 }
323 perror("ioctl"); 345 perror("RTC_ALM_SET ioctl");
324 exit(errno); 346 exit(errno);
325 } 347 }
326 348
327 /* Read the current alarm settings */ 349 /* Read the current alarm settings */
328 retval = ioctl(fd, RTC_ALM_READ, &rtc_tm); 350 retval = ioctl(fd, RTC_ALM_READ, &rtc_tm);
329 if (retval == -1) { 351 if (retval == -1) {
330 perror("ioctl"); 352 perror("RTC_ALM_READ ioctl");
331 exit(errno); 353 exit(errno);
332 } 354 }
333 355
@@ -337,7 +359,7 @@ test_READ:
337 /* Enable alarm interrupts */ 359 /* Enable alarm interrupts */
338 retval = ioctl(fd, RTC_AIE_ON, 0); 360 retval = ioctl(fd, RTC_AIE_ON, 0);
339 if (retval == -1) { 361 if (retval == -1) {
340 perror("ioctl"); 362 perror("RTC_AIE_ON ioctl");
341 exit(errno); 363 exit(errno);
342 } 364 }
343 365
@@ -355,7 +377,7 @@ test_READ:
355 /* Disable alarm interrupts */ 377 /* Disable alarm interrupts */
356 retval = ioctl(fd, RTC_AIE_OFF, 0); 378 retval = ioctl(fd, RTC_AIE_OFF, 0);
357 if (retval == -1) { 379 if (retval == -1) {
358 perror("ioctl"); 380 perror("RTC_AIE_OFF ioctl");
359 exit(errno); 381 exit(errno);
360 } 382 }
361 383
@@ -368,7 +390,7 @@ test_PIE:
368 fprintf(stderr, "\nNo periodic IRQ support\n"); 390 fprintf(stderr, "\nNo periodic IRQ support\n");
369 return 0; 391 return 0;
370 } 392 }
371 perror("ioctl"); 393 perror("RTC_IRQP_READ ioctl");
372 exit(errno); 394 exit(errno);
373 } 395 }
374 fprintf(stderr, "\nPeriodic IRQ rate is %ldHz.\n", tmp); 396 fprintf(stderr, "\nPeriodic IRQ rate is %ldHz.\n", tmp);
@@ -387,7 +409,7 @@ test_PIE:
387 "\n...Periodic IRQ rate is fixed\n"); 409 "\n...Periodic IRQ rate is fixed\n");
388 goto done; 410 goto done;
389 } 411 }
390 perror("ioctl"); 412 perror("RTC_IRQP_SET ioctl");
391 exit(errno); 413 exit(errno);
392 } 414 }
393 415
@@ -397,7 +419,7 @@ test_PIE:
397 /* Enable periodic interrupts */ 419 /* Enable periodic interrupts */
398 retval = ioctl(fd, RTC_PIE_ON, 0); 420 retval = ioctl(fd, RTC_PIE_ON, 0);
399 if (retval == -1) { 421 if (retval == -1) {
400 perror("ioctl"); 422 perror("RTC_PIE_ON ioctl");
401 exit(errno); 423 exit(errno);
402 } 424 }
403 425
@@ -416,7 +438,7 @@ test_PIE:
416 /* Disable periodic interrupts */ 438 /* Disable periodic interrupts */
417 retval = ioctl(fd, RTC_PIE_OFF, 0); 439 retval = ioctl(fd, RTC_PIE_OFF, 0);
418 if (retval == -1) { 440 if (retval == -1) {
419 perror("ioctl"); 441 perror("RTC_PIE_OFF ioctl");
420 exit(errno); 442 exit(errno);
421 } 443 }
422 } 444 }
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/s390/crypto/crypto-API.txt b/Documentation/s390/crypto/crypto-API.txt
deleted file mode 100644
index 71ae6ca9f2c2..000000000000
--- a/Documentation/s390/crypto/crypto-API.txt
+++ /dev/null
@@ -1,83 +0,0 @@
1crypto-API support for z990 Message Security Assist (MSA) instructions
2~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3
4AUTHOR: Thomas Spatzier (tspat@de.ibm.com)
5
6
71. Introduction crypto-API
8~~~~~~~~~~~~~~~~~~~~~~~~~~
9See Documentation/crypto/api-intro.txt for an introduction/description of the
10kernel crypto API.
11According to api-intro.txt support for z990 crypto instructions has been added
12in the algorithm api layer of the crypto API. Several files containing z990
13optimized implementations of crypto algorithms are placed in the
14arch/s390/crypto directory.
15
16
172. Probing for availability of MSA
18~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
19It should be possible to use Kernels with the z990 crypto implementations both
20on machines with MSA available and on those without MSA (pre z990 or z990
21without MSA). Therefore a simple probing mechanism has been implemented:
22In the init function of each crypto module the availability of MSA and of the
23respective crypto algorithm in particular will be tested. If the algorithm is
24available the module will load and register its algorithm with the crypto API.
25
26If the respective crypto algorithm is not available, the init function will
27return -ENOSYS. In that case a fallback to the standard software implementation
28of the crypto algorithm must be taken ( -> the standard crypto modules are
29also built when compiling the kernel).
30
31
323. Ensuring z990 crypto module preference
33~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
34If z990 crypto instructions are available the optimized modules should be
35preferred instead of standard modules.
36
373.1. compiled-in modules
38~~~~~~~~~~~~~~~~~~~~~~~~
39For compiled-in modules it has to be ensured that the z990 modules are linked
40before the standard crypto modules. Then, on system startup the init functions
41of z990 crypto modules will be called first and query for availability of z990
42crypto instructions. If instruction is available, the z990 module will register
43its crypto algorithm implementation -> the load of the standard module will fail
44since the algorithm is already registered.
45If z990 crypto instruction is not available the load of the z990 module will
46fail -> the standard module will load and register its algorithm.
47
483.2. dynamic modules
49~~~~~~~~~~~~~~~~~~~~
50A system administrator has to take care of giving preference to z990 crypto
51modules. If MSA is available appropriate lines have to be added to
52/etc/modprobe.conf.
53
54Example: z990 crypto instruction for SHA1 algorithm is available
55
56 add the following line to /etc/modprobe.conf (assuming the
57 z990 crypto modules for SHA1 is called sha1_z990):
58
59 alias sha1 sha1_z990
60
61 -> when the sha1 algorithm is requested through the crypto API
62 (which has a module autoloader) the z990 module will be loaded.
63
64TBD: a userspace module probing mechanism
65 something like 'probe sha1 sha1_z990 sha1' in modprobe.conf
66 -> try module sha1_z990, if it fails to load standard module sha1
67 the 'probe' statement is currently not supported in modprobe.conf
68
69
704. Currently implemented z990 crypto algorithms
71~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
72The following crypto algorithms with z990 MSA support are currently implemented.
73The name of each algorithm under which it is registered in crypto API and the
74name of the respective module is given in square brackets.
75
76- SHA1 Digest Algorithm [sha1 -> sha1_z990]
77- DES Encrypt/Decrypt Algorithm (64bit key) [des -> des_z990]
78- Triple DES Encrypt/Decrypt Algorithm (128bit key) [des3_ede128 -> des_z990]
79- Triple DES Encrypt/Decrypt Algorithm (192bit key) [des3_ede -> des_z990]
80
81In order to load, for example, the sha1_z990 module when the sha1 algorithm is
82requested (see 3.2.) add 'alias sha1 sha1_z990' to /etc/modprobe.conf.
83
diff --git a/Documentation/s390/zfcpdump.txt b/Documentation/s390/zfcpdump.txt
new file mode 100644
index 000000000000..cf45d27c4608
--- /dev/null
+++ b/Documentation/s390/zfcpdump.txt
@@ -0,0 +1,87 @@
1s390 SCSI dump tool (zfcpdump)
2
3System z machines (z900 or higher) provide hardware support for creating system
4dumps on SCSI disks. The dump process is initiated by booting a dump tool, which
5has to create a dump of the current (probably crashed) Linux image. In order to
6not overwrite memory of the crashed Linux with data of the dump tool, the
7hardware saves some memory plus the register sets of the boot cpu before the
8dump tool is loaded. There exists an SCLP hardware interface to obtain the saved
9memory afterwards. Currently 32 MB are saved.
10
11This zfcpdump implementation consists of a Linux dump kernel together with
12a userspace dump tool, which are loaded together into the saved memory region
13below 32 MB. zfcpdump is installed on a SCSI disk using zipl (as contained in
14the s390-tools package) to make the device bootable. The operator of a Linux
15system can then trigger a SCSI dump by booting the SCSI disk, where zfcpdump
16resides on.
17
18The kernel part of zfcpdump is implemented as a debugfs file under "zcore/mem",
19which exports memory and registers of the crashed Linux in an s390
20standalone dump format. It can be used in the same way as e.g. /dev/mem. The
21dump format defines a 4K header followed by plain uncompressed memory. The
22register sets are stored in the prefix pages of the respective cpus. To build a
23dump enabled kernel with the zcore driver, the kernel config option
24CONFIG_ZFCPDUMP has to be set. When reading from "zcore/mem", the part of
25memory, which has been saved by hardware is read by the driver via the SCLP
26hardware interface. The second part is just copied from the non overwritten real
27memory.
28
29The userspace application of zfcpdump can reside e.g. in an intitramfs or an
30initrd. It reads from zcore/mem and writes the system dump to a file on a
31SCSI disk.
32
33To build a zfcpdump kernel use the following settings in your kernel
34configuration:
35 * CONFIG_ZFCPDUMP=y
36 * Enable ZFCP driver
37 * Enable SCSI driver
38 * Enable ext2 and ext3 filesystems
39 * Disable as many features as possible to keep the kernel small.
40 E.g. network support is not needed at all.
41
42To use the zfcpdump userspace application in an initramfs you have to do the
43following:
44
45 * Copy the zfcpdump executable somewhere into your Linux tree.
46 E.g. to "arch/s390/boot/zfcpdump. If you do not want to include
47 shared libraries, compile the tool with the "-static" gcc option.
48 * If you want to include e2fsck, add it to your source tree, too. The zfcpdump
49 application attempts to start /sbin/e2fsck from the ramdisk.
50 * Use an initramfs config file like the following:
51
52 dir /dev 755 0 0
53 nod /dev/console 644 0 0 c 5 1
54 nod /dev/null 644 0 0 c 1 3
55 nod /dev/sda1 644 0 0 b 8 1
56 nod /dev/sda2 644 0 0 b 8 2
57 nod /dev/sda3 644 0 0 b 8 3
58 nod /dev/sda4 644 0 0 b 8 4
59 nod /dev/sda5 644 0 0 b 8 5
60 nod /dev/sda6 644 0 0 b 8 6
61 nod /dev/sda7 644 0 0 b 8 7
62 nod /dev/sda8 644 0 0 b 8 8
63 nod /dev/sda9 644 0 0 b 8 9
64 nod /dev/sda10 644 0 0 b 8 10
65 nod /dev/sda11 644 0 0 b 8 11
66 nod /dev/sda12 644 0 0 b 8 12
67 nod /dev/sda13 644 0 0 b 8 13
68 nod /dev/sda14 644 0 0 b 8 14
69 nod /dev/sda15 644 0 0 b 8 15
70 file /init arch/s390/boot/zfcpdump 755 0 0
71 file /sbin/e2fsck arch/s390/boot/e2fsck 755 0 0
72 dir /proc 755 0 0
73 dir /sys 755 0 0
74 dir /mnt 755 0 0
75 dir /sbin 755 0 0
76
77 * Issue "make image" to build the zfcpdump image with initramfs.
78
79In a Linux distribution the zfcpdump enabled kernel image must be copied to
80/usr/share/zfcpdump/zfcpdump.image, where the s390 zipl tool is looking for the
81dump kernel when preparing a SCSI dump disk.
82
83If you use a ramdisk copy it to "/usr/share/zfcpdump/zfcpdump.rd".
84
85For more information on how to use zfcpdump refer to the s390 'Using the Dump
86Tools book', which is available from
87http://www.ibm.com/developerworks/linux/linux390.
diff --git a/Documentation/scsi/ChangeLog.megaraid b/Documentation/scsi/ChangeLog.megaraid
index a056bbe67c7e..37796fe45bd0 100644
--- a/Documentation/scsi/ChangeLog.megaraid
+++ b/Documentation/scsi/ChangeLog.megaraid
@@ -1,3 +1,19 @@
1Release Date : Thu Nov 16 15:32:35 EST 2006 -
2 Sumant Patro <sumant.patro@lsi.com>
3Current Version : 2.20.5.1 (scsi module), 2.20.2.6 (cmm module)
4Older Version : 2.20.4.9 (scsi module), 2.20.2.6 (cmm module)
5
61. Changes in Initialization to fix kdump failure.
7 Send SYNC command on loading.
8 This command clears the pending commands in the adapter
9 and re-initialize its internal RAID structure.
10 Without this change, megaraid driver either panics or fails to
11 initialize the adapter during kdump's second kernel boot
12 if there are pending commands or interrupts from other devices
13 sharing the same IRQ.
142. Authors email-id domain name changed from lsil.com to lsi.com.
15 Also modified the MODULE_AUTHOR to megaraidlinux@lsi.com
16
1Release Date : Fri May 19 09:31:45 EST 2006 - Seokmann Ju <sju@lsil.com> 17Release Date : Fri May 19 09:31:45 EST 2006 - Seokmann Ju <sju@lsil.com>
2Current Version : 2.20.4.9 (scsi module), 2.20.2.6 (cmm module) 18Current Version : 2.20.4.9 (scsi module), 2.20.2.6 (cmm module)
3Older Version : 2.20.4.8 (scsi module), 2.20.2.6 (cmm module) 19Older Version : 2.20.4.8 (scsi module), 2.20.2.6 (cmm module)
diff --git a/Documentation/sh/new-machine.txt b/Documentation/sh/new-machine.txt
index 73988e0d112b..5482bf5d005b 100644
--- a/Documentation/sh/new-machine.txt
+++ b/Documentation/sh/new-machine.txt
@@ -17,7 +17,7 @@ of the board-specific code (with the exception of stboards) ended up
17in arch/sh/kernel/ directly, with board-specific headers ending up in 17in arch/sh/kernel/ directly, with board-specific headers ending up in
18include/asm-sh/. For the new kernel, things are broken out by board type, 18include/asm-sh/. For the new kernel, things are broken out by board type,
19companion chip type, and CPU type. Looking at a tree view of this directory 19companion chip type, and CPU type. Looking at a tree view of this directory
20heirarchy looks like the following: 20hierarchy looks like the following:
21 21
22Board-specific code: 22Board-specific code:
23 23
@@ -108,7 +108,7 @@ overloading), and you can feel free to name the directory after the family
108member itself. 108member itself.
109 109
110There are a few things that each board is required to have, both in the 110There are a few things that each board is required to have, both in the
111arch/sh/boards and the include/asm-sh/ heirarchy. In order to better 111arch/sh/boards and the include/asm-sh/ hierarchy. In order to better
112explain this, we use some examples for adding an imaginary board. For 112explain this, we use some examples for adding an imaginary board. For
113setup code, we're required at the very least to provide definitions for 113setup code, we're required at the very least to provide definitions for
114get_system_type() and platform_setup(). For our imaginary board, this 114get_system_type() and platform_setup(). For our imaginary board, this
diff --git a/Documentation/sony-laptop.txt b/Documentation/sony-laptop.txt
new file mode 100644
index 000000000000..7a5c1a81905c
--- /dev/null
+++ b/Documentation/sony-laptop.txt
@@ -0,0 +1,117 @@
1Sony Notebook Control Driver (SNC) Readme
2-----------------------------------------
3 Copyright (C) 2004- 2005 Stelian Pop <stelian@popies.net>
4 Copyright (C) 2007 Mattia Dongili <malattia@linux.it>
5
6This mini-driver drives the SNC and SPIC device present in the ACPI BIOS of the
7Sony Vaio laptops. This driver mixes both devices functions under the same
8(hopefully consistent) interface. This also means that the sonypi driver is
9obsoleted by sony-laptop now.
10
11Fn keys (hotkeys):
12------------------
13Some models report hotkeys through the SNC or SPIC devices, such events are
14reported both through the ACPI subsystem as acpi events and through the INPUT
15subsystem. See the logs of acpid or /proc/acpi/event and
16/proc/bus/input/devices to find out what those events are and which input
17devices are created by the driver.
18
19Backlight control:
20------------------
21If your laptop model supports it, you will find sysfs files in the
22/sys/class/backlight/sony/
23directory. You will be able to query and set the current screen
24brightness:
25 brightness get/set screen brightness (an iteger
26 between 0 and 7)
27 actual_brightness reading from this file will query the HW
28 to get real brightness value
29 max_brightness the maximum brightness value
30
31
32Platform specific:
33------------------
34Loading the sony-laptop module will create a
35/sys/devices/platform/sony-laptop/
36directory populated with some files.
37
38You then read/write integer values from/to those files by using
39standard UNIX tools.
40
41The files are:
42 brightness_default screen brightness which will be set
43 when the laptop will be rebooted
44 cdpower power on/off the internal CD drive
45 audiopower power on/off the internal sound card
46 lanpower power on/off the internal ethernet card
47 (only in debug mode)
48 bluetoothpower power on/off the internal bluetooth device
49 fanspeed get/set the fan speed
50
51Note that some files may be missing if they are not supported
52by your particular laptop model.
53
54Example usage:
55 # echo "1" > /sys/devices/platform/sony-laptop/brightness_default
56sets the lowest screen brightness for the next and later reboots,
57 # echo "8" > /sys/devices/platform/sony-laptop/brightness_default
58sets the highest screen brightness for the next and later reboots,
59 # cat /sys/devices/platform/sony-laptop/brightness_default
60retrieves the value.
61
62 # echo "0" > /sys/devices/platform/sony-laptop/audiopower
63powers off the sound card,
64 # echo "1" > /sys/devices/platform/sony-laptop/audiopower
65powers on the sound card.
66
67Development:
68------------
69
70If you want to help with the development of this driver (and
71you are not afraid of any side effects doing strange things with
72your ACPI BIOS could have on your laptop), load the driver and
73pass the option 'debug=1'.
74
75REPEAT: DON'T DO THIS IF YOU DON'T LIKE RISKY BUSINESS.
76
77In your kernel logs you will find the list of all ACPI methods
78the SNC device has on your laptop. You can see the GCDP/GCDP methods
79used to pwer on/off the CD drive, but there are others.
80
81I HAVE NO IDEA WHAT THOSE METHODS DO.
82
83The sony-laptop driver creates, for some of those methods (the most
84current ones found on several Vaio models), an entry under
85/sys/devices/platform/sony-laptop, just like the 'cdpower' one.
86You can create other entries corresponding to your own laptop methods by
87further editing the source (see the 'sony_nc_values' table, and add a new
88entry to this table with your get/set method names using the
89SNC_HANDLE_NAMES macro).
90
91Your mission, should you accept it, is to try finding out what
92those entries are for, by reading/writing random values from/to those
93files and find out what is the impact on your laptop.
94
95Should you find anything interesting, please report it back to me,
96I will not disavow all knowledge of your actions :)
97
98See also http://www.linux.it/~malattia/wiki/index.php/Sony_drivers for other
99useful info.
100
101Bugs/Limitations:
102-----------------
103
104* This driver is not based on official documentation from Sony
105 (because there is none), so there is no guarantee this driver
106 will work at all, or do the right thing. Although this hasn't
107 happened to me, this driver could do very bad things to your
108 laptop, including permanent damage.
109
110* The sony-laptop and sonypi drivers do not interact at all. In the
111 future, sonypi could use sony-laptop to do (part of) its business.
112
113* spicctrl, which is the userspace tool used to communicate with the
114 sonypi driver (through /dev/sonypi) does not try to use the
115 sony-laptop driver. In the future, spicctrl could try sonypi first,
116 and if it isn't present, try sony-laptop instead.
117
diff --git a/Documentation/sound/alsa/ALSA-Configuration.txt b/Documentation/sound/alsa/ALSA-Configuration.txt
index 9fef210ab50a..73e9a174b642 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.
@@ -364,7 +370,9 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
364 mpu_port - 0x300,0x310,0x320,0x330 = legacy port, 370 mpu_port - 0x300,0x310,0x320,0x330 = legacy port,
365 1 = integrated PCI port, 371 1 = integrated PCI port,
366 0 = disable (default) 372 0 = disable (default)
367 fm_port - 0x388 (default), 0 = disable (default) 373 fm_port - 0x388 = legacy port,
374 1 = integrated PCI port (default),
375 0 = disable
368 soft_ac3 - Software-conversion of raw SPDIF packets (model 033 only) 376 soft_ac3 - Software-conversion of raw SPDIF packets (model 033 only)
369 (default = 1) 377 (default = 1)
370 joystick_port - Joystick port address (0 = disable, 1 = auto-detect) 378 joystick_port - Joystick port address (0 = disable, 1 = auto-detect)
@@ -779,6 +787,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
779 asus-dig ASUS with SPDIF out 787 asus-dig ASUS with SPDIF out
780 asus-dig2 ASUS with SPDIF out (using GPIO2) 788 asus-dig2 ASUS with SPDIF out (using GPIO2)
781 uniwill 3-jack 789 uniwill 3-jack
790 fujitsu Fujitsu Laptops (Pi1536)
782 F1734 2-jack 791 F1734 2-jack
783 lg LG laptop (m1 express dual) 792 lg LG laptop (m1 express dual)
784 lg-lw LG LW20/LW25 laptop 793 lg-lw LG LW20/LW25 laptop
@@ -800,14 +809,18 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
800 ALC262 809 ALC262
801 fujitsu Fujitsu Laptop 810 fujitsu Fujitsu Laptop
802 hp-bpc HP xw4400/6400/8400/9400 laptops 811 hp-bpc HP xw4400/6400/8400/9400 laptops
812 hp-bpc-d7000 HP BPC D7000
803 benq Benq ED8 813 benq Benq ED8
814 hippo Hippo (ATI) with jack detection, Sony UX-90s
815 hippo_1 Hippo (Benq) with jack detection
804 basic fixed pin assignment w/o SPDIF 816 basic fixed pin assignment w/o SPDIF
805 auto auto-config reading BIOS (default) 817 auto auto-config reading BIOS (default)
806 818
807 ALC882/885 819 ALC882/885
808 3stack-dig 3-jack with SPDIF I/O 820 3stack-dig 3-jack with SPDIF I/O
809 6stck-dig 6-jack digital with SPDIF I/O 821 6stack-dig 6-jack digital with SPDIF I/O
810 arima Arima W820Di1 822 arima Arima W820Di1
823 macpro MacPro support
811 auto auto-config reading BIOS (default) 824 auto auto-config reading BIOS (default)
812 825
813 ALC883/888 826 ALC883/888
@@ -817,6 +830,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 830 3stack-6ch-dig 3-jack 6-channel with SPDIF I/O
818 6stack-dig-demo 6-jack digital for Intel demo board 831 6stack-dig-demo 6-jack digital for Intel demo board
819 acer Acer laptops (Travelmate 3012WTMi, Aspire 5600, etc) 832 acer Acer laptops (Travelmate 3012WTMi, Aspire 5600, etc)
833 medion Medion Laptops
834 targa-dig Targa/MSI
835 targa-2ch-dig Targs/MSI with 2-channel
836 laptop-eapd 3-jack with SPDIF I/O and EAPD (Clevo M540JE, M550JE)
820 auto auto-config reading BIOS (default) 837 auto auto-config reading BIOS (default)
821 838
822 ALC861/660 839 ALC861/660
@@ -825,6 +842,16 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
825 6stack-dig 6-jack with SPDIF I/O 842 6stack-dig 6-jack with SPDIF I/O
826 3stack-660 3-jack (for ALC660) 843 3stack-660 3-jack (for ALC660)
827 uniwill-m31 Uniwill M31 laptop 844 uniwill-m31 Uniwill M31 laptop
845 toshiba Toshiba laptop support
846 asus Asus laptop support
847 asus-laptop ASUS F2/F3 laptops
848 auto auto-config reading BIOS (default)
849
850 ALC861VD/660VD
851 3stack 3-jack
852 3stack-dig 3-jack with SPDIF OUT
853 6stack-dig 6-jack with SPDIF OUT
854 3stack-660 3-jack (for ALC660VD)
828 auto auto-config reading BIOS (default) 855 auto auto-config reading BIOS (default)
829 856
830 CMI9880 857 CMI9880
@@ -839,12 +866,14 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
839 basic 3-jack (default) 866 basic 3-jack (default)
840 hp HP nx6320 867 hp HP nx6320
841 thinkpad Lenovo Thinkpad T60/X60/Z60 868 thinkpad Lenovo Thinkpad T60/X60/Z60
869 toshiba Toshiba U205
842 870
843 AD1986A 871 AD1986A
844 6stack 6-jack, separate surrounds (default) 872 6stack 6-jack, separate surrounds (default)
845 3stack 3-stack, shared surrounds 873 3stack 3-stack, shared surrounds
846 laptop 2-channel only (FSC V2060, Samsung M50) 874 laptop 2-channel only (FSC V2060, Samsung M50)
847 laptop-eapd 2-channel with EAPD (Samsung R65, ASUS A6J) 875 laptop-eapd 2-channel with EAPD (Samsung R65, ASUS A6J)
876 ultra 2-channel with EAPD (Samsung Ultra tablet PC)
848 877
849 AD1988 878 AD1988
850 6stack 6-jack 879 6stack 6-jack
@@ -854,11 +883,37 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
854 laptop 3-jack with hp-jack automute 883 laptop 3-jack with hp-jack automute
855 laptop-dig ditto with SPDIF 884 laptop-dig ditto with SPDIF
856 auto auto-config reading BIOS (default) 885 auto auto-config reading BIOS (default)
886
887 Conexant 5045
888 laptop Laptop config
889 test for testing/debugging purpose, almost all controls
890 can be adjusted. Appearing only when compiled with
891 $CONFIG_SND_DEBUG=y
892
893 Conexant 5047
894 laptop Basic Laptop config
895 laptop-hp Laptop config for some HP models (subdevice 30A5)
896 laptop-eapd Laptop config with EAPD support
897 test for testing/debugging purpose, almost all controls
898 can be adjusted. Appearing only when compiled with
899 $CONFIG_SND_DEBUG=y
857 900
858 STAC9200/9205/9220/9221/9254 901 STAC9200/9205/9254
902 ref Reference board
903
904 STAC9220/9221
859 ref Reference board 905 ref Reference board
860 3stack D945 3stack 906 3stack D945 3stack
861 5stack D945 5stack + SPDIF 907 5stack D945 5stack + SPDIF
908 macmini Intel Mac Mini
909 macbook Intel Mac Book
910 macbook-pro-v1 Intel Mac Book Pro 1st generation
911 macbook-pro Intel Mac Book Pro 2nd generation
912
913 STAC9202/9250/9251
914 ref Reference board, base config
915 m2-2 Some Gateway MX series laptops
916 m6 Some Gateway NX series laptops
862 917
863 STAC9227/9228/9229/927x 918 STAC9227/9228/9229/927x
864 ref Reference board 919 ref Reference board
@@ -974,6 +1029,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. 1029 Module for Envy24HT (VT/ICE1724), Envy24PT (VT1720) based PCI sound cards.
975 * MidiMan M Audio Revolution 5.1 1030 * MidiMan M Audio Revolution 5.1
976 * MidiMan M Audio Revolution 7.1 1031 * MidiMan M Audio Revolution 7.1
1032 * MidiMan M Audio Audiophile 192
977 * AMP Ltd AUDIO2000 1033 * AMP Ltd AUDIO2000
978 * TerraTec Aureon 5.1 Sky 1034 * TerraTec Aureon 5.1 Sky
979 * TerraTec Aureon 7.1 Space 1035 * TerraTec Aureon 7.1 Space
@@ -993,7 +1049,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
993 1049
994 model - Use the given board model, one of the following: 1050 model - Use the given board model, one of the following:
995 revo51, revo71, amp2000, prodigy71, prodigy71lt, 1051 revo51, revo71, amp2000, prodigy71, prodigy71lt,
996 prodigy192, aureon51, aureon71, universe, 1052 prodigy192, aureon51, aureon71, universe, ap192,
997 k8x800, phase22, phase28, ms300, av710 1053 k8x800, phase22, phase28, ms300, av710
998 1054
999 This module supports multiple cards and autoprobe. 1055 This module supports multiple cards and autoprobe.
@@ -1049,6 +1105,9 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
1049 buggy_semaphore - Enable workaround for hardwares with buggy 1105 buggy_semaphore - Enable workaround for hardwares with buggy
1050 semaphores (e.g. on some ASUS laptops) 1106 semaphores (e.g. on some ASUS laptops)
1051 (default off) 1107 (default off)
1108 spdif_aclink - Use S/PDIF over AC-link instead of direct connection
1109 from the controller chip
1110 (0 = off, 1 = on, -1 = default)
1052 1111
1053 This module supports one chip and autoprobe. 1112 This module supports one chip and autoprobe.
1054 1113
@@ -1371,6 +1430,13 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
1371 1430
1372 This module supports multiple cards. 1431 This module supports multiple cards.
1373 1432
1433 Module snd-portman2x4
1434 ---------------------
1435
1436 Module for Midiman Portman 2x4 parallel port MIDI interface
1437
1438 This module supports multiple cards.
1439
1374 Module snd-powermac (on ppc only) 1440 Module snd-powermac (on ppc only)
1375 --------------------------------- 1441 ---------------------------------
1376 1442
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/sparse.txt b/Documentation/sparse.txt
index f9c99c9a54f9..1a3bdc27d95e 100644
--- a/Documentation/sparse.txt
+++ b/Documentation/sparse.txt
@@ -45,11 +45,15 @@ special.
45Getting sparse 45Getting sparse
46~~~~~~~~~~~~~~ 46~~~~~~~~~~~~~~
47 47
48With git, you can just get it from 48You can get latest released versions from the Sparse homepage at
49http://www.kernel.org/pub/linux/kernel/people/josh/sparse/
49 50
50 rsync://rsync.kernel.org/pub/scm/devel/sparse/sparse.git 51Alternatively, you can get snapshots of the latest development version
52of sparse using git to clone..
51 53
52and DaveJ has tar-balls at 54 git://git.kernel.org/pub/scm/linux/kernel/git/josh/sparse.git
55
56DaveJ has hourly generated tarballs of the git tree available at..
53 57
54 http://www.codemonkey.org.uk/projects/git-snapshots/sparse/ 58 http://www.codemonkey.org.uk/projects/git-snapshots/sparse/
55 59
diff --git a/Documentation/spi/spi-summary b/Documentation/spi/spi-summary
index 72795796b13d..ecc7c9eb9f29 100644
--- a/Documentation/spi/spi-summary
+++ b/Documentation/spi/spi-summary
@@ -284,7 +284,6 @@ SPI protocol drivers somewhat resemble platform device drivers:
284 static struct spi_driver CHIP_driver = { 284 static struct spi_driver CHIP_driver = {
285 .driver = { 285 .driver = {
286 .name = "CHIP", 286 .name = "CHIP",
287 .bus = &spi_bus_type,
288 .owner = THIS_MODULE, 287 .owner = THIS_MODULE,
289 }, 288 },
290 289
@@ -312,7 +311,7 @@ might look like this unless you're creating a class_device:
312 chip = kzalloc(sizeof *chip, GFP_KERNEL); 311 chip = kzalloc(sizeof *chip, GFP_KERNEL);
313 if (!chip) 312 if (!chip)
314 return -ENOMEM; 313 return -ENOMEM;
315 dev_set_drvdata(&spi->dev, chip); 314 spi_set_drvdata(spi, chip);
316 315
317 ... etc 316 ... etc
318 return 0; 317 return 0;
diff --git a/Documentation/sysrq.txt b/Documentation/sysrq.txt
index 61613166981b..d43aa9d3c105 100644
--- a/Documentation/sysrq.txt
+++ b/Documentation/sysrq.txt
@@ -64,11 +64,6 @@ On all - write a character to /proc/sysrq-trigger. e.g.:
64 64
65* What are the 'command' keys? 65* What are the 'command' keys?
66~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 66~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
67'r' - Turns off keyboard raw mode and sets it to XLATE.
68
69'k' - Secure Access Key (SAK) Kills all programs on the current virtual
70 console. NOTE: See important comments below in SAK section.
71
72'b' - Will immediately reboot the system without syncing or unmounting 67'b' - Will immediately reboot the system without syncing or unmounting
73 your disks. 68 your disks.
74 69
@@ -76,21 +71,39 @@ On all - write a character to /proc/sysrq-trigger. e.g.:
76 71
77'd' - Shows all locks that are held. 72'd' - Shows all locks that are held.
78 73
79'o' - Will shut your system off (if configured and supported). 74'e' - Send a SIGTERM to all processes, except for init.
80 75
81's' - Will attempt to sync all mounted filesystems. 76'f' - Will call oom_kill to kill a memory hog process.
82 77
83'u' - Will attempt to remount all mounted filesystems read-only. 78'g' - Used by kgdb on ppc platforms.
84 79
85'p' - Will dump the current registers and flags to your console. 80'h' - Will display help (actually any other key than those listed
81 above will display help. but 'h' is easy to remember :-)
86 82
87't' - Will dump a list of current tasks and their information to your 83'i' - Send a SIGKILL to all processes, except for init.
88 console. 84
85'k' - Secure Access Key (SAK) Kills all programs on the current virtual
86 console. NOTE: See important comments below in SAK section.
89 87
90'm' - Will dump current memory info to your console. 88'm' - Will dump current memory info to your console.
91 89
92'n' - Used to make RT tasks nice-able 90'n' - Used to make RT tasks nice-able
93 91
92'o' - Will shut your system off (if configured and supported).
93
94'p' - Will dump the current registers and flags to your console.
95
96'q' - Will dump a list of all running timers.
97
98'r' - Turns off keyboard raw mode and sets it to XLATE.
99
100's' - Will attempt to sync all mounted filesystems.
101
102't' - Will dump a list of current tasks and their information to your
103 console.
104
105'u' - Will attempt to remount all mounted filesystems read-only.
106
94'v' - Dumps Voyager SMP processor info to your console. 107'v' - Dumps Voyager SMP processor info to your console.
95 108
96'w' - Dumps tasks that are in uninterruptable (blocked) state. 109'w' - Dumps tasks that are in uninterruptable (blocked) state.
@@ -102,17 +115,6 @@ On all - write a character to /proc/sysrq-trigger. e.g.:
102 it so that only emergency messages like PANICs or OOPSes would 115 it so that only emergency messages like PANICs or OOPSes would
103 make it to your console.) 116 make it to your console.)
104 117
105'f' - Will call oom_kill to kill a memory hog process.
106
107'e' - Send a SIGTERM to all processes, except for init.
108
109'g' - Used by kgdb on ppc platforms.
110
111'i' - Send a SIGKILL to all processes, except for init.
112
113'h' - Will display help (actually any other key than those listed
114 above will display help. but 'h' is easy to remember :-)
115
116* Okay, so what can I use them for? 118* Okay, so what can I use them for?
117~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 119~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
118Well, un'R'aw is very handy when your X server or a svgalib program crashes. 120Well, un'R'aw is very handy when your X server or a svgalib program crashes.
diff --git a/Documentation/ibm-acpi.txt b/Documentation/thinkpad-acpi.txt
index 0132d363feb5..2d4803359a04 100644
--- a/Documentation/ibm-acpi.txt
+++ b/Documentation/thinkpad-acpi.txt
@@ -1,16 +1,22 @@
1 IBM ThinkPad ACPI Extras Driver 1 ThinkPad ACPI Extras Driver
2 2
3 Version 0.12 3 Version 0.14
4 17 August 2005 4 April 21st, 2007
5 5
6 Borislav Deianov <borislav@users.sf.net> 6 Borislav Deianov <borislav@users.sf.net>
7 Henrique de Moraes Holschuh <hmh@hmh.eng.br>
7 http://ibm-acpi.sf.net/ 8 http://ibm-acpi.sf.net/
8 9
9 10
10This is a Linux ACPI driver for the IBM ThinkPad laptops. It supports 11This is a Linux driver for the IBM and Lenovo ThinkPad laptops. It
11various features of these laptops which are accessible through the 12supports various features of these laptops which are accessible
12ACPI framework but not otherwise supported by the generic Linux ACPI 13through the ACPI and ACPI EC framework, but not otherwise fully
13drivers. 14supported by the generic Linux ACPI drivers.
15
16This driver used to be named ibm-acpi until kernel 2.6.21 and release
170.13-20070314. It used to be in the drivers/acpi tree, but it was
18moved to the drivers/misc tree and renamed to thinkpad-acpi for kernel
192.6.22, and release 0.14.
14 20
15 21
16Status 22Status
@@ -21,7 +27,7 @@ detailed description):
21 27
22 - Fn key combinations 28 - Fn key combinations
23 - Bluetooth enable and disable 29 - Bluetooth enable and disable
24 - video output switching, expansion control 30 - video output switching, expansion control
25 - ThinkLight on and off 31 - ThinkLight on and off
26 - limited docking and undocking 32 - limited docking and undocking
27 - UltraBay eject 33 - UltraBay eject
@@ -32,7 +38,7 @@ detailed description):
32 - Experimental: embedded controller register dump 38 - Experimental: embedded controller register dump
33 - LCD brightness control 39 - LCD brightness control
34 - Volume control 40 - Volume control
35 - Experimental: fan speed, fan enable/disable 41 - Fan control and monitoring: fan speed, fan enable/disable
36 - Experimental: WAN enable and disable 42 - Experimental: WAN enable and disable
37 43
38A compatibility table by model and feature is maintained on the web 44A compatibility table by model and feature is maintained on the web
@@ -42,6 +48,8 @@ Please include the following information in your report:
42 48
43 - ThinkPad model name 49 - ThinkPad model name
44 - a copy of your DSDT, from /proc/acpi/dsdt 50 - a copy of your DSDT, from /proc/acpi/dsdt
51 - a copy of the output of dmidecode, with serial numbers
52 and UUIDs masked off
45 - which driver features work and which don't 53 - which driver features work and which don't
46 - the observed behavior of non-working features 54 - the observed behavior of non-working features
47 55
@@ -52,25 +60,85 @@ Installation
52------------ 60------------
53 61
54If you are compiling this driver as included in the Linux kernel 62If you are compiling this driver as included in the Linux kernel
55sources, simply enable the CONFIG_ACPI_IBM option (Power Management / 63sources, simply enable the CONFIG_THINKPAD_ACPI option, and optionally
56ACPI / IBM ThinkPad Laptop Extras). 64enable the CONFIG_THINKPAD_ACPI_BAY option if you want the
65thinkpad-specific bay functionality.
57 66
58Features 67Features
59-------- 68--------
60 69
61The driver creates the /proc/acpi/ibm directory. There is a file under 70The driver exports two different interfaces to userspace, which can be
62that directory for each feature described below. Note that while the 71used to access the features it provides. One is a legacy procfs-based
63driver is still in the alpha stage, the exact proc file format and 72interface, which will be removed at some time in the distant future.
64commands supported by the various features is guaranteed to change 73The other is a new sysfs-based interface which is not complete yet.
65frequently.
66 74
67Driver version -- /proc/acpi/ibm/driver 75The procfs interface creates the /proc/acpi/ibm directory. There is a
68--------------------------------------- 76file under that directory for each feature it supports. The procfs
77interface is mostly frozen, and will change very little if at all: it
78will not be extended to add any new functionality in the driver, instead
79all new functionality will be implemented on the sysfs interface.
80
81The sysfs interface tries to blend in the generic Linux sysfs subsystems
82and classes as much as possible. Since some of these subsystems are not
83yet ready or stabilized, it is expected that this interface will change,
84and any and all userspace programs must deal with it.
85
86
87Notes about the sysfs interface:
88
89Unlike what was done with the procfs interface, correctness when talking
90to the sysfs interfaces will be enforced, as will correctness in the
91thinkpad-acpi's implementation of sysfs interfaces.
92
93Also, any bugs in the thinkpad-acpi sysfs driver code or in the
94thinkpad-acpi's implementation of the sysfs interfaces will be fixed for
95maximum correctness, even if that means changing an interface in
96non-compatible ways. As these interfaces mature both in the kernel and
97in thinkpad-acpi, such changes should become quite rare.
98
99Applications interfacing to the thinkpad-acpi sysfs interfaces must
100follow all sysfs guidelines and correctly process all errors (the sysfs
101interface makes extensive use of errors). File descriptors and open /
102close operations to the sysfs inodes must also be properly implemented.
103
104The version of thinkpad-acpi's sysfs interface is exported by the driver
105as a driver attribute (see below).
106
107Sysfs driver attributes are on the driver's sysfs attribute space,
108for 2.6.20 this is /sys/bus/platform/drivers/thinkpad-acpi/.
109
110Sysfs device attributes are on the driver's sysfs attribute space,
111for 2.6.20 this is /sys/devices/platform/thinkpad-acpi/.
112
113Driver version
114--------------
115
116procfs: /proc/acpi/ibm/driver
117sysfs driver attribute: version
69 118
70The driver name and version. No commands can be written to this file. 119The driver name and version. No commands can be written to this file.
71 120
72Hot keys -- /proc/acpi/ibm/hotkey 121Sysfs interface version
73--------------------------------- 122-----------------------
123
124sysfs driver attribute: interface_version
125
126Version of the thinkpad-acpi sysfs interface, as an unsigned long
127(output in hex format: 0xAAAABBCC), where:
128 AAAA - major revision
129 BB - minor revision
130 CC - bugfix revision
131
132The sysfs interface version changelog for the driver can be found at the
133end of this document. Changes to the sysfs interface done by the kernel
134subsystems are not documented here, nor are they tracked by this
135attribute.
136
137Hot keys
138--------
139
140procfs: /proc/acpi/ibm/hotkey
141sysfs device attribute: hotkey/*
74 142
75Without this driver, only the Fn-F4 key (sleep button) generates an 143Without this driver, only the Fn-F4 key (sleep button) generates an
76ACPI event. With the driver loaded, the hotkey feature enabled and the 144ACPI event. With the driver loaded, the hotkey feature enabled and the
@@ -84,15 +152,6 @@ All labeled Fn-Fx key combinations generate distinct events. In
84addition, the lid microswitch and some docking station buttons may 152addition, the lid microswitch and some docking station buttons may
85also generate such events. 153also generate such events.
86 154
87The following commands can be written to this file:
88
89 echo enable > /proc/acpi/ibm/hotkey -- enable the hot keys feature
90 echo disable > /proc/acpi/ibm/hotkey -- disable the hot keys feature
91 echo 0xffff > /proc/acpi/ibm/hotkey -- enable all possible hot keys
92 echo 0x0000 > /proc/acpi/ibm/hotkey -- disable all possible hot keys
93 ... any other 4-hex-digit mask ...
94 echo reset > /proc/acpi/ibm/hotkey -- restore the original mask
95
96The bit mask allows some control over which hot keys generate ACPI 155The bit mask allows some control over which hot keys generate ACPI
97events. Not all bits in the mask can be modified. Not all bits that 156events. Not all bits in the mask can be modified. Not all bits that
98can be modified do anything. Not all hot keys can be individually 157can be modified do anything. Not all hot keys can be individually
@@ -124,15 +183,77 @@ buttons do not generate ACPI events even with this driver. They *can*
124be used through the "ThinkPad Buttons" utility, see 183be used through the "ThinkPad Buttons" utility, see
125http://www.nongnu.org/tpb/ 184http://www.nongnu.org/tpb/
126 185
127Bluetooth -- /proc/acpi/ibm/bluetooth 186procfs notes:
128------------------------------------- 187
188The following commands can be written to the /proc/acpi/ibm/hotkey file:
189
190 echo enable > /proc/acpi/ibm/hotkey -- enable the hot keys feature
191 echo disable > /proc/acpi/ibm/hotkey -- disable the hot keys feature
192 echo 0xffff > /proc/acpi/ibm/hotkey -- enable all possible hot keys
193 echo 0x0000 > /proc/acpi/ibm/hotkey -- disable all possible hot keys
194 ... any other 4-hex-digit mask ...
195 echo reset > /proc/acpi/ibm/hotkey -- restore the original mask
196
197sysfs notes:
198
199 The hot keys attributes are in a hotkey/ subdirectory off the
200 thinkpad device.
201
202 bios_enabled:
203 Returns the status of the hot keys feature when
204 thinkpad-acpi was loaded. Upon module unload, the hot
205 key feature status will be restored to this value.
206
207 0: hot keys were disabled
208 1: hot keys were enabled
209
210 bios_mask:
211 Returns the hot keys mask when thinkpad-acpi was loaded.
212 Upon module unload, the hot keys mask will be restored
213 to this value.
214
215 enable:
216 Enables/disables the hot keys feature, and reports
217 current status of the hot keys feature.
218
219 0: disables the hot keys feature / feature disabled
220 1: enables the hot keys feature / feature enabled
221
222 mask:
223 bit mask to enable ACPI event generation for each hot
224 key (see above). Returns the current status of the hot
225 keys mask, and allows one to modify it.
226
129 227
130This feature shows the presence and current state of a Bluetooth 228Bluetooth
131device. If Bluetooth is installed, the following commands can be used: 229---------
230
231procfs: /proc/acpi/ibm/bluetooth
232sysfs device attribute: bluetooth/enable
233
234This feature shows the presence and current state of a ThinkPad
235Bluetooth device in the internal ThinkPad CDC slot.
236
237Procfs notes:
238
239If Bluetooth is installed, the following commands can be used:
132 240
133 echo enable > /proc/acpi/ibm/bluetooth 241 echo enable > /proc/acpi/ibm/bluetooth
134 echo disable > /proc/acpi/ibm/bluetooth 242 echo disable > /proc/acpi/ibm/bluetooth
135 243
244Sysfs notes:
245
246 If the Bluetooth CDC card is installed, it can be enabled /
247 disabled through the "bluetooth/enable" thinkpad-acpi device
248 attribute, and its current status can also be queried.
249
250 enable:
251 0: disables Bluetooth / Bluetooth is disabled
252 1: enables Bluetooth / Bluetooth is enabled.
253
254 Note: this interface will be probably be superseeded by the
255 generic rfkill class.
256
136Video output control -- /proc/acpi/ibm/video 257Video output control -- /proc/acpi/ibm/video
137-------------------------------------------- 258--------------------------------------------
138 259
@@ -209,7 +330,7 @@ hot plugging of devices in the Linux ACPI framework. If the laptop was
209booted while not in the dock, the following message is shown in the 330booted while not in the dock, the following message is shown in the
210logs: 331logs:
211 332
212 Mar 17 01:42:34 aero kernel: ibm_acpi: dock device not present 333 Mar 17 01:42:34 aero kernel: thinkpad_acpi: dock device not present
213 334
214In this case, no dock-related events are generated but the dock and 335In this case, no dock-related events are generated but the dock and
215undock commands described below still work. They can be executed 336undock commands described below still work. They can be executed
@@ -269,7 +390,7 @@ This is due to the current lack of support for hot plugging of devices
269in the Linux ACPI framework. If the laptop was booted without the 390in the Linux ACPI framework. If the laptop was booted without the
270UltraBay, the following message is shown in the logs: 391UltraBay, the following message is shown in the logs:
271 392
272 Mar 17 01:42:34 aero kernel: ibm_acpi: bay device not present 393 Mar 17 01:42:34 aero kernel: thinkpad_acpi: bay device not present
273 394
274In this case, no bay-related events are generated but the eject 395In this case, no bay-related events are generated but the eject
275command described below still works. It can be executed manually or 396command described below still works. It can be executed manually or
@@ -313,23 +434,19 @@ supported. Use "eject2" instead of "eject" for the second bay.
313Note: the UltraBay eject support on the 600e/x, A22p and A3x is 434Note: the UltraBay eject support on the 600e/x, A22p and A3x is
314EXPERIMENTAL and may not work as expected. USE WITH CAUTION! 435EXPERIMENTAL and may not work as expected. USE WITH CAUTION!
315 436
316CMOS control -- /proc/acpi/ibm/cmos 437CMOS control
317----------------------------------- 438------------
439
440procfs: /proc/acpi/ibm/cmos
441sysfs device attribute: cmos_command
318 442
319This feature is used internally by the ACPI firmware to control the 443This feature is used internally by the ACPI firmware to control the
320ThinkLight on most newer ThinkPad models. It may also control LCD 444ThinkLight on most newer ThinkPad models. It may also control LCD
321brightness, sounds volume and more, but only on some models. 445brightness, sounds volume and more, but only on some models.
322 446
323The commands are non-negative integer numbers: 447The range of valid cmos command numbers is 0 to 21, but not all have an
324 448effect and the behavior varies from model to model. Here is the behavior
325 echo 0 >/proc/acpi/ibm/cmos 449on the X40 (tpb is the ThinkPad Buttons utility):
326 echo 1 >/proc/acpi/ibm/cmos
327 echo 2 >/proc/acpi/ibm/cmos
328 ...
329
330The range of valid numbers is 0 to 21, but not all have an effect and
331the behavior varies from model to model. Here is the behavior on the
332X40 (tpb is the ThinkPad Buttons utility):
333 450
334 0 - no effect but tpb reports "Volume down" 451 0 - no effect but tpb reports "Volume down"
335 1 - no effect but tpb reports "Volume up" 452 1 - no effect but tpb reports "Volume up"
@@ -342,6 +459,9 @@ X40 (tpb is the ThinkPad Buttons utility):
342 13 - ThinkLight off 459 13 - ThinkLight off
343 14 - no effect but tpb reports ThinkLight status change 460 14 - no effect but tpb reports ThinkLight status change
344 461
462The cmos command interface is prone to firmware split-brain problems, as
463in newer ThinkPads it is just a compatibility layer.
464
345LED control -- /proc/acpi/ibm/led 465LED control -- /proc/acpi/ibm/led
346--------------------------------- 466---------------------------------
347 467
@@ -393,17 +513,17 @@ X40:
393 16 - one medium-pitched beep repeating constantly, stop with 17 513 16 - one medium-pitched beep repeating constantly, stop with 17
394 17 - stop 16 514 17 - stop 16
395 515
396Temperature sensors -- /proc/acpi/ibm/thermal 516Temperature sensors
397--------------------------------------------- 517-------------------
518
519procfs: /proc/acpi/ibm/thermal
520sysfs device attributes: (hwmon) temp*_input
398 521
399Most ThinkPads include six or more separate temperature sensors but 522Most ThinkPads include six or more separate temperature sensors but
400only expose the CPU temperature through the standard ACPI methods. 523only expose the CPU temperature through the standard ACPI methods.
401This feature shows readings from up to eight different sensors on older 524This feature shows readings from up to eight different sensors on older
402ThinkPads, and it has experimental support for up to sixteen different 525ThinkPads, and it has experimental support for up to sixteen different
403sensors on newer ThinkPads. Readings from sensors that are not available 526sensors on newer ThinkPads.
404return -128.
405
406No commands can be written to this file.
407 527
408EXPERIMENTAL: The 16-sensors feature is marked EXPERIMENTAL because the 528EXPERIMENTAL: The 16-sensors feature is marked EXPERIMENTAL because the
409implementation directly accesses hardware registers and may not work as 529implementation directly accesses hardware registers and may not work as
@@ -460,6 +580,20 @@ The A31 has a very atypical layout for the thermal sensors
4608: Bay Battery: secondary sensor 5808: Bay Battery: secondary sensor
461 581
462 582
583Procfs notes:
584 Readings from sensors that are not available return -128.
585 No commands can be written to this file.
586
587Sysfs notes:
588 Sensors that are not available return the ENXIO error. This
589 status may change at runtime, as there are hotplug thermal
590 sensors, like those inside the batteries and docks.
591
592 thinkpad-acpi thermal sensors are reported through the hwmon
593 subsystem, and follow all of the hwmon guidelines at
594 Documentation/hwmon.
595
596
463EXPERIMENTAL: Embedded controller register dump -- /proc/acpi/ibm/ecdump 597EXPERIMENTAL: Embedded controller register dump -- /proc/acpi/ibm/ecdump
464------------------------------------------------------------------------ 598------------------------------------------------------------------------
465 599
@@ -472,7 +606,7 @@ This feature dumps the values of 256 embedded controller
472registers. Values which have changed since the last time the registers 606registers. Values which have changed since the last time the registers
473were dumped are marked with a star: 607were dumped are marked with a star:
474 608
475[root@x40 ibm-acpi]# cat /proc/acpi/ibm/ecdump 609[root@x40 ibm-acpi]# cat /proc/acpi/ibm/ecdump
476EC +00 +01 +02 +03 +04 +05 +06 +07 +08 +09 +0a +0b +0c +0d +0e +0f 610EC +00 +01 +02 +03 +04 +05 +06 +07 +08 +09 +0a +0b +0c +0d +0e +0f
477EC 0x00: a7 47 87 01 fe 96 00 08 01 00 cb 00 00 00 40 00 611EC 0x00: a7 47 87 01 fe 96 00 08 01 00 cb 00 00 00 40 00
478EC 0x10: 00 00 ff ff f4 3c 87 09 01 ff 42 01 ff ff 0d 00 612EC 0x10: 00 00 ff ff f4 3c 87 09 01 ff 42 01 ff ff 0d 00
@@ -503,7 +637,7 @@ vary. The second ensures that the fan-related values do vary, since
503the fan speed fluctuates a bit. The third will (hopefully) mark the 637the fan speed fluctuates a bit. The third will (hopefully) mark the
504fan register with a star: 638fan register with a star:
505 639
506[root@x40 ibm-acpi]# cat /proc/acpi/ibm/ecdump 640[root@x40 ibm-acpi]# cat /proc/acpi/ibm/ecdump
507EC +00 +01 +02 +03 +04 +05 +06 +07 +08 +09 +0a +0b +0c +0d +0e +0f 641EC +00 +01 +02 +03 +04 +05 +06 +07 +08 +09 +0a +0b +0c +0d +0e +0f
508EC 0x00: a7 47 87 01 fe 96 00 08 01 00 cb 00 00 00 40 00 642EC 0x00: a7 47 87 01 fe 96 00 08 01 00 cb 00 00 00 40 00
509EC 0x10: 00 00 ff ff f4 3c 87 09 01 ff 42 01 ff ff 0d 00 643EC 0x10: 00 00 ff ff f4 3c 87 09 01 ff 42 01 ff ff 0d 00
@@ -533,19 +667,59 @@ registers contain the current battery capacity, etc. If you experiment
533with this, do send me your results (including some complete dumps with 667with this, do send me your results (including some complete dumps with
534a description of the conditions when they were taken.) 668a description of the conditions when they were taken.)
535 669
536LCD brightness control -- /proc/acpi/ibm/brightness 670LCD brightness control
537--------------------------------------------------- 671----------------------
672
673procfs: /proc/acpi/ibm/brightness
674sysfs backlight device "thinkpad_screen"
538 675
539This feature allows software control of the LCD brightness on ThinkPad 676This feature allows software control of the LCD brightness on ThinkPad
540models which don't have a hardware brightness slider. The available 677models which don't have a hardware brightness slider.
541commands are: 678
679It has some limitations: the LCD backlight cannot be actually turned on or off
680by this interface, and in many ThinkPad models, the "dim while on battery"
681functionality will be enabled by the BIOS when this interface is used, and
682cannot be controlled.
683
684The backlight control has eight levels, ranging from 0 to 7. Some of the
685levels may not be distinct.
686
687Procfs notes:
688
689 The available commands are:
542 690
543 echo up >/proc/acpi/ibm/brightness 691 echo up >/proc/acpi/ibm/brightness
544 echo down >/proc/acpi/ibm/brightness 692 echo down >/proc/acpi/ibm/brightness
545 echo 'level <level>' >/proc/acpi/ibm/brightness 693 echo 'level <level>' >/proc/acpi/ibm/brightness
546 694
547The <level> number range is 0 to 7, although not all of them may be 695Sysfs notes:
548distinct. The current brightness level is shown in the file. 696
697The interface is implemented through the backlight sysfs class, which is poorly
698documented at this time.
699
700Locate the thinkpad_screen device under /sys/class/backlight, and inside it
701there will be the following attributes:
702
703 max_brightness:
704 Reads the maximum brightness the hardware can be set to.
705 The minimum is always zero.
706
707 actual_brightness:
708 Reads what brightness the screen is set to at this instant.
709
710 brightness:
711 Writes request the driver to change brightness to the given
712 value. Reads will tell you what brightness the driver is trying
713 to set the display to when "power" is set to zero and the display
714 has not been dimmed by a kernel power management event.
715
716 power:
717 power management mode, where 0 is "display on", and 1 to 3 will
718 dim the display backlight to brightness level 0 because
719 thinkpad-acpi cannot really turn the backlight off. Kernel
720 power management events can temporarily increase the current
721 power management level, i.e. they can dim the display.
722
549 723
550Volume control -- /proc/acpi/ibm/volume 724Volume control -- /proc/acpi/ibm/volume
551--------------------------------------- 725---------------------------------------
@@ -563,41 +737,42 @@ distinct. The unmute the volume after the mute command, use either the
563up or down command (the level command will not unmute the volume). 737up or down command (the level command will not unmute the volume).
564The current volume level and mute state is shown in the file. 738The current volume level and mute state is shown in the file.
565 739
566EXPERIMENTAL: fan speed, fan enable/disable -- /proc/acpi/ibm/fan 740Fan control and monitoring: fan speed, fan enable/disable
567----------------------------------------------------------------- 741---------------------------------------------------------
568 742
569This feature is marked EXPERIMENTAL because the implementation 743procfs: /proc/acpi/ibm/fan
570directly accesses hardware registers and may not work as expected. USE 744sysfs device attributes: (hwmon) fan_input, pwm1, pwm1_enable
571WITH CAUTION! To use this feature, you need to supply the 745
572experimental=1 parameter when loading the module. 746NOTE NOTE NOTE: fan control operations are disabled by default for
747safety reasons. To enable them, the module parameter "fan_control=1"
748must be given to thinkpad-acpi.
573 749
574This feature attempts to show the current fan speed, control mode and 750This feature attempts to show the current fan speed, control mode and
575other fan data that might be available. The speed is read directly 751other fan data that might be available. The speed is read directly
576from the hardware registers of the embedded controller. This is known 752from the hardware registers of the embedded controller. This is known
577to work on later R, T and X series ThinkPads but may show a bogus 753to work on later R, T, X and Z series ThinkPads but may show a bogus
578value on other models. 754value on other models.
579 755
580Most ThinkPad fans work in "levels". Level 0 stops the fan. The higher 756Fan levels:
581the level, the higher the fan speed, although adjacent levels often map
582to the same fan speed. 7 is the highest level, where the fan reaches
583the maximum recommended speed. Level "auto" means the EC changes the
584fan level according to some internal algorithm, usually based on
585readings from the thermal sensors. Level "disengaged" means the EC
586disables the speed-locked closed-loop fan control, and drives the fan as
587fast as it can go, which might exceed hardware limits, so use this level
588with caution.
589 757
590The fan usually ramps up or down slowly from one speed to another, 758Most ThinkPad fans work in "levels" at the firmware interface. Level 0
591and it is normal for the EC to take several seconds to react to fan 759stops the fan. The higher the level, the higher the fan speed, although
592commands. 760adjacent levels often map to the same fan speed. 7 is the highest
761level, where the fan reaches the maximum recommended speed.
593 762
594The fan may be enabled or disabled with the following commands: 763Level "auto" means the EC changes the fan level according to some
764internal algorithm, usually based on readings from the thermal sensors.
595 765
596 echo enable >/proc/acpi/ibm/fan 766There is also a "full-speed" level, also known as "disengaged" level.
597 echo disable >/proc/acpi/ibm/fan 767In this level, the EC disables the speed-locked closed-loop fan control,
768and drives the fan as fast as it can go, which might exceed hardware
769limits, so use this level with caution.
598 770
599Placing a fan on level 0 is the same as disabling it. Enabling a fan 771The fan usually ramps up or down slowly from one speed to another, and
600will try to place it in a safe level if it is too slow or disabled. 772it is normal for the EC to take several seconds to react to fan
773commands. The full-speed level may take up to two minutes to ramp up to
774maximum speed, and in some ThinkPads, the tachometer readings go stale
775while the EC is transitioning to the full-speed level.
601 776
602WARNING WARNING WARNING: do not leave the fan disabled unless you are 777WARNING WARNING WARNING: do not leave the fan disabled unless you are
603monitoring all of the temperature sensor readings and you are ready to 778monitoring all of the temperature sensor readings and you are ready to
@@ -615,46 +790,146 @@ fan is turned off when the CPU temperature drops to 49 degrees and the
615HDD temperature drops to 41 degrees. These thresholds cannot 790HDD temperature drops to 41 degrees. These thresholds cannot
616currently be controlled. 791currently be controlled.
617 792
793The ThinkPad's ACPI DSDT code will reprogram the fan on its own when
794certain conditions are met. It will override any fan programming done
795through thinkpad-acpi.
796
797The thinkpad-acpi kernel driver can be programmed to revert the fan
798level to a safe setting if userspace does not issue one of the procfs
799fan commands: "enable", "disable", "level" or "watchdog", or if there
800are no writes to pwm1_enable (or to pwm1 *if and only if* pwm1_enable is
801set to 1, manual mode) within a configurable amount of time of up to
802120 seconds. This functionality is called fan safety watchdog.
803
804Note that the watchdog timer stops after it enables the fan. It will be
805rearmed again automatically (using the same interval) when one of the
806above mentioned fan commands is received. The fan watchdog is,
807therefore, not suitable to protect against fan mode changes made through
808means other than the "enable", "disable", and "level" procfs fan
809commands, or the hwmon fan control sysfs interface.
810
811Procfs notes:
812
813The fan may be enabled or disabled with the following commands:
814
815 echo enable >/proc/acpi/ibm/fan
816 echo disable >/proc/acpi/ibm/fan
817
818Placing a fan on level 0 is the same as disabling it. Enabling a fan
819will try to place it in a safe level if it is too slow or disabled.
820
618The fan level can be controlled with the command: 821The fan level can be controlled with the command:
619 822
620 echo 'level <level>' > /proc/acpi/ibm/thermal 823 echo 'level <level>' > /proc/acpi/ibm/fan
621 824
622Where <level> is an integer from 0 to 7, or one of the words "auto" 825Where <level> is an integer from 0 to 7, or one of the words "auto" or
623or "disengaged" (without the quotes). Not all ThinkPads support the 826"full-speed" (without the quotes). Not all ThinkPads support the "auto"
624"auto" and "disengaged" levels. 827and "full-speed" levels. The driver accepts "disengaged" as an alias for
828"full-speed", and reports it as "disengaged" for backwards
829compatibility.
625 830
626On the X31 and X40 (and ONLY on those models), the fan speed can be 831On the X31 and X40 (and ONLY on those models), the fan speed can be
627controlled to a certain degree. Once the fan is running, it can be 832controlled to a certain degree. Once the fan is running, it can be
628forced to run faster or slower with the following command: 833forced to run faster or slower with the following command:
629 834
630 echo 'speed <speed>' > /proc/acpi/ibm/thermal 835 echo 'speed <speed>' > /proc/acpi/ibm/fan
631 836
632The sustainable range of fan speeds on the X40 appears to be from 837The sustainable range of fan speeds on the X40 appears to be from about
633about 3700 to about 7350. Values outside this range either do not have 8383700 to about 7350. Values outside this range either do not have any
634any effect or the fan speed eventually settles somewhere in that 839effect or the fan speed eventually settles somewhere in that range. The
635range. The fan cannot be stopped or started with this command. 840fan cannot be stopped or started with this command. This functionality
841is incomplete, and not available through the sysfs interface.
636 842
637The ThinkPad's ACPI DSDT code will reprogram the fan on its own when 843To program the safety watchdog, use the "watchdog" command.
638certain conditions are met. It will override any fan programming done
639through ibm-acpi.
640 844
641EXPERIMENTAL: WAN -- /proc/acpi/ibm/wan 845 echo 'watchdog <interval in seconds>' > /proc/acpi/ibm/fan
642--------------------------------------- 846
847If you want to disable the watchdog, use 0 as the interval.
848
849Sysfs notes:
850
851The sysfs interface follows the hwmon subsystem guidelines for the most
852part, and the exception is the fan safety watchdog.
853
854Writes to any of the sysfs attributes may return the EINVAL error if
855that operation is not supported in a given ThinkPad or if the parameter
856is out-of-bounds, and EPERM if it is forbidden. They may also return
857EINTR (interrupted system call), and EIO (I/O error while trying to talk
858to the firmware).
859
860Features not yet implemented by the driver return ENOSYS.
861
862hwmon device attribute pwm1_enable:
863 0: PWM offline (fan is set to full-speed mode)
864 1: Manual PWM control (use pwm1 to set fan level)
865 2: Hardware PWM control (EC "auto" mode)
866 3: reserved (Software PWM control, not implemented yet)
867
868 Modes 0 and 2 are not supported by all ThinkPads, and the
869 driver is not always able to detect this. If it does know a
870 mode is unsupported, it will return -EINVAL.
871
872hwmon device attribute pwm1:
873 Fan level, scaled from the firmware values of 0-7 to the hwmon
874 scale of 0-255. 0 means fan stopped, 255 means highest normal
875 speed (level 7).
876
877 This attribute only commands the fan if pmw1_enable is set to 1
878 (manual PWM control).
879
880hwmon device attribute fan1_input:
881 Fan tachometer reading, in RPM. May go stale on certain
882 ThinkPads while the EC transitions the PWM to offline mode,
883 which can take up to two minutes. May return rubbish on older
884 ThinkPads.
885
886driver attribute fan_watchdog:
887 Fan safety watchdog timer interval, in seconds. Minimum is
888 1 second, maximum is 120 seconds. 0 disables the watchdog.
889
890To stop the fan: set pwm1 to zero, and pwm1_enable to 1.
891
892To start the fan in a safe mode: set pwm1_enable to 2. If that fails
893with EINVAL, try to set pwm1_enable to 1 and pwm1 to at least 128 (255
894would be the safest choice, though).
895
896
897EXPERIMENTAL: WAN
898-----------------
899
900procfs: /proc/acpi/ibm/wan
901sysfs device attribute: wwan/enable
643 902
644This feature is marked EXPERIMENTAL because the implementation 903This feature is marked EXPERIMENTAL because the implementation
645directly accesses hardware registers and may not work as expected. USE 904directly accesses hardware registers and may not work as expected. USE
646WITH CAUTION! To use this feature, you need to supply the 905WITH CAUTION! To use this feature, you need to supply the
647experimental=1 parameter when loading the module. 906experimental=1 parameter when loading the module.
648 907
649This feature shows the presence and current state of a WAN (Sierra 908This feature shows the presence and current state of a W-WAN (Sierra
650Wireless EV-DO) device. If WAN is installed, the following commands can 909Wireless EV-DO) device.
651be used: 910
911It was tested on a Lenovo Thinkpad X60. It should probably work on other
912Thinkpad models which come with this module installed.
913
914Procfs notes:
915
916If the W-WAN card is installed, the following commands can be used:
652 917
653 echo enable > /proc/acpi/ibm/wan 918 echo enable > /proc/acpi/ibm/wan
654 echo disable > /proc/acpi/ibm/wan 919 echo disable > /proc/acpi/ibm/wan
655 920
656It was tested on a Lenovo Thinkpad X60. It should probably work on other 921Sysfs notes:
657Thinkpad models which come with this module installed. 922
923 If the W-WAN card is installed, it can be enabled /
924 disabled through the "wwan/enable" thinkpad-acpi device
925 attribute, and its current status can also be queried.
926
927 enable:
928 0: disables WWAN card / WWAN card is disabled
929 1: enables WWAN card / WWAN card is enabled.
930
931 Note: this interface will be probably be superseeded by the
932 generic rfkill class.
658 933
659Multiple Commands, Module Parameters 934Multiple Commands, Module Parameters
660------------------------------------ 935------------------------------------
@@ -665,64 +940,42 @@ separating them with commas, for example:
665 echo enable,0xffff > /proc/acpi/ibm/hotkey 940 echo enable,0xffff > /proc/acpi/ibm/hotkey
666 echo lcd_disable,crt_enable > /proc/acpi/ibm/video 941 echo lcd_disable,crt_enable > /proc/acpi/ibm/video
667 942
668Commands can also be specified when loading the ibm_acpi module, for 943Commands can also be specified when loading the thinkpad-acpi module,
669example: 944for example:
670 945
671 modprobe ibm_acpi hotkey=enable,0xffff video=auto_disable 946 modprobe thinkpad_acpi hotkey=enable,0xffff video=auto_disable
672 947
673The ibm-acpi kernel driver can be programmed to revert the fan level 948Enabling debugging output
674to a safe setting if userspace does not issue one of the fan commands: 949-------------------------
675"enable", "disable", "level" or "watchdog" within a configurable 950
676ammount of time. To do this, use the "watchdog" command. 951The module takes a debug paramater which can be used to selectively
677 952enable various classes of debugging output, for example:
678 echo 'watchdog <interval>' > /proc/acpi/ibm/fan 953
679 954 modprobe ibm_acpi debug=0xffff
680Interval is the ammount of time in seconds to wait for one of the 955
681above mentioned fan commands before reseting the fan level to a safe 956will enable all debugging output classes. It takes a bitmask, so
682one. If set to zero, the watchdog is disabled (default). When the 957to enable more than one output class, just add their values.
683watchdog timer runs out, it does the exact equivalent of the "enable" 958
684fan command. 959 Debug bitmask Description
685 960 0x0001 Initialization and probing
686Note that the watchdog timer stops after it enables the fan. It will 961 0x0002 Removal
687be rearmed again automatically (using the same interval) when one of 962
688the above mentioned fan commands is received. The fan watchdog is, 963There is also a kernel build option to enable more debugging
689therefore, not suitable to protect against fan mode changes made 964information, which may be necessary to debug driver problems.
690through means other than the "enable", "disable", and "level" fan 965
691commands. 966The level of debugging information output by the driver can be changed
692 967at runtime through sysfs, using the driver attribute debug_level. The
693 968attribute takes the same bitmask as the debug module parameter above.
694Example Configuration 969
695--------------------- 970Force loading of module
696 971-----------------------
697The ACPI support in the kernel is intended to be used in conjunction 972
698with a user-space daemon, acpid. The configuration files for this 973If thinkpad-acpi refuses to detect your ThinkPad, you can try to specify
699daemon control what actions are taken in response to various ACPI 974the module parameter force_load=1. Regardless of whether this works or
700events. An example set of configuration files are included in the 975not, please contact ibm-acpi-devel@lists.sourceforge.net with a report.
701config/ directory of the tarball package available on the web 976
702site. Note that these are provided for illustration purposes only and 977
703may need to be adapted to your particular setup. 978Sysfs interface changelog:
704 979
705The following utility scripts are used by the example action 9800x000100: Initial sysfs support, as a single platform driver and
706scripts (included with ibm-acpi for completeness): 981 device.
707
708 /usr/local/sbin/idectl -- from the hdparm source distribution,
709 see http://www.ibiblio.org/pub/Linux/system/hardware
710 /usr/local/sbin/laptop_mode -- from the Linux kernel source
711 distribution, see Documentation/laptop-mode.txt
712 /sbin/service -- comes with Redhat/Fedora distributions
713 /usr/sbin/hibernate -- from the Software Suspend 2 distribution,
714 see http://softwaresuspend.berlios.de/
715
716Toan T Nguyen <ntt@physics.ucla.edu> notes that Suse uses the
717powersave program to suspend ('powersave --suspend-to-ram') or
718hibernate ('powersave --suspend-to-disk'). This means that the
719hibernate script is not needed on that distribution.
720
721Henrik Brix Andersen <brix@gentoo.org> has written a Gentoo ACPI event
722handler script for the X31. You can get the latest version from
723http://dev.gentoo.org/~brix/files/x31.sh
724
725David Schweikert <dws@ee.eth.ch> has written an alternative blank.sh
726script which works on Debian systems. This scripts has now been
727extended to also work on Fedora systems and included as the default
728blank.sh in the distribution.
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..53ae866ae37b 100644
--- a/Documentation/usb/usbmon.txt
+++ b/Documentation/usb/usbmon.txt
@@ -16,7 +16,7 @@ situation as with tcpdump.
16 16
17Unlike the packet socket, usbmon has an interface which provides traces 17Unlike the packet socket, usbmon has an interface which provides traces
18in a text format. This is used for two purposes. First, it serves as a 18in a text format. This is used for two purposes. First, it serves as a
19common trace exchange format for tools while most sophisticated formats 19common trace exchange format for tools while more sophisticated formats
20are finalized. Second, humans can read it in case tools are not available. 20are finalized. Second, humans can read it in case tools are not available.
21 21
22To collect a raw text trace, execute following steps. 22To collect a raw text trace, execute following steps.
@@ -34,7 +34,7 @@ if usbmon is built into the kernel.
34Verify that bus sockets are present. 34Verify that bus sockets are present.
35 35
36# ls /sys/kernel/debug/usbmon 36# ls /sys/kernel/debug/usbmon
371s 1t 2s 2t 3s 3t 4s 4t 371s 1t 1u 2s 2t 2u 3s 3t 3u 4s 4t 4u
38# 38#
39 39
402. Find which bus connects to the desired device 402. Find which bus connects to the desired device
@@ -54,7 +54,7 @@ Bus=03 means it's bus 3.
54 54
553. Start 'cat' 553. Start 'cat'
56 56
57# cat /sys/kernel/debug/usbmon/3t > /tmp/1.mon.out 57# cat /sys/kernel/debug/usbmon/3u > /tmp/1.mon.out
58 58
59This process will be reading until killed. Naturally, the output can be 59This process will be reading until killed. Naturally, the output can be
60redirected to a desirable location. This is preferred, because it is going 60redirected to a desirable location. This is preferred, because it is going
@@ -75,46 +75,80 @@ that the file size is not excessive for your favourite editor.
75 75
76* Raw text data format 76* Raw text data format
77 77
78The '1t' type data consists of a stream of events, such as URB submission, 78Two formats are supported currently: the original, or '1t' format, and
79the '1u' format. The '1t' format is deprecated in kernel 2.6.21. The '1u'
80format adds a few fields, such as ISO frame descriptors, interval, etc.
81It produces slightly longer lines, but otherwise is a perfect superset
82of '1t' format.
83
84If it is desired to recognize one from the other in a program, look at the
85"address" word (see below), where '1u' format adds a bus number. If 2 colons
86are present, it's the '1t' format, otherwise '1u'.
87
88Any text format data consists of a stream of events, such as URB submission,
79URB callback, submission error. Every event is a text line, which consists 89URB callback, submission error. Every event is a text line, which consists
80of whitespace separated words. The number of position of words may depend 90of 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. 91on the event type, but there is a set of words, common for all types.
82 92
83Here is the list of words, from left to right: 93Here is the list of words, from left to right:
94
84- URB Tag. This is used to identify URBs is normally a kernel mode address 95- URB Tag. This is used to identify URBs is normally a kernel mode address
85 of the URB structure in hexadecimal. 96 of the URB structure in hexadecimal.
97
86- Timestamp in microseconds, a decimal number. The timestamp's resolution 98- Timestamp in microseconds, a decimal number. The timestamp's resolution
87 depends on available clock, and so it can be much worse than a microsecond 99 depends on available clock, and so it can be much worse than a microsecond
88 (if the implementation uses jiffies, for example). 100 (if the implementation uses jiffies, for example).
101
89- Event Type. This type refers to the format of the event, not URB type. 102- Event Type. This type refers to the format of the event, not URB type.
90 Available types are: S - submission, C - callback, E - submission error. 103 Available types are: S - submission, C - callback, E - submission error.
91- "Pipe". The pipe concept is deprecated. This is a composite word, used to 104
92 be derived from information in pipes. It consists of three fields, separated 105- "Address" word (formerly a "pipe"). It consists of four fields, separated by
93 by colons: URB type and direction, Device address, Endpoint number. 106 colons: URB type and direction, Bus number, Device address, Endpoint number.
94 Type and direction are encoded with two bytes in the following manner: 107 Type and direction are encoded with two bytes in the following manner:
95 Ci Co Control input and output 108 Ci Co Control input and output
96 Zi Zo Isochronous input and output 109 Zi Zo Isochronous input and output
97 Ii Io Interrupt input and output 110 Ii Io Interrupt input and output
98 Bi Bo Bulk input and output 111 Bi Bo Bulk input and output
99 Device address and Endpoint number are 3-digit and 2-digit (respectively) 112 Bus number, Device address, and Endpoint are decimal numbers, but they may
100 decimal numbers, with leading zeroes. 113 have leading zeros, for the sake of human readers.
101- URB Status. In most cases, this field contains a number, sometimes negative, 114
102 which represents a "status" field of the URB. This field makes no sense for 115- URB Status word. This is either a letter, or several numbers separated
103 submissions, but is present anyway to help scripts with parsing. When an 116 by colons: URB status, interval, start frame, and error count. Unlike the
104 error occurs, the field contains the error code. In case of a submission of 117 "address" word, all fields save the status are optional. Interval is printed
105 a Control packet, this field contains a Setup Tag instead of an error code. 118 only for interrupt and isochronous URBs. Start frame is printed only for
106 It is easy to tell whether the Setup Tag is present because it is never a 119 isochronous URBs. Error count is printed only for isochronous callback
107 number. Thus if scripts find a number in this field, they proceed to read 120 events.
108 Data Length. If they find something else, like a letter, they read the setup 121
109 packet before reading the Data Length. 122 The status field is a decimal number, sometimes negative, which represents
123 a "status" field of the URB. This field makes no sense for submissions, but
124 is present anyway to help scripts with parsing. When an error occurs, the
125 field contains the error code.
126
127 In case of a submission of a Control packet, this field contains a Setup Tag
128 instead of an group of numbers. It is easy to tell whether the Setup Tag is
129 present because it is never a number. Thus if scripts find a set of numbers
130 in this word, they proceed to read Data Length (except for isochronous URBs).
131 If they find something else, like a letter, they read the setup packet before
132 reading the Data Length or isochronous descriptors.
133
110- Setup packet, if present, consists of 5 words: one of each for bmRequestType, 134- Setup packet, if present, consists of 5 words: one of each for bmRequestType,
111 bRequest, wValue, wIndex, wLength, as specified by the USB Specification 2.0. 135 bRequest, wValue, wIndex, wLength, as specified by the USB Specification 2.0.
112 These words are safe to decode if Setup Tag was 's'. Otherwise, the setup 136 These words are safe to decode if Setup Tag was 's'. Otherwise, the setup
113 packet was present, but not captured, and the fields contain filler. 137 packet was present, but not captured, and the fields contain filler.
138
139- Number of isochronous frame descriptors and descriptors themselves.
140 If an Isochronous transfer event has a set of descriptors, a total number
141 of them in an URB is printed first, then a word per descriptor, up to a
142 total of 5. The word consists of 3 colon-separated decimal numbers for
143 status, offset, and length respectively. For submissions, initial length
144 is reported. For callbacks, actual length is reported.
145
114- Data Length. For submissions, this is the requested length. For callbacks, 146- Data Length. For submissions, this is the requested length. For callbacks,
115 this is the actual length. 147 this is the actual length.
148
116- Data tag. The usbmon may not always capture data, even if length is nonzero. 149- Data tag. The usbmon may not always capture data, even if length is nonzero.
117 The data words are present only if this tag is '='. 150 The data words are present only if this tag is '='.
151
118- Data words follow, in big endian hexadecimal format. Notice that they are 152- Data words follow, in big endian hexadecimal format. Notice that they are
119 not machine words, but really just a byte stream split into words to make 153 not machine words, but really just a byte stream split into words to make
120 it easier to read. Thus, the last word may contain from one to four bytes. 154 it easier to read. Thus, the last word may contain from one to four bytes.
@@ -153,21 +187,167 @@ class ParsedLine {
153 } 187 }
154} 188}
155 189
156This format may be changed in the future.
157
158Examples: 190Examples:
159 191
160An input control transfer to get a port status. 192An input control transfer to get a port status.
161 193
162d5ea89a0 3575914555 S Ci:001:00 s a3 00 0000 0003 0004 4 < 194d5ea89a0 3575914555 S Ci:1:001:0 s a3 00 0000 0003 0004 4 <
163d5ea89a0 3575914560 C Ci:001:00 0 4 = 01050000 195d5ea89a0 3575914560 C Ci:1:001:0 0 4 = 01050000
164 196
165An output bulk transfer to send a SCSI command 0x5E in a 31-byte Bulk wrapper 197An output bulk transfer to send a SCSI command 0x5E in a 31-byte Bulk wrapper
166to a storage device at address 5: 198to a storage device at address 5:
167 199
168dd65f0e8 4128379752 S Bo:005:02 -115 31 = 55534243 5e000000 00000000 00000600 00000000 00000000 00000000 000000 200dd65f0e8 4128379752 S Bo:1:005:2 -115 31 = 55534243 5e000000 00000000 00000600 00000000 00000000 00000000 000000
169dd65f0e8 4128379808 C Bo:005:02 0 31 > 201dd65f0e8 4128379808 C Bo:1:005:2 0 31 >
170 202
171* Raw binary format and API 203* Raw binary format and API
172 204
173TBD 205The overall architecture of the API is about the same as the one above,
206only the events are delivered in binary format. Each event is sent in
207the following structure (its name is made up, so that we can refer to it):
208
209struct usbmon_packet {
210 u64 id; /* 0: URB ID - from submission to callback */
211 unsigned char type; /* 8: Same as text; extensible. */
212 unsigned char xfer_type; /* ISO (0), Intr, Control, Bulk (3) */
213 unsigned char epnum; /* Endpoint number and transfer direction */
214 unsigned char devnum; /* Device address */
215 u16 busnum; /* 12: Bus number */
216 char flag_setup; /* 14: Same as text */
217 char flag_data; /* 15: Same as text; Binary zero is OK. */
218 s64 ts_sec; /* 16: gettimeofday */
219 s32 ts_usec; /* 24: gettimeofday */
220 int status; /* 28: */
221 unsigned int length; /* 32: Length of data (submitted or actual) */
222 unsigned int len_cap; /* 36: Delivered length */
223 unsigned char setup[8]; /* 40: Only for Control 'S' */
224}; /* 48 bytes total */
225
226These events can be received from a character device by reading with read(2),
227with an ioctl(2), or by accessing the buffer with mmap.
228
229The character device is usually called /dev/usbmonN, where N is the USB bus
230number. Number zero (/dev/usbmon0) is special and means "all buses".
231However, this feature is not implemented yet. Note that specific naming
232policy is set by your Linux distribution.
233
234If you create /dev/usbmon0 by hand, make sure that it is owned by root
235and has mode 0600. Otherwise, unpriviledged users will be able to snoop
236keyboard traffic.
237
238The following ioctl calls are available, with MON_IOC_MAGIC 0x92:
239
240 MON_IOCQ_URB_LEN, defined as _IO(MON_IOC_MAGIC, 1)
241
242This call returns the length of data in the next event. Note that majority of
243events contain no data, so if this call returns zero, it does not mean that
244no events are available.
245
246 MON_IOCG_STATS, defined as _IOR(MON_IOC_MAGIC, 3, struct mon_bin_stats)
247
248The argument is a pointer to the following structure:
249
250struct mon_bin_stats {
251 u32 queued;
252 u32 dropped;
253};
254
255The member "queued" refers to the number of events currently queued in the
256buffer (and not to the number of events processed since the last reset).
257
258The member "dropped" is the number of events lost since the last call
259to MON_IOCG_STATS.
260
261 MON_IOCT_RING_SIZE, defined as _IO(MON_IOC_MAGIC, 4)
262
263This call sets the buffer size. The argument is the size in bytes.
264The size may be rounded down to the next chunk (or page). If the requested
265size is out of [unspecified] bounds for this kernel, the call fails with
266-EINVAL.
267
268 MON_IOCQ_RING_SIZE, defined as _IO(MON_IOC_MAGIC, 5)
269
270This call returns the current size of the buffer in bytes.
271
272 MON_IOCX_GET, defined as _IOW(MON_IOC_MAGIC, 6, struct mon_get_arg)
273
274This call waits for events to arrive if none were in the kernel buffer,
275then returns the first event. Its argument is a pointer to the following
276structure:
277
278struct mon_get_arg {
279 struct usbmon_packet *hdr;
280 void *data;
281 size_t alloc; /* Length of data (can be zero) */
282};
283
284Before the call, hdr, data, and alloc should be filled. Upon return, the area
285pointed by hdr contains the next event structure, and the data buffer contains
286the data, if any. The event is removed from the kernel buffer.
287
288 MON_IOCX_MFETCH, defined as _IOWR(MON_IOC_MAGIC, 7, struct mon_mfetch_arg)
289
290This ioctl is primarily used when the application accesses the buffer
291with mmap(2). Its argument is a pointer to the following structure:
292
293struct mon_mfetch_arg {
294 uint32_t *offvec; /* Vector of events fetched */
295 uint32_t nfetch; /* Number of events to fetch (out: fetched) */
296 uint32_t nflush; /* Number of events to flush */
297};
298
299The ioctl operates in 3 stages.
300
301First, it removes and discards up to nflush events from the kernel buffer.
302The actual number of events discarded is returned in nflush.
303
304Second, it waits for an event to be present in the buffer, unless the pseudo-
305device is open with O_NONBLOCK.
306
307Third, it extracts up to nfetch offsets into the mmap buffer, and stores
308them into the offvec. The actual number of event offsets is stored into
309the nfetch.
310
311 MON_IOCH_MFLUSH, defined as _IO(MON_IOC_MAGIC, 8)
312
313This call removes a number of events from the kernel buffer. Its argument
314is the number of events to remove. If the buffer contains fewer events
315than requested, all events present are removed, and no error is reported.
316This works when no events are available too.
317
318 FIONBIO
319
320The ioctl FIONBIO may be implemented in the future, if there's a need.
321
322In addition to ioctl(2) and read(2), the special file of binary API can
323be polled with select(2) and poll(2). But lseek(2) does not work.
324
325* Memory-mapped access of the kernel buffer for the binary API
326
327The basic idea is simple:
328
329To prepare, map the buffer by getting the current size, then using mmap(2).
330Then, execute a loop similar to the one written in pseudo-code below:
331
332 struct mon_mfetch_arg fetch;
333 struct usbmon_packet *hdr;
334 int nflush = 0;
335 for (;;) {
336 fetch.offvec = vec; // Has N 32-bit words
337 fetch.nfetch = N; // Or less than N
338 fetch.nflush = nflush;
339 ioctl(fd, MON_IOCX_MFETCH, &fetch); // Process errors, too
340 nflush = fetch.nfetch; // This many packets to flush when done
341 for (i = 0; i < nflush; i++) {
342 hdr = (struct ubsmon_packet *) &mmap_area[vec[i]];
343 if (hdr->type == '@') // Filler packet
344 continue;
345 caddr_t data = &mmap_area[vec[i]] + 64;
346 process_packet(hdr, data);
347 }
348 }
349
350Thus, the main idea is to execute only one ioctl per N events.
351
352Although the buffer is circular, the returned headers and data do not cross
353the 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
diff --git a/Documentation/video4linux/CARDLIST.bttv b/Documentation/video4linux/CARDLIST.bttv
index 4efa4645885f..b60639130a51 100644
--- a/Documentation/video4linux/CARDLIST.bttv
+++ b/Documentation/video4linux/CARDLIST.bttv
@@ -126,7 +126,7 @@
126125 -> MATRIX Vision Sigma-SQ 126125 -> MATRIX Vision Sigma-SQ
127126 -> MATRIX Vision Sigma-SLC 127126 -> MATRIX Vision Sigma-SLC
128127 -> APAC Viewcomp 878(AMAX) 128127 -> APAC Viewcomp 878(AMAX)
129128 -> DViCO FusionHDTV DVB-T Lite [18ac:db10] 129128 -> DViCO FusionHDTV DVB-T Lite [18ac:db10,18ac:db11]
130129 -> V-Gear MyVCD 130129 -> V-Gear MyVCD
131130 -> Super TV Tuner 131130 -> Super TV Tuner
132131 -> Tibet Systems 'Progress DVR' CS16 132131 -> Tibet Systems 'Progress DVR' CS16
@@ -143,3 +143,5 @@
143142 -> Sabrent TV-FM (bttv version) 143142 -> Sabrent TV-FM (bttv version)
144143 -> Hauppauge ImpactVCB (bt878) [0070:13eb] 144143 -> Hauppauge ImpactVCB (bt878) [0070:13eb]
145144 -> MagicTV 145144 -> MagicTV
146145 -> SSAI Security Video Interface [4149:5353]
147146 -> SSAI Ultrasound Video Interface [414a:5353]
diff --git a/Documentation/video4linux/CARDLIST.cx88 b/Documentation/video4linux/CARDLIST.cx88
index 62e32b49cec9..60f838beb9c8 100644
--- a/Documentation/video4linux/CARDLIST.cx88
+++ b/Documentation/video4linux/CARDLIST.cx88
@@ -37,7 +37,7 @@
37 36 -> AVerTV 303 (M126) [1461:000a] 37 36 -> AVerTV 303 (M126) [1461:000a]
38 37 -> Hauppauge Nova-S-Plus DVB-S [0070:9201,0070:9202] 38 37 -> Hauppauge Nova-S-Plus DVB-S [0070:9201,0070:9202]
39 38 -> Hauppauge Nova-SE2 DVB-S [0070:9200] 39 38 -> Hauppauge Nova-SE2 DVB-S [0070:9200]
40 39 -> KWorld DVB-S 100 [17de:08b2] 40 39 -> KWorld DVB-S 100 [17de:08b2,1421:0341]
41 40 -> Hauppauge WinTV-HVR1100 DVB-T/Hybrid [0070:9400,0070:9402] 41 40 -> Hauppauge WinTV-HVR1100 DVB-T/Hybrid [0070:9400,0070:9402]
42 41 -> Hauppauge WinTV-HVR1100 DVB-T/Hybrid (Low Profile) [0070:9800,0070:9802] 42 41 -> Hauppauge WinTV-HVR1100 DVB-T/Hybrid (Low Profile) [0070:9800,0070:9802]
43 42 -> digitalnow DNTV Live! DVB-T Pro [1822:0025,1822:0019] 43 42 -> digitalnow DNTV Live! DVB-T Pro [1822:0025,1822:0019]
diff --git a/Documentation/video4linux/CARDLIST.ivtv b/Documentation/video4linux/CARDLIST.ivtv
new file mode 100644
index 000000000000..ddd76a0eb100
--- /dev/null
+++ b/Documentation/video4linux/CARDLIST.ivtv
@@ -0,0 +1,18 @@
1 1 -> Hauppauge WinTV PVR-250
2 2 -> Hauppauge WinTV PVR-350
3 3 -> Hauppauge WinTV PVR-150 or PVR-500
4 4 -> AVerMedia M179 [1461:a3ce,1461:a3cf]
5 5 -> Yuan MPG600/Kuroutoshikou iTVC16-STVLP [12ab:fff3,12ab:ffff]
6 6 -> Yuan MPG160/Kuroutoshikou iTVC15-STVLP [12ab:0000,10fc:40a0]
7 7 -> Yuan PG600/DiamondMM PVR-550 [ff92:0070,ffab:0600]
8 8 -> Adaptec AVC-2410 [9005:0093]
9 9 -> Adaptec AVC-2010 [9005:0092]
1010 -> NAGASE TRANSGEAR 5000TV [1461:bfff]
1111 -> AOpen VA2000MAX-STN6 [0000:ff5f]
1212 -> YUAN MPG600GR/Kuroutoshikou CX23416GYC-STVLP [12ab:0600,fbab:0600,1154:0523]
1313 -> I/O Data GV-MVP/RX [10fc:d01e,10fc:d038,10fc:d039]
1414 -> I/O Data GV-MVP/RX2E [10fc:d025]
1515 -> GOTVIEW PCI DVD (partial support only) [12ab:0600]
1616 -> GOTVIEW PCI DVD2 Deluxe [ffac:0600]
1717 -> Yuan MPC622 [ff01:d998]
1818 -> Digital Cowboy DCT-MTVP1 [1461:bfff]
diff --git a/Documentation/video4linux/CARDLIST.saa7134 b/Documentation/video4linux/CARDLIST.saa7134
index f6201cc37ec5..d7bb2e2e4d9b 100644
--- a/Documentation/video4linux/CARDLIST.saa7134
+++ b/Documentation/video4linux/CARDLIST.saa7134
@@ -53,7 +53,7 @@
53 52 -> AverMedia AverTV/305 [1461:2108] 53 52 -> AverMedia AverTV/305 [1461:2108]
54 53 -> ASUS TV-FM 7135 [1043:4845] 54 53 -> ASUS TV-FM 7135 [1043:4845]
55 54 -> LifeView FlyTV Platinum FM / Gold [5168:0214,1489:0214,5168:0304] 55 54 -> LifeView FlyTV Platinum FM / Gold [5168:0214,1489:0214,5168:0304]
56 55 -> LifeView FlyDVB-T DUO [5168:0306] 56 55 -> LifeView FlyDVB-T DUO / MSI TV@nywhere Duo [5168:0306,4E42:0306]
57 56 -> Avermedia AVerTV 307 [1461:a70a] 57 56 -> Avermedia AVerTV 307 [1461:a70a]
58 57 -> Avermedia AVerTV GO 007 FM [1461:f31f] 58 57 -> Avermedia AVerTV GO 007 FM [1461:f31f]
59 58 -> ADS Tech Instant TV (saa7135) [1421:0350,1421:0351,1421:0370,1421:1370] 59 58 -> ADS Tech Instant TV (saa7135) [1421:0350,1421:0351,1421:0370,1421:1370]
@@ -76,7 +76,7 @@
76 75 -> AVerMedia AVerTVHD MCE A180 [1461:1044] 76 75 -> AVerMedia AVerTVHD MCE A180 [1461:1044]
77 76 -> SKNet MonsterTV Mobile [1131:4ee9] 77 76 -> SKNet MonsterTV Mobile [1131:4ee9]
78 77 -> Pinnacle PCTV 40i/50i/110i (saa7133) [11bd:002e] 78 77 -> Pinnacle PCTV 40i/50i/110i (saa7133) [11bd:002e]
79 78 -> ASUSTeK P7131 Dual [1043:4862,1043:4876] 79 78 -> ASUSTeK P7131 Dual [1043:4862,1043:4857]
80 79 -> Sedna/MuchTV PC TV Cardbus TV/Radio (ITO25 Rev:2B) 80 79 -> Sedna/MuchTV PC TV Cardbus TV/Radio (ITO25 Rev:2B)
81 80 -> ASUS Digimatrix TV [1043:0210] 81 80 -> ASUS Digimatrix TV [1043:0210]
82 81 -> Philips Tiger reference design [1131:2018] 82 81 -> Philips Tiger reference design [1131:2018]
@@ -104,3 +104,10 @@
104103 -> Compro Videomate DVB-T200A 104103 -> Compro Videomate DVB-T200A
105104 -> Hauppauge WinTV-HVR1110 DVB-T/Hybrid [0070:6701] 105104 -> Hauppauge WinTV-HVR1110 DVB-T/Hybrid [0070:6701]
106105 -> Terratec Cinergy HT PCMCIA [153b:1172] 106105 -> Terratec Cinergy HT PCMCIA [153b:1172]
107106 -> Encore ENLTV [1131:2342,1131:2341,3016:2344]
108107 -> Encore ENLTV-FM [1131:230f]
109108 -> Terratec Cinergy HT PCI [153b:1175]
110109 -> Philips Tiger - S Reference design
111110 -> Avermedia M102 [1461:f31e]
112111 -> ASUS P7131 4871 [1043:4871]
113112 -> ASUSTeK P7131 Hybrid [1043:4876]
diff --git a/Documentation/video4linux/CARDLIST.usbvision b/Documentation/video4linux/CARDLIST.usbvision
new file mode 100644
index 000000000000..3d6850ef0245
--- /dev/null
+++ b/Documentation/video4linux/CARDLIST.usbvision
@@ -0,0 +1,64 @@
1 0 -> Xanboo [0a6f:0400]
2 1 -> Belkin USB VideoBus II Adapter [050d:0106]
3 2 -> Belkin Components USB VideoBus [050d:0207]
4 3 -> Belkin USB VideoBus II [050d:0208]
5 4 -> echoFX InterView Lite [0571:0002]
6 5 -> USBGear USBG-V1 resp. HAMA USB [0573:0003]
7 6 -> D-Link V100 [0573:0400]
8 7 -> X10 USB Camera [0573:2000]
9 8 -> Hauppauge WinTV USB Live (PAL B/G) [0573:2d00]
10 9 -> Hauppauge WinTV USB Live Pro (NTSC M/N) [0573:2d01]
11 10 -> Zoran Co. PMD (Nogatech) AV-grabber Manhattan [0573:2101]
12 11 -> Nogatech USB-TV (NTSC) FM [0573:4100]
13 12 -> PNY USB-TV (NTSC) FM [0573:4110]
14 13 -> PixelView PlayTv-USB PRO (PAL) FM [0573:4450]
15 14 -> ZTV ZT-721 2.4GHz USB A/V Receiver [0573:4550]
16 15 -> Hauppauge WinTV USB (NTSC M/N) [0573:4d00]
17 16 -> Hauppauge WinTV USB (PAL B/G) [0573:4d01]
18 17 -> Hauppauge WinTV USB (PAL I) [0573:4d02]
19 18 -> Hauppauge WinTV USB (PAL/SECAM L) [0573:4d03]
20 19 -> Hauppauge WinTV USB (PAL D/K) [0573:4d04]
21 20 -> Hauppauge WinTV USB (NTSC FM) [0573:4d10]
22 21 -> Hauppauge WinTV USB (PAL B/G FM) [0573:4d11]
23 22 -> Hauppauge WinTV USB (PAL I FM) [0573:4d12]
24 23 -> Hauppauge WinTV USB (PAL D/K FM) [0573:4d14]
25 24 -> Hauppauge WinTV USB Pro (NTSC M/N) [0573:4d2a]
26 25 -> Hauppauge WinTV USB Pro (NTSC M/N) V2 [0573:4d2b]
27 26 -> Hauppauge WinTV USB Pro (PAL/SECAM B/G/I/D/K/L) [0573:4d2c]
28 27 -> Hauppauge WinTV USB Pro (NTSC M/N) V3 [0573:4d20]
29 28 -> Hauppauge WinTV USB Pro (PAL B/G) [0573:4d21]
30 29 -> Hauppauge WinTV USB Pro (PAL I) [0573:4d22]
31 30 -> Hauppauge WinTV USB Pro (PAL/SECAM L) [0573:4d23]
32 31 -> Hauppauge WinTV USB Pro (PAL D/K) [0573:4d24]
33 32 -> Hauppauge WinTV USB Pro (PAL/SECAM BGDK/I/L) [0573:4d25]
34 33 -> Hauppauge WinTV USB Pro (PAL/SECAM BGDK/I/L) V2 [0573:4d26]
35 34 -> Hauppauge WinTV USB Pro (PAL B/G) V2 [0573:4d27]
36 35 -> Hauppauge WinTV USB Pro (PAL B/G,D/K) [0573:4d28]
37 36 -> Hauppauge WinTV USB Pro (PAL I,D/K) [0573:4d29]
38 37 -> Hauppauge WinTV USB Pro (NTSC M/N FM) [0573:4d30]
39 38 -> Hauppauge WinTV USB Pro (PAL B/G FM) [0573:4d31]
40 39 -> Hauppauge WinTV USB Pro (PAL I FM) [0573:4d32]
41 40 -> Hauppauge WinTV USB Pro (PAL D/K FM) [0573:4d34]
42 41 -> Hauppauge WinTV USB Pro (Temic PAL/SECAM B/G/I/D/K/L FM) [0573:4d35]
43 42 -> Hauppauge WinTV USB Pro (Temic PAL B/G FM) [0573:4d36]
44 43 -> Hauppauge WinTV USB Pro (PAL/SECAM B/G/I/D/K/L FM) [0573:4d37]
45 44 -> Hauppauge WinTV USB Pro (NTSC M/N FM) V2 [0573:4d38]
46 45 -> Camtel Technology USB TV Genie Pro FM Model TVB330 [0768:0006]
47 46 -> Digital Video Creator I [07d0:0001]
48 47 -> Global Village GV-007 (NTSC) [07d0:0002]
49 48 -> Dazzle Fusion Model DVC-50 Rev 1 (NTSC) [07d0:0003]
50 49 -> Dazzle Fusion Model DVC-80 Rev 1 (PAL) [07d0:0004]
51 50 -> Dazzle Fusion Model DVC-90 Rev 1 (SECAM) [07d0:0005]
52 51 -> Eskape Labs MyTV2Go [07f8:9104]
53 52 -> Pinnacle Studio PCTV USB (PAL) [2304:010d]
54 53 -> Pinnacle Studio PCTV USB (SECAM) [2304:0109]
55 54 -> Pinnacle Studio PCTV USB (PAL) FM [2304:0110]
56 55 -> Miro PCTV USB [2304:0111]
57 56 -> Pinnacle Studio PCTV USB (NTSC) FM [2304:0112]
58 57 -> Pinnacle Studio PCTV USB (PAL) FM V2 [2304:0210]
59 58 -> Pinnacle Studio PCTV USB (NTSC) FM V2 [2304:0212]
60 59 -> Pinnacle Studio PCTV USB (PAL) FM V3 [2304:0214]
61 60 -> Pinnacle Studio Linx Video input cable (NTSC) [2304:0300]
62 61 -> Pinnacle Studio Linx Video input cable (PAL) [2304:0301]
63 62 -> Pinnacle PCTV Bungee USB (PAL) FM [2304:0419]
64 63 -> Hauppauge WinTv-USB [2400:4200]
diff --git a/Documentation/video4linux/CQcam.txt b/Documentation/video4linux/CQcam.txt
index ade8651e2443..04986efb731c 100644
--- a/Documentation/video4linux/CQcam.txt
+++ b/Documentation/video4linux/CQcam.txt
@@ -197,10 +197,10 @@ Use the ../../Maintainers file, particularly the VIDEO FOR LINUX and PARALLEL
197PORT SUPPORT sections 197PORT SUPPORT sections
198 198
199The video4linux page: 199The video4linux page:
200 http://roadrunner.swansea.linux.org.uk/v4l.shtml 200 http://linuxtv.org
201 201
202The video4linux2 page: 202The V4L2 API spec:
203 http://millennium.diads.com/bdirks/v4l2.htm 203 http://v4l2spec.bytesex.org/
204 204
205Some web pages about the quickcams: 205Some web pages about the quickcams:
206 http://www.dkfz-heidelberg.de/Macromol/wedemann/mini-HOWTO-cqcam.html 206 http://www.dkfz-heidelberg.de/Macromol/wedemann/mini-HOWTO-cqcam.html
diff --git a/Documentation/video4linux/README.ivtv b/Documentation/video4linux/README.ivtv
new file mode 100644
index 000000000000..73df22c40bfe
--- /dev/null
+++ b/Documentation/video4linux/README.ivtv
@@ -0,0 +1,187 @@
1
2ivtv release notes
3==================
4
5This is a v4l2 device driver for the Conexant cx23415/6 MPEG encoder/decoder.
6The cx23415 can do both encoding and decoding, the cx23416 can only do MPEG
7encoding. Currently the only card featuring full decoding support is the
8Hauppauge PVR-350.
9
10NOTE: this driver requires the latest encoder firmware (version 2.06.039, size
11376836 bytes). Get the firmware from here:
12
13http://dl.ivtvdriver.org/ivtv/firmware/firmware.tar.gz
14
15NOTE: 'normal' TV applications do not work with this driver, you need
16an application that can handle MPEG input such as mplayer, xine, MythTV,
17etc.
18
19The primary goal of the IVTV project is to provide a "clean room" Linux
20Open Source driver implementation for video capture cards based on the
21iCompression iTVC15 or Conexant CX23415/CX23416 MPEG Codec.
22
23Features:
24 * Hardware mpeg2 capture of broadcast video (and sound) via the tuner or
25 S-Video/Composite and audio line-in.
26 * Hardware mpeg2 capture of FM radio where hardware support exists
27 * Supports NTSC, PAL, SECAM with stereo sound
28 * Supports SAP and bilingual transmissions.
29 * Supports raw VBI (closed captions and teletext).
30 * Supports sliced VBI (closed captions and teletext) and is able to insert
31 this into the captured MPEG stream.
32 * Supports raw YUV and PCM input.
33
34Additional features for the PVR-350 (CX23415 based):
35 * Provides hardware mpeg2 playback
36 * Provides comprehensive OSD (On Screen Display: ie. graphics overlaying the
37 video signal)
38 * Provides a framebuffer (allowing X applications to appear on the video
39 device) (this framebuffer is not yet part of the kernel. In the meantime it
40 is available from www.ivtvdriver.org).
41 * Supports raw YUV output.
42
43IMPORTANT: In case of problems first read this page:
44 http://www.ivtvdriver.org/index.php/Troubleshooting
45
46See also:
47
48Homepage + Wiki
49http://www.ivtvdriver.org
50
51IRC
52irc://irc.freenode.net/ivtv-dev
53
54----------------------------------------------------------
55
56Devices
57=======
58
59A maximum of 12 ivtv boards are allowed at the moment.
60
61Cards that don't have a video output capability (i.e. non PVR350 cards)
62lack the vbi8, vbi16, video16 and video48 devices. They also do not
63support the framebuffer device /dev/fbx for OSD.
64
65The radio0 device may or may not be present, depending on whether the
66card has a radio tuner or not.
67
68Here is a list of the base v4l devices:
69crw-rw---- 1 root video 81, 0 Jun 19 22:22 /dev/video0
70crw-rw---- 1 root video 81, 16 Jun 19 22:22 /dev/video16
71crw-rw---- 1 root video 81, 24 Jun 19 22:22 /dev/video24
72crw-rw---- 1 root video 81, 32 Jun 19 22:22 /dev/video32
73crw-rw---- 1 root video 81, 48 Jun 19 22:22 /dev/video48
74crw-rw---- 1 root video 81, 64 Jun 19 22:22 /dev/radio0
75crw-rw---- 1 root video 81, 224 Jun 19 22:22 /dev/vbi0
76crw-rw---- 1 root video 81, 228 Jun 19 22:22 /dev/vbi8
77crw-rw---- 1 root video 81, 232 Jun 19 22:22 /dev/vbi16
78
79Base devices
80============
81
82For every extra card you have the numbers increased by one. For example,
83/dev/video0 is listed as the 'base' encoding capture device so we have:
84
85 /dev/video0 is the encoding capture device for the first card (card 0)
86 /dev/video1 is the encoding capture device for the second card (card 1)
87 /dev/video2 is the encoding capture device for the third card (card 2)
88
89Note that if the first card doesn't have a feature (eg no decoder, so no
90video16, the second card will still use video17. The simple rule is 'add
91the card number to the base device number'. If you have other capture
92cards (e.g. WinTV PCI) that are detected first, then you have to tell
93the ivtv module about it so that it will start counting at 1 (or 2, or
94whatever). Otherwise the device numbers can get confusing. The ivtv
95'ivtv_first_minor' module option can be used for that.
96
97
98/dev/video0
99The encoding capture device(s).
100Read-only.
101
102Reading from this device gets you the MPEG1/2 program stream.
103Example:
104
105cat /dev/video0 > my.mpg (you need to hit ctrl-c to exit)
106
107
108/dev/video16
109The decoder output device(s)
110Write-only. Only present if the MPEG decoder (i.e. CX23415) exists.
111
112An mpeg2 stream sent to this device will appear on the selected video
113display, audio will appear on the line-out/audio out. It is only
114available for cards that support video out. Example:
115
116cat my.mpg >/dev/video16
117
118
119/dev/video24
120The raw audio capture device(s).
121Read-only
122
123The raw audio PCM stereo stream from the currently selected
124tuner or audio line-in. Reading from this device results in a raw
125(signed 16 bit Little Endian, 48000 Hz, stereo pcm) capture.
126This device only captures audio. This should be replaced by an ALSA
127device in the future.
128Note that there is no corresponding raw audio output device, this is
129not supported in the decoder firmware.
130
131
132/dev/video32
133The raw video capture device(s)
134Read-only
135
136The raw YUV video output from the current video input. The YUV format
137is non-standard (V4L2_PIX_FMT_HM12).
138
139Note that the YUV and PCM streams are not synchronized, so they are of
140limited use.
141
142
143/dev/video48
144The raw video display device(s)
145Write-only. Only present if the MPEG decoder (i.e. CX23415) exists.
146
147Writes a YUV stream to the decoder of the card.
148
149
150/dev/radio0
151The radio tuner device(s)
152Cannot be read or written.
153
154Used to enable the radio tuner and tune to a frequency. You cannot
155read or write audio streams with this device. Once you use this
156device to tune the radio, use /dev/video24 to read the raw pcm stream
157or /dev/video0 to get an mpeg2 stream with black video.
158
159
160/dev/vbi0
161The 'vertical blank interval' (Teletext, CC, WSS etc) capture device(s)
162Read-only
163
164Captures the raw (or sliced) video data sent during the Vertical Blank
165Interval. This data is used to encode teletext, closed captions, VPS,
166widescreen signalling, electronic program guide information, and other
167services.
168
169
170/dev/vbi8
171Processed vbi feedback device(s)
172Read-only. Only present if the MPEG decoder (i.e. CX23415) exists.
173
174The sliced VBI data embedded in an MPEG stream is reproduced on this
175device. So while playing back a recording on /dev/video16, you can
176read the embedded VBI data from /dev/vbi8.
177
178
179/dev/vbi16
180The vbi 'display' device(s)
181Write-only. Only present if the MPEG decoder (i.e. CX23415) exists.
182
183Can be used to send sliced VBI data to the video-out connector.
184
185---------------------------------
186
187Hans Verkuil <hverkuil@xs4all.nl>
diff --git a/Documentation/video4linux/Zoran b/Documentation/video4linux/Zoran
index deb218f77adb..85c575ac4fb9 100644
--- a/Documentation/video4linux/Zoran
+++ b/Documentation/video4linux/Zoran
@@ -339,9 +339,9 @@ Information - video4linux/mjpeg extensions:
339(also see below) 339(also see below)
340 340
341Information - video4linux2: 341Information - video4linux2:
342http://www.thedirks.org/v4l2/ 342http://linuxtv.org
343http://v4l2spec.bytesex.org/
343/usr/include/linux/videodev2.h 344/usr/include/linux/videodev2.h
344http://www.bytesex.org/v4l/
345 345
346More information on the video4linux/mjpeg extensions, by Serguei 346More information on the video4linux/mjpeg extensions, by Serguei
347Miridonovi and Rainer Johanni: 347Miridonovi and Rainer Johanni:
diff --git a/Documentation/video4linux/bttv/Insmod-options b/Documentation/video4linux/bttv/Insmod-options
index bb7c2cac7917..5ef75787f83a 100644
--- a/Documentation/video4linux/bttv/Insmod-options
+++ b/Documentation/video4linux/bttv/Insmod-options
@@ -57,7 +57,7 @@ bttv.o
57 i2c_udelay= Allow reduce I2C speed. Default is 5 usecs 57 i2c_udelay= Allow reduce I2C speed. Default is 5 usecs
58 (meaning 66,67 Kbps). The default is the 58 (meaning 66,67 Kbps). The default is the
59 maximum supported speed by kernel bitbang 59 maximum supported speed by kernel bitbang
60 algoritm. You may use lower numbers, if I2C 60 algorithm. You may use lower numbers, if I2C
61 messages are lost (16 is known to work on 61 messages are lost (16 is known to work on
62 all supported cards). 62 all supported cards).
63 63
diff --git a/Documentation/video4linux/cx2341x/fw-decoder-api.txt b/Documentation/video4linux/cx2341x/fw-decoder-api.txt
index 78bf5f21e513..8c317b7a4fc9 100644
--- a/Documentation/video4linux/cx2341x/fw-decoder-api.txt
+++ b/Documentation/video4linux/cx2341x/fw-decoder-api.txt
@@ -21,7 +21,7 @@ Param[0]
21 0 based frame number in GOP to begin playback from. 21 0 based frame number in GOP to begin playback from.
22Param[1] 22Param[1]
23 Specifies the number of muted audio frames to play before normal 23 Specifies the number of muted audio frames to play before normal
24 audio resumes. 24 audio resumes. (This is not implemented in the firmware, leave at 0)
25 25
26------------------------------------------------------------------------------- 26-------------------------------------------------------------------------------
27 27
@@ -32,6 +32,10 @@ Description
32 playback stops at specified PTS. 32 playback stops at specified PTS.
33Param[0] 33Param[0]
34 Display 0=last frame, 1=black 34 Display 0=last frame, 1=black
35 Note: this takes effect immediately, so if you want to wait for a PTS,
36 then use '0', otherwise the screen goes to black at once.
37 You can call this later (even if there is no playback) with a 1 value
38 to set the screen to black.
35Param[1] 39Param[1]
36 PTS low 40 PTS low
37Param[2] 41Param[2]
@@ -60,8 +64,12 @@ Param[0]
60 31 Speed: 64 31 Speed:
61 '0' slow 65 '0' slow
62 '1' fast 66 '1' fast
67 Note: n is limited to 2. Anything higher does not result in
68 faster playback. Instead the host should start dropping frames.
63Param[1] 69Param[1]
64 Direction: 0=forward, 1=reverse 70 Direction: 0=forward, 1=reverse
71 Note: to make reverse playback work you have to write full GOPs in
72 reverse order.
65Param[2] 73Param[2]
66 Picture mask: 74 Picture mask:
67 1=I frames 75 1=I frames
@@ -69,13 +77,16 @@ Param[2]
69 7=I, P, B frames 77 7=I, P, B frames
70Param[3] 78Param[3]
71 B frames per GOP (for reverse play only) 79 B frames per GOP (for reverse play only)
80 Note: for reverse playback the Picture Mask should be set to I or I, P.
81 Adding B frames to the mask will result in corrupt video. This field
82 has to be set to the correct value in order to keep the timing correct.
72Param[4] 83Param[4]
73 Mute audio: 0=disable, 1=enable 84 Mute audio: 0=disable, 1=enable
74Param[5] 85Param[5]
75 Display 0=frame, 1=field 86 Display 0=frame, 1=field
76Param[6] 87Param[6]
77 Specifies the number of muted audio frames to play before normal audio 88 Specifies the number of muted audio frames to play before normal audio
78 resumes. 89 resumes. (Not implemented in the firmware, leave at 0)
79 90
80------------------------------------------------------------------------------- 91-------------------------------------------------------------------------------
81 92
@@ -212,6 +223,7 @@ Description
212 Select audio mode 223 Select audio mode
213Param[0] 224Param[0]
214 Dual mono mode action 225 Dual mono mode action
226 0=Stereo, 1=Left, 2=Right, 3=Mono, 4=Swap, -1=Unchanged
215Param[1] 227Param[1]
216 Stereo mode action: 228 Stereo mode action:
217 0=Stereo, 1=Left, 2=Right, 3=Mono, 4=Swap, -1=Unchanged 229 0=Stereo, 1=Left, 2=Right, 3=Mono, 4=Swap, -1=Unchanged
@@ -224,7 +236,10 @@ Description
224 Setup firmware to notify the host about a particular event. 236 Setup firmware to notify the host about a particular event.
225 Counterpart to API 0xD5 237 Counterpart to API 0xD5
226Param[0] 238Param[0]
227 Event: 0=Audio mode change between stereo and dual channel 239 Event: 0=Audio mode change between mono, (joint) stereo and dual channel.
240 Event: 3=Decoder started
241 Event: 4=Unknown: goes off 10-15 times per second while decoding.
242 Event: 5=Some sync event: goes off once per frame.
228Param[1] 243Param[1]
229 Notification 0=disabled, 1=enabled 244 Notification 0=disabled, 1=enabled
230Param[2] 245Param[2]
@@ -273,43 +288,6 @@ Param[3]
273 288
274------------------------------------------------------------------------------- 289-------------------------------------------------------------------------------
275 290
276Name CX2341X_DEC_SET_AUDIO_OUTPUT
277Enum 27/0x1B
278Description
279 Select audio output format
280Param[0]
281 Bitmask:
282 0:1 Data size:
283 '00' 16 bit
284 '01' 20 bit
285 '10' 24 bit
286 2:7 Unused
287 8:9 Mode:
288 '00' 2 channels
289 '01' 4 channels
290 '10' 6 channels
291 '11' 6 channels with one line data mode
292 (for left justified MSB first mode, 20 bit only)
293 10:11 Unused
294 12:13 Channel format:
295 '00' right justified MSB first mode
296 '01' left justified MSB first mode
297 '10' I2S mode
298 14:15 Unused
299 16:21 Right justify bit count
300 22:31 Unused
301
302-------------------------------------------------------------------------------
303
304Name CX2341X_DEC_SET_AV_DELAY
305Enum 28/0x1C
306Description
307 Set audio/video delay in 90Khz ticks
308Param[0]
309 0=A/V in sync, negative=audio lags, positive=video lags
310
311-------------------------------------------------------------------------------
312
313Name CX2341X_DEC_SET_PREBUFFERING 291Name CX2341X_DEC_SET_PREBUFFERING
314Enum 30/0x1E 292Enum 30/0x1E
315Description 293Description
diff --git a/Documentation/video4linux/cx2341x/fw-decoder-regs.txt b/Documentation/video4linux/cx2341x/fw-decoder-regs.txt
new file mode 100644
index 000000000000..cf52c8f20b9e
--- /dev/null
+++ b/Documentation/video4linux/cx2341x/fw-decoder-regs.txt
@@ -0,0 +1,817 @@
1PVR350 Video decoder registers 0x02002800 -> 0x02002B00
2=======================================================
3
4This list has been worked out through trial and error. There will be mistakes
5and omissions. Some registers have no obvious effect so it's hard to say what
6they do, while others interact with each other, or require a certain load
7sequence. Horizontal filter setup is one example, with six registers working
8in unison and requiring a certain load sequence to correctly configure. The
9indexed colour palette is much easier to set at just two registers, but again
10it requires a certain load sequence.
11
12Some registers are fussy about what they are set to. Load in a bad value & the
13decoder will fail. A firmware reload will often recover, but sometimes a reset
14is required. For registers containing size information, setting them to 0 is
15generally a bad idea. For other control registers i.e. 2878, you'll only find
16out what values are bad when it hangs.
17
18--------------------------------------------------------------------------------
192800
20 bit 0
21 Decoder enable
22 0 = disable
23 1 = enable
24--------------------------------------------------------------------------------
252804
26 bits 0:31
27 Decoder horizontal Y alias register 1
28---------------
292808
30 bits 0:31
31 Decoder horizontal Y alias register 2
32---------------
33280C
34 bits 0:31
35 Decoder horizontal Y alias register 3
36---------------
372810
38 bits 0:31
39 Decoder horizontal Y alias register 4
40---------------
412814
42 bits 0:31
43 Decoder horizontal Y alias register 5
44---------------
452818
46 bits 0:31
47 Decoder horizontal Y alias trigger
48
49 These six registers control the horizontal aliasing filter for the Y plane.
50 The first five registers must all be loaded before accessing the trigger
51 (2818), as this register actually clocks the data through for the first
52 five.
53
54 To correctly program set the filter, this whole procedure must be done 16
55 times. The actual register contents are copied from a lookup-table in the
56 firmware which contains 4 different filter settings.
57
58--------------------------------------------------------------------------------
59281C
60 bits 0:31
61 Decoder horizontal UV alias register 1
62---------------
632820
64 bits 0:31
65 Decoder horizontal UV alias register 2
66---------------
672824
68 bits 0:31
69 Decoder horizontal UV alias register 3
70---------------
712828
72 bits 0:31
73 Decoder horizontal UV alias register 4
74---------------
75282C
76 bits 0:31
77 Decoder horizontal UV alias register 5
78---------------
792830
80 bits 0:31
81 Decoder horizontal UV alias trigger
82
83 These six registers control the horizontal aliasing for the UV plane.
84 Operation is the same as the Y filter, with 2830 being the trigger
85 register.
86
87--------------------------------------------------------------------------------
882834
89 bits 0:15
90 Decoder Y source width in pixels
91
92 bits 16:31
93 Decoder Y destination width in pixels
94---------------
952838
96 bits 0:15
97 Decoder UV source width in pixels
98
99 bits 16:31
100 Decoder UV destination width in pixels
101
102 NOTE: For both registers, the resulting image must be fully visible on
103 screen. If the image exceeds the right edge both the source and destination
104 size must be adjusted to reflect the visible portion. For the source width,
105 you must take into account the scaling when calculating the new value.
106--------------------------------------------------------------------------------
107
108283C
109 bits 0:31
110 Decoder Y horizontal scaling
111 Normally = Reg 2854 >> 2
112---------------
1132840
114 bits 0:31
115 Decoder ?? unknown - horizontal scaling
116 Usually 0x00080514
117---------------
1182844
119 bits 0:31
120 Decoder UV horizontal scaling
121 Normally = Reg 2854 >> 2
122---------------
1232848
124 bits 0:31
125 Decoder ?? unknown - horizontal scaling
126 Usually 0x00100514
127---------------
128284C
129 bits 0:31
130 Decoder ?? unknown - Y plane
131 Usually 0x00200020
132---------------
1332850
134 bits 0:31
135 Decoder ?? unknown - UV plane
136 Usually 0x00200020
137---------------
1382854
139 bits 0:31
140 Decoder 'master' value for horizontal scaling
141---------------
1422858
143 bits 0:31
144 Decoder ?? unknown
145 Usually 0
146---------------
147285C
148 bits 0:31
149 Decoder ?? unknown
150 Normally = Reg 2854 >> 1
151---------------
1522860
153 bits 0:31
154 Decoder ?? unknown
155 Usually 0
156---------------
1572864
158 bits 0:31
159 Decoder ?? unknown
160 Normally = Reg 2854 >> 1
161---------------
1622868
163 bits 0:31
164 Decoder ?? unknown
165 Usually 0
166
167 Most of these registers either control horizontal scaling, or appear linked
168 to it in some way. Register 2854 contains the 'master' value & the other
169 registers can be calculated from that one. You must also remember to
170 correctly set the divider in Reg 2874.
171
172 To enlarge:
173 Reg 2854 = (source_width * 0x00200000) / destination_width
174 Reg 2874 = No divide
175
176 To reduce from full size down to half size:
177 Reg 2854 = (source_width/2 * 0x00200000) / destination width
178 Reg 2874 = Divide by 2
179
180 To reduce from half size down to quarter size:
181 Reg 2854 = (source_width/4 * 0x00200000) / destination width
182 Reg 2874 = Divide by 4
183
184 The result is always rounded up.
185
186--------------------------------------------------------------------------------
187286C
188 bits 0:15
189 Decoder horizontal Y buffer offset
190
191 bits 15:31
192 Decoder horizontal UV buffer offset
193
194 Offset into the video image buffer. If the offset is gradually incremented,
195 the on screen image will move left & wrap around higher up on the right.
196
197--------------------------------------------------------------------------------
1982870
199 bits 0:15
200 Decoder horizontal Y output offset
201
202 bits 16:31
203 Decoder horizontal UV output offset
204
205 Offsets the actual video output. Controls output alignment of the Y & UV
206 planes. The higher the value, the greater the shift to the left. Use
207 reg 2890 to move the image right.
208
209--------------------------------------------------------------------------------
2102874
211 bits 0:1
212 Decoder horizontal Y output size divider
213 00 = No divide
214 01 = Divide by 2
215 10 = Divide by 3
216
217 bits 4:5
218 Decoder horizontal UV output size divider
219 00 = No divide
220 01 = Divide by 2
221 10 = Divide by 3
222
223 bit 8
224 Decoder ?? unknown
225 0 = Normal
226 1 = Affects video output levels
227
228 bit 16
229 Decoder ?? unknown
230 0 = Normal
231 1 = Disable horizontal filter
232
233--------------------------------------------------------------------------------
2342878
235 bit 0
236 ?? unknown
237
238 bit 1
239 osd on/off
240 0 = osd off
241 1 = osd on
242
243 bit 2
244 Decoder + osd video timing
245 0 = NTSC
246 1 = PAL
247
248 bits 3:4
249 ?? unknown
250
251 bit 5
252 Decoder + osd
253 Swaps upper & lower fields
254
255--------------------------------------------------------------------------------
256287C
257 bits 0:10
258 Decoder & osd ?? unknown
259 Moves entire screen horizontally. Starts at 0x005 with the screen
260 shifted heavily to the right. Incrementing in steps of 0x004 will
261 gradually shift the screen to the left.
262
263 bits 11:31
264 ?? unknown
265
266 Normally contents are 0x00101111 (NTSC) or 0x1010111d (PAL)
267
268--------------------------------------------------------------------------------
2692880 -------- ?? unknown
2702884 -------- ?? unknown
271--------------------------------------------------------------------------------
2722888
273 bit 0
274 Decoder + osd ?? unknown
275 0 = Normal
276 1 = Misaligned fields (Correctable through 289C & 28A4)
277
278 bit 4
279 ?? unknown
280
281 bit 8
282 ?? unknown
283
284 Warning: Bad values will require a firmware reload to recover.
285 Known to be bad are 0x000,0x011,0x100,0x111
286--------------------------------------------------------------------------------
287288C
288 bits 0:15
289 osd ?? unknown
290 Appears to affect the osd position stability. The higher the value the
291 more unstable it becomes. Decoder output remains stable.
292
293 bits 16:31
294 osd ?? unknown
295 Same as bits 0:15
296
297--------------------------------------------------------------------------------
2982890
299 bits 0:11
300 Decoder output horizontal offset.
301
302 Horizontal offset moves the video image right. A small left shift is
303 possible, but it's better to use reg 2870 for that due to its greater
304 range.
305
306 NOTE: Video corruption will occur if video window is shifted off the right
307 edge. To avoid this read the notes for 2834 & 2838.
308--------------------------------------------------------------------------------
3092894
310 bits 0:23
311 Decoder output video surround colour.
312
313 Contains the colour (in yuv) used to fill the screen when the video is
314 running in a window.
315--------------------------------------------------------------------------------
3162898
317 bits 0:23
318 Decoder video window colour
319 Contains the colour (in yuv) used to fill the video window when the
320 video is turned off.
321
322 bit 24
323 Decoder video output
324 0 = Video on
325 1 = Video off
326
327 bit 28
328 Decoder plane order
329 0 = Y,UV
330 1 = UV,Y
331
332 bit 29
333 Decoder second plane byte order
334 0 = Normal (UV)
335 1 = Swapped (VU)
336
337 In normal usage, the first plane is Y & the second plane is UV. Though the
338 order of the planes can be swapped, only the byte order of the second plane
339 can be swapped. This isn't much use for the Y plane, but can be useful for
340 the UV plane.
341
342--------------------------------------------------------------------------------
343289C
344 bits 0:15
345 Decoder vertical field offset 1
346
347 bits 16:31
348 Decoder vertical field offset 2
349
350 Controls field output vertical alignment. The higher the number, the lower
351 the image on screen. Known starting values are 0x011E0017 (NTSC) &
352 0x01500017 (PAL)
353--------------------------------------------------------------------------------
35428A0
355 bits 0:15
356 Decoder & osd width in pixels
357
358 bits 16:31
359 Decoder & osd height in pixels
360
361 All output from the decoder & osd are disabled beyond this area. Decoder
362 output will simply go black outside of this region. If the osd tries to
363 exceed this area it will become corrupt.
364--------------------------------------------------------------------------------
36528A4
366 bits 0:11
367 osd left shift.
368
369 Has a range of 0x770->0x7FF. With the exception of 0, any value outside of
370 this range corrupts the osd.
371--------------------------------------------------------------------------------
37228A8
373 bits 0:15
374 osd vertical field offset 1
375
376 bits 16:31
377 osd vertical field offset 2
378
379 Controls field output vertical alignment. The higher the number, the lower
380 the image on screen. Known starting values are 0x011E0017 (NTSC) &
381 0x01500017 (PAL)
382--------------------------------------------------------------------------------
38328AC -------- ?? unknown
384 |
385 V
38628BC -------- ?? unknown
387--------------------------------------------------------------------------------
38828C0
389 bit 0
390 Current output field
391 0 = first field
392 1 = second field
393
394 bits 16:31
395 Current scanline
396 The scanline counts from the top line of the first field
397 through to the last line of the second field.
398--------------------------------------------------------------------------------
39928C4 -------- ?? unknown
400 |
401 V
40228F8 -------- ?? unknown
403--------------------------------------------------------------------------------
40428FC
405 bit 0
406 ?? unknown
407 0 = Normal
408 1 = Breaks decoder & osd output
409--------------------------------------------------------------------------------
4102900
411 bits 0:31
412 Decoder vertical Y alias register 1
413---------------
4142904
415 bits 0:31
416 Decoder vertical Y alias register 2
417---------------
4182908
419 bits 0:31
420 Decoder vertical Y alias trigger
421
422 These three registers control the vertical aliasing filter for the Y plane.
423 Operation is similar to the horizontal Y filter (2804). The only real
424 difference is that there are only two registers to set before accessing
425 the trigger register (2908). As for the horizontal filter, the values are
426 taken from a lookup table in the firmware, and the procedure must be
427 repeated 16 times to fully program the filter.
428--------------------------------------------------------------------------------
429290C
430 bits 0:31
431 Decoder vertical UV alias register 1
432---------------
4332910
434 bits 0:31
435 Decoder vertical UV alias register 2
436---------------
4372914
438 bits 0:31
439 Decoder vertical UV alias trigger
440
441 These three registers control the vertical aliasing filter for the UV
442 plane. Operation is the same as the Y filter, with 2914 being the trigger.
443--------------------------------------------------------------------------------
4442918
445 bits 0:15
446 Decoder Y source height in pixels
447
448 bits 16:31
449 Decoder Y destination height in pixels
450---------------
451291C
452 bits 0:15
453 Decoder UV source height in pixels divided by 2
454
455 bits 16:31
456 Decoder UV destination height in pixels
457
458 NOTE: For both registers, the resulting image must be fully visible on
459 screen. If the image exceeds the bottom edge both the source and
460 destination size must be adjusted to reflect the visible portion. For the
461 source height, you must take into account the scaling when calculating the
462 new value.
463--------------------------------------------------------------------------------
4642920
465 bits 0:31
466 Decoder Y vertical scaling
467 Normally = Reg 2930 >> 2
468---------------
4692924
470 bits 0:31
471 Decoder Y vertical scaling
472 Normally = Reg 2920 + 0x514
473---------------
4742928
475 bits 0:31
476 Decoder UV vertical scaling
477 When enlarging = Reg 2930 >> 2
478 When reducing = Reg 2930 >> 3
479---------------
480292C
481 bits 0:31
482 Decoder UV vertical scaling
483 Normally = Reg 2928 + 0x514
484---------------
4852930
486 bits 0:31
487 Decoder 'master' value for vertical scaling
488---------------
4892934
490 bits 0:31
491 Decoder ?? unknown - Y vertical scaling
492---------------
4932938
494 bits 0:31
495 Decoder Y vertical scaling
496 Normally = Reg 2930
497---------------
498293C
499 bits 0:31
500 Decoder ?? unknown - Y vertical scaling
501---------------
5022940
503 bits 0:31
504 Decoder UV vertical scaling
505 When enlarging = Reg 2930 >> 1
506 When reducing = Reg 2930
507---------------
5082944
509 bits 0:31
510 Decoder ?? unknown - UV vertical scaling
511---------------
5122948
513 bits 0:31
514 Decoder UV vertical scaling
515 Normally = Reg 2940
516---------------
517294C
518 bits 0:31
519 Decoder ?? unknown - UV vertical scaling
520
521 Most of these registers either control vertical scaling, or appear linked
522 to it in some way. Register 2930 contains the 'master' value & all other
523 registers can be calculated from that one. You must also remember to
524 correctly set the divider in Reg 296C
525
526 To enlarge:
527 Reg 2930 = (source_height * 0x00200000) / destination_height
528 Reg 296C = No divide
529
530 To reduce from full size down to half size:
531 Reg 2930 = (source_height/2 * 0x00200000) / destination height
532 Reg 296C = Divide by 2
533
534 To reduce from half down to quarter.
535 Reg 2930 = (source_height/4 * 0x00200000) / destination height
536 Reg 296C = Divide by 4
537
538--------------------------------------------------------------------------------
5392950
540 bits 0:15
541 Decoder Y line index into display buffer, first field
542
543 bits 16:31
544 Decoder Y vertical line skip, first field
545--------------------------------------------------------------------------------
5462954
547 bits 0:15
548 Decoder Y line index into display buffer, second field
549
550 bits 16:31
551 Decoder Y vertical line skip, second field
552--------------------------------------------------------------------------------
5532958
554 bits 0:15
555 Decoder UV line index into display buffer, first field
556
557 bits 16:31
558 Decoder UV vertical line skip, first field
559--------------------------------------------------------------------------------
560295C
561 bits 0:15
562 Decoder UV line index into display buffer, second field
563
564 bits 16:31
565 Decoder UV vertical line skip, second field
566--------------------------------------------------------------------------------
5672960
568 bits 0:15
569 Decoder destination height minus 1
570
571 bits 16:31
572 Decoder destination height divided by 2
573--------------------------------------------------------------------------------
5742964
575 bits 0:15
576 Decoder Y vertical offset, second field
577
578 bits 16:31
579 Decoder Y vertical offset, first field
580
581 These two registers shift the Y plane up. The higher the number, the
582 greater the shift.
583--------------------------------------------------------------------------------
5842968
585 bits 0:15
586 Decoder UV vertical offset, second field
587
588 bits 16:31
589 Decoder UV vertical offset, first field
590
591 These two registers shift the UV plane up. The higher the number, the
592 greater the shift.
593--------------------------------------------------------------------------------
594296C
595 bits 0:1
596 Decoder vertical Y output size divider
597 00 = No divide
598 01 = Divide by 2
599 10 = Divide by 4
600
601 bits 8:9
602 Decoder vertical UV output size divider
603 00 = No divide
604 01 = Divide by 2
605 10 = Divide by 4
606--------------------------------------------------------------------------------
6072970
608 bit 0
609 Decoder ?? unknown
610 0 = Normal
611 1 = Affect video output levels
612
613 bit 16
614 Decoder ?? unknown
615 0 = Normal
616 1 = Disable vertical filter
617
618--------------------------------------------------------------------------------
6192974 -------- ?? unknown
620 |
621 V
62229EF -------- ?? unknown
623--------------------------------------------------------------------------------
6242A00
625 bits 0:2
626 osd colour mode
627 000 = 8 bit indexed
628 001 = 16 bit (565)
629 010 = 15 bit (555)
630 011 = 12 bit (444)
631 100 = 32 bit (8888)
632
633 bits 4:5
634 osd display bpp
635 01 = 8 bit
636 10 = 16 bit
637 11 = 32 bit
638
639 bit 8
640 osd global alpha
641 0 = Off
642 1 = On
643
644 bit 9
645 osd local alpha
646 0 = Off
647 1 = On
648
649 bit 10
650 osd colour key
651 0 = Off
652 1 = On
653
654 bit 11
655 osd ?? unknown
656 Must be 1
657
658 bit 13
659 osd colour space
660 0 = ARGB
661 1 = AYVU
662
663 bits 16:31
664 osd ?? unknown
665 Must be 0x001B (some kind of buffer pointer ?)
666
667 When the bits-per-pixel is set to 8, the colour mode is ignored and
668 assumed to be 8 bit indexed. For 16 & 32 bits-per-pixel the colour depth
669 is honoured, and when using a colour depth that requires fewer bytes than
670 allocated the extra bytes are used as padding. So for a 32 bpp with 8 bit
671 index colour, there are 3 padding bytes per pixel. It's also possible to
672 select 16bpp with a 32 bit colour mode. This results in the pixel width
673 being doubled, but the color key will not work as expected in this mode.
674
675 Colour key is as it suggests. You designate a colour which will become
676 completely transparent. When using 565, 555 or 444 colour modes, the
677 colour key is always 16 bits wide. The colour to key on is set in Reg 2A18.
678
679 Local alpha works differently depending on the colour mode. For 32bpp & 8
680 bit indexed, local alpha is a per-pixel 256 step transparency, with 0 being
681 transparent and 255 being solid. For the 16bpp modes 555 & 444, the unused
682 bit(s) act as a simple transparency switch, with 0 being solid & 1 being
683 fully transparent. There is no local alpha support for 16bit 565.
684
685 Global alpha is a 256 step transparency that applies to the entire osd,
686 with 0 being transparent & 255 being solid.
687
688 It's possible to combine colour key, local alpha & global alpha.
689--------------------------------------------------------------------------------
6902A04
691 bits 0:15
692 osd x coord for left edge
693
694 bits 16:31
695 osd y coord for top edge
696---------------
6972A08
698 bits 0:15
699 osd x coord for right edge
700
701 bits 16:31
702 osd y coord for bottom edge
703
704 For both registers, (0,0) = top left corner of the display area. These
705 registers do not control the osd size, only where it's positioned & how
706 much is visible. The visible osd area cannot exceed the right edge of the
707 display, otherwise the osd will become corrupt. See reg 2A10 for
708 setting osd width.
709--------------------------------------------------------------------------------
7102A0C
711 bits 0:31
712 osd buffer index
713
714 An index into the osd buffer. Slowly incrementing this moves the osd left,
715 wrapping around onto the right edge
716--------------------------------------------------------------------------------
7172A10
718 bits 0:11
719 osd buffer 32 bit word width
720
721 Contains the width of the osd measured in 32 bit words. This means that all
722 colour modes are restricted to a byte width which is divisible by 4.
723--------------------------------------------------------------------------------
7242A14
725 bits 0:15
726 osd height in pixels
727
728 bits 16:32
729 osd line index into buffer
730 osd will start displaying from this line.
731--------------------------------------------------------------------------------
7322A18
733 bits 0:31
734 osd colour key
735
736 Contains the colour value which will be transparent.
737--------------------------------------------------------------------------------
7382A1C
739 bits 0:7
740 osd global alpha
741
742 Contains the global alpha value (equiv ivtvfbctl --alpha XX)
743--------------------------------------------------------------------------------
7442A20 -------- ?? unknown
745 |
746 V
7472A2C -------- ?? unknown
748--------------------------------------------------------------------------------
7492A30
750 bits 0:7
751 osd colour to change in indexed palette
752---------------
7532A34
754 bits 0:31
755 osd colour for indexed palette
756
757 To set the new palette, first load the index of the colour to change into
758 2A30, then load the new colour into 2A34. The full palette is 256 colours,
759 so the index range is 0x00-0xFF
760--------------------------------------------------------------------------------
7612A38 -------- ?? unknown
7622A3C -------- ?? unknown
763--------------------------------------------------------------------------------
7642A40
765 bits 0:31
766 osd ?? unknown
767
768 Affects overall brightness, wrapping around to black
769--------------------------------------------------------------------------------
7702A44
771 bits 0:31
772 osd ?? unknown
773
774 Green tint
775--------------------------------------------------------------------------------
7762A48
777 bits 0:31
778 osd ?? unknown
779
780 Red tint
781--------------------------------------------------------------------------------
7822A4C
783 bits 0:31
784 osd ?? unknown
785
786 Affects overall brightness, wrapping around to black
787--------------------------------------------------------------------------------
7882A50
789 bits 0:31
790 osd ?? unknown
791
792 Colour shift
793--------------------------------------------------------------------------------
7942A54
795 bits 0:31
796 osd ?? unknown
797
798 Colour shift
799--------------------------------------------------------------------------------
8002A58 -------- ?? unknown
801 |
802 V
8032AFC -------- ?? unknown
804--------------------------------------------------------------------------------
8052B00
806 bit 0
807 osd filter control
808 0 = filter off
809 1 = filter on
810
811 bits 1:4
812 osd ?? unknown
813
814--------------------------------------------------------------------------------
815
816v0.4 - 12 March 2007 - Ian Armstrong (ian@iarmst.demon.co.uk)
817
diff --git a/Documentation/video4linux/cx2341x/fw-dma.txt b/Documentation/video4linux/cx2341x/fw-dma.txt
index 8123e262d5b6..be52b6fd1e9a 100644
--- a/Documentation/video4linux/cx2341x/fw-dma.txt
+++ b/Documentation/video4linux/cx2341x/fw-dma.txt
@@ -22,6 +22,8 @@ urged to choose a smaller block size and learn the scatter-gather technique.
22 22
23Mailbox #10 is reserved for DMA transfer information. 23Mailbox #10 is reserved for DMA transfer information.
24 24
25Note: the hardware expects little-endian data ('intel format').
26
25Flow 27Flow
26==== 28====
27 29
@@ -64,7 +66,7 @@ addresses are the physical memory location of the target DMA buffer.
64 66
65Each S-G array element is a struct of three 32-bit words. The first word is 67Each S-G array element is a struct of three 32-bit words. The first word is
66the source address, the second is the destination address. Both take up the 68the source address, the second is the destination address. Both take up the
67entire 32 bits. The lowest 16 bits of the third word is the transfer byte 69entire 32 bits. The lowest 18 bits of the third word is the transfer byte
68count. The high-bit of the third word is the "last" flag. The last-flag tells 70count. The high-bit of the third word is the "last" flag. The last-flag tells
69the card to raise the DMA_DONE interrupt. From hard personal experience, if 71the card to raise the DMA_DONE interrupt. From hard personal experience, if
70you forget to set this bit, the card will still "work" but the stream will 72you forget to set this bit, the card will still "work" but the stream will
@@ -78,8 +80,8 @@ Array Element:
78 80
79- 32-bit Source Address 81- 32-bit Source Address
80- 32-bit Destination Address 82- 32-bit Destination Address
81- 16-bit reserved (high bit is the last flag) 83- 14-bit reserved (high bit is the last flag)
82- 16-bit byte count 84- 18-bit byte count
83 85
84DMA Transfer Status 86DMA Transfer Status
85=================== 87===================
@@ -87,8 +89,8 @@ DMA Transfer Status
87Register 0x0004 holds the DMA Transfer Status: 89Register 0x0004 holds the DMA Transfer Status:
88 90
89Bit 91Bit
904 Scatter-Gather array error
913 DMA write error
922 DMA read error
931 write completed
940 read completed 920 read completed
931 write completed
942 DMA read error
953 DMA write error
964 Scatter-Gather array error
diff --git a/Documentation/video4linux/cx2341x/fw-encoder-api.txt b/Documentation/video4linux/cx2341x/fw-encoder-api.txt
index 15df0df57ddd..5dd3109a8b3f 100644
--- a/Documentation/video4linux/cx2341x/fw-encoder-api.txt
+++ b/Documentation/video4linux/cx2341x/fw-encoder-api.txt
@@ -213,16 +213,6 @@ Param[1]
213 213
214------------------------------------------------------------------------------- 214-------------------------------------------------------------------------------
215 215
216Name CX2341X_ENC_SET_3_2_PULLDOWN
217Enum 177/0xB1
218Description
219 3:2 pulldown properties
220Param[0]
221 0=enabled
222 1=disabled
223
224-------------------------------------------------------------------------------
225
226Name CX2341X_ENC_SET_VBI_LINE 216Name CX2341X_ENC_SET_VBI_LINE
227Enum 183/0xB7 217Enum 183/0xB7
228Description 218Description
@@ -332,9 +322,7 @@ Param[0]
332 '01'=JointStereo 322 '01'=JointStereo
333 '10'=Dual 323 '10'=Dual
334 '11'=Mono 324 '11'=Mono
335 Note: testing seems to indicate that Mono and possibly 325 Note: the cx23415 cannot decode Joint Stereo properly.
336 JointStereo are not working (default to stereo).
337 Dual does work, though.
338 326
339 10:11 Mode Extension used in joint_stereo mode. 327 10:11 Mode Extension used in joint_stereo mode.
340 In Layer I and II they indicate which subbands are in 328 In Layer I and II they indicate which subbands are in
@@ -413,16 +401,34 @@ Name CX2341X_ENC_SET_PGM_INDEX_INFO
413Enum 199/0xC7 401Enum 199/0xC7
414Description 402Description
415 Sets the Program Index Information. 403 Sets the Program Index Information.
404 The information is stored as follows:
405
406 struct info {
407 u32 length; // Length of this frame
408 u32 offset_low; // Offset in the file of the
409 u32 offset_high; // start of this frame
410 u32 mask1; // Bits 0-1 are the type mask:
411 // 1=I, 2=P, 4=B
412 u32 pts; // The PTS of the frame
413 u32 mask2; // Bit 0 is bit 32 of the pts.
414 };
415 u32 table_ptr;
416 struct info index[400];
417
418 The table_ptr is the encoder memory address in the table were
419 *new* entries will be written. Note that this is a ringbuffer,
420 so the table_ptr will wraparound.
416Param[0] 421Param[0]
417 Picture Mask: 422 Picture Mask:
418 0=No index capture 423 0=No index capture
419 1=I frames 424 1=I frames
420 3=I,P frames 425 3=I,P frames
421 7=I,P,B frames 426 7=I,P,B frames
427 (Seems to be ignored, it always indexes I, P and B frames)
422Param[1] 428Param[1]
423 Elements requested (up to 400) 429 Elements requested (up to 400)
424Result[0] 430Result[0]
425 Offset in SDF memory of the table. 431 Offset in the encoder memory of the start of the table.
426Result[1] 432Result[1]
427 Number of allocated elements up to a maximum of Param[1] 433 Number of allocated elements up to a maximum of Param[1]
428 434
@@ -492,12 +498,14 @@ Name CX2341X_ENC_GET_PREV_DMA_INFO_MB_9
492Enum 203/0xCB 498Enum 203/0xCB
493Description 499Description
494 Returns information on the previous DMA transfer in conjunction with 500 Returns information on the previous DMA transfer in conjunction with
495 bit 27 of the interrupt mask. Uses mailbox 9. 501 bit 27 or 18 of the interrupt mask. Uses mailbox 9.
496Result[0] 502Result[0]
497 Status bits: 503 Status bits:
498 Bit 0 set indicates transfer complete 504 0 read completed
499 Bit 2 set indicates transfer error 505 1 write completed
500 Bit 4 set indicates linked list error 506 2 DMA read error
507 3 DMA write error
508 4 Scatter-Gather array error
501Result[1] 509Result[1]
502 DMA type 510 DMA type
503Result[2] 511Result[2]
@@ -655,12 +663,13 @@ Param[0]
655 663
656------------------------------------------------------------------------------- 664-------------------------------------------------------------------------------
657 665
658Name CX2341X_ENC_UNKNOWN 666Name CX2341X_ENC_SET_VERT_CROP_LINE
659Enum 219/0xDB 667Enum 219/0xDB
660Description 668Description
661 Unknown API, it's used by Hauppauge though. 669 Something to do with 'Vertical Crop Line'
662Param[0] 670Param[0]
663 0 This is the value Hauppauge uses, Unknown what it means. 671 If saa7114 and raw VBI capture and 60 Hz, then set to 10001.
672 Else 0.
664 673
665------------------------------------------------------------------------------- 674-------------------------------------------------------------------------------
666 675
@@ -672,21 +681,25 @@ Description
672 the value. 681 the value.
673Param[0] 682Param[0]
674 Command number: 683 Command number:
675 1=set initial SCR value when starting encoding. 684 1=set initial SCR value when starting encoding (works).
676 2=set quality mode (apparently some test setting). 685 2=set quality mode (apparently some test setting).
677 3=setup advanced VIM protection handling (supposedly only for the cx23416 686 3=setup advanced VIM protection handling.
678 for raw YUV). 687 Always 1 for the cx23416 and 0 for cx23415.
679 Actually it looks like this should be 0 for saa7114/5 based card and 1 688 4=generate DVD compatible PTS timestamps
680 for cx25840 based cards.
681 4=generate artificial PTS timestamps
682 5=USB flush mode 689 5=USB flush mode
683 6=something to do with the quantization matrix 690 6=something to do with the quantization matrix
684 7=set navigation pack insertion for DVD 691 7=set navigation pack insertion for DVD: adds 0xbf (private stream 2)
692 packets to the MPEG. The size of these packets is 2048 bytes (including
693 the header of 6 bytes: 0x000001bf + length). The payload is zeroed and
694 it is up to the application to fill them in. These packets are apparently
695 inserted every four frames.
685 8=enable scene change detection (seems to be a failure) 696 8=enable scene change detection (seems to be a failure)
686 9=set history parameters of the video input module 697 9=set history parameters of the video input module
687 10=set input field order of VIM 698 10=set input field order of VIM
688 11=set quantization matrix 699 11=set quantization matrix
689 12=reset audio interface 700 12=reset audio interface after channel change or input switch (has no argument).
701 Needed for the cx2584x, not needed for the mspx4xx, but it doesn't seem to
702 do any harm calling it regardless.
690 13=set audio volume delay 703 13=set audio volume delay
691 14=set audio delay 704 14=set audio delay
692 705
diff --git a/Documentation/video4linux/cx2341x/fw-memory.txt b/Documentation/video4linux/cx2341x/fw-memory.txt
index ef0aad3f88fc..9d736fe8de66 100644
--- a/Documentation/video4linux/cx2341x/fw-memory.txt
+++ b/Documentation/video4linux/cx2341x/fw-memory.txt
@@ -1,6 +1,8 @@
1This document describes the cx2341x memory map and documents some of the register 1This document describes the cx2341x memory map and documents some of the register
2space. 2space.
3 3
4Note: the memory long words are little-endian ('intel format').
5
4Warning! This information was figured out from searching through the memory and 6Warning! This information was figured out from searching through the memory and
5registers, this information may not be correct and is certainly not complete, and 7registers, this information may not be correct and is certainly not complete, and
6was not derived from anything more than searching through the memory space with 8was not derived from anything more than searching through the memory space with
@@ -67,7 +69,7 @@ DMA Registers 0x000-0xff:
67 0x84 - first write linked list reg, for pci memory addr 69 0x84 - first write linked list reg, for pci memory addr
68 0x88 - first write linked list reg, for length of buffer in memory addr 70 0x88 - first write linked list reg, for length of buffer in memory addr
69 (|0x80000000 or this for last link) 71 (|0x80000000 or this for last link)
70 0x8c-0xcc - rest of write linked list reg, 8 sets of 3 total, DMA goes here 72 0x8c-0xdc - rest of write linked list reg, 8 sets of 3 total, DMA goes here
71 from linked list addr in reg 0x0c, firmware must push through or 73 from linked list addr in reg 0x0c, firmware must push through or
72 something. 74 something.
73 0xe0 - first (and only) read linked list reg, for pci memory addr 75 0xe0 - first (and only) read linked list reg, for pci memory addr
@@ -123,12 +125,8 @@ Bit
12329 Encoder VBI capture 12529 Encoder VBI capture
12428 Encoder Video Input Module reset event 12628 Encoder Video Input Module reset event
12527 Encoder DMA complete 12727 Encoder DMA complete
12626 12824 Decoder audio mode change detection event (through event notification)
12725 Decoder copy protect detection event
12824 Decoder audio mode change detection event
12923
13022 Decoder data request 12922 Decoder data request
13121 Decoder I-Frame? done
13220 Decoder DMA complete 13020 Decoder DMA complete
13319 Decoder VBI re-insertion 13119 Decoder VBI re-insertion
13418 Decoder DMA err (linked-list bad) 13218 Decoder DMA err (linked-list bad)
diff --git a/Documentation/video4linux/cx2341x/fw-osd-api.txt b/Documentation/video4linux/cx2341x/fw-osd-api.txt
index 0a602f3e601b..89c4601042c1 100644
--- a/Documentation/video4linux/cx2341x/fw-osd-api.txt
+++ b/Documentation/video4linux/cx2341x/fw-osd-api.txt
@@ -21,7 +21,11 @@ Enum 66/0x42
21Description 21Description
22 Query OSD format 22 Query OSD format
23Result[0] 23Result[0]
24 0=8bit index, 4=AlphaRGB 8:8:8:8 24 0=8bit index
25 1=16bit RGB 5:6:5
26 2=16bit ARGB 1:5:5:5
27 3=16bit ARGB 1:4:4:4
28 4=32bit ARGB 8:8:8:8
25 29
26------------------------------------------------------------------------------- 30-------------------------------------------------------------------------------
27 31
@@ -30,7 +34,11 @@ Enum 67/0x43
30Description 34Description
31 Assign pixel format 35 Assign pixel format
32Param[0] 36Param[0]
33 0=8bit index, 4=AlphaRGB 8:8:8:8 37 0=8bit index
38 1=16bit RGB 5:6:5
39 2=16bit ARGB 1:5:5:5
40 3=16bit ARGB 1:4:4:4
41 4=32bit ARGB 8:8:8:8
34 42
35------------------------------------------------------------------------------- 43-------------------------------------------------------------------------------
36 44
diff --git a/Documentation/video4linux/et61x251.txt b/Documentation/video4linux/et61x251.txt
index 1bdee8f85b9a..1247566c4de3 100644
--- a/Documentation/video4linux/et61x251.txt
+++ b/Documentation/video4linux/et61x251.txt
@@ -23,7 +23,7 @@ Index
23 23
241. Copyright 241. Copyright
25============ 25============
26Copyright (C) 2006 by Luca Risolia <luca.risolia@studio.unibo.it> 26Copyright (C) 2006-2007 by Luca Risolia <luca.risolia@studio.unibo.it>
27 27
28 28
292. Disclaimer 292. Disclaimer
@@ -135,8 +135,9 @@ And finally:
1356. Module loading 1356. Module loading
136================= 136=================
137To use the driver, it is necessary to load the "et61x251" module into memory 137To use the driver, it is necessary to load the "et61x251" module into memory
138after every other module required: "videodev", "usbcore" and, depending on 138after every other module required: "videodev", "v4l2_common", "compat_ioctl32",
139the USB host controller you have, "ehci-hcd", "uhci-hcd" or "ohci-hcd". 139"usbcore" and, depending on the USB host controller you have, "ehci-hcd",
140"uhci-hcd" or "ohci-hcd".
140 141
141Loading can be done as shown below: 142Loading can be done as shown below:
142 143
diff --git a/Documentation/video4linux/meye.txt b/Documentation/video4linux/meye.txt
index ecb34160e61d..5e51c59bf2b0 100644
--- a/Documentation/video4linux/meye.txt
+++ b/Documentation/video4linux/meye.txt
@@ -5,10 +5,9 @@ Vaio Picturebook Motion Eye Camera Driver Readme
5 Copyright (C) 2000 Andrew Tridgell <tridge@samba.org> 5 Copyright (C) 2000 Andrew Tridgell <tridge@samba.org>
6 6
7This driver enable the use of video4linux compatible applications with the 7This driver enable the use of video4linux compatible applications with the
8Motion Eye camera. This driver requires the "Sony Vaio Programmable I/O 8Motion Eye camera. This driver requires the "Sony Laptop Extras" driver (which
9Control Device" driver (which can be found in the "Character drivers" 9can be found in the "Misc devices" section of the kernel configuration utility)
10section of the kernel configuration utility) to be compiled and installed 10to be compiled and installed (using its "camera=1" parameter).
11(using its "camera=1" parameter).
12 11
13It can do at maximum 30 fps @ 320x240 or 15 fps @ 640x480. 12It can do at maximum 30 fps @ 320x240 or 15 fps @ 640x480.
14 13
diff --git a/Documentation/video4linux/sn9c102.txt b/Documentation/video4linux/sn9c102.txt
index 8cda472db36d..5fe0ad7dfc20 100644
--- a/Documentation/video4linux/sn9c102.txt
+++ b/Documentation/video4linux/sn9c102.txt
@@ -1,5 +1,5 @@
1 1
2 SN9C10x PC Camera Controllers 2 SN9C1xx PC Camera Controllers
3 Driver for Linux 3 Driver for Linux
4 ============================= 4 =============================
5 5
@@ -25,7 +25,7 @@ Index
25 25
261. Copyright 261. Copyright
27============ 27============
28Copyright (C) 2004-2006 by Luca Risolia <luca.risolia@studio.unibo.it> 28Copyright (C) 2004-2007 by Luca Risolia <luca.risolia@studio.unibo.it>
29 29
30 30
312. Disclaimer 312. Disclaimer
@@ -53,20 +53,14 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
53 53
544. Overview and features 544. Overview and features
55======================== 55========================
56This driver attempts to support the video interface of the devices mounting the 56This driver attempts to support the video interface of the devices assembling
57SONiX SN9C101, SN9C102 and SN9C103 PC Camera Controllers. 57the SONiX SN9C101, SN9C102, SN9C103, SN9C105 and SN9C120 PC Camera Controllers
58 58("SN9C1xx" from now on).
59It's worth to note that SONiX has never collaborated with the author during the
60development of this project, despite several requests for enough detailed
61specifications of the register tables, compression engine and video data format
62of the above chips. Nevertheless, these informations are no longer necessary,
63because all the aspects related to these chips are known and have been
64described in detail in this documentation.
65 59
66The driver relies on the Video4Linux2 and USB core modules. It has been 60The driver relies on the Video4Linux2 and USB core modules. It has been
67designed to run properly on SMP systems as well. 61designed to run properly on SMP systems as well.
68 62
69The latest version of the SN9C10x driver can be found at the following URL: 63The latest version of the SN9C1xx driver can be found at the following URL:
70http://www.linux-projects.org/ 64http://www.linux-projects.org/
71 65
72Some of the features of the driver are: 66Some of the features of the driver are:
@@ -85,11 +79,11 @@ Some of the features of the driver are:
85 high compression quality (see also "Notes for V4L2 application developers" 79 high compression quality (see also "Notes for V4L2 application developers"
86 and "Video frame formats" paragraphs); 80 and "Video frame formats" paragraphs);
87- full support for the capabilities of many of the possible image sensors that 81- full support for the capabilities of many of the possible image sensors that
88 can be connected to the SN9C10x bridges, including, for instance, red, green, 82 can be connected to the SN9C1xx bridges, including, for instance, red, green,
89 blue and global gain adjustments and exposure (see "Supported devices" 83 blue and global gain adjustments and exposure (see "Supported devices"
90 paragraph for details); 84 paragraph for details);
91- use of default color settings for sunlight conditions; 85- use of default color settings for sunlight conditions;
92- dynamic I/O interface for both SN9C10x and image sensor control and 86- dynamic I/O interface for both SN9C1xx and image sensor control and
93 monitoring (see "Optional device control through 'sysfs'" paragraph); 87 monitoring (see "Optional device control through 'sysfs'" paragraph);
94- dynamic driver control thanks to various module parameters (see "Module 88- dynamic driver control thanks to various module parameters (see "Module
95 parameters" paragraph); 89 parameters" paragraph);
@@ -130,8 +124,8 @@ necessary:
130 CONFIG_USB_UHCI_HCD=m 124 CONFIG_USB_UHCI_HCD=m
131 CONFIG_USB_OHCI_HCD=m 125 CONFIG_USB_OHCI_HCD=m
132 126
133The SN9C103 controller also provides a built-in microphone interface. It is 127The SN9C103, SN9c105 and SN9C120 controllers also provide a built-in microphone
134supported by the USB Audio driver thanks to the ALSA API: 128interface. It is supported by the USB Audio driver thanks to the ALSA API:
135 129
136 # Sound 130 # Sound
137 # 131 #
@@ -155,18 +149,27 @@ And finally:
1556. Module loading 1496. Module loading
156================= 150=================
157To use the driver, it is necessary to load the "sn9c102" module into memory 151To use the driver, it is necessary to load the "sn9c102" module into memory
158after every other module required: "videodev", "usbcore" and, depending on 152after every other module required: "videodev", "v4l2_common", "compat_ioctl32",
159the USB host controller you have, "ehci-hcd", "uhci-hcd" or "ohci-hcd". 153"usbcore" and, depending on the USB host controller you have, "ehci-hcd",
154"uhci-hcd" or "ohci-hcd".
160 155
161Loading can be done as shown below: 156Loading can be done as shown below:
162 157
163 [root@localhost home]# modprobe sn9c102 158 [root@localhost home]# modprobe sn9c102
164 159
165At this point the devices should be recognized. You can invoke "dmesg" to 160Note that the module is called "sn9c102" for historic reasons, althought it
166analyze kernel messages and verify that the loading process has gone well: 161does not just support the SN9C102.
162
163At this point all the devices supported by the driver and connected to the USB
164ports should be recognized. You can invoke "dmesg" to analyze kernel messages
165and verify that the loading process has gone well:
167 166
168 [user@localhost home]$ dmesg 167 [user@localhost home]$ dmesg
169 168
169or, to isolate all the kernel messages generated by the driver:
170
171 [user@localhost home]$ dmesg | grep sn9c102
172
170 173
1717. Module parameters 1747. Module parameters
172==================== 175====================
@@ -198,10 +201,11 @@ Default: 0
198------------------------------------------------------------------------------- 201-------------------------------------------------------------------------------
199Name: frame_timeout 202Name: frame_timeout
200Type: uint array (min = 0, max = 64) 203Type: uint array (min = 0, max = 64)
201Syntax: <n[,...]> 204Syntax: <0|n[,...]>
202Description: Timeout for a video frame in seconds. This parameter is 205Description: Timeout for a video frame in seconds before returning an I/O
203 specific for each detected camera. This parameter can be 206 error; 0 for infinity. This parameter is specific for each
204 changed at runtime thanks to the /sys filesystem interface. 207 detected camera and can be changed at runtime thanks to the
208 /sys filesystem interface.
205Default: 2 209Default: 2
206------------------------------------------------------------------------------- 210-------------------------------------------------------------------------------
207Name: debug 211Name: debug
@@ -212,10 +216,10 @@ Description: Debugging information level, from 0 to 3:
212 1 = critical errors 216 1 = critical errors
213 2 = significant informations 217 2 = significant informations
214 3 = more verbose messages 218 3 = more verbose messages
215 Level 3 is useful for testing only, when only one device 219 Level 3 is useful for testing only. It also shows some more
216 is used. It also shows some more informations about the 220 informations about the hardware being detected.
217 hardware being detected. This parameter can be changed at 221 This parameter can be changed at runtime thanks to the /sys
218 runtime thanks to the /sys filesystem interface. 222 filesystem interface.
219Default: 2 223Default: 2
220------------------------------------------------------------------------------- 224-------------------------------------------------------------------------------
221 225
@@ -223,20 +227,21 @@ Default: 2
2238. Optional device control through "sysfs" [1] 2278. Optional device control through "sysfs" [1]
224========================================== 228==========================================
225If the kernel has been compiled with the CONFIG_VIDEO_ADV_DEBUG option enabled, 229If the kernel has been compiled with the CONFIG_VIDEO_ADV_DEBUG option enabled,
226it is possible to read and write both the SN9C10x and the image sensor 230it is possible to read and write both the SN9C1xx and the image sensor
227registers by using the "sysfs" filesystem interface. 231registers by using the "sysfs" filesystem interface.
228 232
229Every time a supported device is recognized, a write-only file named "green" is 233Every time a supported device is recognized, a write-only file named "green" is
230created in the /sys/class/video4linux/videoX directory. You can set the green 234created in the /sys/class/video4linux/videoX directory. You can set the green
231channel's gain by writing the desired value to it. The value may range from 0 235channel's gain by writing the desired value to it. The value may range from 0
232to 15 for SN9C101 or SN9C102 bridges, from 0 to 127 for SN9C103 bridges. 236to 15 for the SN9C101 or SN9C102 bridges, from 0 to 127 for the SN9C103,
233Similarly, only for SN9C103 controllers, blue and red gain control files are 237SN9C105 and SN9C120 bridges.
234available in the same directory, for which accepted values may range from 0 to 238Similarly, only for the SN9C103, SN9C105 and SN9C120 controllers, blue and red
235127. 239gain control files are available in the same directory, for which accepted
240values may range from 0 to 127.
236 241
237There are other four entries in the directory above for each registered camera: 242There are other four entries in the directory above for each registered camera:
238"reg", "val", "i2c_reg" and "i2c_val". The first two files control the 243"reg", "val", "i2c_reg" and "i2c_val". The first two files control the
239SN9C10x bridge, while the other two control the sensor chip. "reg" and 244SN9C1xx bridge, while the other two control the sensor chip. "reg" and
240"i2c_reg" hold the values of the current register index where the following 245"i2c_reg" hold the values of the current register index where the following
241reading/writing operations are addressed at through "val" and "i2c_val". Their 246reading/writing operations are addressed at through "val" and "i2c_val". Their
242use is not intended for end-users. Note that "i2c_reg" and "i2c_val" will not 247use is not intended for end-users. Note that "i2c_reg" and "i2c_val" will not
@@ -259,61 +264,84 @@ Now let's set the green gain's register of the SN9C101 or SN9C102 chips to 2:
259 [root@localhost #] echo 0x11 > reg 264 [root@localhost #] echo 0x11 > reg
260 [root@localhost #] echo 2 > val 265 [root@localhost #] echo 2 > val
261 266
262Note that the SN9C10x always returns 0 when some of its registers are read. 267Note that the SN9C1xx always returns 0 when some of its registers are read.
263To avoid race conditions, all the I/O accesses to the above files are 268To avoid race conditions, all the I/O accesses to the above files are
264serialized. 269serialized.
265
266The sysfs interface also provides the "frame_header" entry, which exports the 270The sysfs interface also provides the "frame_header" entry, which exports the
267frame header of the most recent requested and captured video frame. The header 271frame header of the most recent requested and captured video frame. The header
268is always 18-bytes long and is appended to every video frame by the SN9C10x 272is always 18-bytes long and is appended to every video frame by the SN9C1xx
269controllers. As an example, this additional information can be used by the user 273controllers. As an example, this additional information can be used by the user
270application for implementing auto-exposure features via software. 274application for implementing auto-exposure features via software.
271 275
272The following table describes the frame header: 276The following table describes the frame header exported by the SN9C101 and
273 277SN9C102:
274Byte # Value Description 278
275------ ----- ----------- 279Byte # Value or bits Description
2760x00 0xFF Frame synchronisation pattern. 280------ ------------- -----------
2770x01 0xFF Frame synchronisation pattern. 2810x00 0xFF Frame synchronisation pattern
2780x02 0x00 Frame synchronisation pattern. 2820x01 0xFF Frame synchronisation pattern
2790x03 0xC4 Frame synchronisation pattern. 2830x02 0x00 Frame synchronisation pattern
2800x04 0xC4 Frame synchronisation pattern. 2840x03 0xC4 Frame synchronisation pattern
2810x05 0x96 Frame synchronisation pattern. 2850x04 0xC4 Frame synchronisation pattern
2820x06 0xXX Unknown meaning. The exact value depends on the chip; 2860x05 0x96 Frame synchronisation pattern
283 possible values are 0x00, 0x01 and 0x20. 2870x06 [3:0] Read channel gain control = (1+R_GAIN/8)
2840x07 0xXX Variable value, whose bits are ff00uzzc, where ff is a 288 [7:4] Blue channel gain control = (1+B_GAIN/8)
285 frame counter, u is unknown, zz is a size indicator 2890x07 [ 0 ] Compression mode. 0=No compression, 1=Compression enabled
286 (00 = VGA, 01 = SIF, 10 = QSIF) and c stands for 290 [2:1] Maximum scale factor for compression
287 "compression enabled" (1 = yes, 0 = no). 291 [ 3 ] 1 = USB fifo(2K bytes) is full
2880x08 0xXX Brightness sum inside Auto-Exposure area (low-byte). 292 [ 4 ] 1 = Digital gain is finish
2890x09 0xXX Brightness sum inside Auto-Exposure area (high-byte). 293 [ 5 ] 1 = Exposure is finish
290 For a pure white image, this number will be equal to 500 294 [7:6] Frame index
291 times the area of the specified AE area. For images 2950x08 [7:0] Y sum inside Auto-Exposure area (low-byte)
292 that are not pure white, the value scales down according 2960x09 [7:0] Y sum inside Auto-Exposure area (high-byte)
293 to relative whiteness. 297 where Y sum = (R/4 + 5G/16 + B/8) / 32
2940x0A 0xXX Brightness sum outside Auto-Exposure area (low-byte). 2980x0A [7:0] Y sum outside Auto-Exposure area (low-byte)
2950x0B 0xXX Brightness sum outside Auto-Exposure area (high-byte). 2990x0B [7:0] Y sum outside Auto-Exposure area (high-byte)
296 For a pure white image, this number will be equal to 125 300 where Y sum = (R/4 + 5G/16 + B/8) / 128
297 times the area outside of the specified AE area. For 3010x0C 0xXX Not used
298 images that are not pure white, the value scales down 3020x0D 0xXX Not used
299 according to relative whiteness. 3030x0E 0xXX Not used
300 according to relative whiteness. 3040x0F 0xXX Not used
301 3050x10 0xXX Not used
302The following bytes are used by the SN9C103 bridge only: 3060x11 0xXX Not used
303 307
3040x0C 0xXX Unknown meaning 308The following table describes the frame header exported by the SN9C103:
3050x0D 0xXX Unknown meaning 309
3060x0E 0xXX Unknown meaning 310Byte # Value or bits Description
3070x0F 0xXX Unknown meaning 311------ ------------- -----------
3080x10 0xXX Unknown meaning 3120x00 0xFF Frame synchronisation pattern
3090x11 0xXX Unknown meaning 3130x01 0xFF Frame synchronisation pattern
3140x02 0x00 Frame synchronisation pattern
3150x03 0xC4 Frame synchronisation pattern
3160x04 0xC4 Frame synchronisation pattern
3170x05 0x96 Frame synchronisation pattern
3180x06 [6:0] Read channel gain control = (1/2+R_GAIN/64)
3190x07 [6:0] Blue channel gain control = (1/2+B_GAIN/64)
320 [7:4]
3210x08 [ 0 ] Compression mode. 0=No compression, 1=Compression enabled
322 [2:1] Maximum scale factor for compression
323 [ 3 ] 1 = USB fifo(2K bytes) is full
324 [ 4 ] 1 = Digital gain is finish
325 [ 5 ] 1 = Exposure is finish
326 [7:6] Frame index
3270x09 [7:0] Y sum inside Auto-Exposure area (low-byte)
3280x0A [7:0] Y sum inside Auto-Exposure area (high-byte)
329 where Y sum = (R/4 + 5G/16 + B/8) / 32
3300x0B [7:0] Y sum outside Auto-Exposure area (low-byte)
3310x0C [7:0] Y sum outside Auto-Exposure area (high-byte)
332 where Y sum = (R/4 + 5G/16 + B/8) / 128
3330x0D [1:0] Audio frame number
334 [ 2 ] 1 = Audio is recording
3350x0E [7:0] Audio summation (low-byte)
3360x0F [7:0] Audio summation (high-byte)
3370x10 [7:0] Audio sample count
3380x11 [7:0] Audio peak data in audio frame
310 339
311The AE area (sx, sy, ex, ey) in the active window can be set by programming the 340The AE area (sx, sy, ex, ey) in the active window can be set by programming the
312registers 0x1c, 0x1d, 0x1e and 0x1f of the SN9C10x controllers, where one unit 341registers 0x1c, 0x1d, 0x1e and 0x1f of the SN9C1xx controllers, where one unit
313corresponds to 32 pixels. 342corresponds to 32 pixels.
314 343
315[1] Part of the meaning of the frame header has been documented by Bertrik 344[1] The frame headers exported by the SN9C105 and SN9C120 are not described.
316 Sikken.
317 345
318 346
3199. Supported devices 3479. Supported devices
@@ -323,15 +351,19 @@ here. They have never collaborated with the author, so no advertising.
323 351
324From the point of view of a driver, what unambiguously identify a device are 352From the point of view of a driver, what unambiguously identify a device are
325its vendor and product USB identifiers. Below is a list of known identifiers of 353its vendor and product USB identifiers. Below is a list of known identifiers of
326devices mounting the SN9C10x PC camera controllers: 354devices assembling the SN9C1xx PC camera controllers:
327 355
328Vendor ID Product ID 356Vendor ID Product ID
329--------- ---------- 357--------- ----------
3580x0471 0x0327
3590x0471 0x0328
3300x0c45 0x6001 3600x0c45 0x6001
3310x0c45 0x6005 3610x0c45 0x6005
3320x0c45 0x6007 3620x0c45 0x6007
3330x0c45 0x6009 3630x0c45 0x6009
3340x0c45 0x600d 3640x0c45 0x600d
3650x0c45 0x6011
3660x0c45 0x6019
3350x0c45 0x6024 3670x0c45 0x6024
3360x0c45 0x6025 3680x0c45 0x6025
3370x0c45 0x6028 3690x0c45 0x6028
@@ -342,6 +374,7 @@ Vendor ID Product ID
3420x0c45 0x602d 3740x0c45 0x602d
3430x0c45 0x602e 3750x0c45 0x602e
3440x0c45 0x6030 3760x0c45 0x6030
3770x0c45 0x603f
3450x0c45 0x6080 3780x0c45 0x6080
3460x0c45 0x6082 3790x0c45 0x6082
3470x0c45 0x6083 3800x0c45 0x6083
@@ -368,24 +401,51 @@ Vendor ID Product ID
3680x0c45 0x60bb 4010x0c45 0x60bb
3690x0c45 0x60bc 4020x0c45 0x60bc
3700x0c45 0x60be 4030x0c45 0x60be
4040x0c45 0x60c0
4050x0c45 0x60c2
4060x0c45 0x60c8
4070x0c45 0x60cc
4080x0c45 0x60ea
4090x0c45 0x60ec
4100x0c45 0x60ef
4110x0c45 0x60fa
4120x0c45 0x60fb
4130x0c45 0x60fc
4140x0c45 0x60fe
4150x0c45 0x6102
4160x0c45 0x6108
4170x0c45 0x610f
4180x0c45 0x6130
4190x0c45 0x6138
4200x0c45 0x613a
4210x0c45 0x613b
4220x0c45 0x613c
4230x0c45 0x613e
371 424
372The list above does not imply that all those devices work with this driver: up 425The list above does not imply that all those devices work with this driver: up
373until now only the ones that mount the following image sensors are supported; 426until now only the ones that assemble the following pairs of SN9C1xx bridges
374kernel messages will always tell you whether this is the case: 427and image sensors are supported; kernel messages will always tell you whether
375 428this is the case (see "Module loading" paragraph):
376Model Manufacturer 429
377----- ------------ 430Image sensor / SN9C1xx bridge | SN9C10[12] SN9C103 SN9C105 SN9C120
378HV7131D Hynix Semiconductor, Inc. 431-------------------------------------------------------------------------------
379MI-0343 Micron Technology, Inc. 432HV7131D Hynix Semiconductor | Yes No No No
380OV7630 OmniVision Technologies, Inc. 433HV7131R Hynix Semiconductor | No Yes Yes Yes
381PAS106B PixArt Imaging, Inc. 434MI-0343 Micron Technology | Yes No No No
382PAS202BCA PixArt Imaging, Inc. 435MI-0360 Micron Technology | No Yes No No
383PAS202BCB PixArt Imaging, Inc. 436OV7630 OmniVision Technologies | Yes Yes No No
384TAS5110C1B Taiwan Advanced Sensor Corporation 437OV7660 OmniVision Technologies | No No Yes Yes
385TAS5130D1B Taiwan Advanced Sensor Corporation 438PAS106B PixArt Imaging | Yes No No No
386 439PAS202B PixArt Imaging | Yes Yes No No
387All the available control settings of each image sensor are supported through 440TAS5110C1B Taiwan Advanced Sensor | Yes No No No
388the V4L2 interface. 441TAS5110D Taiwan Advanced Sensor | Yes No No No
442TAS5130D1B Taiwan Advanced Sensor | Yes No No No
443
444"Yes" means that the pair is supported by the driver, while "No" means that the
445pair does not exist or is not supported by the driver.
446
447Only some of the available control settings of each image sensor are supported
448through the V4L2 interface.
389 449
390Donations of new models for further testing and support would be much 450Donations of new models for further testing and support would be much
391appreciated. Non-available hardware will not be supported by the author of this 451appreciated. Non-available hardware will not be supported by the author of this
@@ -429,12 +489,15 @@ supplied by this driver).
429 489
43011. Video frame formats [1] 49011. Video frame formats [1]
431======================= 491=======================
432The SN9C10x PC Camera Controllers can send images in two possible video 492The SN9C1xx PC Camera Controllers can send images in two possible video
433formats over the USB: either native "Sequential RGB Bayer" or Huffman 493formats over the USB: either native "Sequential RGB Bayer" or compressed.
434compressed. The latter is used to achieve high frame rates. The current video 494The compression is used to achieve high frame rates. With regard to the
435format may be selected or queried from the user application by calling the 495SN9C101, SN9C102 and SN9C103, the compression is based on the Huffman encoding
436VIDIOC_S_FMT or VIDIOC_G_FMT ioctl's, as described in the V4L2 API 496algorithm described below, while with regard to the SN9C105 and SN9C120 the
437specifications. 497compression is based on the JPEG standard.
498The current video format may be selected or queried from the user application
499by calling the VIDIOC_S_FMT or VIDIOC_G_FMT ioctl's, as described in the V4L2
500API specifications.
438 501
439The name "Sequential Bayer" indicates the organization of the red, green and 502The name "Sequential Bayer" indicates the organization of the red, green and
440blue pixels in one video frame. Each pixel is associated with a 8-bit long 503blue pixels in one video frame. Each pixel is associated with a 8-bit long
@@ -447,14 +510,14 @@ G[m] R[m+1] G[m+2] R[m+2] ... G[2m-2] R[2m-1]
447... G[n(m-2)] R[n(m-1)] 510... G[n(m-2)] R[n(m-1)]
448 511
449The above matrix also represents the sequential or progressive read-out mode of 512The above matrix also represents the sequential or progressive read-out mode of
450the (n, m) Bayer color filter array used in many CCD/CMOS image sensors. 513the (n, m) Bayer color filter array used in many CCD or CMOS image sensors.
451 514
452One compressed video frame consists of a bitstream that encodes for every R, G, 515The Huffman compressed video frame consists of a bitstream that encodes for
453or B pixel the difference between the value of the pixel itself and some 516every R, G, or B pixel the difference between the value of the pixel itself and
454reference pixel value. Pixels are organised in the Bayer pattern and the Bayer 517some reference pixel value. Pixels are organised in the Bayer pattern and the
455sub-pixels are tracked individually and alternatingly. For example, in the 518Bayer sub-pixels are tracked individually and alternatingly. For example, in
456first line values for the B and G1 pixels are alternatingly encoded, while in 519the first line values for the B and G1 pixels are alternatingly encoded, while
457the second line values for the G2 and R pixels are alternatingly encoded. 520in the second line values for the G2 and R pixels are alternatingly encoded.
458 521
459The pixel reference value is calculated as follows: 522The pixel reference value is calculated as follows:
460- the 4 top left pixels are encoded in raw uncompressed 8-bit format; 523- the 4 top left pixels are encoded in raw uncompressed 8-bit format;
@@ -470,8 +533,9 @@ The pixel reference value is calculated as follows:
470 decoding. 533 decoding.
471 534
472The algorithm purely describes the conversion from compressed Bayer code used 535The algorithm purely describes the conversion from compressed Bayer code used
473in the SN9C10x chips to uncompressed Bayer. Additional steps are required to 536in the SN9C101, SN9C102 and SN9C103 chips to uncompressed Bayer. Additional
474convert this to a color image (i.e. a color interpolation algorithm). 537steps are required to convert this to a color image (i.e. a color interpolation
538algorithm).
475 539
476The following Huffman codes have been found: 540The following Huffman codes have been found:
4770: +0 (relative to reference pixel value) 5410: +0 (relative to reference pixel value)
@@ -506,13 +570,19 @@ order):
506- Philippe Coval for having helped testing the PAS202BCA image sensor; 570- Philippe Coval for having helped testing the PAS202BCA image sensor;
507- Joao Rodrigo Fuzaro, Joao Limirio, Claudio Filho and Caio Begotti for the 571- Joao Rodrigo Fuzaro, Joao Limirio, Claudio Filho and Caio Begotti for the
508 donation of a webcam; 572 donation of a webcam;
573- Dennis Heitmann for the donation of a webcam;
509- Jon Hollstrom for the donation of a webcam; 574- Jon Hollstrom for the donation of a webcam;
575- Nick McGill for the donation of a webcam;
510- Carlos Eduardo Medaglia Dyonisio, who added the support for the PAS202BCB 576- Carlos Eduardo Medaglia Dyonisio, who added the support for the PAS202BCB
511 image sensor; 577 image sensor;
512- Stefano Mozzi, who donated 45 EU; 578- Stefano Mozzi, who donated 45 EU;
513- Andrew Pearce for the donation of a webcam; 579- Andrew Pearce for the donation of a webcam;
580- John Pullan for the donation of a webcam;
514- Bertrik Sikken, who reverse-engineered and documented the Huffman compression 581- Bertrik Sikken, who reverse-engineered and documented the Huffman compression
515 algorithm used in the SN9C10x controllers and implemented the first decoder; 582 algorithm used in the SN9C101, SN9C102 and SN9C103 controllers and
583 implemented the first decoder;
516- Mizuno Takafumi for the donation of a webcam; 584- Mizuno Takafumi for the donation of a webcam;
517- an "anonymous" donator (who didn't want his name to be revealed) for the 585- an "anonymous" donator (who didn't want his name to be revealed) for the
518 donation of a webcam. 586 donation of a webcam.
587- an anonymous donator for the donation of four webcams and two boards with ten
588 image sensors.
diff --git a/Documentation/video4linux/zc0301.txt b/Documentation/video4linux/zc0301.txt
index f406f5e80046..befdfdacdc5b 100644
--- a/Documentation/video4linux/zc0301.txt
+++ b/Documentation/video4linux/zc0301.txt
@@ -23,7 +23,7 @@ Index
23 23
241. Copyright 241. Copyright
25============ 25============
26Copyright (C) 2006 by Luca Risolia <luca.risolia@studio.unibo.it> 26Copyright (C) 2006-2007 by Luca Risolia <luca.risolia@studio.unibo.it>
27 27
28 28
292. Disclaimer 292. Disclaimer
@@ -125,8 +125,9 @@ And finally:
1256. Module loading 1256. Module loading
126================= 126=================
127To use the driver, it is necessary to load the "zc0301" module into memory 127To use the driver, it is necessary to load the "zc0301" module into memory
128after every other module required: "videodev", "usbcore" and, depending on 128after every other module required: "videodev", "v4l2_common", "compat_ioctl32",
129the USB host controller you have, "ehci-hcd", "uhci-hcd" or "ohci-hcd". 129"usbcore" and, depending on the USB host controller you have, "ehci-hcd",
130"uhci-hcd" or "ohci-hcd".
130 131
131Loading can be done as shown below: 132Loading can be done as shown below:
132 133
@@ -211,12 +212,11 @@ Vendor ID Product ID
2110x041e 0x4036 2120x041e 0x4036
2120x041e 0x403a 2130x041e 0x403a
2130x0458 0x7007 2140x0458 0x7007
2140x0458 0x700C 2150x0458 0x700c
2150x0458 0x700f 2160x0458 0x700f
2160x046d 0x08ae 2170x046d 0x08ae
2170x055f 0xd003 2180x055f 0xd003
2180x055f 0xd004 2190x055f 0xd004
2190x046d 0x08ae
2200x0ac8 0x0301 2200x0ac8 0x0301
2210x0ac8 0x301b 2210x0ac8 0x301b
2220x0ac8 0x303b 2220x0ac8 0x303b
diff --git a/Documentation/video4linux/zr364xx.txt b/Documentation/video4linux/zr364xx.txt
new file mode 100644
index 000000000000..c76992d0ff4d
--- /dev/null
+++ b/Documentation/video4linux/zr364xx.txt
@@ -0,0 +1,65 @@
1Zoran 364xx based USB webcam module version 0.72
2site: http://royale.zerezo.com/zr364xx/
3mail: royale@zerezo.com
4
5introduction:
6This brings support under Linux for the Aiptek PocketDV 3300 in webcam mode.
7If you just want to get on your PC the pictures and movies on the camera, you should use the usb-storage module instead.
8The driver works with several other cameras in webcam mode (see the list below).
9Maybe this code can work for other JPEG/USB cams based on the Coach chips from Zoran?
10Possible chipsets are : ZR36430 (ZR36430BGC) and maybe ZR36431, ZR36440, ZR36442...
11You can try the experience changing the vendor/product ID values (look at the source code).
12You can get these values by looking at /var/log/messages when you plug your camera, or by typing : cat /proc/bus/usb/devices.
13If you manage to use your cam with this code, you can send me a mail (royale@zerezo.com) with the name of your cam and a patch if needed.
14This is a beta release of the driver.
15Since version 0.70, this driver is only compatible with V4L2 API and 2.6.x kernels.
16If you need V4L1 or 2.4x kernels support, please use an older version, but the code is not maintained anymore.
17Good luck!
18
19install:
20In order to use this driver, you must compile it with your kernel.
21Location: Device Drivers -> Multimedia devices -> Video For Linux -> Video Capture Adapters -> V4L USB devices
22
23usage:
24modprobe zr364xx debug=X mode=Y
25 - debug : set to 1 to enable verbose debug messages
26 - mode : 0 = 320x240, 1 = 160x120, 2 = 640x480
27You can then use the camera with V4L2 compatible applications, for example Ekiga.
28To capture a single image, try this: dd if=/dev/video0 of=test.jpg bs=1 count=1
29
30links :
31http://mxhaard.free.fr/ (support for many others cams including some Aiptek PocketDV)
32http://www.harmwal.nl/pccam880/ (this project also supports cameras based on this chipset)
33
34supported devices:
35------ ------- ----------- -----
36Vendor Product Distributor Model
37------ ------- ----------- -----
380x08ca 0x0109 Aiptek PocketDV 3300
390x08ca 0x0109 Maxell Maxcam PRO DV3
400x041e 0x4024 Creative PC-CAM 880
410x0d64 0x0108 Aiptek Fidelity 3200
420x0d64 0x0108 Praktica DCZ 1.3 S
430x0d64 0x0108 Genius Digital Camera (?)
440x0d64 0x0108 DXG Technology Fashion Cam
450x0546 0x3187 Polaroid iON 230
460x0d64 0x3108 Praktica Exakta DC 2200
470x0d64 0x3108 Genius G-Shot D211
480x0595 0x4343 Concord Eye-Q Duo 1300
490x0595 0x4343 Concord Eye-Q Duo 2000
500x0595 0x4343 Fujifilm EX-10
510x0595 0x4343 Ricoh RDC-6000
520x0595 0x4343 Digitrex DSC 1300
530x0595 0x4343 Firstline FDC 2000
540x0bb0 0x500d Concord EyeQ Go Wireless
550x0feb 0x2004 CRS Electronic 3.3 Digital Camera
560x0feb 0x2004 Packard Bell DSC-300
570x055f 0xb500 Mustek MDC 3000
580x08ca 0x2062 Aiptek PocketDV 5700
590x052b 0x1a18 Chiphead Megapix V12
600x04c8 0x0729 Konica Revio 2
610x04f2 0xa208 Creative PC-CAM 850
620x0784 0x0040 Traveler Slimline X5
630x06d6 0x0034 Trust Powerc@m 750
640x0a17 0x0062 Pentax Optio 50L
65
diff --git a/Documentation/x86_64/boot-options.txt b/Documentation/x86_64/boot-options.txt
index 5c86ed6f0448..85f51e5a749f 100644
--- a/Documentation/x86_64/boot-options.txt
+++ b/Documentation/x86_64/boot-options.txt
@@ -180,40 +180,81 @@ PCI
180 pci=lastbus=NUMBER Scan upto NUMBER busses, no matter what the mptable says. 180 pci=lastbus=NUMBER Scan upto NUMBER busses, no matter what the mptable says.
181 pci=noacpi Don't use ACPI to set up PCI interrupt routing. 181 pci=noacpi Don't use ACPI to set up PCI interrupt routing.
182 182
183IOMMU 183IOMMU (input/output memory management unit)
184 184
185 iommu=[size][,noagp][,off][,force][,noforce][,leak][,memaper[=order]][,merge] 185 Currently four x86-64 PCI-DMA mapping implementations exist:
186 [,forcesac][,fullflush][,nomerge][,noaperture][,calgary] 186
187 size set size of iommu (in bytes) 187 1. <arch/x86_64/kernel/pci-nommu.c>: use no hardware/software IOMMU at all
188 noagp don't initialize the AGP driver and use full aperture. 188 (e.g. because you have < 3 GB memory).
189 off don't use the IOMMU 189 Kernel boot message: "PCI-DMA: Disabling IOMMU"
190 leak turn on simple iommu leak tracing (only when CONFIG_IOMMU_LEAK is on) 190
191 memaper[=order] allocate an own aperture over RAM with size 32MB^order. 191 2. <arch/x86_64/kernel/pci-gart.c>: AMD GART based hardware IOMMU.
192 noforce don't force IOMMU usage. Default. 192 Kernel boot message: "PCI-DMA: using GART IOMMU"
193 force Force IOMMU. 193
194 merge Do SG merging. Implies force (experimental) 194 3. <arch/x86_64/kernel/pci-swiotlb.c> : Software IOMMU implementation. Used
195 nomerge Don't do SG merging. 195 e.g. if there is no hardware IOMMU in the system and it is need because
196 forcesac For SAC mode for masks <40bits (experimental) 196 you have >3GB memory or told the kernel to us it (iommu=soft))
197 fullflush Flush IOMMU on each allocation (default) 197 Kernel boot message: "PCI-DMA: Using software bounce buffering
198 nofullflush Don't use IOMMU fullflush 198 for IO (SWIOTLB)"
199 allowed overwrite iommu off workarounds for specific chipsets. 199
200 soft Use software bounce buffering (default for Intel machines) 200 4. <arch/x86_64/pci-calgary.c> : IBM Calgary hardware IOMMU. Used in IBM
201 noaperture Don't touch the aperture for AGP. 201 pSeries and xSeries servers. This hardware IOMMU supports DMA address
202 allowdac Allow DMA >4GB 202 mapping with memory protection, etc.
203 When off all DMA over >4GB is forced through an IOMMU or bounce 203 Kernel boot message: "PCI-DMA: Using Calgary IOMMU"
204 buffering. 204
205 nodac Forbid DMA >4GB 205 iommu=[<size>][,noagp][,off][,force][,noforce][,leak[=<nr_of_leak_pages>]
206 panic Always panic when IOMMU overflows 206 [,memaper[=<order>]][,merge][,forcesac][,fullflush][,nomerge]
207 calgary Use the Calgary IOMMU if it is available 207 [,noaperture][,calgary]
208 208
209 swiotlb=pages[,force] 209 General iommu options:
210 210 off Don't initialize and use any kind of IOMMU.
211 pages Prereserve that many 128K pages for the software IO bounce buffering. 211 noforce Don't force hardware IOMMU usage when it is not needed.
212 force Force all IO through the software TLB. 212 (default).
213 213 force Force the use of the hardware IOMMU even when it is
214 calgary=[64k,128k,256k,512k,1M,2M,4M,8M] 214 not actually needed (e.g. because < 3 GB memory).
215 calgary=[translate_empty_slots] 215 soft Use software bounce buffering (SWIOTLB) (default for
216 calgary=[disable=<PCI bus number>] 216 Intel machines). This can be used to prevent the usage
217 of an available hardware IOMMU.
218
219 iommu options only relevant to the AMD GART hardware IOMMU:
220 <size> Set the size of the remapping area in bytes.
221 allowed Overwrite iommu off workarounds for specific chipsets.
222 fullflush Flush IOMMU on each allocation (default).
223 nofullflush Don't use IOMMU fullflush.
224 leak Turn on simple iommu leak tracing (only when
225 CONFIG_IOMMU_LEAK is on). Default number of leak pages
226 is 20.
227 memaper[=<order>] Allocate an own aperture over RAM with size 32MB<<order.
228 (default: order=1, i.e. 64MB)
229 merge Do scatter-gather (SG) merging. Implies "force"
230 (experimental).
231 nomerge Don't do scatter-gather (SG) merging.
232 noaperture Ask the IOMMU not to touch the aperture for AGP.
233 forcesac Force single-address cycle (SAC) mode for masks <40bits
234 (experimental).
235 noagp Don't initialize the AGP driver and use full aperture.
236 allowdac Allow double-address cycle (DAC) mode, i.e. DMA >4GB.
237 DAC is used with 32-bit PCI to push a 64-bit address in
238 two cycles. When off all DMA over >4GB is forced through
239 an IOMMU or software bounce buffering.
240 nodac Forbid DAC mode, i.e. DMA >4GB.
241 panic Always panic when IOMMU overflows.
242 calgary Use the Calgary IOMMU if it is available
243
244 iommu options only relevant to the software bounce buffering (SWIOTLB) IOMMU
245 implementation:
246 swiotlb=<pages>[,force]
247 <pages> Prereserve that many 128K pages for the software IO
248 bounce buffering.
249 force Force all IO through the software TLB.
250
251 Settings for the IBM Calgary hardware IOMMU currently found in IBM
252 pSeries and xSeries machines:
253
254 calgary=[64k,128k,256k,512k,1M,2M,4M,8M]
255 calgary=[translate_empty_slots]
256 calgary=[disable=<PCI bus number>]
257 panic Always panic when IOMMU overflows
217 258
218 64k,...,8M - Set the size of each PCI slot's translation table 259 64k,...,8M - Set the size of each PCI slot's translation table
219 when using the Calgary IOMMU. This is the size of the translation 260 when using the Calgary IOMMU. This is the size of the translation
@@ -234,14 +275,14 @@ IOMMU
234 275
235Debugging 276Debugging
236 277
237 oops=panic Always panic on oopses. Default is to just kill the process, 278 oops=panic Always panic on oopses. Default is to just kill the process,
238 but there is a small probability of deadlocking the machine. 279 but there is a small probability of deadlocking the machine.
239 This will also cause panics on machine check exceptions. 280 This will also cause panics on machine check exceptions.
240 Useful together with panic=30 to trigger a reboot. 281 Useful together with panic=30 to trigger a reboot.
241 282
242 kstack=N Print that many words from the kernel stack in oops dumps. 283 kstack=N Print N words from the kernel stack in oops dumps.
243 284
244 pagefaulttrace Dump all page faults. Only useful for extreme debugging 285 pagefaulttrace Dump all page faults. Only useful for extreme debugging
245 and will create a lot of output. 286 and will create a lot of output.
246 287
247 call_trace=[old|both|newfallback|new] 288 call_trace=[old|both|newfallback|new]
@@ -251,15 +292,4 @@ Debugging
251 newfallback: use new unwinder but fall back to old if it gets 292 newfallback: use new unwinder but fall back to old if it gets
252 stuck (default) 293 stuck (default)
253 294
254 call_trace=[old|both|newfallback|new] 295Miscellaneous
255 old: use old inexact backtracer
256 new: use new exact dwarf2 unwinder
257 both: print entries from both
258 newfallback: use new unwinder but fall back to old if it gets
259 stuck (default)
260
261Misc
262
263 noreplacement Don't replace instructions with more appropriate ones
264 for the CPU. This may be useful on asymmetric MP systems
265 where some CPU have less capabilities than the others.
diff --git a/Documentation/x86_64/cpu-hotplug-spec b/Documentation/x86_64/cpu-hotplug-spec
index 5c0fa345e556..3c23e0587db3 100644
--- a/Documentation/x86_64/cpu-hotplug-spec
+++ b/Documentation/x86_64/cpu-hotplug-spec
@@ -2,7 +2,7 @@ Firmware support for CPU hotplug under Linux/x86-64
2--------------------------------------------------- 2---------------------------------------------------
3 3
4Linux/x86-64 supports CPU hotplug now. For various reasons Linux wants to 4Linux/x86-64 supports CPU hotplug now. For various reasons Linux wants to
5know in advance boot time the maximum number of CPUs that could be plugged 5know in advance of boot time the maximum number of CPUs that could be plugged
6into the system. ACPI 3.0 currently has no official way to supply 6into the system. ACPI 3.0 currently has no official way to supply
7this information from the firmware to the operating system. 7this information from the firmware to the operating system.
8 8
diff --git a/Documentation/x86_64/kernel-stacks b/Documentation/x86_64/kernel-stacks
index bddfddd466ab..5ad65d51fb95 100644
--- a/Documentation/x86_64/kernel-stacks
+++ b/Documentation/x86_64/kernel-stacks
@@ -9,9 +9,9 @@ zombie. While the thread is in user space the kernel stack is empty
9except for the thread_info structure at the bottom. 9except for the thread_info structure at the bottom.
10 10
11In addition to the per thread stacks, there are specialized stacks 11In addition to the per thread stacks, there are specialized stacks
12associated with each cpu. These stacks are only used while the kernel 12associated with each CPU. These stacks are only used while the kernel
13is in control on that cpu, when a cpu returns to user space the 13is in control on that CPU; when a CPU returns to user space the
14specialized stacks contain no useful data. The main cpu stacks is 14specialized stacks contain no useful data. The main CPU stacks are:
15 15
16* Interrupt stack. IRQSTACKSIZE 16* Interrupt stack. IRQSTACKSIZE
17 17
@@ -32,17 +32,17 @@ x86_64 also has a feature which is not available on i386, the ability
32to automatically switch to a new stack for designated events such as 32to automatically switch to a new stack for designated events such as
33double fault or NMI, which makes it easier to handle these unusual 33double fault or NMI, which makes it easier to handle these unusual
34events on x86_64. This feature is called the Interrupt Stack Table 34events on x86_64. This feature is called the Interrupt Stack Table
35(IST). There can be up to 7 IST entries per cpu. The IST code is an 35(IST). There can be up to 7 IST entries per CPU. The IST code is an
36index into the Task State Segment (TSS), the IST entries in the TSS 36index into the Task State Segment (TSS). The IST entries in the TSS
37point to dedicated stacks, each stack can be a different size. 37point to dedicated stacks; each stack can be a different size.
38 38
39An IST is selected by an non-zero value in the IST field of an 39An IST is selected by a non-zero value in the IST field of an
40interrupt-gate descriptor. When an interrupt occurs and the hardware 40interrupt-gate descriptor. When an interrupt occurs and the hardware
41loads such a descriptor, the hardware automatically sets the new stack 41loads such a descriptor, the hardware automatically sets the new stack
42pointer based on the IST value, then invokes the interrupt handler. If 42pointer based on the IST value, then invokes the interrupt handler. If
43software wants to allow nested IST interrupts then the handler must 43software wants to allow nested IST interrupts then the handler must
44adjust the IST values on entry to and exit from the interrupt handler. 44adjust the IST values on entry to and exit from the interrupt handler.
45(this is occasionally done, e.g. for debug exceptions) 45(This is occasionally done, e.g. for debug exceptions.)
46 46
47Events with different IST codes (i.e. with different stacks) can be 47Events with different IST codes (i.e. with different stacks) can be
48nested. For example, a debug interrupt can safely be interrupted by an 48nested. For example, a debug interrupt can safely be interrupted by an
@@ -58,17 +58,17 @@ The currently assigned IST stacks are :-
58 58
59 Used for interrupt 12 - Stack Fault Exception (#SS). 59 Used for interrupt 12 - Stack Fault Exception (#SS).
60 60
61 This allows to recover from invalid stack segments. Rarely 61 This allows the CPU to recover from invalid stack segments. Rarely
62 happens. 62 happens.
63 63
64* DOUBLEFAULT_STACK. EXCEPTION_STKSZ (PAGE_SIZE). 64* DOUBLEFAULT_STACK. EXCEPTION_STKSZ (PAGE_SIZE).
65 65
66 Used for interrupt 8 - Double Fault Exception (#DF). 66 Used for interrupt 8 - Double Fault Exception (#DF).
67 67
68 Invoked when handling a exception causes another exception. Happens 68 Invoked when handling one exception causes another exception. Happens
69 when the kernel is very confused (e.g. kernel stack pointer corrupt) 69 when the kernel is very confused (e.g. kernel stack pointer corrupt).
70 Using a separate stack allows to recover from it well enough in many 70 Using a separate stack allows the kernel to recover from it well enough
71 cases to still output an oops. 71 in many cases to still output an oops.
72 72
73* NMI_STACK. EXCEPTION_STKSZ (PAGE_SIZE). 73* NMI_STACK. EXCEPTION_STKSZ (PAGE_SIZE).
74 74
diff --git a/Documentation/x86_64/machinecheck b/Documentation/x86_64/machinecheck
new file mode 100644
index 000000000000..068a6d9904b9
--- /dev/null
+++ b/Documentation/x86_64/machinecheck
@@ -0,0 +1,70 @@
1
2Configurable sysfs parameters for the x86-64 machine check code.
3
4Machine checks report internal hardware error conditions detected
5by the CPU. Uncorrected errors typically cause a machine check
6(often with panic), corrected ones cause a machine check log entry.
7
8Machine checks are organized in banks (normally associated with
9a hardware subsystem) and subevents in a bank. The exact meaning
10of the banks and subevent is CPU specific.
11
12mcelog knows how to decode them.
13
14When you see the "Machine check errors logged" message in the system
15log then mcelog should run to collect and decode machine check entries
16from /dev/mcelog. Normally mcelog should be run regularly from a cronjob.
17
18Each CPU has a directory in /sys/devices/system/machinecheck/machinecheckN
19(N = CPU number)
20
21The directory contains some configurable entries:
22
23Entries:
24
25bankNctl
26(N bank number)
27 64bit Hex bitmask enabling/disabling specific subevents for bank N
28 When a bit in the bitmask is zero then the respective
29 subevent will not be reported.
30 By default all events are enabled.
31 Note that BIOS maintain another mask to disable specific events
32 per bank. This is not visible here
33
34The following entries appear for each CPU, but they are truly shared
35between all CPUs.
36
37check_interval
38 How often to poll for corrected machine check errors, in seconds
39 (Note output is hexademical). Default 5 minutes.
40
41tolerant
42 Tolerance level. When a machine check exception occurs for a non
43 corrected machine check the kernel can take different actions.
44 Since machine check exceptions can happen any time it is sometimes
45 risky for the kernel to kill a process because it defies
46 normal kernel locking rules. The tolerance level configures
47 how hard the kernel tries to recover even at some risk of deadlock.
48
49 0: always panic,
50 1: panic if deadlock possible,
51 2: try to avoid panic,
52 3: never panic or exit (for testing only)
53
54 Default: 1
55
56 Note this only makes a difference if the CPU allows recovery
57 from a machine check exception. Current x86 CPUs generally do not.
58
59trigger
60 Program to run when a machine check event is detected.
61 This is an alternative to running mcelog regularly from cron
62 and allows to detect events faster.
63
64TBD document entries for AMD threshold interrupt configuration
65
66For more details about the x86 machine check architecture
67see the Intel and AMD architecture manuals from their developer websites.
68
69For more details about the architecture see
70see http://one.firstfloor.org/~andi/mce.pdf
diff --git a/Documentation/x86_64/mm.txt b/Documentation/x86_64/mm.txt
index 133561b9cb0c..f42798ed1c54 100644
--- a/Documentation/x86_64/mm.txt
+++ b/Documentation/x86_64/mm.txt
@@ -3,26 +3,26 @@
3 3
4Virtual memory map with 4 level page tables: 4Virtual memory map with 4 level page tables:
5 5
60000000000000000 - 00007fffffffffff (=47bits) user space, different per mm 60000000000000000 - 00007fffffffffff (=47 bits) user space, different per mm
7hole caused by [48:63] sign extension 7hole caused by [48:63] sign extension
8ffff800000000000 - ffff80ffffffffff (=40bits) guard hole 8ffff800000000000 - ffff80ffffffffff (=40 bits) guard hole
9ffff810000000000 - ffffc0ffffffffff (=46bits) direct mapping of all phys. memory 9ffff810000000000 - ffffc0ffffffffff (=46 bits) direct mapping of all phys. memory
10ffffc10000000000 - ffffc1ffffffffff (=40bits) hole 10ffffc10000000000 - ffffc1ffffffffff (=40 bits) hole
11ffffc20000000000 - ffffe1ffffffffff (=45bits) vmalloc/ioremap space 11ffffc20000000000 - ffffe1ffffffffff (=45 bits) vmalloc/ioremap space
12... unused hole ... 12... unused hole ...
13ffffffff80000000 - ffffffff82800000 (=40MB) kernel text mapping, from phys 0 13ffffffff80000000 - ffffffff82800000 (=40 MB) kernel text mapping, from phys 0
14... unused hole ... 14... unused hole ...
15ffffffff88000000 - fffffffffff00000 (=1919MB) module mapping space 15ffffffff88000000 - fffffffffff00000 (=1919 MB) module mapping space
16 16
17The direct mapping covers all memory in the system upto the highest 17The direct mapping covers all memory in the system up to the highest
18memory address (this means in some cases it can also include PCI memory 18memory address (this means in some cases it can also include PCI memory
19holes) 19holes).
20 20
21vmalloc space is lazily synchronized into the different PML4 pages of 21vmalloc space is lazily synchronized into the different PML4 pages of
22the processes using the page fault handler, with init_level4_pgt as 22the processes using the page fault handler, with init_level4_pgt as
23reference. 23reference.
24 24
25Current X86-64 implementations only support 40 bit of address space, 25Current X86-64 implementations only support 40 bits of address space,
26but we support upto 46bits. This expands into MBZ space in the page tables. 26but we support up to 46 bits. This expands into MBZ space in the page tables.
27 27
28-Andi Kleen, Jul 2004 28-Andi Kleen, Jul 2004