aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorDavid Vrabel <david.vrabel@csr.com>2008-10-20 11:07:19 -0400
committerDavid Vrabel <david.vrabel@csr.com>2008-10-20 11:07:19 -0400
commit61e0e79ee3c609eb34edf2fe023708cba6a79b1f (patch)
tree663deacffd4071120dc9badb70428fe5f124c7b9 /Documentation
parentc15895ef30c2c03e99802951787183039a349d32 (diff)
parent0cfd81031a26717fe14380d18275f8e217571615 (diff)
Merge branch 'master' into for-upstream
Conflicts: Documentation/ABI/testing/sysfs-bus-usb drivers/Makefile
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/00-INDEX7
-rw-r--r--Documentation/ABI/stable/sysfs-driver-usb-usbtmc62
-rw-r--r--Documentation/ABI/testing/sysfs-bus-usb16
-rw-r--r--Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg43
-rw-r--r--Documentation/ABI/testing/sysfs-class-regulator55
-rw-r--r--Documentation/ABI/testing/sysfs-profiling13
-rw-r--r--Documentation/DMA-API.txt2
-rw-r--r--Documentation/DocBook/Makefile2
-rw-r--r--Documentation/DocBook/gadget.tmpl3
-rw-r--r--Documentation/DocBook/kernel-api.tmpl5
-rw-r--r--Documentation/DocBook/mac80211.tmpl12
-rw-r--r--Documentation/DocBook/procfs-guide.tmpl29
-rw-r--r--Documentation/DocBook/procfs_example.c20
-rw-r--r--Documentation/DocBook/videobook.tmpl1654
-rw-r--r--Documentation/HOWTO4
-rw-r--r--Documentation/RCU/checklist.txt2
-rw-r--r--Documentation/RCU/rcuref.txt16
-rw-r--r--Documentation/RCU/whatisRCU.txt2
-rw-r--r--Documentation/SAK.txt2
-rw-r--r--Documentation/SELinux.txt27
-rw-r--r--Documentation/SubmitChecklist3
-rw-r--r--Documentation/SubmittingDrivers2
-rw-r--r--Documentation/SubmittingPatches11
-rw-r--r--Documentation/blackfin/kgdb.txt155
-rw-r--r--Documentation/block/data-integrity.txt4
-rw-r--r--Documentation/block/deadline-iosched.txt14
-rw-r--r--Documentation/cdrom/ide-cd3
-rw-r--r--Documentation/cris/README2
-rw-r--r--Documentation/development-process/1.Intro274
-rw-r--r--Documentation/development-process/2.Process459
-rw-r--r--Documentation/development-process/3.Early-stage195
-rw-r--r--Documentation/development-process/4.Coding384
-rw-r--r--Documentation/development-process/5.Posting278
-rw-r--r--Documentation/development-process/6.Followthrough202
-rw-r--r--Documentation/development-process/7.AdvancedTopics173
-rw-r--r--Documentation/development-process/8.Conclusion74
-rw-r--r--Documentation/devices.txt3
-rw-r--r--Documentation/dontdiff59
-rw-r--r--Documentation/fb/intelfb.txt1
-rw-r--r--Documentation/fb/uvesafb.txt4
-rw-r--r--Documentation/fb/viafb.modes870
-rw-r--r--Documentation/fb/viafb.txt214
-rw-r--r--Documentation/feature-removal-schedule.txt39
-rw-r--r--Documentation/filesystems/autofs4-mount-control.txt393
-rw-r--r--Documentation/filesystems/ext3.txt3
-rw-r--r--Documentation/filesystems/ext4.txt51
-rw-r--r--Documentation/filesystems/fiemap.txt228
-rw-r--r--Documentation/filesystems/nfsroot.txt2
-rw-r--r--Documentation/filesystems/ocfs2.txt6
-rw-r--r--Documentation/filesystems/proc.txt86
-rw-r--r--Documentation/filesystems/ramfs-rootfs-initramfs.txt2
-rw-r--r--Documentation/gpio.txt9
-rw-r--r--Documentation/hwmon/adt747076
-rw-r--r--Documentation/hwmon/it874
-rw-r--r--Documentation/hwmon/lm8510
-rw-r--r--Documentation/hwmon/lm879
-rw-r--r--Documentation/hwmon/lm9045
-rw-r--r--Documentation/hwmon/pc873607
-rw-r--r--Documentation/hwmon/pc874272
-rw-r--r--Documentation/hwmon/w83781d37
-rw-r--r--Documentation/hwmon/w83791d43
-rw-r--r--Documentation/i2c/busses/i2c-viapro8
-rw-r--r--Documentation/i2c/dev-interface110
-rw-r--r--Documentation/i2c/smbus-protocol4
-rw-r--r--Documentation/i2c/writing-clients4
-rw-r--r--Documentation/ia64/kvm.txt9
-rw-r--r--Documentation/ioctl-number.txt3
-rw-r--r--Documentation/kernel-doc-nano-HOWTO.txt4
-rw-r--r--Documentation/kernel-parameters.txt78
-rw-r--r--Documentation/kobject.txt4
-rw-r--r--Documentation/laptops/disk-shock-protection.txt149
-rw-r--r--Documentation/networking/LICENSE.qlge46
-rw-r--r--Documentation/networking/can.txt44
-rw-r--r--Documentation/networking/cs89x0.txt4
-rw-r--r--Documentation/networking/multiqueue.txt54
-rw-r--r--Documentation/networking/phonet.txt175
-rw-r--r--Documentation/networking/regulatory.txt194
-rw-r--r--Documentation/networking/tproxy.txt85
-rw-r--r--Documentation/networking/vortex.txt9
-rw-r--r--Documentation/pcmcia/driver-changes.txt6
-rw-r--r--Documentation/power/regulator/machine.txt140
-rw-r--r--Documentation/power/regulator/regulator.txt8
-rw-r--r--Documentation/power/s2ram.txt18
-rw-r--r--Documentation/powerpc/00-INDEX4
-rw-r--r--Documentation/powerpc/dts-bindings/fsl/83xx-512x-pci.txt40
-rw-r--r--Documentation/powerpc/dts-bindings/fsl/8xxx_gpio.txt40
-rw-r--r--Documentation/powerpc/dts-bindings/fsl/dma.txt13
-rw-r--r--Documentation/powerpc/dts-bindings/fsl/ssi.txt23
-rw-r--r--Documentation/powerpc/ppc_htab.txt118
-rw-r--r--Documentation/powerpc/smp.txt34
-rw-r--r--Documentation/rfkill.txt32
-rw-r--r--Documentation/s390/CommonIO11
-rw-r--r--Documentation/scheduler/sched-design-CFS.txt395
-rw-r--r--Documentation/scsi/ChangeLog.megaraid6
-rw-r--r--Documentation/scsi/scsi_fc_transport.txt36
-rw-r--r--Documentation/sound/alsa/ALSA-Configuration.txt62
-rw-r--r--Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl65
-rw-r--r--Documentation/sound/alsa/soc/dapm.txt12
-rw-r--r--Documentation/sparc/sbus_drivers.txt309
-rw-r--r--Documentation/spi/pxa2xx34
-rw-r--r--Documentation/sysctl/kernel.txt1
-rw-r--r--Documentation/timers/00-INDEX10
-rw-r--r--Documentation/timers/hpet.txt (renamed from Documentation/hpet.txt)43
-rw-r--r--Documentation/usb/anchors.txt17
-rw-r--r--Documentation/usb/misc_usbsevseg.txt46
-rw-r--r--Documentation/usb/power-management.txt8
-rw-r--r--Documentation/video4linux/CARDLIST.au08282
-rw-r--r--Documentation/video4linux/CARDLIST.bttv1
-rw-r--r--Documentation/video4linux/CARDLIST.cx238852
-rw-r--r--Documentation/video4linux/CARDLIST.cx888
-rw-r--r--Documentation/video4linux/CARDLIST.em28xx4
-rw-r--r--Documentation/video4linux/CARDLIST.saa71348
-rw-r--r--Documentation/video4linux/CARDLIST.tuner2
-rw-r--r--Documentation/video4linux/gspca.txt28
-rw-r--r--Documentation/video4linux/m5602.txt12
-rw-r--r--Documentation/video4linux/soc-camera.txt120
-rw-r--r--Documentation/w1/00-INDEX2
-rw-r--r--Documentation/w1/masters/ds249052
-rw-r--r--Documentation/w1/slaves/00-INDEX4
-rw-r--r--Documentation/w1/slaves/w1_therm41
-rw-r--r--Documentation/w1/w1.generic11
-rw-r--r--Documentation/x86/00-INDEX4
-rw-r--r--Documentation/x86/boot.txt (renamed from Documentation/x86/i386/boot.txt)2
-rw-r--r--Documentation/x86/mtrr.txt (renamed from Documentation/mtrr.txt)4
-rw-r--r--Documentation/x86/pat.txt54
-rw-r--r--Documentation/x86/usb-legacy-support.txt (renamed from Documentation/x86/i386/usb-legacy-support.txt)0
-rw-r--r--Documentation/x86/x86_64/boot-options.txt4
-rw-r--r--Documentation/x86/zero-page.txt (renamed from Documentation/x86/i386/zero-page.txt)0
128 files changed, 6362 insertions, 2930 deletions
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 5b5aba404aac..7286ad090db7 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -21,6 +21,9 @@ Changes
21 - list of changes that break older software packages. 21 - list of changes that break older software packages.
22CodingStyle 22CodingStyle
23 - how the boss likes the C code in the kernel to look. 23 - how the boss likes the C code in the kernel to look.
24development-process/
25 - An extended tutorial on how to work with the kernel development
26 process.
24DMA-API.txt 27DMA-API.txt
25 - DMA API, pci_ API & extensions for non-consistent memory machines. 28 - DMA API, pci_ API & extensions for non-consistent memory machines.
26DMA-ISA-LPC.txt 29DMA-ISA-LPC.txt
@@ -159,8 +162,6 @@ hayes-esp.txt
159 - info on using the Hayes ESP serial driver. 162 - info on using the Hayes ESP serial driver.
160highuid.txt 163highuid.txt
161 - notes on the change from 16 bit to 32 bit user/group IDs. 164 - notes on the change from 16 bit to 32 bit user/group IDs.
162hpet.txt
163 - High Precision Event Timer Driver for Linux.
164timers/ 165timers/
165 - info on the timer related topics 166 - info on the timer related topics
166hw_random.txt 167hw_random.txt
@@ -251,8 +252,6 @@ mono.txt
251 - how to execute Mono-based .NET binaries with the help of BINFMT_MISC. 252 - how to execute Mono-based .NET binaries with the help of BINFMT_MISC.
252moxa-smartio 253moxa-smartio
253 - file with info on installing/using Moxa multiport serial driver. 254 - file with info on installing/using Moxa multiport serial driver.
254mtrr.txt
255 - how to use PPro Memory Type Range Registers to increase performance.
256mutex-design.txt 255mutex-design.txt
257 - info on the generic mutex subsystem. 256 - info on the generic mutex subsystem.
258namespaces/ 257namespaces/
diff --git a/Documentation/ABI/stable/sysfs-driver-usb-usbtmc b/Documentation/ABI/stable/sysfs-driver-usb-usbtmc
new file mode 100644
index 000000000000..9a75fb22187d
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-driver-usb-usbtmc
@@ -0,0 +1,62 @@
1What: /sys/bus/usb/drivers/usbtmc/devices/*/interface_capabilities
2What: /sys/bus/usb/drivers/usbtmc/devices/*/device_capabilities
3Date: August 2008
4Contact: Greg Kroah-Hartman <gregkh@suse.de>
5Description:
6 These files show the various USB TMC capabilities as described
7 by the device itself. The full description of the bitfields
8 can be found in the USB TMC documents from the USB-IF entitled
9 "Universal Serial Bus Test and Measurement Class Specification
10 (USBTMC) Revision 1.0" section 4.2.1.8.
11
12 The files are read only.
13
14
15What: /sys/bus/usb/drivers/usbtmc/devices/*/usb488_interface_capabilities
16What: /sys/bus/usb/drivers/usbtmc/devices/*/usb488_device_capabilities
17Date: August 2008
18Contact: Greg Kroah-Hartman <gregkh@suse.de>
19Description:
20 These files show the various USB TMC capabilities as described
21 by the device itself. The full description of the bitfields
22 can be found in the USB TMC documents from the USB-IF entitled
23 "Universal Serial Bus Test and Measurement Class, Subclass
24 USB488 Specification (USBTMC-USB488) Revision 1.0" section
25 4.2.2.
26
27 The files are read only.
28
29
30What: /sys/bus/usb/drivers/usbtmc/devices/*/TermChar
31Date: August 2008
32Contact: Greg Kroah-Hartman <gregkh@suse.de>
33Description:
34 This file is the TermChar value to be sent to the USB TMC
35 device as described by the document, "Universal Serial Bus Test
36 and Measurement Class Specification
37 (USBTMC) Revision 1.0" as published by the USB-IF.
38
39 Note that the TermCharEnabled file determines if this value is
40 sent to the device or not.
41
42
43What: /sys/bus/usb/drivers/usbtmc/devices/*/TermCharEnabled
44Date: August 2008
45Contact: Greg Kroah-Hartman <gregkh@suse.de>
46Description:
47 This file determines if the TermChar is to be sent to the
48 device on every transaction or not. For more details about
49 this, please see the document, "Universal Serial Bus Test and
50 Measurement Class Specification (USBTMC) Revision 1.0" as
51 published by the USB-IF.
52
53
54What: /sys/bus/usb/drivers/usbtmc/devices/*/auto_abort
55Date: August 2008
56Contact: Greg Kroah-Hartman <gregkh@suse.de>
57Description:
58 This file determines if the the transaction of the USB TMC
59 device is to be automatically aborted if there is any error.
60 For more details about this, please see the document,
61 "Universal Serial Bus Test and Measurement Class Specification
62 (USBTMC) Revision 1.0" as published by the USB-IF.
diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb
index 273a7f099f46..7772928ee48f 100644
--- a/Documentation/ABI/testing/sysfs-bus-usb
+++ b/Documentation/ABI/testing/sysfs-bus-usb
@@ -86,6 +86,22 @@ Users:
86 PowerTOP <power@bughost.org> 86 PowerTOP <power@bughost.org>
87 http://www.lesswatts.org/projects/powertop/ 87 http://www.lesswatts.org/projects/powertop/
88 88
89What: /sys/bus/usb/device/<busnum>-<devnum>...:<config num>-<interface num>/supports_autosuspend
90Date: January 2008
91KernelVersion: 2.6.27
92Contact: Sarah Sharp <sarah.a.sharp@intel.com>
93Description:
94 When read, this file returns 1 if the interface driver
95 for this interface supports autosuspend. It also
96 returns 1 if no driver has claimed this interface, as an
97 unclaimed interface will not stop the device from being
98 autosuspended if all other interface drivers are idle.
99 The file returns 0 if autosuspend support has not been
100 added to the driver.
101Users:
102 USB PM tool
103 git://git.moblin.org/users/sarah/usb-pm-tool/
104
89What: /sys/bus/usb/device/.../authorized 105What: /sys/bus/usb/device/.../authorized
90Date: July 2008 106Date: July 2008
91KernelVersion: 2.6.26 107KernelVersion: 2.6.26
diff --git a/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg b/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg
new file mode 100644
index 000000000000..cb830df8777c
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg
@@ -0,0 +1,43 @@
1Where: /sys/bus/usb/.../powered
2Date: August 2008
3Kernel Version: 2.6.26
4Contact: Harrison Metzger <harrisonmetz@gmail.com>
5Description: Controls whether the device's display will powered.
6 A value of 0 is off and a non-zero value is on.
7
8Where: /sys/bus/usb/.../mode_msb
9Where: /sys/bus/usb/.../mode_lsb
10Date: August 2008
11Kernel Version: 2.6.26
12Contact: Harrison Metzger <harrisonmetz@gmail.com>
13Description: Controls the devices display mode.
14 For a 6 character display the values are
15 MSB 0x06; LSB 0x3F, and
16 for an 8 character display the values are
17 MSB 0x08; LSB 0xFF.
18
19Where: /sys/bus/usb/.../textmode
20Date: August 2008
21Kernel Version: 2.6.26
22Contact: Harrison Metzger <harrisonmetz@gmail.com>
23Description: Controls the way the device interprets its text buffer.
24 raw: each character controls its segment manually
25 hex: each character is between 0-15
26 ascii: each character is between '0'-'9' and 'A'-'F'.
27
28Where: /sys/bus/usb/.../text
29Date: August 2008
30Kernel Version: 2.6.26
31Contact: Harrison Metzger <harrisonmetz@gmail.com>
32Description: The text (or data) for the device to display
33
34Where: /sys/bus/usb/.../decimals
35Date: August 2008
36Kernel Version: 2.6.26
37Contact: Harrison Metzger <harrisonmetz@gmail.com>
38Description: Controls the decimal places on the device.
39 To set the nth decimal place, give this field
40 the value of 10 ** n. Assume this field has
41 the value k and has 1 or more decimal places set,
42 to set the mth place (where m is not already set),
43 change this fields value to k + 10 ** m. \ No newline at end of file
diff --git a/Documentation/ABI/testing/sysfs-class-regulator b/Documentation/ABI/testing/sysfs-class-regulator
index 79a4a75b2d2c..3731f6f29bcb 100644
--- a/Documentation/ABI/testing/sysfs-class-regulator
+++ b/Documentation/ABI/testing/sysfs-class-regulator
@@ -1,7 +1,7 @@
1What: /sys/class/regulator/.../state 1What: /sys/class/regulator/.../state
2Date: April 2008 2Date: April 2008
3KernelVersion: 2.6.26 3KernelVersion: 2.6.26
4Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> 4Contact: Liam Girdwood <lrg@slimlogic.co.uk>
5Description: 5Description:
6 Each regulator directory will contain a field called 6 Each regulator directory will contain a field called
7 state. This holds the regulator output state. 7 state. This holds the regulator output state.
@@ -27,7 +27,7 @@ Description:
27What: /sys/class/regulator/.../type 27What: /sys/class/regulator/.../type
28Date: April 2008 28Date: April 2008
29KernelVersion: 2.6.26 29KernelVersion: 2.6.26
30Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> 30Contact: Liam Girdwood <lrg@slimlogic.co.uk>
31Description: 31Description:
32 Each regulator directory will contain a field called 32 Each regulator directory will contain a field called
33 type. This holds the regulator type. 33 type. This holds the regulator type.
@@ -51,7 +51,7 @@ Description:
51What: /sys/class/regulator/.../microvolts 51What: /sys/class/regulator/.../microvolts
52Date: April 2008 52Date: April 2008
53KernelVersion: 2.6.26 53KernelVersion: 2.6.26
54Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> 54Contact: Liam Girdwood <lrg@slimlogic.co.uk>
55Description: 55Description:
56 Each regulator directory will contain a field called 56 Each regulator directory will contain a field called
57 microvolts. This holds the regulator output voltage setting 57 microvolts. This holds the regulator output voltage setting
@@ -65,7 +65,7 @@ Description:
65What: /sys/class/regulator/.../microamps 65What: /sys/class/regulator/.../microamps
66Date: April 2008 66Date: April 2008
67KernelVersion: 2.6.26 67KernelVersion: 2.6.26
68Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> 68Contact: Liam Girdwood <lrg@slimlogic.co.uk>
69Description: 69Description:
70 Each regulator directory will contain a field called 70 Each regulator directory will contain a field called
71 microamps. This holds the regulator output current limit 71 microamps. This holds the regulator output current limit
@@ -79,7 +79,7 @@ Description:
79What: /sys/class/regulator/.../opmode 79What: /sys/class/regulator/.../opmode
80Date: April 2008 80Date: April 2008
81KernelVersion: 2.6.26 81KernelVersion: 2.6.26
82Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> 82Contact: Liam Girdwood <lrg@slimlogic.co.uk>
83Description: 83Description:
84 Each regulator directory will contain a field called 84 Each regulator directory will contain a field called
85 opmode. This holds the regulator operating mode setting. 85 opmode. This holds the regulator operating mode setting.
@@ -102,7 +102,7 @@ Description:
102What: /sys/class/regulator/.../min_microvolts 102What: /sys/class/regulator/.../min_microvolts
103Date: April 2008 103Date: April 2008
104KernelVersion: 2.6.26 104KernelVersion: 2.6.26
105Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> 105Contact: Liam Girdwood <lrg@slimlogic.co.uk>
106Description: 106Description:
107 Each regulator directory will contain a field called 107 Each regulator directory will contain a field called
108 min_microvolts. This holds the minimum safe working regulator 108 min_microvolts. This holds the minimum safe working regulator
@@ -116,7 +116,7 @@ Description:
116What: /sys/class/regulator/.../max_microvolts 116What: /sys/class/regulator/.../max_microvolts
117Date: April 2008 117Date: April 2008
118KernelVersion: 2.6.26 118KernelVersion: 2.6.26
119Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> 119Contact: Liam Girdwood <lrg@slimlogic.co.uk>
120Description: 120Description:
121 Each regulator directory will contain a field called 121 Each regulator directory will contain a field called
122 max_microvolts. This holds the maximum safe working regulator 122 max_microvolts. This holds the maximum safe working regulator
@@ -130,7 +130,7 @@ Description:
130What: /sys/class/regulator/.../min_microamps 130What: /sys/class/regulator/.../min_microamps
131Date: April 2008 131Date: April 2008
132KernelVersion: 2.6.26 132KernelVersion: 2.6.26
133Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> 133Contact: Liam Girdwood <lrg@slimlogic.co.uk>
134Description: 134Description:
135 Each regulator directory will contain a field called 135 Each regulator directory will contain a field called
136 min_microamps. This holds the minimum safe working regulator 136 min_microamps. This holds the minimum safe working regulator
@@ -145,7 +145,7 @@ Description:
145What: /sys/class/regulator/.../max_microamps 145What: /sys/class/regulator/.../max_microamps
146Date: April 2008 146Date: April 2008
147KernelVersion: 2.6.26 147KernelVersion: 2.6.26
148Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> 148Contact: Liam Girdwood <lrg@slimlogic.co.uk>
149Description: 149Description:
150 Each regulator directory will contain a field called 150 Each regulator directory will contain a field called
151 max_microamps. This holds the maximum safe working regulator 151 max_microamps. This holds the maximum safe working regulator
@@ -157,10 +157,23 @@ Description:
157 platform code. 157 platform code.
158 158
159 159
160What: /sys/class/regulator/.../name
161Date: October 2008
162KernelVersion: 2.6.28
163Contact: Liam Girdwood <lrg@slimlogic.co.uk>
164Description:
165 Each regulator directory will contain a field called
166 name. This holds a string identifying the regulator for
167 display purposes.
168
169 NOTE: this will be empty if no suitable name is provided
170 by platform or regulator drivers.
171
172
160What: /sys/class/regulator/.../num_users 173What: /sys/class/regulator/.../num_users
161Date: April 2008 174Date: April 2008
162KernelVersion: 2.6.26 175KernelVersion: 2.6.26
163Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> 176Contact: Liam Girdwood <lrg@slimlogic.co.uk>
164Description: 177Description:
165 Each regulator directory will contain a field called 178 Each regulator directory will contain a field called
166 num_users. This holds the number of consumer devices that 179 num_users. This holds the number of consumer devices that
@@ -170,7 +183,7 @@ Description:
170What: /sys/class/regulator/.../requested_microamps 183What: /sys/class/regulator/.../requested_microamps
171Date: April 2008 184Date: April 2008
172KernelVersion: 2.6.26 185KernelVersion: 2.6.26
173Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> 186Contact: Liam Girdwood <lrg@slimlogic.co.uk>
174Description: 187Description:
175 Each regulator directory will contain a field called 188 Each regulator directory will contain a field called
176 requested_microamps. This holds the total requested load 189 requested_microamps. This holds the total requested load
@@ -181,7 +194,7 @@ Description:
181What: /sys/class/regulator/.../parent 194What: /sys/class/regulator/.../parent
182Date: April 2008 195Date: April 2008
183KernelVersion: 2.6.26 196KernelVersion: 2.6.26
184Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> 197Contact: Liam Girdwood <lrg@slimlogic.co.uk>
185Description: 198Description:
186 Some regulator directories will contain a link called parent. 199 Some regulator directories will contain a link called parent.
187 This points to the parent or supply regulator if one exists. 200 This points to the parent or supply regulator if one exists.
@@ -189,7 +202,7 @@ Description:
189What: /sys/class/regulator/.../suspend_mem_microvolts 202What: /sys/class/regulator/.../suspend_mem_microvolts
190Date: May 2008 203Date: May 2008
191KernelVersion: 2.6.26 204KernelVersion: 2.6.26
192Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> 205Contact: Liam Girdwood <lrg@slimlogic.co.uk>
193Description: 206Description:
194 Each regulator directory will contain a field called 207 Each regulator directory will contain a field called
195 suspend_mem_microvolts. This holds the regulator output 208 suspend_mem_microvolts. This holds the regulator output
@@ -203,7 +216,7 @@ Description:
203What: /sys/class/regulator/.../suspend_disk_microvolts 216What: /sys/class/regulator/.../suspend_disk_microvolts
204Date: May 2008 217Date: May 2008
205KernelVersion: 2.6.26 218KernelVersion: 2.6.26
206Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> 219Contact: Liam Girdwood <lrg@slimlogic.co.uk>
207Description: 220Description:
208 Each regulator directory will contain a field called 221 Each regulator directory will contain a field called
209 suspend_disk_microvolts. This holds the regulator output 222 suspend_disk_microvolts. This holds the regulator output
@@ -217,7 +230,7 @@ Description:
217What: /sys/class/regulator/.../suspend_standby_microvolts 230What: /sys/class/regulator/.../suspend_standby_microvolts
218Date: May 2008 231Date: May 2008
219KernelVersion: 2.6.26 232KernelVersion: 2.6.26
220Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> 233Contact: Liam Girdwood <lrg@slimlogic.co.uk>
221Description: 234Description:
222 Each regulator directory will contain a field called 235 Each regulator directory will contain a field called
223 suspend_standby_microvolts. This holds the regulator output 236 suspend_standby_microvolts. This holds the regulator output
@@ -231,7 +244,7 @@ Description:
231What: /sys/class/regulator/.../suspend_mem_mode 244What: /sys/class/regulator/.../suspend_mem_mode
232Date: May 2008 245Date: May 2008
233KernelVersion: 2.6.26 246KernelVersion: 2.6.26
234Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> 247Contact: Liam Girdwood <lrg@slimlogic.co.uk>
235Description: 248Description:
236 Each regulator directory will contain a field called 249 Each regulator directory will contain a field called
237 suspend_mem_mode. This holds the regulator operating mode 250 suspend_mem_mode. This holds the regulator operating mode
@@ -245,7 +258,7 @@ Description:
245What: /sys/class/regulator/.../suspend_disk_mode 258What: /sys/class/regulator/.../suspend_disk_mode
246Date: May 2008 259Date: May 2008
247KernelVersion: 2.6.26 260KernelVersion: 2.6.26
248Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> 261Contact: Liam Girdwood <lrg@slimlogic.co.uk>
249Description: 262Description:
250 Each regulator directory will contain a field called 263 Each regulator directory will contain a field called
251 suspend_disk_mode. This holds the regulator operating mode 264 suspend_disk_mode. This holds the regulator operating mode
@@ -258,7 +271,7 @@ Description:
258What: /sys/class/regulator/.../suspend_standby_mode 271What: /sys/class/regulator/.../suspend_standby_mode
259Date: May 2008 272Date: May 2008
260KernelVersion: 2.6.26 273KernelVersion: 2.6.26
261Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> 274Contact: Liam Girdwood <lrg@slimlogic.co.uk>
262Description: 275Description:
263 Each regulator directory will contain a field called 276 Each regulator directory will contain a field called
264 suspend_standby_mode. This holds the regulator operating mode 277 suspend_standby_mode. This holds the regulator operating mode
@@ -272,7 +285,7 @@ Description:
272What: /sys/class/regulator/.../suspend_mem_state 285What: /sys/class/regulator/.../suspend_mem_state
273Date: May 2008 286Date: May 2008
274KernelVersion: 2.6.26 287KernelVersion: 2.6.26
275Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> 288Contact: Liam Girdwood <lrg@slimlogic.co.uk>
276Description: 289Description:
277 Each regulator directory will contain a field called 290 Each regulator directory will contain a field called
278 suspend_mem_state. This holds the regulator operating state 291 suspend_mem_state. This holds the regulator operating state
@@ -287,7 +300,7 @@ Description:
287What: /sys/class/regulator/.../suspend_disk_state 300What: /sys/class/regulator/.../suspend_disk_state
288Date: May 2008 301Date: May 2008
289KernelVersion: 2.6.26 302KernelVersion: 2.6.26
290Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> 303Contact: Liam Girdwood <lrg@slimlogic.co.uk>
291Description: 304Description:
292 Each regulator directory will contain a field called 305 Each regulator directory will contain a field called
293 suspend_disk_state. This holds the regulator operating state 306 suspend_disk_state. This holds the regulator operating state
@@ -302,7 +315,7 @@ Description:
302What: /sys/class/regulator/.../suspend_standby_state 315What: /sys/class/regulator/.../suspend_standby_state
303Date: May 2008 316Date: May 2008
304KernelVersion: 2.6.26 317KernelVersion: 2.6.26
305Contact: Liam Girdwood <lg@opensource.wolfsonmicro.com> 318Contact: Liam Girdwood <lrg@slimlogic.co.uk>
306Description: 319Description:
307 Each regulator directory will contain a field called 320 Each regulator directory will contain a field called
308 suspend_standby_state. This holds the regulator operating 321 suspend_standby_state. This holds the regulator operating
diff --git a/Documentation/ABI/testing/sysfs-profiling b/Documentation/ABI/testing/sysfs-profiling
new file mode 100644
index 000000000000..b02d8b8c173a
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-profiling
@@ -0,0 +1,13 @@
1What: /sys/kernel/profile
2Date: September 2008
3Contact: Dave Hansen <dave@linux.vnet.ibm.com>
4Description:
5 /sys/kernel/profile is the runtime equivalent
6 of the boot-time profile= option.
7
8 You can get the same effect running:
9
10 echo 2 > /sys/kernel/profile
11
12 as you would by issuing profile=2 on the boot
13 command line.
diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.txt
index d8b63d164e41..b8e86460046e 100644
--- a/Documentation/DMA-API.txt
+++ b/Documentation/DMA-API.txt
@@ -337,7 +337,7 @@ With scatterlists, you use the resulting mapping like this:
337 int i, count = dma_map_sg(dev, sglist, nents, direction); 337 int i, count = dma_map_sg(dev, sglist, nents, direction);
338 struct scatterlist *sg; 338 struct scatterlist *sg;
339 339
340 for (i = 0, sg = sglist; i < count; i++, sg++) { 340 for_each_sg(sglist, sg, count, i) {
341 hw_address[i] = sg_dma_address(sg); 341 hw_address[i] = sg_dma_address(sg);
342 hw_len[i] = sg_dma_len(sg); 342 hw_len[i] = sg_dma_len(sg);
343 } 343 }
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 1615350b7b53..fabc06466b93 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -6,7 +6,7 @@
6# To add a new book the only step required is to add the book to the 6# To add a new book the only step required is to add the book to the
7# list of DOCBOOKS. 7# list of DOCBOOKS.
8 8
9DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \ 9DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml \
10 kernel-hacking.xml kernel-locking.xml deviceiobook.xml \ 10 kernel-hacking.xml kernel-locking.xml deviceiobook.xml \
11 procfs-guide.xml writing_usb_driver.xml networking.xml \ 11 procfs-guide.xml writing_usb_driver.xml networking.xml \
12 kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \ 12 kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \
diff --git a/Documentation/DocBook/gadget.tmpl b/Documentation/DocBook/gadget.tmpl
index ea3bc9565e6a..6ef2f0073e5a 100644
--- a/Documentation/DocBook/gadget.tmpl
+++ b/Documentation/DocBook/gadget.tmpl
@@ -557,6 +557,9 @@ Near-term plans include converting all of them, except for "gadgetfs".
557</para> 557</para>
558 558
559!Edrivers/usb/gadget/f_acm.c 559!Edrivers/usb/gadget/f_acm.c
560!Edrivers/usb/gadget/f_ecm.c
561!Edrivers/usb/gadget/f_subset.c
562!Edrivers/usb/gadget/f_obex.c
560!Edrivers/usb/gadget/f_serial.c 563!Edrivers/usb/gadget/f_serial.c
561 564
562</sect1> 565</sect1>
diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl
index b7b1482f6e04..9d0058e788e5 100644
--- a/Documentation/DocBook/kernel-api.tmpl
+++ b/Documentation/DocBook/kernel-api.tmpl
@@ -283,6 +283,7 @@ X!Earch/x86/kernel/mca_32.c
283 <chapter id="security"> 283 <chapter id="security">
284 <title>Security Framework</title> 284 <title>Security Framework</title>
285!Isecurity/security.c 285!Isecurity/security.c
286!Esecurity/inode.c
286 </chapter> 287 </chapter>
287 288
288 <chapter id="audit"> 289 <chapter id="audit">
@@ -364,6 +365,10 @@ X!Edrivers/pnp/system.c
364!Eblock/blk-barrier.c 365!Eblock/blk-barrier.c
365!Eblock/blk-tag.c 366!Eblock/blk-tag.c
366!Iblock/blk-tag.c 367!Iblock/blk-tag.c
368!Eblock/blk-integrity.c
369!Iblock/blktrace.c
370!Iblock/genhd.c
371!Eblock/genhd.c
367 </chapter> 372 </chapter>
368 373
369 <chapter id="chrdev"> 374 <chapter id="chrdev">
diff --git a/Documentation/DocBook/mac80211.tmpl b/Documentation/DocBook/mac80211.tmpl
index b651e0a4b1c0..77c3c202991b 100644
--- a/Documentation/DocBook/mac80211.tmpl
+++ b/Documentation/DocBook/mac80211.tmpl
@@ -145,7 +145,6 @@ usage should require reading the full document.
145 this though and the recommendation to allow only a single 145 this though and the recommendation to allow only a single
146 interface in STA mode at first! 146 interface in STA mode at first!
147 </para> 147 </para>
148!Finclude/net/mac80211.h ieee80211_if_types
149!Finclude/net/mac80211.h ieee80211_if_init_conf 148!Finclude/net/mac80211.h ieee80211_if_init_conf
150!Finclude/net/mac80211.h ieee80211_if_conf 149!Finclude/net/mac80211.h ieee80211_if_conf
151 </chapter> 150 </chapter>
@@ -177,8 +176,7 @@ usage should require reading the full document.
177 <title>functions/definitions</title> 176 <title>functions/definitions</title>
178!Finclude/net/mac80211.h ieee80211_rx_status 177!Finclude/net/mac80211.h ieee80211_rx_status
179!Finclude/net/mac80211.h mac80211_rx_flags 178!Finclude/net/mac80211.h mac80211_rx_flags
180!Finclude/net/mac80211.h ieee80211_tx_control 179!Finclude/net/mac80211.h ieee80211_tx_info
181!Finclude/net/mac80211.h ieee80211_tx_status_flags
182!Finclude/net/mac80211.h ieee80211_rx 180!Finclude/net/mac80211.h ieee80211_rx
183!Finclude/net/mac80211.h ieee80211_rx_irqsafe 181!Finclude/net/mac80211.h ieee80211_rx_irqsafe
184!Finclude/net/mac80211.h ieee80211_tx_status 182!Finclude/net/mac80211.h ieee80211_tx_status
@@ -189,12 +187,11 @@ usage should require reading the full document.
189!Finclude/net/mac80211.h ieee80211_ctstoself_duration 187!Finclude/net/mac80211.h ieee80211_ctstoself_duration
190!Finclude/net/mac80211.h ieee80211_generic_frame_duration 188!Finclude/net/mac80211.h ieee80211_generic_frame_duration
191!Finclude/net/mac80211.h ieee80211_get_hdrlen_from_skb 189!Finclude/net/mac80211.h ieee80211_get_hdrlen_from_skb
192!Finclude/net/mac80211.h ieee80211_get_hdrlen 190!Finclude/net/mac80211.h ieee80211_hdrlen
193!Finclude/net/mac80211.h ieee80211_wake_queue 191!Finclude/net/mac80211.h ieee80211_wake_queue
194!Finclude/net/mac80211.h ieee80211_stop_queue 192!Finclude/net/mac80211.h ieee80211_stop_queue
195!Finclude/net/mac80211.h ieee80211_start_queues
196!Finclude/net/mac80211.h ieee80211_stop_queues
197!Finclude/net/mac80211.h ieee80211_wake_queues 193!Finclude/net/mac80211.h ieee80211_wake_queues
194!Finclude/net/mac80211.h ieee80211_stop_queues
198 </sect1> 195 </sect1>
199 </chapter> 196 </chapter>
200 197
@@ -230,8 +227,7 @@ usage should require reading the full document.
230 <title>Multiple queues and QoS support</title> 227 <title>Multiple queues and QoS support</title>
231 <para>TBD</para> 228 <para>TBD</para>
232!Finclude/net/mac80211.h ieee80211_tx_queue_params 229!Finclude/net/mac80211.h ieee80211_tx_queue_params
233!Finclude/net/mac80211.h ieee80211_tx_queue_stats_data 230!Finclude/net/mac80211.h ieee80211_tx_queue_stats
234!Finclude/net/mac80211.h ieee80211_tx_queue
235 </chapter> 231 </chapter>
236 232
237 <chapter id="AP"> 233 <chapter id="AP">
diff --git a/Documentation/DocBook/procfs-guide.tmpl b/Documentation/DocBook/procfs-guide.tmpl
index 8a5dc6e021ff..9eba4b7af73d 100644
--- a/Documentation/DocBook/procfs-guide.tmpl
+++ b/Documentation/DocBook/procfs-guide.tmpl
@@ -14,17 +14,20 @@
14 <othername>(J.A.K.)</othername> 14 <othername>(J.A.K.)</othername>
15 <surname>Mouw</surname> 15 <surname>Mouw</surname>
16 <affiliation> 16 <affiliation>
17 <orgname>Delft University of Technology</orgname>
18 <orgdiv>Faculty of Information Technology and Systems</orgdiv>
19 <address> 17 <address>
20 <email>J.A.K.Mouw@its.tudelft.nl</email> 18 <email>mouw@nl.linux.org</email>
21 <pob>PO BOX 5031</pob>
22 <postcode>2600 GA</postcode>
23 <city>Delft</city>
24 <country>The Netherlands</country>
25 </address> 19 </address>
26 </affiliation> 20 </affiliation>
27 </author> 21 </author>
22 <othercredit>
23 <contrib>
24 This software and documentation were written while working on the
25 LART computing board
26 (<ulink url="http://www.lartmaker.nl/">http://www.lartmaker.nl/</ulink>),
27 which was sponsored by the Delt University of Technology projects
28 Mobile Multi-media Communications and Ubiquitous Communications.
29 </contrib>
30 </othercredit>
28 </authorgroup> 31 </authorgroup>
29 32
30 <revhistory> 33 <revhistory>
@@ -109,18 +112,6 @@
109 </para> 112 </para>
110 113
111 <para> 114 <para>
112 This documentation was written while working on the LART
113 computing board (<ulink
114 url="http://www.lart.tudelft.nl/">http://www.lart.tudelft.nl/</ulink>),
115 which is sponsored by the Mobile Multi-media Communications
116 (<ulink
117 url="http://www.mmc.tudelft.nl/">http://www.mmc.tudelft.nl/</ulink>)
118 and Ubiquitous Communications (<ulink
119 url="http://www.ubicom.tudelft.nl/">http://www.ubicom.tudelft.nl/</ulink>)
120 projects.
121 </para>
122
123 <para>
124 Erik 115 Erik
125 </para> 116 </para>
126 </preface> 117 </preface>
diff --git a/Documentation/DocBook/procfs_example.c b/Documentation/DocBook/procfs_example.c
index 2f3de0fb8365..8c6396e4bf31 100644
--- a/Documentation/DocBook/procfs_example.c
+++ b/Documentation/DocBook/procfs_example.c
@@ -1,28 +1,16 @@
1/* 1/*
2 * procfs_example.c: an example proc interface 2 * procfs_example.c: an example proc interface
3 * 3 *
4 * Copyright (C) 2001, Erik Mouw (J.A.K.Mouw@its.tudelft.nl) 4 * Copyright (C) 2001, Erik Mouw (mouw@nl.linux.org)
5 * 5 *
6 * This file accompanies the procfs-guide in the Linux kernel 6 * This file accompanies the procfs-guide in the Linux kernel
7 * source. Its main use is to demonstrate the concepts and 7 * source. Its main use is to demonstrate the concepts and
8 * functions described in the guide. 8 * functions described in the guide.
9 * 9 *
10 * This software has been developed while working on the LART 10 * This software has been developed while working on the LART
11 * computing board (http://www.lart.tudelft.nl/), which is 11 * computing board (http://www.lartmaker.nl), which was sponsored
12 * sponsored by the Mobile Multi-media Communications 12 * by the Delt University of Technology projects Mobile Multi-media
13 * (http://www.mmc.tudelft.nl/) and Ubiquitous Communications 13 * Communications and Ubiquitous Communications.
14 * (http://www.ubicom.tudelft.nl/) projects.
15 *
16 * The author can be reached at:
17 *
18 * Erik Mouw
19 * Information and Communication Theory Group
20 * Faculty of Information Technology and Systems
21 * Delft University of Technology
22 * P.O. Box 5031
23 * 2600 GA Delft
24 * The Netherlands
25 *
26 * 14 *
27 * This program is free software; you can redistribute 15 * This program is free software; you can redistribute
28 * it and/or modify it under the terms of the GNU General 16 * it and/or modify it under the terms of the GNU General
diff --git a/Documentation/DocBook/videobook.tmpl b/Documentation/DocBook/videobook.tmpl
deleted file mode 100644
index 0bc25949b668..000000000000
--- a/Documentation/DocBook/videobook.tmpl
+++ /dev/null
@@ -1,1654 +0,0 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
4
5<book id="V4LGuide">
6 <bookinfo>
7 <title>Video4Linux Programming</title>
8
9 <authorgroup>
10 <author>
11 <firstname>Alan</firstname>
12 <surname>Cox</surname>
13 <affiliation>
14 <address>
15 <email>alan@redhat.com</email>
16 </address>
17 </affiliation>
18 </author>
19 </authorgroup>
20
21 <copyright>
22 <year>2000</year>
23 <holder>Alan Cox</holder>
24 </copyright>
25
26 <legalnotice>
27 <para>
28 This documentation is free software; you can redistribute
29 it and/or modify it under the terms of the GNU General Public
30 License as published by the Free Software Foundation; either
31 version 2 of the License, or (at your option) any later
32 version.
33 </para>
34
35 <para>
36 This program is distributed in the hope that it will be
37 useful, but WITHOUT ANY WARRANTY; without even the implied
38 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
39 See the GNU General Public License for more details.
40 </para>
41
42 <para>
43 You should have received a copy of the GNU General Public
44 License along with this program; if not, write to the Free
45 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
46 MA 02111-1307 USA
47 </para>
48
49 <para>
50 For more details see the file COPYING in the source
51 distribution of Linux.
52 </para>
53 </legalnotice>
54 </bookinfo>
55
56<toc></toc>
57
58 <chapter id="intro">
59 <title>Introduction</title>
60 <para>
61 Parts of this document first appeared in Linux Magazine under a
62 ninety day exclusivity.
63 </para>
64 <para>
65 Video4Linux is intended to provide a common programming interface
66 for the many TV and capture cards now on the market, as well as
67 parallel port and USB video cameras. Radio, teletext decoders and
68 vertical blanking data interfaces are also provided.
69 </para>
70 </chapter>
71 <chapter id="radio">
72 <title>Radio Devices</title>
73 <para>
74 There are a wide variety of radio interfaces available for PC's, and these
75 are generally very simple to program. The biggest problem with supporting
76 such devices is normally extracting documentation from the vendor.
77 </para>
78 <para>
79 The radio interface supports a simple set of control ioctls standardised
80 across all radio and tv interfaces. It does not support read or write, which
81 are used for video streams. The reason radio cards do not allow you to read
82 the audio stream into an application is that without exception they provide
83 a connection on to a soundcard. Soundcards can be used to read the radio
84 data just fine.
85 </para>
86 <sect1 id="registerradio">
87 <title>Registering Radio Devices</title>
88 <para>
89 The Video4linux core provides an interface for registering devices. The
90 first step in writing our radio card driver is to register it.
91 </para>
92 <programlisting>
93
94
95static struct video_device my_radio
96{
97 "My radio",
98 VID_TYPE_TUNER,
99 radio_open.
100 radio_close,
101 NULL, /* no read */
102 NULL, /* no write */
103 NULL, /* no poll */
104 radio_ioctl,
105 NULL, /* no special init function */
106 NULL /* no private data */
107};
108
109
110 </programlisting>
111 <para>
112 This declares our video4linux device driver interface. The VID_TYPE_ value
113 defines what kind of an interface we are, and defines basic capabilities.
114 </para>
115 <para>
116 The only defined value relevant for a radio card is VID_TYPE_TUNER which
117 indicates that the device can be tuned. Clearly our radio is going to have some
118 way to change channel so it is tuneable.
119 </para>
120 <para>
121 We declare an open and close routine, but we do not need read or write,
122 which are used to read and write video data to or from the card itself. As
123 we have no read or write there is no poll function.
124 </para>
125 <para>
126 The private initialise function is run when the device is registered. In
127 this driver we've already done all the work needed. The final pointer is a
128 private data pointer that can be used by the device driver to attach and
129 retrieve private data structures. We set this field "priv" to NULL for
130 the moment.
131 </para>
132 <para>
133 Having the structure defined is all very well but we now need to register it
134 with the kernel.
135 </para>
136 <programlisting>
137
138
139static int io = 0x320;
140
141int __init myradio_init(struct video_init *v)
142{
143 if(!request_region(io, MY_IO_SIZE, "myradio"))
144 {
145 printk(KERN_ERR
146 "myradio: port 0x%03X is in use.\n", io);
147 return -EBUSY;
148 }
149
150 if(video_device_register(&amp;my_radio, VFL_TYPE_RADIO)==-1) {
151 release_region(io, MY_IO_SIZE);
152 return -EINVAL;
153 }
154 return 0;
155}
156
157 </programlisting>
158 <para>
159 The first stage of the initialisation, as is normally the case, is to check
160 that the I/O space we are about to fiddle with doesn't belong to some other
161 driver. If it is we leave well alone. If the user gives the address of the
162 wrong device then we will spot this. These policies will generally avoid
163 crashing the machine.
164 </para>
165 <para>
166 Now we ask the Video4Linux layer to register the device for us. We hand it
167 our carefully designed video_device structure and also tell it which group
168 of devices we want it registered with. In this case VFL_TYPE_RADIO.
169 </para>
170 <para>
171 The types available are
172 </para>
173 <table frame="all" id="Device_Types"><title>Device Types</title>
174 <tgroup cols="3" align="left">
175 <tbody>
176 <row>
177 <entry>VFL_TYPE_RADIO</entry><entry>/dev/radio{n}</entry><entry>
178
179 Radio devices are assigned in this block. As with all of these
180 selections the actual number assignment is done by the video layer
181 accordijng to what is free.</entry>
182 </row><row>
183 <entry>VFL_TYPE_GRABBER</entry><entry>/dev/video{n}</entry><entry>
184 Video capture devices and also -- counter-intuitively for the name --
185 hardware video playback devices such as MPEG2 cards.</entry>
186 </row><row>
187 <entry>VFL_TYPE_VBI</entry><entry>/dev/vbi{n}</entry><entry>
188 The VBI devices capture the hidden lines on a television picture
189 that carry further information like closed caption data, teletext
190 (primarily in Europe) and now Intercast and the ATVEC internet
191 television encodings.</entry>
192 </row><row>
193 <entry>VFL_TYPE_VTX</entry><entry>/dev/vtx[n}</entry><entry>
194 VTX is 'Videotext' also known as 'Teletext'. This is a system for
195 sending numbered, 40x25, mostly textual page images over the hidden
196 lines. Unlike the /dev/vbi interfaces, this is for 'smart' decoder
197 chips. (The use of the word smart here has to be taken in context,
198 the smartest teletext chips are fairly dumb pieces of technology).
199 </entry>
200 </row>
201 </tbody>
202 </tgroup>
203 </table>
204 <para>
205 We are most definitely a radio.
206 </para>
207 <para>
208 Finally we allocate our I/O space so that nobody treads on us and return 0
209 to signify general happiness with the state of the universe.
210 </para>
211 </sect1>
212 <sect1 id="openradio">
213 <title>Opening And Closing The Radio</title>
214
215 <para>
216 The functions we declared in our video_device are mostly very simple.
217 Firstly we can drop in what is basically standard code for open and close.
218 </para>
219 <programlisting>
220
221
222static int users = 0;
223
224static int radio_open(struct video_device *dev, int flags)
225{
226 if(users)
227 return -EBUSY;
228 users++;
229 return 0;
230}
231
232 </programlisting>
233 <para>
234 At open time we need to do nothing but check if someone else is also using
235 the radio card. If nobody is using it we make a note that we are using it,
236 then we ensure that nobody unloads our driver on us.
237 </para>
238 <programlisting>
239
240
241static int radio_close(struct video_device *dev)
242{
243 users--;
244}
245
246 </programlisting>
247 <para>
248 At close time we simply need to reduce the user count and allow the module
249 to become unloadable.
250 </para>
251 <para>
252 If you are sharp you will have noticed neither the open nor the close
253 routines attempt to reset or change the radio settings. This is intentional.
254 It allows an application to set up the radio and exit. It avoids a user
255 having to leave an application running all the time just to listen to the
256 radio.
257 </para>
258 </sect1>
259 <sect1 id="ioctlradio">
260 <title>The Ioctl Interface</title>
261 <para>
262 This leaves the ioctl routine, without which the driver will not be
263 terribly useful to anyone.
264 </para>
265 <programlisting>
266
267
268static int radio_ioctl(struct video_device *dev, unsigned int cmd, void *arg)
269{
270 switch(cmd)
271 {
272 case VIDIOCGCAP:
273 {
274 struct video_capability v;
275 v.type = VID_TYPE_TUNER;
276 v.channels = 1;
277 v.audios = 1;
278 v.maxwidth = 0;
279 v.minwidth = 0;
280 v.maxheight = 0;
281 v.minheight = 0;
282 strcpy(v.name, "My Radio");
283 if(copy_to_user(arg, &amp;v, sizeof(v)))
284 return -EFAULT;
285 return 0;
286 }
287
288 </programlisting>
289 <para>
290 VIDIOCGCAP is the first ioctl all video4linux devices must support. It
291 allows the applications to find out what sort of a card they have found and
292 to figure out what they want to do about it. The fields in the structure are
293 </para>
294 <table frame="all" id="video_capability_fields"><title>struct video_capability fields</title>
295 <tgroup cols="2" align="left">
296 <tbody>
297 <row>
298 <entry>name</entry><entry>The device text name. This is intended for the user.</entry>
299 </row><row>
300 <entry>channels</entry><entry>The number of different channels you can tune on
301 this card. It could even by zero for a card that has
302 no tuning capability. For our simple FM radio it is 1.
303 An AM/FM radio would report 2.</entry>
304 </row><row>
305 <entry>audios</entry><entry>The number of audio inputs on this device. For our
306 radio there is only one audio input.</entry>
307 </row><row>
308 <entry>minwidth,minheight</entry><entry>The smallest size the card is capable of capturing
309 images in. We set these to zero. Radios do not
310 capture pictures</entry>
311 </row><row>
312 <entry>maxwidth,maxheight</entry><entry>The largest image size the card is capable of
313 capturing. For our radio we report 0.
314 </entry>
315 </row><row>
316 <entry>type</entry><entry>This reports the capabilities of the device, and
317 matches the field we filled in in the struct
318 video_device when registering.</entry>
319 </row>
320 </tbody>
321 </tgroup>
322 </table>
323 <para>
324 Having filled in the fields, we use copy_to_user to copy the structure into
325 the users buffer. If the copy fails we return an EFAULT to the application
326 so that it knows it tried to feed us garbage.
327 </para>
328 <para>
329 The next pair of ioctl operations select which tuner is to be used and let
330 the application find the tuner properties. We have only a single FM band
331 tuner in our example device.
332 </para>
333 <programlisting>
334
335
336 case VIDIOCGTUNER:
337 {
338 struct video_tuner v;
339 if(copy_from_user(&amp;v, arg, sizeof(v))!=0)
340 return -EFAULT;
341 if(v.tuner)
342 return -EINVAL;
343 v.rangelow=(87*16000);
344 v.rangehigh=(108*16000);
345 v.flags = VIDEO_TUNER_LOW;
346 v.mode = VIDEO_MODE_AUTO;
347 v.signal = 0xFFFF;
348 strcpy(v.name, "FM");
349 if(copy_to_user(&amp;v, arg, sizeof(v))!=0)
350 return -EFAULT;
351 return 0;
352 }
353
354 </programlisting>
355 <para>
356 The VIDIOCGTUNER ioctl allows applications to query a tuner. The application
357 sets the tuner field to the tuner number it wishes to query. The query does
358 not change the tuner that is being used, it merely enquires about the tuner
359 in question.
360 </para>
361 <para>
362 We have exactly one tuner so after copying the user buffer to our temporary
363 structure we complain if they asked for a tuner other than tuner 0.
364 </para>
365 <para>
366 The video_tuner structure has the following fields
367 </para>
368 <table frame="all" id="video_tuner_fields"><title>struct video_tuner fields</title>
369 <tgroup cols="2" align="left">
370 <tbody>
371 <row>
372 <entry>int tuner</entry><entry>The number of the tuner in question</entry>
373 </row><row>
374 <entry>char name[32]</entry><entry>A text description of this tuner. "FM" will do fine.
375 This is intended for the application.</entry>
376 </row><row>
377 <entry>u32 flags</entry>
378 <entry>Tuner capability flags</entry>
379 </row>
380 <row>
381 <entry>u16 mode</entry><entry>The current reception mode</entry>
382
383 </row><row>
384 <entry>u16 signal</entry><entry>The signal strength scaled between 0 and 65535. If
385 a device cannot tell the signal strength it should
386 report 65535. Many simple cards contain only a
387 signal/no signal bit. Such cards will report either
388 0 or 65535.</entry>
389
390 </row><row>
391 <entry>u32 rangelow, rangehigh</entry><entry>
392 The range of frequencies supported by the radio
393 or TV. It is scaled according to the VIDEO_TUNER_LOW
394 flag.</entry>
395
396 </row>
397 </tbody>
398 </tgroup>
399 </table>
400
401 <table frame="all" id="video_tuner_flags"><title>struct video_tuner flags</title>
402 <tgroup cols="2" align="left">
403 <tbody>
404 <row>
405 <entry>VIDEO_TUNER_PAL</entry><entry>A PAL TV tuner</entry>
406 </row><row>
407 <entry>VIDEO_TUNER_NTSC</entry><entry>An NTSC (US) TV tuner</entry>
408 </row><row>
409 <entry>VIDEO_TUNER_SECAM</entry><entry>A SECAM (French) TV tuner</entry>
410 </row><row>
411 <entry>VIDEO_TUNER_LOW</entry><entry>
412 The tuner frequency is scaled in 1/16th of a KHz
413 steps. If not it is in 1/16th of a MHz steps
414 </entry>
415 </row><row>
416 <entry>VIDEO_TUNER_NORM</entry><entry>The tuner can set its format</entry>
417 </row><row>
418 <entry>VIDEO_TUNER_STEREO_ON</entry><entry>The tuner is currently receiving a stereo signal</entry>
419 </row>
420 </tbody>
421 </tgroup>
422 </table>
423
424 <table frame="all" id="video_tuner_modes"><title>struct video_tuner modes</title>
425 <tgroup cols="2" align="left">
426 <tbody>
427 <row>
428 <entry>VIDEO_MODE_PAL</entry><entry>PAL Format</entry>
429 </row><row>
430 <entry>VIDEO_MODE_NTSC</entry><entry>NTSC Format (USA)</entry>
431 </row><row>
432 <entry>VIDEO_MODE_SECAM</entry><entry>French Format</entry>
433 </row><row>
434 <entry>VIDEO_MODE_AUTO</entry><entry>A device that does not need to do
435 TV format switching</entry>
436 </row>
437 </tbody>
438 </tgroup>
439 </table>
440 <para>
441 The settings for the radio card are thus fairly simple. We report that we
442 are a tuner called "FM" for FM radio. In order to get the best tuning
443 resolution we report VIDEO_TUNER_LOW and select tuning to 1/16th of KHz. Its
444 unlikely our card can do that resolution but it is a fair bet the card can
445 do better than 1/16th of a MHz. VIDEO_TUNER_LOW is appropriate to almost all
446 radio usage.
447 </para>
448 <para>
449 We report that the tuner automatically handles deciding what format it is
450 receiving - true enough as it only handles FM radio. Our example card is
451 also incapable of detecting stereo or signal strengths so it reports a
452 strength of 0xFFFF (maximum) and no stereo detected.
453 </para>
454 <para>
455 To finish off we set the range that can be tuned to be 87-108Mhz, the normal
456 FM broadcast radio range. It is important to find out what the card is
457 actually capable of tuning. It is easy enough to simply use the FM broadcast
458 range. Unfortunately if you do this you will discover the FM broadcast
459 ranges in the USA, Europe and Japan are all subtly different and some users
460 cannot receive all the stations they wish.
461 </para>
462 <para>
463 The application also needs to be able to set the tuner it wishes to use. In
464 our case, with a single tuner this is rather simple to arrange.
465 </para>
466 <programlisting>
467
468 case VIDIOCSTUNER:
469 {
470 struct video_tuner v;
471 if(copy_from_user(&amp;v, arg, sizeof(v)))
472 return -EFAULT;
473 if(v.tuner != 0)
474 return -EINVAL;
475 return 0;
476 }
477
478 </programlisting>
479 <para>
480 We copy the user supplied structure into kernel memory so we can examine it.
481 If the user has selected a tuner other than zero we reject the request. If
482 they wanted tuner 0 then, surprisingly enough, that is the current tuner already.
483 </para>
484 <para>
485 The next two ioctls we need to provide are to get and set the frequency of
486 the radio. These both use an unsigned long argument which is the frequency.
487 The scale of the frequency depends on the VIDEO_TUNER_LOW flag as I
488 mentioned earlier on. Since we have VIDEO_TUNER_LOW set this will be in
489 1/16ths of a KHz.
490 </para>
491 <programlisting>
492
493static unsigned long current_freq;
494
495
496
497 case VIDIOCGFREQ:
498 if(copy_to_user(arg, &amp;current_freq,
499 sizeof(unsigned long))
500 return -EFAULT;
501 return 0;
502
503 </programlisting>
504 <para>
505 Querying the frequency in our case is relatively simple. Our radio card is
506 too dumb to let us query the signal strength so we remember our setting if
507 we know it. All we have to do is copy it to the user.
508 </para>
509 <programlisting>
510
511
512 case VIDIOCSFREQ:
513 {
514 u32 freq;
515 if(copy_from_user(arg, &amp;freq,
516 sizeof(unsigned long))!=0)
517 return -EFAULT;
518 if(hardware_set_freq(freq)&lt;0)
519 return -EINVAL;
520 current_freq = freq;
521 return 0;
522 }
523
524 </programlisting>
525 <para>
526 Setting the frequency is a little more complex. We begin by copying the
527 desired frequency into kernel space. Next we call a hardware specific routine
528 to set the radio up. This might be as simple as some scaling and a few
529 writes to an I/O port. For most radio cards it turns out a good deal more
530 complicated and may involve programming things like a phase locked loop on
531 the card. This is what documentation is for.
532 </para>
533 <para>
534 The final set of operations we need to provide for our radio are the
535 volume controls. Not all radio cards can even do volume control. After all
536 there is a perfectly good volume control on the sound card. We will assume
537 our radio card has a simple 4 step volume control.
538 </para>
539 <para>
540 There are two ioctls with audio we need to support
541 </para>
542 <programlisting>
543
544static int current_volume=0;
545
546 case VIDIOCGAUDIO:
547 {
548 struct video_audio v;
549 if(copy_from_user(&amp;v, arg, sizeof(v)))
550 return -EFAULT;
551 if(v.audio != 0)
552 return -EINVAL;
553 v.volume = 16384*current_volume;
554 v.step = 16384;
555 strcpy(v.name, "Radio");
556 v.mode = VIDEO_SOUND_MONO;
557 v.balance = 0;
558 v.base = 0;
559 v.treble = 0;
560
561 if(copy_to_user(arg. &amp;v, sizeof(v)))
562 return -EFAULT;
563 return 0;
564 }
565
566 </programlisting>
567 <para>
568 Much like the tuner we start by copying the user structure into kernel
569 space. Again we check if the user has asked for a valid audio input. We have
570 only input 0 and we punt if they ask for another input.
571 </para>
572 <para>
573 Then we fill in the video_audio structure. This has the following format
574 </para>
575 <table frame="all" id="video_audio_fields"><title>struct video_audio fields</title>
576 <tgroup cols="2" align="left">
577 <tbody>
578 <row>
579 <entry>audio</entry><entry>The input the user wishes to query</entry>
580 </row><row>
581 <entry>volume</entry><entry>The volume setting on a scale of 0-65535</entry>
582 </row><row>
583 <entry>base</entry><entry>The base level on a scale of 0-65535</entry>
584 </row><row>
585 <entry>treble</entry><entry>The treble level on a scale of 0-65535</entry>
586 </row><row>
587 <entry>flags</entry><entry>The features this audio device supports
588 </entry>
589 </row><row>
590 <entry>name</entry><entry>A text name to display to the user. We picked
591 "Radio" as it explains things quite nicely.</entry>
592 </row><row>
593 <entry>mode</entry><entry>The current reception mode for the audio
594
595 We report MONO because our card is too stupid to know if it is in
596 mono or stereo.
597 </entry>
598 </row><row>
599 <entry>balance</entry><entry>The stereo balance on a scale of 0-65535, 32768 is
600 middle.</entry>
601 </row><row>
602 <entry>step</entry><entry>The step by which the volume control jumps. This is
603 used to help make it easy for applications to set
604 slider behaviour.</entry>
605 </row>
606 </tbody>
607 </tgroup>
608 </table>
609
610 <table frame="all" id="video_audio_flags"><title>struct video_audio flags</title>
611 <tgroup cols="2" align="left">
612 <tbody>
613 <row>
614 <entry>VIDEO_AUDIO_MUTE</entry><entry>The audio is currently muted. We
615 could fake this in our driver but we
616 choose not to bother.</entry>
617 </row><row>
618 <entry>VIDEO_AUDIO_MUTABLE</entry><entry>The input has a mute option</entry>
619 </row><row>
620 <entry>VIDEO_AUDIO_TREBLE</entry><entry>The input has a treble control</entry>
621 </row><row>
622 <entry>VIDEO_AUDIO_BASS</entry><entry>The input has a base control</entry>
623 </row>
624 </tbody>
625 </tgroup>
626 </table>
627
628 <table frame="all" id="video_audio_modes"><title>struct video_audio modes</title>
629 <tgroup cols="2" align="left">
630 <tbody>
631 <row>
632 <entry>VIDEO_SOUND_MONO</entry><entry>Mono sound</entry>
633 </row><row>
634 <entry>VIDEO_SOUND_STEREO</entry><entry>Stereo sound</entry>
635 </row><row>
636 <entry>VIDEO_SOUND_LANG1</entry><entry>Alternative language 1 (TV specific)</entry>
637 </row><row>
638 <entry>VIDEO_SOUND_LANG2</entry><entry>Alternative language 2 (TV specific)</entry>
639 </row>
640 </tbody>
641 </tgroup>
642 </table>
643 <para>
644 Having filled in the structure we copy it back to user space.
645 </para>
646 <para>
647 The VIDIOCSAUDIO ioctl allows the user to set the audio parameters in the
648 video_audio structure. The driver does its best to honour the request.
649 </para>
650 <programlisting>
651
652 case VIDIOCSAUDIO:
653 {
654 struct video_audio v;
655 if(copy_from_user(&amp;v, arg, sizeof(v)))
656 return -EFAULT;
657 if(v.audio)
658 return -EINVAL;
659 current_volume = v/16384;
660 hardware_set_volume(current_volume);
661 return 0;
662 }
663
664 </programlisting>
665 <para>
666 In our case there is very little that the user can set. The volume is
667 basically the limit. Note that we could pretend to have a mute feature
668 by rewriting this to
669 </para>
670 <programlisting>
671
672 case VIDIOCSAUDIO:
673 {
674 struct video_audio v;
675 if(copy_from_user(&amp;v, arg, sizeof(v)))
676 return -EFAULT;
677 if(v.audio)
678 return -EINVAL;
679 current_volume = v/16384;
680 if(v.flags&amp;VIDEO_AUDIO_MUTE)
681 hardware_set_volume(0);
682 else
683 hardware_set_volume(current_volume);
684 current_muted = v.flags &amp;
685 VIDEO_AUDIO_MUTE;
686 return 0;
687 }
688
689 </programlisting>
690 <para>
691 This with the corresponding changes to the VIDIOCGAUDIO code to report the
692 state of the mute flag we save and to report the card has a mute function,
693 will allow applications to use a mute facility with this card. It is
694 questionable whether this is a good idea however. User applications can already
695 fake this themselves and kernel space is precious.
696 </para>
697 <para>
698 We now have a working radio ioctl handler. So we just wrap up the function
699 </para>
700 <programlisting>
701
702
703 }
704 return -ENOIOCTLCMD;
705}
706
707 </programlisting>
708 <para>
709 and pass the Video4Linux layer back an error so that it knows we did not
710 understand the request we got passed.
711 </para>
712 </sect1>
713 <sect1 id="modradio">
714 <title>Module Wrapper</title>
715 <para>
716 Finally we add in the usual module wrapping and the driver is done.
717 </para>
718 <programlisting>
719
720#ifndef MODULE
721
722static int io = 0x300;
723
724#else
725
726static int io = -1;
727
728#endif
729
730MODULE_AUTHOR("Alan Cox");
731MODULE_DESCRIPTION("A driver for an imaginary radio card.");
732module_param(io, int, 0444);
733MODULE_PARM_DESC(io, "I/O address of the card.");
734
735static int __init init(void)
736{
737 if(io==-1)
738 {
739 printk(KERN_ERR
740 "You must set an I/O address with io=0x???\n");
741 return -EINVAL;
742 }
743 return myradio_init(NULL);
744}
745
746static void __exit cleanup(void)
747{
748 video_unregister_device(&amp;my_radio);
749 release_region(io, MY_IO_SIZE);
750}
751
752module_init(init);
753module_exit(cleanup);
754
755 </programlisting>
756 <para>
757 In this example we set the IO base by default if the driver is compiled into
758 the kernel: you can still set it using "my_radio.irq" if this file is called <filename>my_radio.c</filename>. For the module we require the
759 user sets the parameter. We set io to a nonsense port (-1) so that we can
760 tell if the user supplied an io parameter or not.
761 </para>
762 <para>
763 We use MODULE_ defines to give an author for the card driver and a
764 description. We also use them to declare that io is an integer and it is the
765 address of the card, and can be read by anyone from sysfs.
766 </para>
767 <para>
768 The clean-up routine unregisters the video_device we registered, and frees
769 up the I/O space. Note that the unregister takes the actual video_device
770 structure as its argument. Unlike the file operations structure which can be
771 shared by all instances of a device a video_device structure as an actual
772 instance of the device. If you are registering multiple radio devices you
773 need to fill in one structure per device (most likely by setting up a
774 template and copying it to each of the actual device structures).
775 </para>
776 </sect1>
777 </chapter>
778 <chapter id="Video_Capture_Devices">
779 <title>Video Capture Devices</title>
780 <sect1 id="introvid">
781 <title>Video Capture Device Types</title>
782 <para>
783 The video capture devices share the same interfaces as radio devices. In
784 order to explain the video capture interface I will use the example of a
785 camera that has no tuners or audio input. This keeps the example relatively
786 clean. To get both combine the two driver examples.
787 </para>
788 <para>
789 Video capture devices divide into four categories. A little technology
790 backgrounder. Full motion video even at television resolution (which is
791 actually fairly low) is pretty resource-intensive. You are continually
792 passing megabytes of data every second from the capture card to the display.
793 several alternative approaches have emerged because copying this through the
794 processor and the user program is a particularly bad idea .
795 </para>
796 <para>
797 The first is to add the television image onto the video output directly.
798 This is also how some 3D cards work. These basic cards can generally drop the
799 video into any chosen rectangle of the display. Cards like this, which
800 include most mpeg1 cards that used the feature connector, aren't very
801 friendly in a windowing environment. They don't understand windows or
802 clipping. The video window is always on the top of the display.
803 </para>
804 <para>
805 Chroma keying is a technique used by cards to get around this. It is an old
806 television mixing trick where you mark all the areas you wish to replace
807 with a single clear colour that isn't used in the image - TV people use an
808 incredibly bright blue while computing people often use a particularly
809 virulent purple. Bright blue occurs on the desktop. Anyone with virulent
810 purple windows has another problem besides their TV overlay.
811 </para>
812 <para>
813 The third approach is to copy the data from the capture card to the video
814 card, but to do it directly across the PCI bus. This relieves the processor
815 from doing the work but does require some smartness on the part of the video
816 capture chip, as well as a suitable video card. Programming this kind of
817 card and more so debugging it can be extremely tricky. There are some quite
818 complicated interactions with the display and you may also have to cope with
819 various chipset bugs that show up when PCI cards start talking to each
820 other.
821 </para>
822 <para>
823 To keep our example fairly simple we will assume a card that supports
824 overlaying a flat rectangular image onto the frame buffer output, and which
825 can also capture stuff into processor memory.
826 </para>
827 </sect1>
828 <sect1 id="regvid">
829 <title>Registering Video Capture Devices</title>
830 <para>
831 This time we need to add more functions for our camera device.
832 </para>
833 <programlisting>
834static struct video_device my_camera
835{
836 "My Camera",
837 VID_TYPE_OVERLAY|VID_TYPE_SCALES|\
838 VID_TYPE_CAPTURE|VID_TYPE_CHROMAKEY,
839 camera_open.
840 camera_close,
841 camera_read, /* no read */
842 NULL, /* no write */
843 camera_poll, /* no poll */
844 camera_ioctl,
845 NULL, /* no special init function */
846 NULL /* no private data */
847};
848 </programlisting>
849 <para>
850 We need a read() function which is used for capturing data from
851 the card, and we need a poll function so that a driver can wait for the next
852 frame to be captured.
853 </para>
854 <para>
855 We use the extra video capability flags that did not apply to the
856 radio interface. The video related flags are
857 </para>
858 <table frame="all" id="Capture_Capabilities"><title>Capture Capabilities</title>
859 <tgroup cols="2" align="left">
860 <tbody>
861 <row>
862<entry>VID_TYPE_CAPTURE</entry><entry>We support image capture</entry>
863</row><row>
864<entry>VID_TYPE_TELETEXT</entry><entry>A teletext capture device (vbi{n])</entry>
865</row><row>
866<entry>VID_TYPE_OVERLAY</entry><entry>The image can be directly overlaid onto the
867 frame buffer</entry>
868</row><row>
869<entry>VID_TYPE_CHROMAKEY</entry><entry>Chromakey can be used to select which parts
870 of the image to display</entry>
871</row><row>
872<entry>VID_TYPE_CLIPPING</entry><entry>It is possible to give the board a list of
873 rectangles to draw around. </entry>
874</row><row>
875<entry>VID_TYPE_FRAMERAM</entry><entry>The video capture goes into the video memory
876 and actually changes it. Applications need
877 to know this so they can clean up after the
878 card</entry>
879</row><row>
880<entry>VID_TYPE_SCALES</entry><entry>The image can be scaled to various sizes,
881 rather than being a single fixed size.</entry>
882</row><row>
883<entry>VID_TYPE_MONOCHROME</entry><entry>The capture will be monochrome. This isn't a
884 complete answer to the question since a mono
885 camera on a colour capture card will still
886 produce mono output.</entry>
887</row><row>
888<entry>VID_TYPE_SUBCAPTURE</entry><entry>The card allows only part of its field of
889 view to be captured. This enables
890 applications to avoid copying all of a large
891 image into memory when only some section is
892 relevant.</entry>
893 </row>
894 </tbody>
895 </tgroup>
896 </table>
897 <para>
898 We set VID_TYPE_CAPTURE so that we are seen as a capture card,
899 VID_TYPE_CHROMAKEY so the application knows it is time to draw in virulent
900 purple, and VID_TYPE_SCALES because we can be resized.
901 </para>
902 <para>
903 Our setup is fairly similar. This time we also want an interrupt line
904 for the 'frame captured' signal. Not all cards have this so some of them
905 cannot handle poll().
906 </para>
907 <programlisting>
908
909
910static int io = 0x320;
911static int irq = 11;
912
913int __init mycamera_init(struct video_init *v)
914{
915 if(!request_region(io, MY_IO_SIZE, "mycamera"))
916 {
917 printk(KERN_ERR
918 "mycamera: port 0x%03X is in use.\n", io);
919 return -EBUSY;
920 }
921
922 if(video_device_register(&amp;my_camera,
923 VFL_TYPE_GRABBER)==-1) {
924 release_region(io, MY_IO_SIZE);
925 return -EINVAL;
926 }
927 return 0;
928}
929
930 </programlisting>
931 <para>
932 This is little changed from the needs of the radio card. We specify
933 VFL_TYPE_GRABBER this time as we want to be allocated a /dev/video name.
934 </para>
935 </sect1>
936 <sect1 id="opvid">
937 <title>Opening And Closing The Capture Device</title>
938 <programlisting>
939
940
941static int users = 0;
942
943static int camera_open(struct video_device *dev, int flags)
944{
945 if(users)
946 return -EBUSY;
947 if(request_irq(irq, camera_irq, 0, "camera", dev)&lt;0)
948 return -EBUSY;
949 users++;
950 return 0;
951}
952
953
954static int camera_close(struct video_device *dev)
955{
956 users--;
957 free_irq(irq, dev);
958}
959 </programlisting>
960 <para>
961 The open and close routines are also quite similar. The only real change is
962 that we now request an interrupt for the camera device interrupt line. If we
963 cannot get the interrupt we report EBUSY to the application and give up.
964 </para>
965 </sect1>
966 <sect1 id="irqvid">
967 <title>Interrupt Handling</title>
968 <para>
969 Our example handler is for an ISA bus device. If it was PCI you would be
970 able to share the interrupt and would have set IRQF_SHARED to indicate a
971 shared IRQ. We pass the device pointer as the interrupt routine argument. We
972 don't need to since we only support one card but doing this will make it
973 easier to upgrade the driver for multiple devices in the future.
974 </para>
975 <para>
976 Our interrupt routine needs to do little if we assume the card can simply
977 queue one frame to be read after it captures it.
978 </para>
979 <programlisting>
980
981
982static struct wait_queue *capture_wait;
983static int capture_ready = 0;
984
985static void camera_irq(int irq, void *dev_id,
986 struct pt_regs *regs)
987{
988 capture_ready=1;
989 wake_up_interruptible(&amp;capture_wait);
990}
991 </programlisting>
992 <para>
993 The interrupt handler is nice and simple for this card as we are assuming
994 the card is buffering the frame for us. This means we have little to do but
995 wake up anybody interested. We also set a capture_ready flag, as we may
996 capture a frame before an application needs it. In this case we need to know
997 that a frame is ready. If we had to collect the frame on the interrupt life
998 would be more complex.
999 </para>
1000 <para>
1001 The two new routines we need to supply are camera_read which returns a
1002 frame, and camera_poll which waits for a frame to become ready.
1003 </para>
1004 <programlisting>
1005
1006
1007static int camera_poll(struct video_device *dev,
1008 struct file *file, struct poll_table *wait)
1009{
1010 poll_wait(file, &amp;capture_wait, wait);
1011 if(capture_read)
1012 return POLLIN|POLLRDNORM;
1013 return 0;
1014}
1015
1016 </programlisting>
1017 <para>
1018 Our wait queue for polling is the capture_wait queue. This will cause the
1019 task to be woken up by our camera_irq routine. We check capture_read to see
1020 if there is an image present and if so report that it is readable.
1021 </para>
1022 </sect1>
1023 <sect1 id="rdvid">
1024 <title>Reading The Video Image</title>
1025 <programlisting>
1026
1027
1028static long camera_read(struct video_device *dev, char *buf,
1029 unsigned long count)
1030{
1031 struct wait_queue wait = { current, NULL };
1032 u8 *ptr;
1033 int len;
1034 int i;
1035
1036 add_wait_queue(&amp;capture_wait, &amp;wait);
1037
1038 while(!capture_ready)
1039 {
1040 if(file->flags&amp;O_NDELAY)
1041 {
1042 remove_wait_queue(&amp;capture_wait, &amp;wait);
1043 current->state = TASK_RUNNING;
1044 return -EWOULDBLOCK;
1045 }
1046 if(signal_pending(current))
1047 {
1048 remove_wait_queue(&amp;capture_wait, &amp;wait);
1049 current->state = TASK_RUNNING;
1050 return -ERESTARTSYS;
1051 }
1052 schedule();
1053 current->state = TASK_INTERRUPTIBLE;
1054 }
1055 remove_wait_queue(&amp;capture_wait, &amp;wait);
1056 current->state = TASK_RUNNING;
1057
1058 </programlisting>
1059 <para>
1060 The first thing we have to do is to ensure that the application waits until
1061 the next frame is ready. The code here is almost identical to the mouse code
1062 we used earlier in this chapter. It is one of the common building blocks of
1063 Linux device driver code and probably one which you will find occurs in any
1064 drivers you write.
1065 </para>
1066 <para>
1067 We wait for a frame to be ready, or for a signal to interrupt our waiting. If a
1068 signal occurs we need to return from the system call so that the signal can
1069 be sent to the application itself. We also check to see if the user actually
1070 wanted to avoid waiting - ie if they are using non-blocking I/O and have other things
1071 to get on with.
1072 </para>
1073 <para>
1074 Next we copy the data from the card to the user application. This is rarely
1075 as easy as our example makes out. We will add capture_w, and capture_h here
1076 to hold the width and height of the captured image. We assume the card only
1077 supports 24bit RGB for now.
1078 </para>
1079 <programlisting>
1080
1081
1082
1083 capture_ready = 0;
1084
1085 ptr=(u8 *)buf;
1086 len = capture_w * 3 * capture_h; /* 24bit RGB */
1087
1088 if(len>count)
1089 len=count; /* Doesn't all fit */
1090
1091 for(i=0; i&lt;len; i++)
1092 {
1093 put_user(inb(io+IMAGE_DATA), ptr);
1094 ptr++;
1095 }
1096
1097 hardware_restart_capture();
1098
1099 return i;
1100}
1101
1102 </programlisting>
1103 <para>
1104 For a real hardware device you would try to avoid the loop with put_user().
1105 Each call to put_user() has a time overhead checking whether the accesses to user
1106 space are allowed. It would be better to read a line into a temporary buffer
1107 then copy this to user space in one go.
1108 </para>
1109 <para>
1110 Having captured the image and put it into user space we can kick the card to
1111 get the next frame acquired.
1112 </para>
1113 </sect1>
1114 <sect1 id="iocvid">
1115 <title>Video Ioctl Handling</title>
1116 <para>
1117 As with the radio driver the major control interface is via the ioctl()
1118 function. Video capture devices support the same tuner calls as a radio
1119 device and also support additional calls to control how the video functions
1120 are handled. In this simple example the card has no tuners to avoid making
1121 the code complex.
1122 </para>
1123 <programlisting>
1124
1125
1126
1127static int camera_ioctl(struct video_device *dev, unsigned int cmd, void *arg)
1128{
1129 switch(cmd)
1130 {
1131 case VIDIOCGCAP:
1132 {
1133 struct video_capability v;
1134 v.type = VID_TYPE_CAPTURE|\
1135 VID_TYPE_CHROMAKEY|\
1136 VID_TYPE_SCALES|\
1137 VID_TYPE_OVERLAY;
1138 v.channels = 1;
1139 v.audios = 0;
1140 v.maxwidth = 640;
1141 v.minwidth = 16;
1142 v.maxheight = 480;
1143 v.minheight = 16;
1144 strcpy(v.name, "My Camera");
1145 if(copy_to_user(arg, &amp;v, sizeof(v)))
1146 return -EFAULT;
1147 return 0;
1148 }
1149
1150
1151 </programlisting>
1152 <para>
1153 The first ioctl we must support and which all video capture and radio
1154 devices are required to support is VIDIOCGCAP. This behaves exactly the same
1155 as with a radio device. This time, however, we report the extra capabilities
1156 we outlined earlier on when defining our video_dev structure.
1157 </para>
1158 <para>
1159 We now set the video flags saying that we support overlay, capture,
1160 scaling and chromakey. We also report size limits - our smallest image is
1161 16x16 pixels, our largest is 640x480.
1162 </para>
1163 <para>
1164 To keep things simple we report no audio and no tuning capabilities at all.
1165 </para>
1166 <programlisting>
1167
1168 case VIDIOCGCHAN:
1169 {
1170 struct video_channel v;
1171 if(copy_from_user(&amp;v, arg, sizeof(v)))
1172 return -EFAULT;
1173 if(v.channel != 0)
1174 return -EINVAL;
1175 v.flags = 0;
1176 v.tuners = 0;
1177 v.type = VIDEO_TYPE_CAMERA;
1178 v.norm = VIDEO_MODE_AUTO;
1179 strcpy(v.name, "Camera Input");break;
1180 if(copy_to_user(&amp;v, arg, sizeof(v)))
1181 return -EFAULT;
1182 return 0;
1183 }
1184
1185
1186 </programlisting>
1187 <para>
1188 This follows what is very much the standard way an ioctl handler looks
1189 in Linux. We copy the data into a kernel space variable and we check that the
1190 request is valid (in this case that the input is 0). Finally we copy the
1191 camera info back to the user.
1192 </para>
1193 <para>
1194 The VIDIOCGCHAN ioctl allows a user to ask about video channels (that is
1195 inputs to the video card). Our example card has a single camera input. The
1196 fields in the structure are
1197 </para>
1198 <table frame="all" id="video_channel_fields"><title>struct video_channel fields</title>
1199 <tgroup cols="2" align="left">
1200 <tbody>
1201 <row>
1202
1203 <entry>channel</entry><entry>The channel number we are selecting</entry>
1204 </row><row>
1205 <entry>name</entry><entry>The name for this channel. This is intended
1206 to describe the port to the user.
1207 Appropriate names are therefore things like
1208 "Camera" "SCART input"</entry>
1209 </row><row>
1210 <entry>flags</entry><entry>Channel properties</entry>
1211 </row><row>
1212 <entry>type</entry><entry>Input type</entry>
1213 </row><row>
1214 <entry>norm</entry><entry>The current television encoding being used
1215 if relevant for this channel.
1216 </entry>
1217 </row>
1218 </tbody>
1219 </tgroup>
1220 </table>
1221 <table frame="all" id="video_channel_flags"><title>struct video_channel flags</title>
1222 <tgroup cols="2" align="left">
1223 <tbody>
1224 <row>
1225 <entry>VIDEO_VC_TUNER</entry><entry>Channel has a tuner.</entry>
1226 </row><row>
1227 <entry>VIDEO_VC_AUDIO</entry><entry>Channel has audio.</entry>
1228 </row>
1229 </tbody>
1230 </tgroup>
1231 </table>
1232 <table frame="all" id="video_channel_types"><title>struct video_channel types</title>
1233 <tgroup cols="2" align="left">
1234 <tbody>
1235 <row>
1236 <entry>VIDEO_TYPE_TV</entry><entry>Television input.</entry>
1237 </row><row>
1238 <entry>VIDEO_TYPE_CAMERA</entry><entry>Fixed camera input.</entry>
1239 </row><row>
1240 <entry>0</entry><entry>Type is unknown.</entry>
1241 </row>
1242 </tbody>
1243 </tgroup>
1244 </table>
1245 <table frame="all" id="video_channel_norms"><title>struct video_channel norms</title>
1246 <tgroup cols="2" align="left">
1247 <tbody>
1248 <row>
1249 <entry>VIDEO_MODE_PAL</entry><entry>PAL encoded Television</entry>
1250 </row><row>
1251 <entry>VIDEO_MODE_NTSC</entry><entry>NTSC (US) encoded Television</entry>
1252 </row><row>
1253 <entry>VIDEO_MODE_SECAM</entry><entry>SECAM (French) Television </entry>
1254 </row><row>
1255 <entry>VIDEO_MODE_AUTO</entry><entry>Automatic switching, or format does not
1256 matter</entry>
1257 </row>
1258 </tbody>
1259 </tgroup>
1260 </table>
1261 <para>
1262 The corresponding VIDIOCSCHAN ioctl allows a user to change channel and to
1263 request the norm is changed - for example to switch between a PAL or an NTSC
1264 format camera.
1265 </para>
1266 <programlisting>
1267
1268
1269 case VIDIOCSCHAN:
1270 {
1271 struct video_channel v;
1272 if(copy_from_user(&amp;v, arg, sizeof(v)))
1273 return -EFAULT;
1274 if(v.channel != 0)
1275 return -EINVAL;
1276 if(v.norm != VIDEO_MODE_AUTO)
1277 return -EINVAL;
1278 return 0;
1279 }
1280
1281
1282 </programlisting>
1283 <para>
1284 The implementation of this call in our driver is remarkably easy. Because we
1285 are assuming fixed format hardware we need only check that the user has not
1286 tried to change anything.
1287 </para>
1288 <para>
1289 The user also needs to be able to configure and adjust the picture they are
1290 seeing. This is much like adjusting a television set. A user application
1291 also needs to know the palette being used so that it knows how to display
1292 the image that has been captured. The VIDIOCGPICT and VIDIOCSPICT ioctl
1293 calls provide this information.
1294 </para>
1295 <programlisting>
1296
1297
1298 case VIDIOCGPICT
1299 {
1300 struct video_picture v;
1301 v.brightness = hardware_brightness();
1302 v.hue = hardware_hue();
1303 v.colour = hardware_saturation();
1304 v.contrast = hardware_brightness();
1305 /* Not settable */
1306 v.whiteness = 32768;
1307 v.depth = 24; /* 24bit */
1308 v.palette = VIDEO_PALETTE_RGB24;
1309 if(copy_to_user(&amp;v, arg,
1310 sizeof(v)))
1311 return -EFAULT;
1312 return 0;
1313 }
1314
1315
1316 </programlisting>
1317 <para>
1318 The brightness, hue, color, and contrast provide the picture controls that
1319 are akin to a conventional television. Whiteness provides additional
1320 control for greyscale images. All of these values are scaled between 0-65535
1321 and have 32768 as the mid point setting. The scaling means that applications
1322 do not have to worry about the capability range of the hardware but can let
1323 it make a best effort attempt.
1324 </para>
1325 <para>
1326 Our depth is 24, as this is in bits. We will be returning RGB24 format. This
1327 has one byte of red, then one of green, then one of blue. This then repeats
1328 for every other pixel in the image. The other common formats the interface
1329 defines are
1330 </para>
1331 <table frame="all" id="Framebuffer_Encodings"><title>Framebuffer Encodings</title>
1332 <tgroup cols="2" align="left">
1333 <tbody>
1334 <row>
1335 <entry>GREY</entry><entry>Linear greyscale. This is for simple cameras and the
1336 like</entry>
1337 </row><row>
1338 <entry>RGB565</entry><entry>The top 5 bits hold 32 red levels, the next six bits
1339 hold green and the low 5 bits hold blue. </entry>
1340 </row><row>
1341 <entry>RGB555</entry><entry>The top bit is clear. The red green and blue levels
1342 each occupy five bits.</entry>
1343 </row>
1344 </tbody>
1345 </tgroup>
1346 </table>
1347 <para>
1348 Additional modes are support for YUV capture formats. These are common for
1349 TV and video conferencing applications.
1350 </para>
1351 <para>
1352 The VIDIOCSPICT ioctl allows a user to set some of the picture parameters.
1353 Exactly which ones are supported depends heavily on the card itself. It is
1354 possible to support many modes and effects in software. In general doing
1355 this in the kernel is a bad idea. Video capture is a performance-sensitive
1356 application and the programs can often do better if they aren't being
1357 'helped' by an overkeen driver writer. Thus for our device we will report
1358 RGB24 only and refuse to allow a change.
1359 </para>
1360 <programlisting>
1361
1362
1363 case VIDIOCSPICT:
1364 {
1365 struct video_picture v;
1366 if(copy_from_user(&amp;v, arg, sizeof(v)))
1367 return -EFAULT;
1368 if(v.depth!=24 ||
1369 v.palette != VIDEO_PALETTE_RGB24)
1370 return -EINVAL;
1371 set_hardware_brightness(v.brightness);
1372 set_hardware_hue(v.hue);
1373 set_hardware_saturation(v.colour);
1374 set_hardware_brightness(v.contrast);
1375 return 0;
1376 }
1377
1378
1379 </programlisting>
1380 <para>
1381 We check the user has not tried to change the palette or the depth. We do
1382 not want to carry out some of the changes and then return an error. This may
1383 confuse the application which will be assuming no change occurred.
1384 </para>
1385 <para>
1386 In much the same way as you need to be able to set the picture controls to
1387 get the right capture images, many cards need to know what they are
1388 displaying onto when generating overlay output. In some cases getting this
1389 wrong even makes a nasty mess or may crash the computer. For that reason
1390 the VIDIOCSBUF ioctl used to set up the frame buffer information may well
1391 only be usable by root.
1392 </para>
1393 <para>
1394 We will assume our card is one of the old ISA devices with feature connector
1395 and only supports a couple of standard video modes. Very common for older
1396 cards although the PCI devices are way smarter than this.
1397 </para>
1398 <programlisting>
1399
1400
1401static struct video_buffer capture_fb;
1402
1403 case VIDIOCGFBUF:
1404 {
1405 if(copy_to_user(arg, &amp;capture_fb,
1406 sizeof(capture_fb)))
1407 return -EFAULT;
1408 return 0;
1409
1410 }
1411
1412
1413 </programlisting>
1414 <para>
1415 We keep the frame buffer information in the format the ioctl uses. This
1416 makes it nice and easy to work with in the ioctl calls.
1417 </para>
1418 <programlisting>
1419
1420 case VIDIOCSFBUF:
1421 {
1422 struct video_buffer v;
1423
1424 if(!capable(CAP_SYS_ADMIN))
1425 return -EPERM;
1426
1427 if(copy_from_user(&amp;v, arg, sizeof(v)))
1428 return -EFAULT;
1429 if(v.width!=320 &amp;&amp; v.width!=640)
1430 return -EINVAL;
1431 if(v.height!=200 &amp;&amp; v.height!=240
1432 &amp;&amp; v.height!=400
1433 &amp;&amp; v.height !=480)
1434 return -EINVAL;
1435 memcpy(&amp;capture_fb, &amp;v, sizeof(v));
1436 hardware_set_fb(&amp;v);
1437 return 0;
1438 }
1439
1440
1441
1442 </programlisting>
1443 <para>
1444 The capable() function checks a user has the required capability. The Linux
1445 operating system has a set of about 30 capabilities indicating privileged
1446 access to services. The default set up gives the superuser (uid 0) all of
1447 them and nobody else has any.
1448 </para>
1449 <para>
1450 We check that the user has the SYS_ADMIN capability, that is they are
1451 allowed to operate as the machine administrator. We don't want anyone but
1452 the administrator making a mess of the display.
1453 </para>
1454 <para>
1455 Next we check for standard PC video modes (320 or 640 wide with either
1456 EGA or VGA depths). If the mode is not a standard video mode we reject it as
1457 not supported by our card. If the mode is acceptable we save it so that
1458 VIDIOCFBUF will give the right answer next time it is called. The
1459 hardware_set_fb() function is some undescribed card specific function to
1460 program the card for the desired mode.
1461 </para>
1462 <para>
1463 Before the driver can display an overlay window it needs to know where the
1464 window should be placed, and also how large it should be. If the card
1465 supports clipping it needs to know which rectangles to omit from the
1466 display. The video_window structure is used to describe the way the image
1467 should be displayed.
1468 </para>
1469 <table frame="all" id="video_window_fields"><title>struct video_window fields</title>
1470 <tgroup cols="2" align="left">
1471 <tbody>
1472 <row>
1473 <entry>width</entry><entry>The width in pixels of the desired image. The card
1474 may use a smaller size if this size is not available</entry>
1475 </row><row>
1476 <entry>height</entry><entry>The height of the image. The card may use a smaller
1477 size if this size is not available.</entry>
1478 </row><row>
1479 <entry>x</entry><entry> The X position of the top left of the window. This
1480 is in pixels relative to the left hand edge of the
1481 picture. Not all cards can display images aligned on
1482 any pixel boundary. If the position is unsuitable
1483 the card adjusts the image right and reduces the
1484 width.</entry>
1485 </row><row>
1486 <entry>y</entry><entry> The Y position of the top left of the window. This
1487 is counted in pixels relative to the top edge of the
1488 picture. As with the width if the card cannot
1489 display starting on this line it will adjust the
1490 values.</entry>
1491 </row><row>
1492 <entry>chromakey</entry><entry>The colour (expressed in RGB32 format) for the
1493 chromakey colour if chroma keying is being used. </entry>
1494 </row><row>
1495 <entry>clips</entry><entry>An array of rectangles that must not be drawn
1496 over.</entry>
1497 </row><row>
1498 <entry>clipcount</entry><entry>The number of clips in this array.</entry>
1499 </row>
1500 </tbody>
1501 </tgroup>
1502 </table>
1503 <para>
1504 Each clip is a struct video_clip which has the following fields
1505 </para>
1506 <table frame="all" id="video_clip_fields"><title>video_clip fields</title>
1507 <tgroup cols="2" align="left">
1508 <tbody>
1509 <row>
1510 <entry>x, y</entry><entry>Co-ordinates relative to the display</entry>
1511 </row><row>
1512 <entry>width, height</entry><entry>Width and height in pixels</entry>
1513 </row><row>
1514 <entry>next</entry><entry>A spare field for the application to use</entry>
1515 </row>
1516 </tbody>
1517 </tgroup>
1518 </table>
1519 <para>
1520 The driver is required to ensure it always draws in the area requested or a smaller area, and that it never draws in any of the areas that are clipped.
1521 This may well mean it has to leave alone. small areas the application wished to be
1522 drawn.
1523 </para>
1524 <para>
1525 Our example card uses chromakey so does not have to address most of the
1526 clipping. We will add a video_window structure to our global variables to
1527 remember our parameters, as we did with the frame buffer.
1528 </para>
1529 <programlisting>
1530
1531
1532 case VIDIOCGWIN:
1533 {
1534 if(copy_to_user(arg, &amp;capture_win,
1535 sizeof(capture_win)))
1536 return -EFAULT;
1537 return 0;
1538 }
1539
1540
1541 case VIDIOCSWIN:
1542 {
1543 struct video_window v;
1544 if(copy_from_user(&amp;v, arg, sizeof(v)))
1545 return -EFAULT;
1546 if(v.width &gt; 640 || v.height &gt; 480)
1547 return -EINVAL;
1548 if(v.width &lt; 16 || v.height &lt; 16)
1549 return -EINVAL;
1550 hardware_set_key(v.chromakey);
1551 hardware_set_window(v);
1552 memcpy(&amp;capture_win, &amp;v, sizeof(v));
1553 capture_w = v.width;
1554 capture_h = v.height;
1555 return 0;
1556 }
1557
1558
1559 </programlisting>
1560 <para>
1561 Because we are using Chromakey our setup is fairly simple. Mostly we have to
1562 check the values are sane and load them into the capture card.
1563 </para>
1564 <para>
1565 With all the setup done we can now turn on the actual capture/overlay. This
1566 is done with the VIDIOCCAPTURE ioctl. This takes a single integer argument
1567 where 0 is on and 1 is off.
1568 </para>
1569 <programlisting>
1570
1571
1572 case VIDIOCCAPTURE:
1573 {
1574 int v;
1575 if(get_user(v, (int *)arg))
1576 return -EFAULT;
1577 if(v==0)
1578 hardware_capture_off();
1579 else
1580 {
1581 if(capture_fb.width == 0
1582 || capture_w == 0)
1583 return -EINVAL;
1584 hardware_capture_on();
1585 }
1586 return 0;
1587 }
1588
1589
1590 </programlisting>
1591 <para>
1592 We grab the flag from user space and either enable or disable according to
1593 its value. There is one small corner case we have to consider here. Suppose
1594 that the capture was requested before the video window or the frame buffer
1595 had been set up. In those cases there will be unconfigured fields in our
1596 card data, as well as unconfigured hardware settings. We check for this case and
1597 return an error if the frame buffer or the capture window width is zero.
1598 </para>
1599 <programlisting>
1600
1601
1602 default:
1603 return -ENOIOCTLCMD;
1604 }
1605}
1606 </programlisting>
1607 <para>
1608
1609 We don't need to support any other ioctls, so if we get this far, it is time
1610 to tell the video layer that we don't now what the user is talking about.
1611 </para>
1612 </sect1>
1613 <sect1 id="endvid">
1614 <title>Other Functionality</title>
1615 <para>
1616 The Video4Linux layer supports additional features, including a high
1617 performance mmap() based capture mode and capturing part of the image.
1618 These features are out of the scope of the book. You should however have enough
1619 example code to implement most simple video4linux devices for radio and TV
1620 cards.
1621 </para>
1622 </sect1>
1623 </chapter>
1624 <chapter id="bugs">
1625 <title>Known Bugs And Assumptions</title>
1626 <para>
1627 <variablelist>
1628 <varlistentry><term>Multiple Opens</term>
1629 <listitem>
1630 <para>
1631 The driver assumes multiple opens should not be allowed. A driver
1632 can work around this but not cleanly.
1633 </para>
1634 </listitem></varlistentry>
1635
1636 <varlistentry><term>API Deficiencies</term>
1637 <listitem>
1638 <para>
1639 The existing API poorly reflects compression capable devices. There
1640 are plans afoot to merge V4L, V4L2 and some other ideas into a
1641 better interface.
1642 </para>
1643 </listitem></varlistentry>
1644 </variablelist>
1645
1646 </para>
1647 </chapter>
1648
1649 <chapter id="pubfunctions">
1650 <title>Public Functions Provided</title>
1651!Edrivers/media/video/v4l2-dev.c
1652 </chapter>
1653
1654</book>
diff --git a/Documentation/HOWTO b/Documentation/HOWTO
index 48a3955f05fc..8495fc970391 100644
--- a/Documentation/HOWTO
+++ b/Documentation/HOWTO
@@ -112,7 +112,7 @@ required reading:
112 112
113 Other excellent descriptions of how to create patches properly are: 113 Other excellent descriptions of how to create patches properly are:
114 "The Perfect Patch" 114 "The Perfect Patch"
115 http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt 115 http://userweb.kernel.org/~akpm/stuff/tpp.txt
116 "Linux kernel patch submission format" 116 "Linux kernel patch submission format"
117 http://linux.yyz.us/patch-format.html 117 http://linux.yyz.us/patch-format.html
118 118
@@ -620,7 +620,7 @@ all time. It should describe the patch completely, containing:
620For more details on what this should all look like, please see the 620For more details on what this should all look like, please see the
621ChangeLog section of the document: 621ChangeLog section of the document:
622 "The Perfect Patch" 622 "The Perfect Patch"
623 http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt 623 http://userweb.kernel.org/~akpm/stuff/tpp.txt
624 624
625 625
626 626
diff --git a/Documentation/RCU/checklist.txt b/Documentation/RCU/checklist.txt
index cf5562cbe356..6e253407b3dc 100644
--- a/Documentation/RCU/checklist.txt
+++ b/Documentation/RCU/checklist.txt
@@ -210,7 +210,7 @@ over a rather long period of time, but improvements are always welcome!
210 number of updates per grace period. 210 number of updates per grace period.
211 211
2129. All RCU list-traversal primitives, which include 2129. All RCU list-traversal primitives, which include
213 rcu_dereference(), list_for_each_rcu(), list_for_each_entry_rcu(), 213 rcu_dereference(), list_for_each_entry_rcu(),
214 list_for_each_continue_rcu(), and list_for_each_safe_rcu(), 214 list_for_each_continue_rcu(), and list_for_each_safe_rcu(),
215 must be either within an RCU read-side critical section or 215 must be either within an RCU read-side critical section or
216 must be protected by appropriate update-side locks. RCU 216 must be protected by appropriate update-side locks. RCU
diff --git a/Documentation/RCU/rcuref.txt b/Documentation/RCU/rcuref.txt
index 451de2ad8329..4202ad093130 100644
--- a/Documentation/RCU/rcuref.txt
+++ b/Documentation/RCU/rcuref.txt
@@ -29,9 +29,9 @@ release_referenced() delete()
29 } 29 }
30 30
31If this list/array is made lock free using RCU as in changing the 31If this list/array is made lock free using RCU as in changing the
32write_lock() in add() and delete() to spin_lock and changing read_lock 32write_lock() in add() and delete() to spin_lock() and changing read_lock()
33in search_and_reference to rcu_read_lock(), the atomic_get in 33in search_and_reference() to rcu_read_lock(), the atomic_inc() in
34search_and_reference could potentially hold reference to an element which 34search_and_reference() could potentially hold reference to an element which
35has already been deleted from the list/array. Use atomic_inc_not_zero() 35has already been deleted from the list/array. Use atomic_inc_not_zero()
36in this scenario as follows: 36in this scenario as follows:
37 37
@@ -40,20 +40,20 @@ add() search_and_reference()
40{ { 40{ {
41 alloc_object rcu_read_lock(); 41 alloc_object rcu_read_lock();
42 ... search_for_element 42 ... search_for_element
43 atomic_set(&el->rc, 1); if (atomic_inc_not_zero(&el->rc)) { 43 atomic_set(&el->rc, 1); if (!atomic_inc_not_zero(&el->rc)) {
44 write_lock(&list_lock); rcu_read_unlock(); 44 spin_lock(&list_lock); rcu_read_unlock();
45 return FAIL; 45 return FAIL;
46 add_element } 46 add_element }
47 ... ... 47 ... ...
48 write_unlock(&list_lock); rcu_read_unlock(); 48 spin_unlock(&list_lock); rcu_read_unlock();
49} } 49} }
503. 4. 503. 4.
51release_referenced() delete() 51release_referenced() delete()
52{ { 52{ {
53 ... write_lock(&list_lock); 53 ... spin_lock(&list_lock);
54 if (atomic_dec_and_test(&el->rc)) ... 54 if (atomic_dec_and_test(&el->rc)) ...
55 call_rcu(&el->head, el_free); delete_element 55 call_rcu(&el->head, el_free); delete_element
56 ... write_unlock(&list_lock); 56 ... spin_unlock(&list_lock);
57} ... 57} ...
58 if (atomic_dec_and_test(&el->rc)) 58 if (atomic_dec_and_test(&el->rc))
59 call_rcu(&el->head, el_free); 59 call_rcu(&el->head, el_free);
diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt
index e04d643a9f57..96170824a717 100644
--- a/Documentation/RCU/whatisRCU.txt
+++ b/Documentation/RCU/whatisRCU.txt
@@ -786,8 +786,6 @@ RCU pointer/list traversal:
786 list_for_each_entry_rcu 786 list_for_each_entry_rcu
787 hlist_for_each_entry_rcu 787 hlist_for_each_entry_rcu
788 788
789 list_for_each_rcu (to be deprecated in favor of
790 list_for_each_entry_rcu)
791 list_for_each_continue_rcu (to be deprecated in favor of new 789 list_for_each_continue_rcu (to be deprecated in favor of new
792 list_for_each_entry_continue_rcu) 790 list_for_each_entry_continue_rcu)
793 791
diff --git a/Documentation/SAK.txt b/Documentation/SAK.txt
index b9019ca872ea..74be14679ed8 100644
--- a/Documentation/SAK.txt
+++ b/Documentation/SAK.txt
@@ -1,5 +1,5 @@
1Linux 2.4.2 Secure Attention Key (SAK) handling 1Linux 2.4.2 Secure Attention Key (SAK) handling
218 March 2001, Andrew Morton <akpm@osdl.org> 218 March 2001, Andrew Morton
3 3
4An operating system's Secure Attention Key is a security tool which is 4An operating system's Secure Attention Key is a security tool which is
5provided as protection against trojan password capturing programs. It 5provided as protection against trojan password capturing programs. It
diff --git a/Documentation/SELinux.txt b/Documentation/SELinux.txt
new file mode 100644
index 000000000000..07eae00f3314
--- /dev/null
+++ b/Documentation/SELinux.txt
@@ -0,0 +1,27 @@
1If you want to use SELinux, chances are you will want
2to use the distro-provided policies, or install the
3latest reference policy release from
4 http://oss.tresys.com/projects/refpolicy
5
6However, if you want to install a dummy policy for
7testing, you can do using 'mdp' provided under
8scripts/selinux. Note that this requires the selinux
9userspace to be installed - in particular you will
10need checkpolicy to compile a kernel, and setfiles and
11fixfiles to label the filesystem.
12
13 1. Compile the kernel with selinux enabled.
14 2. Type 'make' to compile mdp.
15 3. Make sure that you are not running with
16 SELinux enabled and a real policy. If
17 you are, reboot with selinux disabled
18 before continuing.
19 4. Run install_policy.sh:
20 cd scripts/selinux
21 sh install_policy.sh
22
23Step 4 will create a new dummy policy valid for your
24kernel, with a single selinux user, role, and type.
25It will compile the policy, will set your SELINUXTYPE to
26dummy in /etc/selinux/config, install the compiled policy
27as 'dummy', and relabel your filesystem.
diff --git a/Documentation/SubmitChecklist b/Documentation/SubmitChecklist
index 21f0795af20f..ac5e0b2f1097 100644
--- a/Documentation/SubmitChecklist
+++ b/Documentation/SubmitChecklist
@@ -85,3 +85,6 @@ kernel patches.
8523: Tested after it has been merged into the -mm patchset to make sure 8523: Tested after it has been merged into the -mm patchset to make sure
86 that it still works with all of the other queued patches and various 86 that it still works with all of the other queued patches and various
87 changes in the VM, VFS, and other subsystems. 87 changes in the VM, VFS, and other subsystems.
88
8924: All memory barriers {e.g., barrier(), rmb(), wmb()} need a comment in the
90 source code that explains the logic of what they are doing and why.
diff --git a/Documentation/SubmittingDrivers b/Documentation/SubmittingDrivers
index 24f2eb40cae5..99e72a81fa2f 100644
--- a/Documentation/SubmittingDrivers
+++ b/Documentation/SubmittingDrivers
@@ -41,7 +41,7 @@ Linux 2.4:
41Linux 2.6: 41Linux 2.6:
42 The same rules apply as 2.4 except that you should follow linux-kernel 42 The same rules apply as 2.4 except that you should follow linux-kernel
43 to track changes in API's. The final contact point for Linux 2.6 43 to track changes in API's. The final contact point for Linux 2.6
44 submissions is Andrew Morton <akpm@osdl.org>. 44 submissions is Andrew Morton.
45 45
46What Criteria Determine Acceptance 46What Criteria Determine Acceptance
47---------------------------------- 47----------------------------------
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index f79ad9ff6031..f309d3c6221c 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -77,7 +77,7 @@ Quilt:
77http://savannah.nongnu.org/projects/quilt 77http://savannah.nongnu.org/projects/quilt
78 78
79Andrew Morton's patch scripts: 79Andrew Morton's patch scripts:
80http://www.zip.com.au/~akpm/linux/patches/ 80http://userweb.kernel.org/~akpm/stuff/patch-scripts.tar.gz
81Instead of these scripts, quilt is the recommended patch management 81Instead of these scripts, quilt is the recommended patch management
82tool (see above). 82tool (see above).
83 83
@@ -405,7 +405,7 @@ person it names. This tag documents that potentially interested parties
405have been included in the discussion 405have been included in the discussion
406 406
407 407
40814) Using Test-by: and Reviewed-by: 40814) Using Tested-by: and Reviewed-by:
409 409
410A Tested-by: tag indicates that the patch has been successfully tested (in 410A Tested-by: tag indicates that the patch has been successfully tested (in
411some environment) by the person named. This tag informs maintainers that 411some environment) by the person named. This tag informs maintainers that
@@ -653,7 +653,7 @@ SECTION 3 - REFERENCES
653---------------------- 653----------------------
654 654
655Andrew Morton, "The perfect patch" (tpp). 655Andrew Morton, "The perfect patch" (tpp).
656 <http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt> 656 <http://userweb.kernel.org/~akpm/stuff/tpp.txt>
657 657
658Jeff Garzik, "Linux kernel patch submission format". 658Jeff Garzik, "Linux kernel patch submission format".
659 <http://linux.yyz.us/patch-format.html> 659 <http://linux.yyz.us/patch-format.html>
@@ -672,4 +672,9 @@ Kernel Documentation/CodingStyle:
672 672
673Linus Torvalds's mail on the canonical patch format: 673Linus Torvalds's mail on the canonical patch format:
674 <http://lkml.org/lkml/2005/4/7/183> 674 <http://lkml.org/lkml/2005/4/7/183>
675
676Andi Kleen, "On submitting kernel patches"
677 Some strategies to get difficult or controversal changes in.
678 http://halobates.de/on-submitting-patches.pdf
679
675-- 680--
diff --git a/Documentation/blackfin/kgdb.txt b/Documentation/blackfin/kgdb.txt
deleted file mode 100644
index 84f6a484ae9a..000000000000
--- a/Documentation/blackfin/kgdb.txt
+++ /dev/null
@@ -1,155 +0,0 @@
1 A Simple Guide to Configure KGDB
2
3 Sonic Zhang <sonic.zhang@analog.com>
4 Aug. 24th 2006
5
6
7This KGDB patch enables the kernel developer to do source level debugging on
8the kernel for the Blackfin architecture. The debugging works over either the
9ethernet interface or one of the uarts. Both software breakpoints and
10hardware breakpoints are supported in this version.
11http://docs.blackfin.uclinux.org/doku.php?id=kgdb
12
13
142 known issues:
151. This bug:
16 http://blackfin.uclinux.org/tracker/index.php?func=detail&aid=544&group_id=18&atid=145
17 The GDB client for Blackfin uClinux causes incorrect values of local
18 variables to be displayed when the user breaks the running of kernel in GDB.
192. Because of a hardware bug in Blackfin 533 v1.0.3:
20 05000067 - Watchpoints (Hardware Breakpoints) are not supported
21 Hardware breakpoints cannot be set properly.
22
23
24Debug over Ethernet:
25
261. Compile and install the cross platform version of gdb for blackfin, which
27 can be found at $(BINROOT)/bfin-elf-gdb.
28
292. Apply this patch to the 2.6.x kernel. Select the menuconfig option under
30 "Kernel hacking" -> "Kernel debugging" -> "KGDB: kernel debug with remote gdb".
31 With this selected, option "Full Symbolic/Source Debugging support" and
32 "Compile the kernel with frame pointers" are also selected.
33
343. Select option "KGDB: connect over (Ethernet)". Add "kgdboe=@target-IP/,@host-IP/" to
35 the option "Compiled-in Kernel Boot Parameter" under "Kernel hacking".
36
374. Connect minicom to the serial port and boot the kernel image.
38
395. Configure the IP "/> ifconfig eth0 target-IP"
40
416. Start GDB client "bfin-elf-gdb vmlinux".
42
437. Connect to the target "(gdb) target remote udp:target-IP:6443".
44
458. Set software breakpoint "(gdb) break sys_open".
46
479. Continue "(gdb) c".
48
4910. Run ls in the target console "/> ls".
50
5111. Breakpoint hits. "Breakpoint 1: sys_open(..."
52
5312. Display local variables and function paramters.
54 (*) This operation gives wrong results, see known issue 1.
55
5613. Single stepping "(gdb) si".
57
5814. Remove breakpoint 1. "(gdb) del 1"
59
6015. Set hardware breakpoint "(gdb) hbreak sys_open".
61
6216. Continue "(gdb) c".
63
6417. Run ls in the target console "/> ls".
65
6618. Hardware breakpoint hits. "Breakpoint 1: sys_open(...".
67 (*) This hardware breakpoint will not be hit, see known issue 2.
68
6919. Continue "(gdb) c".
70
7120. Interrupt the target in GDB "Ctrl+C".
72
7321. Detach from the target "(gdb) detach".
74
7522. Exit GDB "(gdb) quit".
76
77
78Debug over the UART:
79
801. Compile and install the cross platform version of gdb for blackfin, which
81 can be found at $(BINROOT)/bfin-elf-gdb.
82
832. Apply this patch to the 2.6.x kernel. Select the menuconfig option under
84 "Kernel hacking" -> "Kernel debugging" -> "KGDB: kernel debug with remote gdb".
85 With this selected, option "Full Symbolic/Source Debugging support" and
86 "Compile the kernel with frame pointers" are also selected.
87
883. Select option "KGDB: connect over (UART)". Set "KGDB: UART port number" to be
89 a different one from the console. Don't forget to change the mode of
90 blackfin serial driver to PIO. Otherwise kgdb works incorrectly on UART.
91
924. If you want connect to kgdb when the kernel boots, enable
93 "KGDB: Wait for gdb connection early"
94
955. Compile kernel.
96
976. Connect minicom to the serial port of the console and boot the kernel image.
98
997. Start GDB client "bfin-elf-gdb vmlinux".
100
1018. Set the baud rate in GDB "(gdb) set remotebaud 57600".
102
1039. Connect to the target on the second serial port "(gdb) target remote /dev/ttyS1".
104
10510. Set software breakpoint "(gdb) break sys_open".
106
10711. Continue "(gdb) c".
108
10912. Run ls in the target console "/> ls".
110
11113. A breakpoint is hit. "Breakpoint 1: sys_open(..."
112
11314. All other operations are the same as that in KGDB over Ethernet.
114
115
116Debug over the same UART as console:
117
1181. Compile and install the cross platform version of gdb for blackfin, which
119 can be found at $(BINROOT)/bfin-elf-gdb.
120
1212. Apply this patch to the 2.6.x kernel. Select the menuconfig option under
122 "Kernel hacking" -> "Kernel debugging" -> "KGDB: kernel debug with remote gdb".
123 With this selected, option "Full Symbolic/Source Debugging support" and
124 "Compile the kernel with frame pointers" are also selected.
125
1263. Select option "KGDB: connect over UART". Set "KGDB: UART port number" to console.
127 Don't forget to change the mode of blackfin serial driver to PIO.
128 Otherwise kgdb works incorrectly on UART.
129
1304. If you want connect to kgdb when the kernel boots, enable
131 "KGDB: Wait for gdb connection early"
132
1335. Connect minicom to the serial port and boot the kernel image.
134
1356. (Optional) Ask target to wait for gdb connection by entering Ctrl+A. In minicom, you should enter Ctrl+A+A.
136
1377. Start GDB client "bfin-elf-gdb vmlinux".
138
1398. Set the baud rate in GDB "(gdb) set remotebaud 57600".
140
1419. Connect to the target "(gdb) target remote /dev/ttyS0".
142
14310. Set software breakpoint "(gdb) break sys_open".
144
14511. Continue "(gdb) c". Then enter Ctrl+C twice to stop GDB connection.
146
14712. Run ls in the target console "/> ls". Dummy string can be seen on the console.
148
14913. Then connect the gdb to target again. "(gdb) target remote /dev/ttyS0".
150 Now you will find a breakpoint is hit. "Breakpoint 1: sys_open(..."
151
15214. All other operations are the same as that in KGDB over Ethernet. The only
153 difference is that after continue command in GDB, please stop GDB
154 connection by 2 "Ctrl+C"s and connect again after breakpoints are hit or
155 Ctrl+A is entered.
diff --git a/Documentation/block/data-integrity.txt b/Documentation/block/data-integrity.txt
index e9dc8d86adc7..e8ca040ba2cf 100644
--- a/Documentation/block/data-integrity.txt
+++ b/Documentation/block/data-integrity.txt
@@ -246,7 +246,7 @@ will require extra work due to the application tag.
246 retrieve the tag buffer using bio_integrity_get_tag(). 246 retrieve the tag buffer using bio_integrity_get_tag().
247 247
248 248
2496.3 PASSING EXISTING INTEGRITY METADATA 2495.3 PASSING EXISTING INTEGRITY METADATA
250 250
251 Filesystems that either generate their own integrity metadata or 251 Filesystems that either generate their own integrity metadata or
252 are capable of transferring IMD from user space can use the 252 are capable of transferring IMD from user space can use the
@@ -283,7 +283,7 @@ will require extra work due to the application tag.
283 integrity upon completion. 283 integrity upon completion.
284 284
285 285
2866.4 REGISTERING A BLOCK DEVICE AS CAPABLE OF EXCHANGING INTEGRITY 2865.4 REGISTERING A BLOCK DEVICE AS CAPABLE OF EXCHANGING INTEGRITY
287 METADATA 287 METADATA
288 288
289 To enable integrity exchange on a block device the gendisk must be 289 To enable integrity exchange on a block device the gendisk must be
diff --git a/Documentation/block/deadline-iosched.txt b/Documentation/block/deadline-iosched.txt
index c23cab13c3d1..72576769e0f4 100644
--- a/Documentation/block/deadline-iosched.txt
+++ b/Documentation/block/deadline-iosched.txt
@@ -30,12 +30,18 @@ write_expire (in ms)
30Similar to read_expire mentioned above, but for writes. 30Similar to read_expire mentioned above, but for writes.
31 31
32 32
33fifo_batch 33fifo_batch (number of requests)
34---------- 34----------
35 35
36When a read request expires its deadline, we must move some requests from 36Requests are grouped into ``batches'' of a particular data direction (read or
37the sorted io scheduler list to the block device dispatch queue. fifo_batch 37write) which are serviced in increasing sector order. To limit extra seeking,
38controls how many requests we move. 38deadline expiries are only checked between batches. fifo_batch controls the
39maximum number of requests per batch.
40
41This parameter tunes the balance between per-request latency and aggregate
42throughput. When low latency is the primary concern, smaller is better (where
43a value of 1 yields first-come first-served behaviour). Increasing fifo_batch
44generally improves throughput, at the cost of latency variation.
39 45
40 46
41writes_starved (number of dispatches) 47writes_starved (number of dispatches)
diff --git a/Documentation/cdrom/ide-cd b/Documentation/cdrom/ide-cd
index 91c0dcc6fa5c..2c558cd6c1ef 100644
--- a/Documentation/cdrom/ide-cd
+++ b/Documentation/cdrom/ide-cd
@@ -145,8 +145,7 @@ useful for reading photocds.
145 145
146To play an audio CD, you should first unmount and remove any data 146To play an audio CD, you should first unmount and remove any data
147CDROM. Any of the CDROM player programs should then work (workman, 147CDROM. Any of the CDROM player programs should then work (workman,
148workbone, cdplayer, etc.). Lacking anything else, you could use the 148workbone, cdplayer, etc.).
149cdtester program in Documentation/cdrom/sbpcd.
150 149
151On a few drives, you can read digital audio directly using a program 150On a few drives, you can read digital audio directly using a program
152such as cdda2wav. The only types of drive which I've heard support 151such as cdda2wav. The only types of drive which I've heard support
diff --git a/Documentation/cris/README b/Documentation/cris/README
index 795a1dabe6c7..d9b086869a60 100644
--- a/Documentation/cris/README
+++ b/Documentation/cris/README
@@ -27,7 +27,7 @@ operating system.
27The ETRAX 100LX chip 27The ETRAX 100LX chip
28-------------------- 28--------------------
29 29
30For reference, plase see the press-release: 30For reference, please see the press-release:
31 31
32http://www.axis.com/news/us/001101_etrax.htm 32http://www.axis.com/news/us/001101_etrax.htm
33 33
diff --git a/Documentation/development-process/1.Intro b/Documentation/development-process/1.Intro
new file mode 100644
index 000000000000..8cc2cba2b10d
--- /dev/null
+++ b/Documentation/development-process/1.Intro
@@ -0,0 +1,274 @@
11: A GUIDE TO THE KERNEL DEVELOPMENT PROCESS
2
3The purpose of this document is to help developers (and their managers)
4work with the development community with a minimum of frustration. It is
5an attempt to document how this community works in a way which is
6accessible to those who are not intimately familiar with Linux kernel
7development (or, indeed, free software development in general). While
8there is some technical material here, this is very much a process-oriented
9discussion which does not require a deep knowledge of kernel programming to
10understand.
11
12
131.1: EXECUTIVE SUMMARY
14
15The rest of this section covers the scope of the kernel development process
16and the kinds of frustrations that developers and their employers can
17encounter there. There are a great many reasons why kernel code should be
18merged into the official ("mainline") kernel, including automatic
19availability to users, community support in many forms, and the ability to
20influence the direction of kernel development. Code contributed to the
21Linux kernel must be made available under a GPL-compatible license.
22
23Section 2 introduces the development process, the kernel release cycle, and
24the mechanics of the merge window. The various phases in the patch
25development, review, and merging cycle are covered. There is some
26discussion of tools and mailing lists. Developers wanting to get started
27with kernel development are encouraged to track down and fix bugs as an
28initial exercise.
29
30Section 3 covers early-stage project planning, with an emphasis on
31involving the development community as soon as possible.
32
33Section 4 is about the coding process; several pitfalls which have been
34encountered by other developers are discussed. Some requirements for
35patches are covered, and there is an introduction to some of the tools
36which can help to ensure that kernel patches are correct.
37
38Section 5 talks about the process of posting patches for review. To be
39taken seriously by the development community, patches must be properly
40formatted and described, and they must be sent to the right place.
41Following the advice in this section should help to ensure the best
42possible reception for your work.
43
44Section 6 covers what happens after posting patches; the job is far from
45done at that point. Working with reviewers is a crucial part of the
46development process; this section offers a number of tips on how to avoid
47problems at this important stage. Developers are cautioned against
48assuming that the job is done when a patch is merged into the mainline.
49
50Section 7 introduces a couple of "advanced" topics: managing patches with
51git and reviewing patches posted by others.
52
53Section 8 concludes the document with pointers to sources for more
54information on kernel development.
55
56
571.2: WHAT THIS DOCUMENT IS ABOUT
58
59The Linux kernel, at over 6 million lines of code and well over 1000 active
60contributors, is one of the largest and most active free software projects
61in existence. Since its humble beginning in 1991, this kernel has evolved
62into a best-of-breed operating system component which runs on pocket-sized
63digital music players, desktop PCs, the largest supercomputers in
64existence, and all types of systems in between. It is a robust, efficient,
65and scalable solution for almost any situation.
66
67With the growth of Linux has come an increase in the number of developers
68(and companies) wishing to participate in its development. Hardware
69vendors want to ensure that Linux supports their products well, making
70those products attractive to Linux users. Embedded systems vendors, who
71use Linux as a component in an integrated product, want Linux to be as
72capable and well-suited to the task at hand as possible. Distributors and
73other software vendors who base their products on Linux have a clear
74interest in the capabilities, performance, and reliability of the Linux
75kernel. And end users, too, will often wish to change Linux to make it
76better suit their needs.
77
78One of the most compelling features of Linux is that it is accessible to
79these developers; anybody with the requisite skills can improve Linux and
80influence the direction of its development. Proprietary products cannot
81offer this kind of openness, which is a characteristic of the free software
82process. But, if anything, the kernel is even more open than most other
83free software projects. A typical three-month kernel development cycle can
84involve over 1000 developers working for more than 100 different companies
85(or for no company at all).
86
87Working with the kernel development community is not especially hard. But,
88that notwithstanding, many potential contributors have experienced
89difficulties when trying to do kernel work. The kernel community has
90evolved its own distinct ways of operating which allow it to function
91smoothly (and produce a high-quality product) in an environment where
92thousands of lines of code are being changed every day. So it is not
93surprising that Linux kernel development process differs greatly from
94proprietary development methods.
95
96The kernel's development process may come across as strange and
97intimidating to new developers, but there are good reasons and solid
98experience behind it. A developer who does not understand the kernel
99community's ways (or, worse, who tries to flout or circumvent them) will
100have a frustrating experience in store. The development community, while
101being helpful to those who are trying to learn, has little time for those
102who will not listen or who do not care about the development process.
103
104It is hoped that those who read this document will be able to avoid that
105frustrating experience. There is a lot of material here, but the effort
106involved in reading it will be repaid in short order. The development
107community is always in need of developers who will help to make the kernel
108better; the following text should help you - or those who work for you -
109join our community.
110
111
1121.3: CREDITS
113
114This document was written by Jonathan Corbet, corbet@lwn.net. It has been
115improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland
116Dreier, Randy Dunlap, Jake Edge, Jiri Kosina, Matt Mackall, Arthur Marsh,
117Amanda McPherson, Andrew Morton, Andrew Price, Tsugikazu Shibata, and
118Jochen Voß.
119
120This work was supported by the Linux Foundation; thanks especially to
121Amanda McPherson, who saw the value of this effort and made it all happen.
122
123
1241.4: THE IMPORTANCE OF GETTING CODE INTO THE MAINLINE
125
126Some companies and developers occasionally wonder why they should bother
127learning how to work with the kernel community and get their code into the
128mainline kernel (the "mainline" being the kernel maintained by Linus
129Torvalds and used as a base by Linux distributors). In the short term,
130contributing code can look like an avoidable expense; it seems easier to
131just keep the code separate and support users directly. The truth of the
132matter is that keeping code separate ("out of tree") is a false economy.
133
134As a way of illustrating the costs of out-of-tree code, here are a few
135relevant aspects of the kernel development process; most of these will be
136discussed in greater detail later in this document. Consider:
137
138- Code which has been merged into the mainline kernel is available to all
139 Linux users. It will automatically be present on all distributions which
140 enable it. There is no need for driver disks, downloads, or the hassles
141 of supporting multiple versions of multiple distributions; it all just
142 works, for the developer and for the user. Incorporation into the
143 mainline solves a large number of distribution and support problems.
144
145- While kernel developers strive to maintain a stable interface to user
146 space, the internal kernel API is in constant flux. The lack of a stable
147 internal interface is a deliberate design decision; it allows fundamental
148 improvements to be made at any time and results in higher-quality code.
149 But one result of that policy is that any out-of-tree code requires
150 constant upkeep if it is to work with new kernels. Maintaining
151 out-of-tree code requires significant amounts of work just to keep that
152 code working.
153
154 Code which is in the mainline, instead, does not require this work as the
155 result of a simple rule requiring any developer who makes an API change
156 to also fix any code that breaks as the result of that change. So code
157 which has been merged into the mainline has significantly lower
158 maintenance costs.
159
160- Beyond that, code which is in the kernel will often be improved by other
161 developers. Surprising results can come from empowering your user
162 community and customers to improve your product.
163
164- Kernel code is subjected to review, both before and after merging into
165 the mainline. No matter how strong the original developer's skills are,
166 this review process invariably finds ways in which the code can be
167 improved. Often review finds severe bugs and security problems. This is
168 especially true for code which has been developed in a closed
169 environment; such code benefits strongly from review by outside
170 developers. Out-of-tree code is lower-quality code.
171
172- Participation in the development process is your way to influence the
173 direction of kernel development. Users who complain from the sidelines
174 are heard, but active developers have a stronger voice - and the ability
175 to implement changes which make the kernel work better for their needs.
176
177- When code is maintained separately, the possibility that a third party
178 will contribute a different implementation of a similar feature always
179 exists. Should that happen, getting your code merged will become much
180 harder - to the point of impossibility. Then you will be faced with the
181 unpleasant alternatives of either (1) maintaining a nonstandard feature
182 out of tree indefinitely, or (2) abandoning your code and migrating your
183 users over to the in-tree version.
184
185- Contribution of code is the fundamental action which makes the whole
186 process work. By contributing your code you can add new functionality to
187 the kernel and provide capabilities and examples which are of use to
188 other kernel developers. If you have developed code for Linux (or are
189 thinking about doing so), you clearly have an interest in the continued
190 success of this platform; contributing code is one of the best ways to
191 help ensure that success.
192
193All of the reasoning above applies to any out-of-tree kernel code,
194including code which is distributed in proprietary, binary-only form.
195There are, however, additional factors which should be taken into account
196before considering any sort of binary-only kernel code distribution. These
197include:
198
199- The legal issues around the distribution of proprietary kernel modules
200 are cloudy at best; quite a few kernel copyright holders believe that
201 most binary-only modules are derived products of the kernel and that, as
202 a result, their distribution is a violation of the GNU General Public
203 license (about which more will be said below). Your author is not a
204 lawyer, and nothing in this document can possibly be considered to be
205 legal advice. The true legal status of closed-source modules can only be
206 determined by the courts. But the uncertainty which haunts those modules
207 is there regardless.
208
209- Binary modules greatly increase the difficulty of debugging kernel
210 problems, to the point that most kernel developers will not even try. So
211 the distribution of binary-only modules will make it harder for your
212 users to get support from the community.
213
214- Support is also harder for distributors of binary-only modules, who must
215 provide a version of the module for every distribution and every kernel
216 version they wish to support. Dozens of builds of a single module can
217 be required to provide reasonably comprehensive coverage, and your users
218 will have to upgrade your module separately every time they upgrade their
219 kernel.
220
221- Everything that was said above about code review applies doubly to
222 closed-source code. Since this code is not available at all, it cannot
223 have been reviewed by the community and will, beyond doubt, have serious
224 problems.
225
226Makers of embedded systems, in particular, may be tempted to disregard much
227of what has been said in this section in the belief that they are shipping
228a self-contained product which uses a frozen kernel version and requires no
229more development after its release. This argument misses the value of
230widespread code review and the value of allowing your users to add
231capabilities to your product. But these products, too, have a limited
232commercial life, after which a new version must be released. At that
233point, vendors whose code is in the mainline and well maintained will be
234much better positioned to get the new product ready for market quickly.
235
236
2371.5: LICENSING
238
239Code is contributed to the Linux kernel under a number of licenses, but all
240code must be compatible with version 2 of the GNU General Public License
241(GPLv2), which is the license covering the kernel distribution as a whole.
242In practice, that means that all code contributions are covered either by
243GPLv2 (with, optionally, language allowing distribution under later
244versions of the GPL) or the three-clause BSD license. Any contributions
245which are not covered by a compatible license will not be accepted into the
246kernel.
247
248Copyright assignments are not required (or requested) for code contributed
249to the kernel. All code merged into the mainline kernel retains its
250original ownership; as a result, the kernel now has thousands of owners.
251
252One implication of this ownership structure is that any attempt to change
253the licensing of the kernel is doomed to almost certain failure. There are
254few practical scenarios where the agreement of all copyright holders could
255be obtained (or their code removed from the kernel). So, in particular,
256there is no prospect of a migration to version 3 of the GPL in the
257foreseeable future.
258
259It is imperative that all code contributed to the kernel be legitimately
260free software. For that reason, code from anonymous (or pseudonymous)
261contributors will not be accepted. All contributors are required to "sign
262off" on their code, stating that the code can be distributed with the
263kernel under the GPL. Code which has not been licensed as free software by
264its owner, or which risks creating copyright-related problems for the
265kernel (such as code which derives from reverse-engineering efforts lacking
266proper safeguards) cannot be contributed.
267
268Questions about copyright-related issues are common on Linux development
269mailing lists. Such questions will normally receive no shortage of
270answers, but one should bear in mind that the people answering those
271questions are not lawyers and cannot provide legal advice. If you have
272legal questions relating to Linux source code, there is no substitute for
273talking with a lawyer who understands this field. Relying on answers
274obtained on technical mailing lists is a risky affair.
diff --git a/Documentation/development-process/2.Process b/Documentation/development-process/2.Process
new file mode 100644
index 000000000000..d750321acd5a
--- /dev/null
+++ b/Documentation/development-process/2.Process
@@ -0,0 +1,459 @@
12: HOW THE DEVELOPMENT PROCESS WORKS
2
3Linux kernel development in the early 1990's was a pretty loose affair,
4with relatively small numbers of users and developers involved. With a
5user base in the millions and with some 2,000 developers involved over the
6course of one year, the kernel has since had to evolve a number of
7processes to keep development happening smoothly. A solid understanding of
8how the process works is required in order to be an effective part of it.
9
10
112.1: THE BIG PICTURE
12
13The kernel developers use a loosely time-based release process, with a new
14major kernel release happening every two or three months. The recent
15release history looks like this:
16
17 2.6.26 July 13, 2008
18 2.6.25 April 16, 2008
19 2.6.24 January 24, 2008
20 2.6.23 October 9, 2007
21 2.6.22 July 8, 2007
22 2.6.21 April 25, 2007
23 2.6.20 February 4, 2007
24
25Every 2.6.x release is a major kernel release with new features, internal
26API changes, and more. A typical 2.6 release can contain over 10,000
27changesets with changes to several hundred thousand lines of code. 2.6 is
28thus the leading edge of Linux kernel development; the kernel uses a
29rolling development model which is continually integrating major changes.
30
31A relatively straightforward discipline is followed with regard to the
32merging of patches for each release. At the beginning of each development
33cycle, the "merge window" is said to be open. At that time, code which is
34deemed to be sufficiently stable (and which is accepted by the development
35community) is merged into the mainline kernel. The bulk of changes for a
36new development cycle (and all of the major changes) will be merged during
37this time, at a rate approaching 1,000 changes ("patches," or "changesets")
38per day.
39
40(As an aside, it is worth noting that the changes integrated during the
41merge window do not come out of thin air; they have been collected, tested,
42and staged ahead of time. How that process works will be described in
43detail later on).
44
45The merge window lasts for two weeks. At the end of this time, Linus
46Torvalds will declare that the window is closed and release the first of
47the "rc" kernels. For the kernel which is destined to be 2.6.26, for
48example, the release which happens at the end of the merge window will be
49called 2.6.26-rc1. The -rc1 release is the signal that the time to merge
50new features has passed, and that the time to stabilize the next kernel has
51begun.
52
53Over the next six to ten weeks, only patches which fix problems should be
54submitted to the mainline. On occasion a more significant change will be
55allowed, but such occasions are rare; developers who try to merge new
56features outside of the merge window tend to get an unfriendly reception.
57As a general rule, if you miss the merge window for a given feature, the
58best thing to do is to wait for the next development cycle. (An occasional
59exception is made for drivers for previously-unsupported hardware; if they
60touch no in-tree code, they cannot cause regressions and should be safe to
61add at any time).
62
63As fixes make their way into the mainline, the patch rate will slow over
64time. Linus releases new -rc kernels about once a week; a normal series
65will get up to somewhere between -rc6 and -rc9 before the kernel is
66considered to be sufficiently stable and the final 2.6.x release is made.
67At that point the whole process starts over again.
68
69As an example, here is how the 2.6.25 development cycle went (all dates in
702008):
71
72 January 24 2.6.24 stable release
73 February 10 2.6.25-rc1, merge window closes
74 February 15 2.6.25-rc2
75 February 24 2.6.25-rc3
76 March 4 2.6.25-rc4
77 March 9 2.6.25-rc5
78 March 16 2.6.25-rc6
79 March 25 2.6.25-rc7
80 April 1 2.6.25-rc8
81 April 11 2.6.25-rc9
82 April 16 2.6.25 stable release
83
84How do the developers decide when to close the development cycle and create
85the stable release? The most significant metric used is the list of
86regressions from previous releases. No bugs are welcome, but those which
87break systems which worked in the past are considered to be especially
88serious. For this reason, patches which cause regressions are looked upon
89unfavorably and are quite likely to be reverted during the stabilization
90period.
91
92The developers' goal is to fix all known regressions before the stable
93release is made. In the real world, this kind of perfection is hard to
94achieve; there are just too many variables in a project of this size.
95There comes a point where delaying the final release just makes the problem
96worse; the pile of changes waiting for the next merge window will grow
97larger, creating even more regressions the next time around. So most 2.6.x
98kernels go out with a handful of known regressions though, hopefully, none
99of them are serious.
100
101Once a stable release is made, its ongoing maintenance is passed off to the
102"stable team," currently comprised of Greg Kroah-Hartman and Chris Wright.
103The stable team will release occasional updates to the stable release using
104the 2.6.x.y numbering scheme. To be considered for an update release, a
105patch must (1) fix a significant bug, and (2) already be merged into the
106mainline for the next development kernel. Continuing our 2.6.25 example,
107the history (as of this writing) is:
108
109 May 1 2.6.25.1
110 May 6 2.6.25.2
111 May 9 2.6.25.3
112 May 15 2.6.25.4
113 June 7 2.6.25.5
114 June 9 2.6.25.6
115 June 16 2.6.25.7
116 June 21 2.6.25.8
117 June 24 2.6.25.9
118
119Stable updates for a given kernel are made for approximately six months;
120after that, the maintenance of stable releases is solely the responsibility
121of the distributors which have shipped that particular kernel.
122
123
1242.2: THE LIFECYCLE OF A PATCH
125
126Patches do not go directly from the developer's keyboard into the mainline
127kernel. There is, instead, a somewhat involved (if somewhat informal)
128process designed to ensure that each patch is reviewed for quality and that
129each patch implements a change which is desirable to have in the mainline.
130This process can happen quickly for minor fixes, or, in the case of large
131and controversial changes, go on for years. Much developer frustration
132comes from a lack of understanding of this process or from attempts to
133circumvent it.
134
135In the hopes of reducing that frustration, this document will describe how
136a patch gets into the kernel. What follows below is an introduction which
137describes the process in a somewhat idealized way. A much more detailed
138treatment will come in later sections.
139
140The stages that a patch goes through are, generally:
141
142 - Design. This is where the real requirements for the patch - and the way
143 those requirements will be met - are laid out. Design work is often
144 done without involving the community, but it is better to do this work
145 in the open if at all possible; it can save a lot of time redesigning
146 things later.
147
148 - Early review. Patches are posted to the relevant mailing list, and
149 developers on that list reply with any comments they may have. This
150 process should turn up any major problems with a patch if all goes
151 well.
152
153 - Wider review. When the patch is getting close to ready for mainline
154 inclusion, it will be accepted by a relevant subsystem maintainer -
155 though this acceptance is not a guarantee that the patch will make it
156 all the way to the mainline. The patch will show up in the maintainer's
157 subsystem tree and into the staging trees (described below). When the
158 process works, this step leads to more extensive review of the patch and
159 the discovery of any problems resulting from the integration of this
160 patch with work being done by others.
161
162 - Merging into the mainline. Eventually, a successful patch will be
163 merged into the mainline repository managed by Linus Torvalds. More
164 comments and/or problems may surface at this time; it is important that
165 the developer be responsive to these and fix any issues which arise.
166
167 - Stable release. The number of users potentially affected by the patch
168 is now large, so, once again, new problems may arise.
169
170 - Long-term maintenance. While it is certainly possible for a developer
171 to forget about code after merging it, that sort of behavior tends to
172 leave a poor impression in the development community. Merging code
173 eliminates some of the maintenance burden, in that others will fix
174 problems caused by API changes. But the original developer should
175 continue to take responsibility for the code if it is to remain useful
176 in the longer term.
177
178One of the largest mistakes made by kernel developers (or their employers)
179is to try to cut the process down to a single "merging into the mainline"
180step. This approach invariably leads to frustration for everybody
181involved.
182
183
1842.3: HOW PATCHES GET INTO THE KERNEL
185
186There is exactly one person who can merge patches into the mainline kernel
187repository: Linus Torvalds. But, of the over 12,000 patches which went
188into the 2.6.25 kernel, only 250 (around 2%) were directly chosen by Linus
189himself. The kernel project has long since grown to a size where no single
190developer could possibly inspect and select every patch unassisted. The
191way the kernel developers have addressed this growth is through the use of
192a lieutenant system built around a chain of trust.
193
194The kernel code base is logically broken down into a set of subsystems:
195networking, specific architecture support, memory management, video
196devices, etc. Most subsystems have a designated maintainer, a developer
197who has overall responsibility for the code within that subsystem. These
198subsystem maintainers are the gatekeepers (in a loose way) for the portion
199of the kernel they manage; they are the ones who will (usually) accept a
200patch for inclusion into the mainline kernel.
201
202Subsystem maintainers each manage their own version of the kernel source
203tree, usually (but certainly not always) using the git source management
204tool. Tools like git (and related tools like quilt or mercurial) allow
205maintainers to track a list of patches, including authorship information
206and other metadata. At any given time, the maintainer can identify which
207patches in his or her repository are not found in the mainline.
208
209When the merge window opens, top-level maintainers will ask Linus to "pull"
210the patches they have selected for merging from their repositories. If
211Linus agrees, the stream of patches will flow up into his repository,
212becoming part of the mainline kernel. The amount of attention that Linus
213pays to specific patches received in a pull operation varies. It is clear
214that, sometimes, he looks quite closely. But, as a general rule, Linus
215trusts the subsystem maintainers to not send bad patches upstream.
216
217Subsystem maintainers, in turn, can pull patches from other maintainers.
218For example, the networking tree is built from patches which accumulated
219first in trees dedicated to network device drivers, wireless networking,
220etc. This chain of repositories can be arbitrarily long, though it rarely
221exceeds two or three links. Since each maintainer in the chain trusts
222those managing lower-level trees, this process is known as the "chain of
223trust."
224
225Clearly, in a system like this, getting patches into the kernel depends on
226finding the right maintainer. Sending patches directly to Linus is not
227normally the right way to go.
228
229
2302.4: STAGING TREES
231
232The chain of subsystem trees guides the flow of patches into the kernel,
233but it also raises an interesting question: what if somebody wants to look
234at all of the patches which are being prepared for the next merge window?
235Developers will be interested in what other changes are pending to see
236whether there are any conflicts to worry about; a patch which changes a
237core kernel function prototype, for example, will conflict with any other
238patches which use the older form of that function. Reviewers and testers
239want access to the changes in their integrated form before all of those
240changes land in the mainline kernel. One could pull changes from all of
241the interesting subsystem trees, but that would be a big and error-prone
242job.
243
244The answer comes in the form of staging trees, where subsystem trees are
245collected for testing and review. The older of these trees, maintained by
246Andrew Morton, is called "-mm" (for memory management, which is how it got
247started). The -mm tree integrates patches from a long list of subsystem
248trees; it also has some patches aimed at helping with debugging.
249
250Beyond that, -mm contains a significant collection of patches which have
251been selected by Andrew directly. These patches may have been posted on a
252mailing list, or they may apply to a part of the kernel for which there is
253no designated subsystem tree. As a result, -mm operates as a sort of
254subsystem tree of last resort; if there is no other obvious path for a
255patch into the mainline, it is likely to end up in -mm. Miscellaneous
256patches which accumulate in -mm will eventually either be forwarded on to
257an appropriate subsystem tree or be sent directly to Linus. In a typical
258development cycle, approximately 10% of the patches going into the mainline
259get there via -mm.
260
261The current -mm patch can always be found from the front page of
262
263 http://kernel.org/
264
265Those who want to see the current state of -mm can get the "-mm of the
266moment" tree, found at:
267
268 http://userweb.kernel.org/~akpm/mmotm/
269
270Use of the MMOTM tree is likely to be a frustrating experience, though;
271there is a definite chance that it will not even compile.
272
273The other staging tree, started more recently, is linux-next, maintained by
274Stephen Rothwell. The linux-next tree is, by design, a snapshot of what
275the mainline is expected to look like after the next merge window closes.
276Linux-next trees are announced on the linux-kernel and linux-next mailing
277lists when they are assembled; they can be downloaded from:
278
279 http://www.kernel.org/pub/linux/kernel/people/sfr/linux-next/
280
281Some information about linux-next has been gathered at:
282
283 http://linux.f-seidel.de/linux-next/pmwiki/
284
285How the linux-next tree will fit into the development process is still
286changing. As of this writing, the first full development cycle involving
287linux-next (2.6.26) is coming to an end; thus far, it has proved to be a
288valuable resource for finding and fixing integration problems before the
289beginning of the merge window. See http://lwn.net/Articles/287155/ for
290more information on how linux-next has worked to set up the 2.6.27 merge
291window.
292
293Some developers have begun to suggest that linux-next should be used as the
294target for future development as well. The linux-next tree does tend to be
295far ahead of the mainline and is more representative of the tree into which
296any new work will be merged. The downside to this idea is that the
297volatility of linux-next tends to make it a difficult development target.
298See http://lwn.net/Articles/289013/ for more information on this topic, and
299stay tuned; much is still in flux where linux-next is involved.
300
301
3022.5: TOOLS
303
304As can be seen from the above text, the kernel development process depends
305heavily on the ability to herd collections of patches in various
306directions. The whole thing would not work anywhere near as well as it
307does without suitably powerful tools. Tutorials on how to use these tools
308are well beyond the scope of this document, but there is space for a few
309pointers.
310
311By far the dominant source code management system used by the kernel
312community is git. Git is one of a number of distributed version control
313systems being developed in the free software community. It is well tuned
314for kernel development, in that it performs quite well when dealing with
315large repositories and large numbers of patches. It also has a reputation
316for being difficult to learn and use, though it has gotten better over
317time. Some sort of familiarity with git is almost a requirement for kernel
318developers; even if they do not use it for their own work, they'll need git
319to keep up with what other developers (and the mainline) are doing.
320
321Git is now packaged by almost all Linux distributions. There is a home
322page at
323
324 http://git.or.cz/
325
326That page has pointers to documentation and tutorials. One should be
327aware, in particular, of the Kernel Hacker's Guide to git, which has
328information specific to kernel development:
329
330 http://linux.yyz.us/git-howto.html
331
332Among the kernel developers who do not use git, the most popular choice is
333almost certainly Mercurial:
334
335 http://www.selenic.com/mercurial/
336
337Mercurial shares many features with git, but it provides an interface which
338many find easier to use.
339
340The other tool worth knowing about is Quilt:
341
342 http://savannah.nongnu.org/projects/quilt/
343
344Quilt is a patch management system, rather than a source code management
345system. It does not track history over time; it is, instead, oriented
346toward tracking a specific set of changes against an evolving code base.
347Some major subsystem maintainers use quilt to manage patches intended to go
348upstream. For the management of certain kinds of trees (-mm, for example),
349quilt is the best tool for the job.
350
351
3522.6: MAILING LISTS
353
354A great deal of Linux kernel development work is done by way of mailing
355lists. It is hard to be a fully-functioning member of the community
356without joining at least one list somewhere. But Linux mailing lists also
357represent a potential hazard to developers, who risk getting buried under a
358load of electronic mail, running afoul of the conventions used on the Linux
359lists, or both.
360
361Most kernel mailing lists are run on vger.kernel.org; the master list can
362be found at:
363
364 http://vger.kernel.org/vger-lists.html
365
366There are lists hosted elsewhere, though; a number of them are at
367lists.redhat.com.
368
369The core mailing list for kernel development is, of course, linux-kernel.
370This list is an intimidating place to be; volume can reach 500 messages per
371day, the amount of noise is high, the conversation can be severely
372technical, and participants are not always concerned with showing a high
373degree of politeness. But there is no other place where the kernel
374development community comes together as a whole; developers who avoid this
375list will miss important information.
376
377There are a few hints which can help with linux-kernel survival:
378
379- Have the list delivered to a separate folder, rather than your main
380 mailbox. One must be able to ignore the stream for sustained periods of
381 time.
382
383- Do not try to follow every conversation - nobody else does. It is
384 important to filter on both the topic of interest (though note that
385 long-running conversations can drift away from the original subject
386 without changing the email subject line) and the people who are
387 participating.
388
389- Do not feed the trolls. If somebody is trying to stir up an angry
390 response, ignore them.
391
392- When responding to linux-kernel email (or that on other lists) preserve
393 the Cc: header for all involved. In the absence of a strong reason (such
394 as an explicit request), you should never remove recipients. Always make
395 sure that the person you are responding to is in the Cc: list. This
396 convention also makes it unnecessary to explicitly ask to be copied on
397 replies to your postings.
398
399- Search the list archives (and the net as a whole) before asking
400 questions. Some developers can get impatient with people who clearly
401 have not done their homework.
402
403- Avoid top-posting (the practice of putting your answer above the quoted
404 text you are responding to). It makes your response harder to read and
405 makes a poor impression.
406
407- Ask on the correct mailing list. Linux-kernel may be the general meeting
408 point, but it is not the best place to find developers from all
409 subsystems.
410
411The last point - finding the correct mailing list - is a common place for
412beginning developers to go wrong. Somebody who asks a networking-related
413question on linux-kernel will almost certainly receive a polite suggestion
414to ask on the netdev list instead, as that is the list frequented by most
415networking developers. Other lists exist for the SCSI, video4linux, IDE,
416filesystem, etc. subsystems. The best place to look for mailing lists is
417in the MAINTAINERS file packaged with the kernel source.
418
419
4202.7: GETTING STARTED WITH KERNEL DEVELOPMENT
421
422Questions about how to get started with the kernel development process are
423common - from both individuals and companies. Equally common are missteps
424which make the beginning of the relationship harder than it has to be.
425
426Companies often look to hire well-known developers to get a development
427group started. This can, in fact, be an effective technique. But it also
428tends to be expensive and does not do much to grow the pool of experienced
429kernel developers. It is possible to bring in-house developers up to speed
430on Linux kernel development, given the investment of a bit of time. Taking
431this time can endow an employer with a group of developers who understand
432the kernel and the company both, and who can help to train others as well.
433Over the medium term, this is often the more profitable approach.
434
435Individual developers are often, understandably, at a loss for a place to
436start. Beginning with a large project can be intimidating; one often wants
437to test the waters with something smaller first. This is the point where
438some developers jump into the creation of patches fixing spelling errors or
439minor coding style issues. Unfortunately, such patches create a level of
440noise which is distracting for the development community as a whole, so,
441increasingly, they are looked down upon. New developers wishing to
442introduce themselves to the community will not get the sort of reception
443they wish for by these means.
444
445Andrew Morton gives this advice for aspiring kernel developers
446
447 The #1 project for all kernel beginners should surely be "make sure
448 that the kernel runs perfectly at all times on all machines which
449 you can lay your hands on". Usually the way to do this is to work
450 with others on getting things fixed up (this can require
451 persistence!) but that's fine - it's a part of kernel development.
452
453(http://lwn.net/Articles/283982/).
454
455In the absence of obvious problems to fix, developers are advised to look
456at the current lists of regressions and open bugs in general. There is
457never any shortage of issues in need of fixing; by addressing these issues,
458developers will gain experience with the process while, at the same time,
459building respect with the rest of the development community.
diff --git a/Documentation/development-process/3.Early-stage b/Documentation/development-process/3.Early-stage
new file mode 100644
index 000000000000..307a159a70ca
--- /dev/null
+++ b/Documentation/development-process/3.Early-stage
@@ -0,0 +1,195 @@
13: EARLY-STAGE PLANNING
2
3When contemplating a Linux kernel development project, it can be tempting
4to jump right in and start coding. As with any significant project,
5though, much of the groundwork for success is best laid before the first
6line of code is written. Some time spent in early planning and
7communication can save far more time later on.
8
9
103.1: SPECIFYING THE PROBLEM
11
12Like any engineering project, a successful kernel enhancement starts with a
13clear description of the problem to be solved. In some cases, this step is
14easy: when a driver is needed for a specific piece of hardware, for
15example. In others, though, it is tempting to confuse the real problem
16with the proposed solution, and that can lead to difficulties.
17
18Consider an example: some years ago, developers working with Linux audio
19sought a way to run applications without dropouts or other artifacts caused
20by excessive latency in the system. The solution they arrived at was a
21kernel module intended to hook into the Linux Security Module (LSM)
22framework; this module could be configured to give specific applications
23access to the realtime scheduler. This module was implemented and sent to
24the linux-kernel mailing list, where it immediately ran into problems.
25
26To the audio developers, this security module was sufficient to solve their
27immediate problem. To the wider kernel community, though, it was seen as a
28misuse of the LSM framework (which is not intended to confer privileges
29onto processes which they would not otherwise have) and a risk to system
30stability. Their preferred solutions involved realtime scheduling access
31via the rlimit mechanism for the short term, and ongoing latency reduction
32work in the long term.
33
34The audio community, however, could not see past the particular solution
35they had implemented; they were unwilling to accept alternatives. The
36resulting disagreement left those developers feeling disillusioned with the
37entire kernel development process; one of them went back to an audio list
38and posted this:
39
40 There are a number of very good Linux kernel developers, but they
41 tend to get outshouted by a large crowd of arrogant fools. Trying
42 to communicate user requirements to these people is a waste of
43 time. They are much too "intelligent" to listen to lesser mortals.
44
45(http://lwn.net/Articles/131776/).
46
47The reality of the situation was different; the kernel developers were far
48more concerned about system stability, long-term maintenance, and finding
49the right solution to the problem than they were with a specific module.
50The moral of the story is to focus on the problem - not a specific solution
51- and to discuss it with the development community before investing in the
52creation of a body of code.
53
54So, when contemplating a kernel development project, one should obtain
55answers to a short set of questions:
56
57 - What, exactly, is the problem which needs to be solved?
58
59 - Who are the users affected by this problem? Which use cases should the
60 solution address?
61
62 - How does the kernel fall short in addressing that problem now?
63
64Only then does it make sense to start considering possible solutions.
65
66
673.2: EARLY DISCUSSION
68
69When planning a kernel development project, it makes great sense to hold
70discussions with the community before launching into implementation. Early
71communication can save time and trouble in a number of ways:
72
73 - It may well be that the problem is addressed by the kernel in ways which
74 you have not understood. The Linux kernel is large and has a number of
75 features and capabilities which are not immediately obvious. Not all
76 kernel capabilities are documented as well as one might like, and it is
77 easy to miss things. Your author has seen the posting of a complete
78 driver which duplicated an existing driver that the new author had been
79 unaware of. Code which reinvents existing wheels is not only wasteful;
80 it will also not be accepted into the mainline kernel.
81
82 - There may be elements of the proposed solution which will not be
83 acceptable for mainline merging. It is better to find out about
84 problems like this before writing the code.
85
86 - It's entirely possible that other developers have thought about the
87 problem; they may have ideas for a better solution, and may be willing
88 to help in the creation of that solution.
89
90Years of experience with the kernel development community have taught a
91clear lesson: kernel code which is designed and developed behind closed
92doors invariably has problems which are only revealed when the code is
93released into the community. Sometimes these problems are severe,
94requiring months or years of effort before the code can be brought up to
95the kernel community's standards. Some examples include:
96
97 - The Devicescape network stack was designed and implemented for
98 single-processor systems. It could not be merged into the mainline
99 until it was made suitable for multiprocessor systems. Retrofitting
100 locking and such into code is a difficult task; as a result, the merging
101 of this code (now called mac80211) was delayed for over a year.
102
103 - The Reiser4 filesystem included a number of capabilities which, in the
104 core kernel developers' opinion, should have been implemented in the
105 virtual filesystem layer instead. It also included features which could
106 not easily be implemented without exposing the system to user-caused
107 deadlocks. The late revelation of these problems - and refusal to
108 address some of them - has caused Reiser4 to stay out of the mainline
109 kernel.
110
111 - The AppArmor security module made use of internal virtual filesystem
112 data structures in ways which were considered to be unsafe and
113 unreliable. This code has since been significantly reworked, but
114 remains outside of the mainline.
115
116In each of these cases, a great deal of pain and extra work could have been
117avoided with some early discussion with the kernel developers.
118
119
1203.3: WHO DO YOU TALK TO?
121
122When developers decide to take their plans public, the next question will
123be: where do we start? The answer is to find the right mailing list(s) and
124the right maintainer. For mailing lists, the best approach is to look in
125the MAINTAINERS file for a relevant place to post. If there is a suitable
126subsystem list, posting there is often preferable to posting on
127linux-kernel; you are more likely to reach developers with expertise in the
128relevant subsystem and the environment may be more supportive.
129
130Finding maintainers can be a bit harder. Again, the MAINTAINERS file is
131the place to start. That file tends to not always be up to date, though,
132and not all subsystems are represented there. The person listed in the
133MAINTAINERS file may, in fact, not be the person who is actually acting in
134that role currently. So, when there is doubt about who to contact, a
135useful trick is to use git (and "git log" in particular) to see who is
136currently active within the subsystem of interest. Look at who is writing
137patches, and who, if anybody, is attaching Signed-off-by lines to those
138patches. Those are the people who will be best placed to help with a new
139development project.
140
141If all else fails, talking to Andrew Morton can be an effective way to
142track down a maintainer for a specific piece of code.
143
144
1453.4: WHEN TO POST?
146
147If possible, posting your plans during the early stages can only be
148helpful. Describe the problem being solved and any plans that have been
149made on how the implementation will be done. Any information you can
150provide can help the development community provide useful input on the
151project.
152
153One discouraging thing which can happen at this stage is not a hostile
154reaction, but, instead, little or no reaction at all. The sad truth of the
155matter is (1) kernel developers tend to be busy, (2) there is no shortage
156of people with grand plans and little code (or even prospect of code) to
157back them up, and (3) nobody is obligated to review or comment on ideas
158posted by others. If a request-for-comments posting yields little in the
159way of comments, do not assume that it means there is no interest in the
160project. Unfortunately, you also cannot assume that there are no problems
161with your idea. The best thing to do in this situation is to proceed,
162keeping the community informed as you go.
163
164
1653.5: GETTING OFFICIAL BUY-IN
166
167If your work is being done in a corporate environment - as most Linux
168kernel work is - you must, obviously, have permission from suitably
169empowered managers before you can post your company's plans or code to a
170public mailing list. The posting of code which has not been cleared for
171release under a GPL-compatible license can be especially problematic; the
172sooner that a company's management and legal staff can agree on the posting
173of a kernel development project, the better off everybody involved will be.
174
175Some readers may be thinking at this point that their kernel work is
176intended to support a product which does not yet have an officially
177acknowledged existence. Revealing their employer's plans on a public
178mailing list may not be a viable option. In cases like this, it is worth
179considering whether the secrecy is really necessary; there is often no real
180need to keep development plans behind closed doors.
181
182That said, there are also cases where a company legitimately cannot
183disclose its plans early in the development process. Companies with
184experienced kernel developers may choose to proceed in an open-loop manner
185on the assumption that they will be able to avoid serious integration
186problems later. For companies without that sort of in-house expertise, the
187best option is often to hire an outside developer to review the plans under
188a non-disclosure agreement. The Linux Foundation operates an NDA program
189designed to help with this sort of situation; more information can be found
190at:
191
192 http://www.linuxfoundation.org/en/NDA_program
193
194This kind of review is often enough to avoid serious problems later on
195without requiring public disclosure of the project.
diff --git a/Documentation/development-process/4.Coding b/Documentation/development-process/4.Coding
new file mode 100644
index 000000000000..014aca8f14e2
--- /dev/null
+++ b/Documentation/development-process/4.Coding
@@ -0,0 +1,384 @@
14: GETTING THE CODE RIGHT
2
3While there is much to be said for a solid and community-oriented design
4process, the proof of any kernel development project is in the resulting
5code. It is the code which will be examined by other developers and merged
6(or not) into the mainline tree. So it is the quality of this code which
7will determine the ultimate success of the project.
8
9This section will examine the coding process. We'll start with a look at a
10number of ways in which kernel developers can go wrong. Then the focus
11will shift toward doing things right and the tools which can help in that
12quest.
13
14
154.1: PITFALLS
16
17* Coding style
18
19The kernel has long had a standard coding style, described in
20Documentation/CodingStyle. For much of that time, the policies described
21in that file were taken as being, at most, advisory. As a result, there is
22a substantial amount of code in the kernel which does not meet the coding
23style guidelines. The presence of that code leads to two independent
24hazards for kernel developers.
25
26The first of these is to believe that the kernel coding standards do not
27matter and are not enforced. The truth of the matter is that adding new
28code to the kernel is very difficult if that code is not coded according to
29the standard; many developers will request that the code be reformatted
30before they will even review it. A code base as large as the kernel
31requires some uniformity of code to make it possible for developers to
32quickly understand any part of it. So there is no longer room for
33strangely-formatted code.
34
35Occasionally, the kernel's coding style will run into conflict with an
36employer's mandated style. In such cases, the kernel's style will have to
37win before the code can be merged. Putting code into the kernel means
38giving up a degree of control in a number of ways - including control over
39how the code is formatted.
40
41The other trap is to assume that code which is already in the kernel is
42urgently in need of coding style fixes. Developers may start to generate
43reformatting patches as a way of gaining familiarity with the process, or
44as a way of getting their name into the kernel changelogs - or both. But
45pure coding style fixes are seen as noise by the development community;
46they tend to get a chilly reception. So this type of patch is best
47avoided. It is natural to fix the style of a piece of code while working
48on it for other reasons, but coding style changes should not be made for
49their own sake.
50
51The coding style document also should not be read as an absolute law which
52can never be transgressed. If there is a good reason to go against the
53style (a line which becomes far less readable if split to fit within the
5480-column limit, for example), just do it.
55
56
57* Abstraction layers
58
59Computer Science professors teach students to make extensive use of
60abstraction layers in the name of flexibility and information hiding.
61Certainly the kernel makes extensive use of abstraction; no project
62involving several million lines of code could do otherwise and survive.
63But experience has shown that excessive or premature abstraction can be
64just as harmful as premature optimization. Abstraction should be used to
65the level required and no further.
66
67At a simple level, consider a function which has an argument which is
68always passed as zero by all callers. One could retain that argument just
69in case somebody eventually needs to use the extra flexibility that it
70provides. By that time, though, chances are good that the code which
71implements this extra argument has been broken in some subtle way which was
72never noticed - because it has never been used. Or, when the need for
73extra flexibility arises, it does not do so in a way which matches the
74programmer's early expectation. Kernel developers will routinely submit
75patches to remove unused arguments; they should, in general, not be added
76in the first place.
77
78Abstraction layers which hide access to hardware - often to allow the bulk
79of a driver to be used with multiple operating systems - are especially
80frowned upon. Such layers obscure the code and may impose a performance
81penalty; they do not belong in the Linux kernel.
82
83On the other hand, if you find yourself copying significant amounts of code
84from another kernel subsystem, it is time to ask whether it would, in fact,
85make sense to pull out some of that code into a separate library or to
86implement that functionality at a higher level. There is no value in
87replicating the same code throughout the kernel.
88
89
90* #ifdef and preprocessor use in general
91
92The C preprocessor seems to present a powerful temptation to some C
93programmers, who see it as a way to efficiently encode a great deal of
94flexibility into a source file. But the preprocessor is not C, and heavy
95use of it results in code which is much harder for others to read and
96harder for the compiler to check for correctness. Heavy preprocessor use
97is almost always a sign of code which needs some cleanup work.
98
99Conditional compilation with #ifdef is, indeed, a powerful feature, and it
100is used within the kernel. But there is little desire to see code which is
101sprinkled liberally with #ifdef blocks. As a general rule, #ifdef use
102should be confined to header files whenever possible.
103Conditionally-compiled code can be confined to functions which, if the code
104is not to be present, simply become empty. The compiler will then quietly
105optimize out the call to the empty function. The result is far cleaner
106code which is easier to follow.
107
108C preprocessor macros present a number of hazards, including possible
109multiple evaluation of expressions with side effects and no type safety.
110If you are tempted to define a macro, consider creating an inline function
111instead. The code which results will be the same, but inline functions are
112easier to read, do not evaluate their arguments multiple times, and allow
113the compiler to perform type checking on the arguments and return value.
114
115
116* Inline functions
117
118Inline functions present a hazard of their own, though. Programmers can
119become enamored of the perceived efficiency inherent in avoiding a function
120call and fill a source file with inline functions. Those functions,
121however, can actually reduce performance. Since their code is replicated
122at each call site, they end up bloating the size of the compiled kernel.
123That, in turn, creates pressure on the processor's memory caches, which can
124slow execution dramatically. Inline functions, as a rule, should be quite
125small and relatively rare. The cost of a function call, after all, is not
126that high; the creation of large numbers of inline functions is a classic
127example of premature optimization.
128
129In general, kernel programmers ignore cache effects at their peril. The
130classic time/space tradeoff taught in beginning data structures classes
131often does not apply to contemporary hardware. Space *is* time, in that a
132larger program will run slower than one which is more compact.
133
134
135* Locking
136
137In May, 2006, the "Devicescape" networking stack was, with great
138fanfare, released under the GPL and made available for inclusion in the
139mainline kernel. This donation was welcome news; support for wireless
140networking in Linux was considered substandard at best, and the Devicescape
141stack offered the promise of fixing that situation. Yet, this code did not
142actually make it into the mainline until June, 2007 (2.6.22). What
143happened?
144
145This code showed a number of signs of having been developed behind
146corporate doors. But one large problem in particular was that it was not
147designed to work on multiprocessor systems. Before this networking stack
148(now called mac80211) could be merged, a locking scheme needed to be
149retrofitted onto it.
150
151Once upon a time, Linux kernel code could be developed without thinking
152about the concurrency issues presented by multiprocessor systems. Now,
153however, this document is being written on a dual-core laptop. Even on
154single-processor systems, work being done to improve responsiveness will
155raise the level of concurrency within the kernel. The days when kernel
156code could be written without thinking about locking are long past.
157
158Any resource (data structures, hardware registers, etc.) which could be
159accessed concurrently by more than one thread must be protected by a lock.
160New code should be written with this requirement in mind; retrofitting
161locking after the fact is a rather more difficult task. Kernel developers
162should take the time to understand the available locking primitives well
163enough to pick the right tool for the job. Code which shows a lack of
164attention to concurrency will have a difficult path into the mainline.
165
166
167* Regressions
168
169One final hazard worth mentioning is this: it can be tempting to make a
170change (which may bring big improvements) which causes something to break
171for existing users. This kind of change is called a "regression," and
172regressions have become most unwelcome in the mainline kernel. With few
173exceptions, changes which cause regressions will be backed out if the
174regression cannot be fixed in a timely manner. Far better to avoid the
175regression in the first place.
176
177It is often argued that a regression can be justified if it causes things
178to work for more people than it creates problems for. Why not make a
179change if it brings new functionality to ten systems for each one it
180breaks? The best answer to this question was expressed by Linus in July,
1812007:
182
183 So we don't fix bugs by introducing new problems. That way lies
184 madness, and nobody ever knows if you actually make any real
185 progress at all. Is it two steps forwards, one step back, or one
186 step forward and two steps back?
187
188(http://lwn.net/Articles/243460/).
189
190An especially unwelcome type of regression is any sort of change to the
191user-space ABI. Once an interface has been exported to user space, it must
192be supported indefinitely. This fact makes the creation of user-space
193interfaces particularly challenging: since they cannot be changed in
194incompatible ways, they must be done right the first time. For this
195reason, a great deal of thought, clear documentation, and wide review for
196user-space interfaces is always required.
197
198
199
2004.2: CODE CHECKING TOOLS
201
202For now, at least, the writing of error-free code remains an ideal that few
203of us can reach. What we can hope to do, though, is to catch and fix as
204many of those errors as possible before our code goes into the mainline
205kernel. To that end, the kernel developers have put together an impressive
206array of tools which can catch a wide variety of obscure problems in an
207automated way. Any problem caught by the computer is a problem which will
208not afflict a user later on, so it stands to reason that the automated
209tools should be used whenever possible.
210
211The first step is simply to heed the warnings produced by the compiler.
212Contemporary versions of gcc can detect (and warn about) a large number of
213potential errors. Quite often, these warnings point to real problems.
214Code submitted for review should, as a rule, not produce any compiler
215warnings. When silencing warnings, take care to understand the real cause
216and try to avoid "fixes" which make the warning go away without addressing
217its cause.
218
219Note that not all compiler warnings are enabled by default. Build the
220kernel with "make EXTRA_CFLAGS=-W" to get the full set.
221
222The kernel provides several configuration options which turn on debugging
223features; most of these are found in the "kernel hacking" submenu. Several
224of these options should be turned on for any kernel used for development or
225testing purposes. In particular, you should turn on:
226
227 - ENABLE_WARN_DEPRECATED, ENABLE_MUST_CHECK, and FRAME_WARN to get an
228 extra set of warnings for problems like the use of deprecated interfaces
229 or ignoring an important return value from a function. The output
230 generated by these warnings can be verbose, but one need not worry about
231 warnings from other parts of the kernel.
232
233 - DEBUG_OBJECTS will add code to track the lifetime of various objects
234 created by the kernel and warn when things are done out of order. If
235 you are adding a subsystem which creates (and exports) complex objects
236 of its own, consider adding support for the object debugging
237 infrastructure.
238
239 - DEBUG_SLAB can find a variety of memory allocation and use errors; it
240 should be used on most development kernels.
241
242 - DEBUG_SPINLOCK, DEBUG_SPINLOCK_SLEEP, and DEBUG_MUTEXES will find a
243 number of common locking errors.
244
245There are quite a few other debugging options, some of which will be
246discussed below. Some of them have a significant performance impact and
247should not be used all of the time. But some time spent learning the
248available options will likely be paid back many times over in short order.
249
250One of the heavier debugging tools is the locking checker, or "lockdep."
251This tool will track the acquisition and release of every lock (spinlock or
252mutex) in the system, the order in which locks are acquired relative to
253each other, the current interrupt environment, and more. It can then
254ensure that locks are always acquired in the same order, that the same
255interrupt assumptions apply in all situations, and so on. In other words,
256lockdep can find a number of scenarios in which the system could, on rare
257occasion, deadlock. This kind of problem can be painful (for both
258developers and users) in a deployed system; lockdep allows them to be found
259in an automated manner ahead of time. Code with any sort of non-trivial
260locking should be run with lockdep enabled before being submitted for
261inclusion.
262
263As a diligent kernel programmer, you will, beyond doubt, check the return
264status of any operation (such as a memory allocation) which can fail. The
265fact of the matter, though, is that the resulting failure recovery paths
266are, probably, completely untested. Untested code tends to be broken code;
267you could be much more confident of your code if all those error-handling
268paths had been exercised a few times.
269
270The kernel provides a fault injection framework which can do exactly that,
271especially where memory allocations are involved. With fault injection
272enabled, a configurable percentage of memory allocations will be made to
273fail; these failures can be restricted to a specific range of code.
274Running with fault injection enabled allows the programmer to see how the
275code responds when things go badly. See
276Documentation/fault-injection/fault-injection.text for more information on
277how to use this facility.
278
279Other kinds of errors can be found with the "sparse" static analysis tool.
280With sparse, the programmer can be warned about confusion between
281user-space and kernel-space addresses, mixture of big-endian and
282small-endian quantities, the passing of integer values where a set of bit
283flags is expected, and so on. Sparse must be installed separately (it can
284be found at http://www.kernel.org/pub/software/devel/sparse/ if your
285distributor does not package it); it can then be run on the code by adding
286"C=1" to your make command.
287
288Other kinds of portability errors are best found by compiling your code for
289other architectures. If you do not happen to have an S/390 system or a
290Blackfin development board handy, you can still perform the compilation
291step. A large set of cross compilers for x86 systems can be found at
292
293 http://www.kernel.org/pub/tools/crosstool/
294
295Some time spent installing and using these compilers will help avoid
296embarrassment later.
297
298
2994.3: DOCUMENTATION
300
301Documentation has often been more the exception than the rule with kernel
302development. Even so, adequate documentation will help to ease the merging
303of new code into the kernel, make life easier for other developers, and
304will be helpful for your users. In many cases, the addition of
305documentation has become essentially mandatory.
306
307The first piece of documentation for any patch is its associated
308changelog. Log entries should describe the problem being solved, the form
309of the solution, the people who worked on the patch, any relevant
310effects on performance, and anything else that might be needed to
311understand the patch.
312
313Any code which adds a new user-space interface - including new sysfs or
314/proc files - should include documentation of that interface which enables
315user-space developers to know what they are working with. See
316Documentation/ABI/README for a description of how this documentation should
317be formatted and what information needs to be provided.
318
319The file Documentation/kernel-parameters.txt describes all of the kernel's
320boot-time parameters. Any patch which adds new parameters should add the
321appropriate entries to this file.
322
323Any new configuration options must be accompanied by help text which
324clearly explains the options and when the user might want to select them.
325
326Internal API information for many subsystems is documented by way of
327specially-formatted comments; these comments can be extracted and formatted
328in a number of ways by the "kernel-doc" script. If you are working within
329a subsystem which has kerneldoc comments, you should maintain them and add
330them, as appropriate, for externally-available functions. Even in areas
331which have not been so documented, there is no harm in adding kerneldoc
332comments for the future; indeed, this can be a useful activity for
333beginning kernel developers. The format of these comments, along with some
334information on how to create kerneldoc templates can be found in the file
335Documentation/kernel-doc-nano-HOWTO.txt.
336
337Anybody who reads through a significant amount of existing kernel code will
338note that, often, comments are most notable by their absence. Once again,
339the expectations for new code are higher than they were in the past;
340merging uncommented code will be harder. That said, there is little desire
341for verbosely-commented code. The code should, itself, be readable, with
342comments explaining the more subtle aspects.
343
344Certain things should always be commented. Uses of memory barriers should
345be accompanied by a line explaining why the barrier is necessary. The
346locking rules for data structures generally need to be explained somewhere.
347Major data structures need comprehensive documentation in general.
348Non-obvious dependencies between separate bits of code should be pointed
349out. Anything which might tempt a code janitor to make an incorrect
350"cleanup" needs a comment saying why it is done the way it is. And so on.
351
352
3534.4: INTERNAL API CHANGES
354
355The binary interface provided by the kernel to user space cannot be broken
356except under the most severe circumstances. The kernel's internal
357programming interfaces, instead, are highly fluid and can be changed when
358the need arises. If you find yourself having to work around a kernel API,
359or simply not using a specific functionality because it does not meet your
360needs, that may be a sign that the API needs to change. As a kernel
361developer, you are empowered to make such changes.
362
363There are, of course, some catches. API changes can be made, but they need
364to be well justified. So any patch making an internal API change should be
365accompanied by a description of what the change is and why it is
366necessary. This kind of change should also be broken out into a separate
367patch, rather than buried within a larger patch.
368
369The other catch is that a developer who changes an internal API is
370generally charged with the task of fixing any code within the kernel tree
371which is broken by the change. For a widely-used function, this duty can
372lead to literally hundreds or thousands of changes - many of which are
373likely to conflict with work being done by other developers. Needless to
374say, this can be a large job, so it is best to be sure that the
375justification is solid.
376
377When making an incompatible API change, one should, whenever possible,
378ensure that code which has not been updated is caught by the compiler.
379This will help you to be sure that you have found all in-tree uses of that
380interface. It will also alert developers of out-of-tree code that there is
381a change that they need to respond to. Supporting out-of-tree code is not
382something that kernel developers need to be worried about, but we also do
383not have to make life harder for out-of-tree developers than it it needs to
384be.
diff --git a/Documentation/development-process/5.Posting b/Documentation/development-process/5.Posting
new file mode 100644
index 000000000000..dd48132a74dd
--- /dev/null
+++ b/Documentation/development-process/5.Posting
@@ -0,0 +1,278 @@
15: POSTING PATCHES
2
3Sooner or later, the time comes when your work is ready to be presented to
4the community for review and, eventually, inclusion into the mainline
5kernel. Unsurprisingly, the kernel development community has evolved a set
6of conventions and procedures which are used in the posting of patches;
7following them will make life much easier for everybody involved. This
8document will attempt to cover these expectations in reasonable detail;
9more information can also be found in the files SubmittingPatches,
10SubmittingDrivers, and SubmitChecklist in the kernel documentation
11directory.
12
13
145.1: WHEN TO POST
15
16There is a constant temptation to avoid posting patches before they are
17completely "ready." For simple patches, that is not a problem. If the
18work being done is complex, though, there is a lot to be gained by getting
19feedback from the community before the work is complete. So you should
20consider posting in-progress work, or even making a git tree available so
21that interested developers can catch up with your work at any time.
22
23When posting code which is not yet considered ready for inclusion, it is a
24good idea to say so in the posting itself. Also mention any major work
25which remains to be done and any known problems. Fewer people will look at
26patches which are known to be half-baked, but those who do will come in
27with the idea that they can help you drive the work in the right direction.
28
29
305.2: BEFORE CREATING PATCHES
31
32There are a number of things which should be done before you consider
33sending patches to the development community. These include:
34
35 - Test the code to the extent that you can. Make use of the kernel's
36 debugging tools, ensure that the kernel will build with all reasonable
37 combinations of configuration options, use cross-compilers to build for
38 different architectures, etc.
39
40 - Make sure your code is compliant with the kernel coding style
41 guidelines.
42
43 - Does your change have performance implications? If so, you should run
44 benchmarks showing what the impact (or benefit) of your change is; a
45 summary of the results should be included with the patch.
46
47 - Be sure that you have the right to post the code. If this work was done
48 for an employer, the employer likely has a right to the work and must be
49 agreeable with its release under the GPL.
50
51As a general rule, putting in some extra thought before posting code almost
52always pays back the effort in short order.
53
54
555.3: PATCH PREPARATION
56
57The preparation of patches for posting can be a surprising amount of work,
58but, once again, attempting to save time here is not generally advisable
59even in the short term.
60
61Patches must be prepared against a specific version of the kernel. As a
62general rule, a patch should be based on the current mainline as found in
63Linus's git tree. It may become necessary to make versions against -mm,
64linux-next, or a subsystem tree, though, to facilitate wider testing and
65review. Depending on the area of your patch and what is going on
66elsewhere, basing a patch against these other trees can require a
67significant amount of work resolving conflicts and dealing with API
68changes.
69
70Only the most simple changes should be formatted as a single patch;
71everything else should be made as a logical series of changes. Splitting
72up patches is a bit of an art; some developers spend a long time figuring
73out how to do it in the way that the community expects. There are a few
74rules of thumb, however, which can help considerably:
75
76 - The patch series you post will almost certainly not be the series of
77 changes found in your working revision control system. Instead, the
78 changes you have made need to be considered in their final form, then
79 split apart in ways which make sense. The developers are interested in
80 discrete, self-contained changes, not the path you took to get to those
81 changes.
82
83 - Each logically independent change should be formatted as a separate
84 patch. These changes can be small ("add a field to this structure") or
85 large (adding a significant new driver, for example), but they should be
86 conceptually small and amenable to a one-line description. Each patch
87 should make a specific change which can be reviewed on its own and
88 verified to do what it says it does.
89
90 - As a way of restating the guideline above: do not mix different types of
91 changes in the same patch. If a single patch fixes a critical security
92 bug, rearranges a few structures, and reformats the code, there is a
93 good chance that it will be passed over and the important fix will be
94 lost.
95
96 - Each patch should yield a kernel which builds and runs properly; if your
97 patch series is interrupted in the middle, the result should still be a
98 working kernel. Partial application of a patch series is a common
99 scenario when the "git bisect" tool is used to find regressions; if the
100 result is a broken kernel, you will make life harder for developers and
101 users who are engaging in the noble work of tracking down problems.
102
103 - Do not overdo it, though. One developer recently posted a set of edits
104 to a single file as 500 separate patches - an act which did not make him
105 the most popular person on the kernel mailing list. A single patch can
106 be reasonably large as long as it still contains a single *logical*
107 change.
108
109 - It can be tempting to add a whole new infrastructure with a series of
110 patches, but to leave that infrastructure unused until the final patch
111 in the series enables the whole thing. This temptation should be
112 avoided if possible; if that series adds regressions, bisection will
113 finger the last patch as the one which caused the problem, even though
114 the real bug is elsewhere. Whenever possible, a patch which adds new
115 code should make that code active immediately.
116
117Working to create the perfect patch series can be a frustrating process
118which takes quite a bit of time and thought after the "real work" has been
119done. When done properly, though, it is time well spent.
120
121
1225.4: PATCH FORMATTING
123
124So now you have a perfect series of patches for posting, but the work is
125not done quite yet. Each patch needs to be formatted into a message which
126quickly and clearly communicates its purpose to the rest of the world. To
127that end, each patch will be composed of the following:
128
129 - An optional "From" line naming the author of the patch. This line is
130 only necessary if you are passing on somebody else's patch via email,
131 but it never hurts to add it when in doubt.
132
133 - A one-line description of what the patch does. This message should be
134 enough for a reader who sees it with no other context to figure out the
135 scope of the patch; it is the line that will show up in the "short form"
136 changelogs. This message is usually formatted with the relevant
137 subsystem name first, followed by the purpose of the patch. For
138 example:
139
140 gpio: fix build on CONFIG_GPIO_SYSFS=n
141
142 - A blank line followed by a detailed description of the contents of the
143 patch. This description can be as long as is required; it should say
144 what the patch does and why it should be applied to the kernel.
145
146 - One or more tag lines, with, at a minimum, one Signed-off-by: line from
147 the author of the patch. Tags will be described in more detail below.
148
149The above three items should, normally, be the text used when committing
150the change to a revision control system. They are followed by:
151
152 - The patch itself, in the unified ("-u") patch format. Using the "-p"
153 option to diff will associate function names with changes, making the
154 resulting patch easier for others to read.
155
156You should avoid including changes to irrelevant files (those generated by
157the build process, for example, or editor backup files) in the patch. The
158file "dontdiff" in the Documentation directory can help in this regard;
159pass it to diff with the "-X" option.
160
161The tags mentioned above are used to describe how various developers have
162been associated with the development of this patch. They are described in
163detail in the SubmittingPatches document; what follows here is a brief
164summary. Each of these lines has the format:
165
166 tag: Full Name <email address> optional-other-stuff
167
168The tags in common use are:
169
170 - Signed-off-by: this is a developer's certification that he or she has
171 the right to submit the patch for inclusion into the kernel. It is an
172 agreement to the Developer's Certificate of Origin, the full text of
173 which can be found in Documentation/SubmittingPatches. Code without a
174 proper signoff cannot be merged into the mainline.
175
176 - Acked-by: indicates an agreement by another developer (often a
177 maintainer of the relevant code) that the patch is appropriate for
178 inclusion into the kernel.
179
180 - Tested-by: states that the named person has tested the patch and found
181 it to work.
182
183 - Reviewed-by: the named developer has reviewed the patch for correctness;
184 see the reviewer's statement in Documentation/SubmittingPatches for more
185 detail.
186
187 - Reported-by: names a user who reported a problem which is fixed by this
188 patch; this tag is used to give credit to the (often underappreciated)
189 people who test our code and let us know when things do not work
190 correctly.
191
192 - Cc: the named person received a copy of the patch and had the
193 opportunity to comment on it.
194
195Be careful in the addition of tags to your patches: only Cc: is appropriate
196for addition without the explicit permission of the person named.
197
198
1995.5: SENDING THE PATCH
200
201Before you mail your patches, there are a couple of other things you should
202take care of:
203
204 - Are you sure that your mailer will not corrupt the patches? Patches
205 which have had gratuitous white-space changes or line wrapping performed
206 by the mail client will not apply at the other end, and often will not
207 be examined in any detail. If there is any doubt at all, mail the patch
208 to yourself and convince yourself that it shows up intact.
209
210 Documentation/email-clients.txt has some helpful hints on making
211 specific mail clients work for sending patches.
212
213 - Are you sure your patch is free of silly mistakes? You should always
214 run patches through scripts/checkpatch.pl and address the complaints it
215 comes up with. Please bear in mind that checkpatch.pl, while being the
216 embodiment of a fair amount of thought about what kernel patches should
217 look like, is not smarter than you. If fixing a checkpatch.pl complaint
218 would make the code worse, don't do it.
219
220Patches should always be sent as plain text. Please do not send them as
221attachments; that makes it much harder for reviewers to quote sections of
222the patch in their replies. Instead, just put the patch directly into your
223message.
224
225When mailing patches, it is important to send copies to anybody who might
226be interested in it. Unlike some other projects, the kernel encourages
227people to err on the side of sending too many copies; don't assume that the
228relevant people will see your posting on the mailing lists. In particular,
229copies should go to:
230
231 - The maintainer(s) of the affected subsystem(s). As described earlier,
232 the MAINTAINERS file is the first place to look for these people.
233
234 - Other developers who have been working in the same area - especially
235 those who might be working there now. Using git to see who else has
236 modified the files you are working on can be helpful.
237
238 - If you are responding to a bug report or a feature request, copy the
239 original poster as well.
240
241 - Send a copy to the relevant mailing list, or, if nothing else applies,
242 the linux-kernel list.
243
244 - If you are fixing a bug, think about whether the fix should go into the
245 next stable update. If so, stable@kernel.org should get a copy of the
246 patch. Also add a "Cc: stable@kernel.org" to the tags within the patch
247 itself; that will cause the stable team to get a notification when your
248 fix goes into the mainline.
249
250When selecting recipients for a patch, it is good to have an idea of who
251you think will eventually accept the patch and get it merged. While it
252is possible to send patches directly to Linus Torvalds and have him merge
253them, things are not normally done that way. Linus is busy, and there are
254subsystem maintainers who watch over specific parts of the kernel. Usually
255you will be wanting that maintainer to merge your patches. If there is no
256obvious maintainer, Andrew Morton is often the patch target of last resort.
257
258Patches need good subject lines. The canonical format for a patch line is
259something like:
260
261 [PATCH nn/mm] subsys: one-line description of the patch
262
263where "nn" is the ordinal number of the patch, "mm" is the total number of
264patches in the series, and "subsys" is the name of the affected subsystem.
265Clearly, nn/mm can be omitted for a single, standalone patch.
266
267If you have a significant series of patches, it is customary to send an
268introductory description as part zero. This convention is not universally
269followed though; if you use it, remember that information in the
270introduction does not make it into the kernel changelogs. So please ensure
271that the patches, themselves, have complete changelog information.
272
273In general, the second and following parts of a multi-part patch should be
274sent as a reply to the first part so that they all thread together at the
275receiving end. Tools like git and quilt have commands to mail out a set of
276patches with the proper threading. If you have a long series, though, and
277are using git, please provide the --no-chain-reply-to option to avoid
278creating exceptionally deep nesting.
diff --git a/Documentation/development-process/6.Followthrough b/Documentation/development-process/6.Followthrough
new file mode 100644
index 000000000000..a8fba3d83a85
--- /dev/null
+++ b/Documentation/development-process/6.Followthrough
@@ -0,0 +1,202 @@
16: FOLLOWTHROUGH
2
3At this point, you have followed the guidelines given so far and, with the
4addition of your own engineering skills, have posted a perfect series of
5patches. One of the biggest mistakes that even experienced kernel
6developers can make is to conclude that their work is now done. In truth,
7posting patches indicates a transition into the next stage of the process,
8with, possibly, quite a bit of work yet to be done.
9
10It is a rare patch which is so good at its first posting that there is no
11room for improvement. The kernel development process recognizes this fact,
12and, as a result, is heavily oriented toward the improvement of posted
13code. You, as the author of that code, will be expected to work with the
14kernel community to ensure that your code is up to the kernel's quality
15standards. A failure to participate in this process is quite likely to
16prevent the inclusion of your patches into the mainline.
17
18
196.1: WORKING WITH REVIEWERS
20
21A patch of any significance will result in a number of comments from other
22developers as they review the code. Working with reviewers can be, for
23many developers, the most intimidating part of the kernel development
24process. Life can be made much easier, though, if you keep a few things in
25mind:
26
27 - If you have explained your patch well, reviewers will understand its
28 value and why you went to the trouble of writing it. But that value
29 will not keep them from asking a fundamental question: what will it be
30 like to maintain a kernel with this code in it five or ten years later?
31 Many of the changes you may be asked to make - from coding style tweaks
32 to substantial rewrites - come from the understanding that Linux will
33 still be around and under development a decade from now.
34
35 - Code review is hard work, and it is a relatively thankless occupation;
36 people remember who wrote kernel code, but there is little lasting fame
37 for those who reviewed it. So reviewers can get grumpy, especially when
38 they see the same mistakes being made over and over again. If you get a
39 review which seems angry, insulting, or outright offensive, resist the
40 impulse to respond in kind. Code review is about the code, not about
41 the people, and code reviewers are not attacking you personally.
42
43 - Similarly, code reviewers are not trying to promote their employers'
44 agendas at the expense of your own. Kernel developers often expect to
45 be working on the kernel years from now, but they understand that their
46 employer could change. They truly are, almost without exception,
47 working toward the creation of the best kernel they can; they are not
48 trying to create discomfort for their employers' competitors.
49
50What all of this comes down to is that, when reviewers send you comments,
51you need to pay attention to the technical observations that they are
52making. Do not let their form of expression or your own pride keep that
53from happening. When you get review comments on a patch, take the time to
54understand what the reviewer is trying to say. If possible, fix the things
55that the reviewer is asking you to fix. And respond back to the reviewer:
56thank them, and describe how you will answer their questions.
57
58Note that you do not have to agree with every change suggested by
59reviewers. If you believe that the reviewer has misunderstood your code,
60explain what is really going on. If you have a technical objection to a
61suggested change, describe it and justify your solution to the problem. If
62your explanations make sense, the reviewer will accept them. Should your
63explanation not prove persuasive, though, especially if others start to
64agree with the reviewer, take some time to think things over again. It can
65be easy to become blinded by your own solution to a problem to the point
66that you don't realize that something is fundamentally wrong or, perhaps,
67you're not even solving the right problem.
68
69One fatal mistake is to ignore review comments in the hope that they will
70go away. They will not go away. If you repost code without having
71responded to the comments you got the time before, you're likely to find
72that your patches go nowhere.
73
74Speaking of reposting code: please bear in mind that reviewers are not
75going to remember all the details of the code you posted the last time
76around. So it is always a good idea to remind reviewers of previously
77raised issues and how you dealt with them; the patch changelog is a good
78place for this kind of information. Reviewers should not have to search
79through list archives to familiarize themselves with what was said last
80time; if you help them get a running start, they will be in a better mood
81when they revisit your code.
82
83What if you've tried to do everything right and things still aren't going
84anywhere? Most technical disagreements can be resolved through discussion,
85but there are times when somebody simply has to make a decision. If you
86honestly believe that this decision is going against you wrongly, you can
87always try appealing to a higher power. As of this writing, that higher
88power tends to be Andrew Morton. Andrew has a great deal of respect in the
89kernel development community; he can often unjam a situation which seems to
90be hopelessly blocked. Appealing to Andrew should not be done lightly,
91though, and not before all other alternatives have been explored. And bear
92in mind, of course, that he may not agree with you either.
93
94
956.2: WHAT HAPPENS NEXT
96
97If a patch is considered to be a good thing to add to the kernel, and once
98most of the review issues have been resolved, the next step is usually
99entry into a subsystem maintainer's tree. How that works varies from one
100subsystem to the next; each maintainer has his or her own way of doing
101things. In particular, there may be more than one tree - one, perhaps,
102dedicated to patches planned for the next merge window, and another for
103longer-term work.
104
105For patches applying to areas for which there is no obvious subsystem tree
106(memory management patches, for example), the default tree often ends up
107being -mm. Patches which affect multiple subsystems can also end up going
108through the -mm tree.
109
110Inclusion into a subsystem tree can bring a higher level of visibility to a
111patch. Now other developers working with that tree will get the patch by
112default. Subsystem trees typically feed into -mm and linux-next as well,
113making their contents visible to the development community as a whole. At
114this point, there's a good chance that you will get more comments from a
115new set of reviewers; these comments need to be answered as in the previous
116round.
117
118What may also happen at this point, depending on the nature of your patch,
119is that conflicts with work being done by others turn up. In the worst
120case, heavy patch conflicts can result in some work being put on the back
121burner so that the remaining patches can be worked into shape and merged.
122Other times, conflict resolution will involve working with the other
123developers and, possibly, moving some patches between trees to ensure that
124everything applies cleanly. This work can be a pain, but count your
125blessings: before the advent of the linux-next tree, these conflicts often
126only turned up during the merge window and had to be addressed in a hurry.
127Now they can be resolved at leisure, before the merge window opens.
128
129Some day, if all goes well, you'll log on and see that your patch has been
130merged into the mainline kernel. Congratulations! Once the celebration is
131complete (and you have added yourself to the MAINTAINERS file), though, it
132is worth remembering an important little fact: the job still is not done.
133Merging into the mainline brings its own challenges.
134
135To begin with, the visibility of your patch has increased yet again. There
136may be a new round of comments from developers who had not been aware of
137the patch before. It may be tempting to ignore them, since there is no
138longer any question of your code being merged. Resist that temptation,
139though; you still need to be responsive to developers who have questions or
140suggestions.
141
142More importantly, though: inclusion into the mainline puts your code into
143the hands of a much larger group of testers. Even if you have contributed
144a driver for hardware which is not yet available, you will be surprised by
145how many people will build your code into their kernels. And, of course,
146where there are testers, there will be bug reports.
147
148The worst sort of bug reports are regressions. If your patch causes a
149regression, you'll find an uncomfortable number of eyes upon you;
150regressions need to be fixed as soon as possible. If you are unwilling or
151unable to fix the regression (and nobody else does it for you), your patch
152will almost certainly be removed during the stabilization period. Beyond
153negating all of the work you have done to get your patch into the mainline,
154having a patch pulled as the result of a failure to fix a regression could
155well make it harder for you to get work merged in the future.
156
157After any regressions have been dealt with, there may be other, ordinary
158bugs to deal with. The stabilization period is your best opportunity to
159fix these bugs and ensure that your code's debut in a mainline kernel
160release is as solid as possible. So, please, answer bug reports, and fix
161the problems if at all possible. That's what the stabilization period is
162for; you can start creating cool new patches once any problems with the old
163ones have been taken care of.
164
165And don't forget that there are other milestones which may also create bug
166reports: the next mainline stable release, when prominent distributors pick
167up a version of the kernel containing your patch, etc. Continuing to
168respond to these reports is a matter of basic pride in your work. If that
169is insufficient motivation, though, it's also worth considering that the
170development community remembers developers who lose interest in their code
171after it's merged. The next time you post a patch, they will be evaluating
172it with the assumption that you will not be around to maintain it
173afterward.
174
175
1766.3: OTHER THINGS THAT CAN HAPPEN
177
178One day, you may open your mail client and see that somebody has mailed you
179a patch to your code. That is one of the advantages of having your code
180out there in the open, after all. If you agree with the patch, you can
181either forward it on to the subsystem maintainer (be sure to include a
182proper From: line so that the attribution is correct, and add a signoff of
183your own), or send an Acked-by: response back and let the original poster
184send it upward.
185
186If you disagree with the patch, send a polite response explaining why. If
187possible, tell the author what changes need to be made to make the patch
188acceptable to you. There is a certain resistance to merging patches which
189are opposed by the author and maintainer of the code, but it only goes so
190far. If you are seen as needlessly blocking good work, those patches will
191eventually flow around you and get into the mainline anyway. In the Linux
192kernel, nobody has absolute veto power over any code. Except maybe Linus.
193
194On very rare occasion, you may see something completely different: another
195developer posts a different solution to your problem. At that point,
196chances are that one of the two patches will not be merged, and "mine was
197here first" is not considered to be a compelling technical argument. If
198somebody else's patch displaces yours and gets into the mainline, there is
199really only one way to respond: be pleased that your problem got solved and
200get on with your work. Having one's work shoved aside in this manner can
201be hurtful and discouraging, but the community will remember your reaction
202long after they have forgotten whose patch actually got merged.
diff --git a/Documentation/development-process/7.AdvancedTopics b/Documentation/development-process/7.AdvancedTopics
new file mode 100644
index 000000000000..a2cf74093aa1
--- /dev/null
+++ b/Documentation/development-process/7.AdvancedTopics
@@ -0,0 +1,173 @@
17: ADVANCED TOPICS
2
3At this point, hopefully, you have a handle on how the development process
4works. There is still more to learn, however! This section will cover a
5number of topics which can be helpful for developers wanting to become a
6regular part of the Linux kernel development process.
7
87.1: MANAGING PATCHES WITH GIT
9
10The use of distributed version control for the kernel began in early 2002,
11when Linus first started playing with the proprietary BitKeeper
12application. While BitKeeper was controversial, the approach to software
13version management it embodied most certainly was not. Distributed version
14control enabled an immediate acceleration of the kernel development
15project. In current times, there are several free alternatives to
16BitKeeper. For better or for worse, the kernel project has settled on git
17as its tool of choice.
18
19Managing patches with git can make life much easier for the developer,
20especially as the volume of those patches grows. Git also has its rough
21edges and poses certain hazards; it is a young and powerful tool which is
22still being civilized by its developers. This document will not attempt to
23teach the reader how to use git; that would be sufficient material for a
24long document in its own right. Instead, the focus here will be on how git
25fits into the kernel development process in particular. Developers who
26wish to come up to speed with git will find more information at:
27
28 http://git.or.cz/
29
30 http://www.kernel.org/pub/software/scm/git/docs/user-manual.html
31
32and on various tutorials found on the web.
33
34The first order of business is to read the above sites and get a solid
35understanding of how git works before trying to use it to make patches
36available to others. A git-using developer should be able to obtain a copy
37of the mainline repository, explore the revision history, commit changes to
38the tree, use branches, etc. An understanding of git's tools for the
39rewriting of history (such as rebase) is also useful. Git comes with its
40own terminology and concepts; a new user of git should know about refs,
41remote branches, the index, fast-forward merges, pushes and pulls, detached
42heads, etc. It can all be a little intimidating at the outset, but the
43concepts are not that hard to grasp with a bit of study.
44
45Using git to generate patches for submission by email can be a good
46exercise while coming up to speed.
47
48When you are ready to start putting up git trees for others to look at, you
49will, of course, need a server that can be pulled from. Setting up such a
50server with git-daemon is relatively straightforward if you have a system
51which is accessible to the Internet. Otherwise, free, public hosting sites
52(Github, for example) are starting to appear on the net. Established
53developers can get an account on kernel.org, but those are not easy to come
54by; see http://kernel.org/faq/ for more information.
55
56The normal git workflow involves the use of a lot of branches. Each line
57of development can be separated into a separate "topic branch" and
58maintained independently. Branches in git are cheap, there is no reason to
59not make free use of them. And, in any case, you should not do your
60development in any branch which you intend to ask others to pull from.
61Publicly-available branches should be created with care; merge in patches
62from development branches when they are in complete form and ready to go -
63not before.
64
65Git provides some powerful tools which can allow you to rewrite your
66development history. An inconvenient patch (one which breaks bisection,
67say, or which has some other sort of obvious bug) can be fixed in place or
68made to disappear from the history entirely. A patch series can be
69rewritten as if it had been written on top of today's mainline, even though
70you have been working on it for months. Changes can be transparently
71shifted from one branch to another. And so on. Judicious use of git's
72ability to revise history can help in the creation of clean patch sets with
73fewer problems.
74
75Excessive use of this capability can lead to other problems, though, beyond
76a simple obsession for the creation of the perfect project history.
77Rewriting history will rewrite the changes contained in that history,
78turning a tested (hopefully) kernel tree into an untested one. But, beyond
79that, developers cannot easily collaborate if they do not have a shared
80view of the project history; if you rewrite history which other developers
81have pulled into their repositories, you will make life much more difficult
82for those developers. So a simple rule of thumb applies here: history
83which has been exported to others should generally be seen as immutable
84thereafter.
85
86So, once you push a set of changes to your publicly-available server, those
87changes should not be rewritten. Git will attempt to enforce this rule if
88you try to push changes which do not result in a fast-forward merge
89(i.e. changes which do not share the same history). It is possible to
90override this check, and there may be times when it is necessary to rewrite
91an exported tree. Moving changesets between trees to avoid conflicts in
92linux-next is one example. But such actions should be rare. This is one
93of the reasons why development should be done in private branches (which
94can be rewritten if necessary) and only moved into public branches when
95it's in a reasonably advanced state.
96
97As the mainline (or other tree upon which a set of changes is based)
98advances, it is tempting to merge with that tree to stay on the leading
99edge. For a private branch, rebasing can be an easy way to keep up with
100another tree, but rebasing is not an option once a tree is exported to the
101world. Once that happens, a full merge must be done. Merging occasionally
102makes good sense, but overly frequent merges can clutter the history
103needlessly. Suggested technique in this case is to merge infrequently, and
104generally only at specific release points (such as a mainline -rc
105release). If you are nervous about specific changes, you can always
106perform test merges in a private branch. The git "rerere" tool can be
107useful in such situations; it remembers how merge conflicts were resolved
108so that you don't have to do the same work twice.
109
110One of the biggest recurring complaints about tools like git is this: the
111mass movement of patches from one repository to another makes it easy to
112slip in ill-advised changes which go into the mainline below the review
113radar. Kernel developers tend to get unhappy when they see that kind of
114thing happening; putting up a git tree with unreviewed or off-topic patches
115can affect your ability to get trees pulled in the future. Quoting Linus:
116
117 You can send me patches, but for me to pull a git patch from you, I
118 need to know that you know what you're doing, and I need to be able
119 to trust things *without* then having to go and check every
120 individual change by hand.
121
122(http://lwn.net/Articles/224135/).
123
124To avoid this kind of situation, ensure that all patches within a given
125branch stick closely to the associated topic; a "driver fixes" branch
126should not be making changes to the core memory management code. And, most
127importantly, do not use a git tree to bypass the review process. Post an
128occasional summary of the tree to the relevant list, and, when the time is
129right, request that the tree be included in linux-next.
130
131If and when others start to send patches for inclusion into your tree,
132don't forget to review them. Also ensure that you maintain the correct
133authorship information; the git "am" tool does its best in this regard, but
134you may have to add a "From:" line to the patch if it has been relayed to
135you via a third party.
136
137When requesting a pull, be sure to give all the relevant information: where
138your tree is, what branch to pull, and what changes will result from the
139pull. The git request-pull command can be helpful in this regard; it will
140format the request as other developers expect, and will also check to be
141sure that you have remembered to push those changes to the public server.
142
143
1447.2: REVIEWING PATCHES
145
146Some readers will certainly object to putting this section with "advanced
147topics" on the grounds that even beginning kernel developers should be
148reviewing patches. It is certainly true that there is no better way to
149learn how to program in the kernel environment than by looking at code
150posted by others. In addition, reviewers are forever in short supply; by
151looking at code you can make a significant contribution to the process as a
152whole.
153
154Reviewing code can be an intimidating prospect, especially for a new kernel
155developer who may well feel nervous about questioning code - in public -
156which has been posted by those with more experience. Even code written by
157the most experienced developers can be improved, though. Perhaps the best
158piece of advice for reviewers (all reviewers) is this: phrase review
159comments as questions rather than criticisms. Asking "how does the lock
160get released in this path?" will always work better than stating "the
161locking here is wrong."
162
163Different developers will review code from different points of view. Some
164are mostly concerned with coding style and whether code lines have trailing
165white space. Others will focus primarily on whether the change implemented
166by the patch as a whole is a good thing for the kernel or not. Yet others
167will check for problematic locking, excessive stack usage, possible
168security issues, duplication of code found elsewhere, adequate
169documentation, adverse effects on performance, user-space ABI changes, etc.
170All types of review, if they lead to better code going into the kernel, are
171welcome and worthwhile.
172
173
diff --git a/Documentation/development-process/8.Conclusion b/Documentation/development-process/8.Conclusion
new file mode 100644
index 000000000000..1990ab4b4949
--- /dev/null
+++ b/Documentation/development-process/8.Conclusion
@@ -0,0 +1,74 @@
18: FOR MORE INFORMATION
2
3There are numerous sources of information on Linux kernel development and
4related topics. First among those will always be the Documentation
5directory found in the kernel source distribution. The top-level HOWTO
6file is an important starting point; SubmittingPatches and
7SubmittingDrivers are also something which all kernel developers should
8read. Many internal kernel APIs are documented using the kerneldoc
9mechanism; "make htmldocs" or "make pdfdocs" can be used to generate those
10documents in HTML or PDF format (though the version of TeX shipped by some
11distributions runs into internal limits and fails to process the documents
12properly).
13
14Various web sites discuss kernel development at all levels of detail. Your
15author would like to humbly suggest http://lwn.net/ as a source;
16information on many specific kernel topics can be found via the LWN kernel
17index at:
18
19 http://lwn.net/Kernel/Index/
20
21Beyond that, a valuable resource for kernel developers is:
22
23 http://kernelnewbies.org/
24
25Information about the linux-next tree gathers at:
26
27 http://linux.f-seidel.de/linux-next/pmwiki/
28
29And, of course, one should not forget http://kernel.org/, the definitive
30location for kernel release information.
31
32There are a number of books on kernel development:
33
34 Linux Device Drivers, 3rd Edition (Jonathan Corbet, Alessandro
35 Rubini, and Greg Kroah-Hartman). Online at
36 http://lwn.net/Kernel/LDD3/.
37
38 Linux Kernel Development (Robert Love).
39
40 Understanding the Linux Kernel (Daniel Bovet and Marco Cesati).
41
42All of these books suffer from a common fault, though: they tend to be
43somewhat obsolete by the time they hit the shelves, and they have been on
44the shelves for a while now. Still, there is quite a bit of good
45information to be found there.
46
47Documentation for git can be found at:
48
49 http://www.kernel.org/pub/software/scm/git/docs/
50
51 http://www.kernel.org/pub/software/scm/git/docs/user-manual.html
52
53
549: CONCLUSION
55
56Congratulations to anybody who has made it through this long-winded
57document. Hopefully it has provided a helpful understanding of how the
58Linux kernel is developed and how you can participate in that process.
59
60In the end, it's the participation that matters. Any open source software
61project is no more than the sum of what its contributors put into it. The
62Linux kernel has progressed as quickly and as well as it has because it has
63been helped by an impressively large group of developers, all of whom are
64working to make it better. The kernel is a premier example of what can be
65done when thousands of people work together toward a common goal.
66
67The kernel can always benefit from a larger developer base, though. There
68is always more work to do. But, just as importantly, most other
69participants in the Linux ecosystem can benefit through contributing to the
70kernel. Getting code into the mainline is the key to higher code quality,
71lower maintenance and distribution costs, a higher level of influence over
72the direction of kernel development, and more. It is a situation where
73everybody involved wins. Fire up your editor and come join us; you will be
74more than welcome.
diff --git a/Documentation/devices.txt b/Documentation/devices.txt
index 05c80645e4ee..2be08240ee80 100644
--- a/Documentation/devices.txt
+++ b/Documentation/devices.txt
@@ -2571,6 +2571,9 @@ Your cooperation is appreciated.
2571 160 = /dev/usb/legousbtower0 1st USB Legotower device 2571 160 = /dev/usb/legousbtower0 1st USB Legotower device
2572 ... 2572 ...
2573 175 = /dev/usb/legousbtower15 16th USB Legotower device 2573 175 = /dev/usb/legousbtower15 16th USB Legotower device
2574 176 = /dev/usb/usbtmc1 First USB TMC device
2575 ...
2576 192 = /dev/usb/usbtmc16 16th USB TMC device
2574 240 = /dev/usb/dabusb0 First daubusb device 2577 240 = /dev/usb/dabusb0 First daubusb device
2575 ... 2578 ...
2576 243 = /dev/usb/dabusb3 Fourth dabusb device 2579 243 = /dev/usb/dabusb3 Fourth dabusb device
diff --git a/Documentation/dontdiff b/Documentation/dontdiff
index 27809357da58..1e89a51ea49b 100644
--- a/Documentation/dontdiff
+++ b/Documentation/dontdiff
@@ -2,11 +2,13 @@
2*.aux 2*.aux
3*.bin 3*.bin
4*.cpio 4*.cpio
5*.css 5*.csp
6*.dsp
6*.dvi 7*.dvi
8*.elf
7*.eps 9*.eps
8*.fw.gen.S
9*.fw 10*.fw
11*.gen.S
10*.gif 12*.gif
11*.grep 13*.grep
12*.grp 14*.grp
@@ -30,6 +32,7 @@
30*.s 32*.s
31*.sgml 33*.sgml
32*.so 34*.so
35*.so.dbg
33*.symtypes 36*.symtypes
34*.tab.c 37*.tab.c
35*.tab.h 38*.tab.h
@@ -38,24 +41,17 @@
38*.xml 41*.xml
39*_MODULES 42*_MODULES
40*_vga16.c 43*_vga16.c
41*cscope*
42*~ 44*~
43*.9 45*.9
44*.9.gz 46*.9.gz
45.* 47.*
46.cscope
47.gitignore
48.mailmap
49.mm 48.mm
5053c700_d.h 4953c700_d.h
5153c8xx_d.h*
52COPYING
53CREDITS
54CVS 50CVS
55ChangeSet 51ChangeSet
56Image 52Image
57Kerntypes 53Kerntypes
58MODS.txt 54Module.markers
59Module.symvers 55Module.symvers
60PENDING 56PENDING
61SCCS 57SCCS
@@ -73,7 +69,9 @@ autoconf.h*
73bbootsect 69bbootsect
74bin2c 70bin2c
75binkernel.spec 71binkernel.spec
72binoffset
76bootsect 73bootsect
74bounds.h
77bsetup 75bsetup
78btfixupprep 76btfixupprep
79build 77build
@@ -89,39 +87,36 @@ config_data.h*
89config_data.gz* 87config_data.gz*
90conmakehash 88conmakehash
91consolemap_deftbl.c* 89consolemap_deftbl.c*
90cpustr.h
92crc32table.h* 91crc32table.h*
93cscope.* 92cscope.*
94defkeymap.c* 93defkeymap.c
95devlist.h* 94devlist.h*
96docproc 95docproc
97dummy_sym.c*
98elf2ecoff 96elf2ecoff
99elfconfig.h* 97elfconfig.h*
100filelist
101fixdep 98fixdep
102fore200e_mkfirm 99fore200e_mkfirm
103fore200e_pca_fw.c* 100fore200e_pca_fw.c*
104gconf 101gconf
105gen-devlist 102gen-devlist
106gen-kdb_cmds.c*
107gen_crc32table 103gen_crc32table
108gen_init_cpio 104gen_init_cpio
109genksyms 105genksyms
110gentbl
111*_gray256.c 106*_gray256.c
107ihex2fw
112ikconfig.h* 108ikconfig.h*
113initramfs_data.cpio 109initramfs_data.cpio
114initramfs_data.cpio.gz 110initramfs_data.cpio.gz
115initramfs_list 111initramfs_list
116kallsyms 112kallsyms
117kconfig 113kconfig
118kconfig.tk 114keywords.c
119keywords.c*
120ksym.c* 115ksym.c*
121ksym.h* 116ksym.h*
122kxgettext 117kxgettext
123lkc_defs.h 118lkc_defs.h
124lex.c* 119lex.c
125lex.*.c 120lex.*.c
126logo_*.c 121logo_*.c
127logo_*_clut224.c 122logo_*_clut224.c
@@ -130,7 +125,6 @@ lxdialog
130mach-types 125mach-types
131mach-types.h 126mach-types.h
132machtypes.h 127machtypes.h
133make_times_h
134map 128map
135maui_boot.h 129maui_boot.h
136mconf 130mconf
@@ -138,6 +132,7 @@ miboot*
138mk_elfconfig 132mk_elfconfig
139mkboot 133mkboot
140mkbugboot 134mkbugboot
135mkcpustr
141mkdep 136mkdep
142mkprep 137mkprep
143mktables 138mktables
@@ -145,11 +140,12 @@ mktree
145modpost 140modpost
146modules.order 141modules.order
147modversions.h* 142modversions.h*
143ncscope.*
148offset.h 144offset.h
149offsets.h 145offsets.h
150oui.c* 146oui.c*
151parse.c* 147parse.c
152parse.h* 148parse.h
153patches* 149patches*
154pca200e.bin 150pca200e.bin
155pca200e_ecd.bin2 151pca200e_ecd.bin2
@@ -157,7 +153,7 @@ piggy.gz
157piggyback 153piggyback
158pnmtologo 154pnmtologo
159ppc_defs.h* 155ppc_defs.h*
160promcon_tbl.c* 156promcon_tbl.c
161pss_boot.h 157pss_boot.h
162qconf 158qconf
163raid6altivec*.c 159raid6altivec*.c
@@ -168,27 +164,38 @@ series
168setup 164setup
169setup.bin 165setup.bin
170setup.elf 166setup.elf
171sim710_d.h*
172sImage 167sImage
173sm_tbl* 168sm_tbl*
174split-include 169split-include
170syscalltab.h
175tags 171tags
176tftpboot.img 172tftpboot.img
177timeconst.h 173timeconst.h
178times.h* 174times.h*
179tkparse
180trix_boot.h 175trix_boot.h
181utsrelease.h* 176utsrelease.h*
177vdso-syms.lds
182vdso.lds 178vdso.lds
179vdso32-int80-syms.lds
180vdso32-syms.lds
181vdso32-syscall-syms.lds
182vdso32-sysenter-syms.lds
183vdso32.lds
184vdso32.so.dbg
185vdso64.lds
186vdso64.so.dbg
183version.h* 187version.h*
184vmlinux 188vmlinux
185vmlinux-* 189vmlinux-*
186vmlinux.aout 190vmlinux.aout
187vmlinux*.lds* 191vmlinux.lds
188vmlinux*.scr
189vsyscall.lds 192vsyscall.lds
193vsyscall_32.lds
190wanxlfw.inc 194wanxlfw.inc
191uImage 195uImage
192unifdef 196unifdef
197wakeup.bin
198wakeup.elf
199wakeup.lds
193zImage* 200zImage*
194zconf.hash.c 201zconf.hash.c
diff --git a/Documentation/fb/intelfb.txt b/Documentation/fb/intelfb.txt
index 27a3160650a4..dd9e944ea628 100644
--- a/Documentation/fb/intelfb.txt
+++ b/Documentation/fb/intelfb.txt
@@ -14,6 +14,7 @@ graphics devices. These would include:
14 Intel 915GM 14 Intel 915GM
15 Intel 945G 15 Intel 945G
16 Intel 945GM 16 Intel 945GM
17 Intel 945GME
17 Intel 965G 18 Intel 965G
18 Intel 965GM 19 Intel 965GM
19 20
diff --git a/Documentation/fb/uvesafb.txt b/Documentation/fb/uvesafb.txt
index bcfc233a0080..7ac3c4078ff9 100644
--- a/Documentation/fb/uvesafb.txt
+++ b/Documentation/fb/uvesafb.txt
@@ -52,7 +52,7 @@ are either given on the kernel command line or as module parameters, e.g.:
52 52
53 video=uvesafb:1024x768-32,mtrr:3,ywrap (compiled into the kernel) 53 video=uvesafb:1024x768-32,mtrr:3,ywrap (compiled into the kernel)
54 54
55 # modprobe uvesafb mode=1024x768-32 mtrr=3 scroll=ywrap (module) 55 # modprobe uvesafb mode_option=1024x768-32 mtrr=3 scroll=ywrap (module)
56 56
57Accepted options: 57Accepted options:
58 58
@@ -105,7 +105,7 @@ vtotal:n
105<mode> The mode you want to set, in the standard modedb format. Refer to 105<mode> The mode you want to set, in the standard modedb format. Refer to
106 modedb.txt for a detailed description. When uvesafb is compiled as 106 modedb.txt for a detailed description. When uvesafb is compiled as
107 a module, the mode string should be provided as a value of the 107 a module, the mode string should be provided as a value of the
108 'mode' option. 108 'mode_option' option.
109 109
110vbemode:x 110vbemode:x
111 Force the use of VBE mode x. The mode will only be set if it's 111 Force the use of VBE mode x. The mode will only be set if it's
diff --git a/Documentation/fb/viafb.modes b/Documentation/fb/viafb.modes
new file mode 100644
index 000000000000..02e5b487f00e
--- /dev/null
+++ b/Documentation/fb/viafb.modes
@@ -0,0 +1,870 @@
1#
2#
3# These data are based on the CRTC parameters in
4#
5# VIA Integration Graphics Chip
6# (C) 2004 VIA Technologies Inc.
7#
8
9#
10# 640x480, 60 Hz, Non-Interlaced (25.175 MHz dotclock)
11#
12# Horizontal Vertical
13# Resolution 640 480
14# Scan Frequency 31.469 kHz 59.94 Hz
15# Sync Width 3.813 us 0.064 ms
16# 12 chars 2 lines
17# Front Porch 0.636 us 0.318 ms
18# 2 chars 10 lines
19# Back Porch 1.907 us 1.048 ms
20# 6 chars 33 lines
21# Active Time 25.422 us 15.253 ms
22# 80 chars 480 lines
23# Blank Time 6.356 us 1.430 ms
24# 20 chars 45 lines
25# Polarity negative negative
26#
27
28mode "640x480-60"
29# D: 25.175 MHz, H: 31.469 kHz, V: 59.94 Hz
30 geometry 640 480 640 480 32
31 timings 39722 48 16 33 10 96 2 endmode mode "480x640-60"
32# D: 24.823 MHz, H: 39.780 kHz, V: 60.00 Hz
33 geometry 480 640 480 640 32 timings 39722 72 24 19 1 48 3 endmode
34#
35# 640x480, 75 Hz, Non-Interlaced (31.50 MHz dotclock)
36#
37# Horizontal Vertical
38# Resolution 640 480
39# Scan Frequency 37.500 kHz 75.00 Hz
40# Sync Width 2.032 us 0.080 ms
41# 8 chars 3 lines
42# Front Porch 0.508 us 0.027 ms
43# 2 chars 1 lines
44# Back Porch 3.810 us 0.427 ms
45# 15 chars 16 lines
46# Active Time 20.317 us 12.800 ms
47# 80 chars 480 lines
48# Blank Time 6.349 us 0.533 ms
49# 25 chars 20 lines
50# Polarity negative negative
51#
52 mode "640x480-75"
53# D: 31.50 MHz, H: 37.500 kHz, V: 75.00 Hz
54 geometry 640 480 640 480 32 timings 31747 120 16 16 1 64 3 endmode
55#
56# 640x480, 85 Hz, Non-Interlaced (36.000 MHz dotclock)
57#
58# Horizontal Vertical
59# Resolution 640 480
60# Scan Frequency 43.269 kHz 85.00 Hz
61# Sync Width 1.556 us 0.069 ms
62# 7 chars 3 lines
63# Front Porch 1.556 us 0.023 ms
64# 7 chars 1 lines
65# Back Porch 2.222 us 0.578 ms
66# 10 chars 25 lines
67# Active Time 17.778 us 11.093 ms
68# 80 chars 480 lines
69# Blank Time 5.333 us 0.670 ms
70# 24 chars 29 lines
71# Polarity negative negative
72#
73 mode "640x480-85"
74# D: 36.000 MHz, H: 43.269 kHz, V: 85.00 Hz
75 geometry 640 480 640 480 32 timings 27777 80 56 25 1 56 3 endmode
76#
77# 640x480, 100 Hz, Non-Interlaced (43.163 MHz dotclock)
78#
79# Horizontal Vertical
80# Resolution 640 480
81# Scan Frequency 50.900 kHz 100.00 Hz
82# Sync Width 1.483 us 0.058 ms
83# 8 chars 3 lines
84# Front Porch 0.927 us 0.019 ms
85# 5 chars 1 lines
86# Back Porch 2.409 us 0.475 ms
87# 13 chars 25 lines
88# Active Time 14.827 us 9.430 ms
89# 80 chars 480 lines
90# Blank Time 4.819 us 0.570 ms
91# 26 chars 29 lines
92# Polarity positive positive
93#
94 mode "640x480-100"
95# D: 43.163 MHz, H: 50.900 kHz, V: 100.00 Hz
96 geometry 640 480 640 480 32 timings 23168 104 40 25 1 64 3 endmode
97#
98# 640x480, 120 Hz, Non-Interlaced (52.406 MHz dotclock)
99#
100# Horizontal Vertical
101# Resolution 640 480
102# Scan Frequency 61.800 kHz 120.00 Hz
103# Sync Width 1.221 us 0.048 ms
104# 8 chars 3 lines
105# Front Porch 0.763 us 0.016 ms
106# 5 chars 1 lines
107# Back Porch 1.984 us 0.496 ms
108# 13 chars 31 lines
109# Active Time 12.212 us 7.767 ms
110# 80 chars 480 lines
111# Blank Time 3.969 us 0.566 ms
112# 26 chars 35 lines
113# Polarity positive positive
114#
115 mode "640x480-120"
116# D: 52.406 MHz, H: 61.800 kHz, V: 120.00 Hz
117 geometry 640 480 640 480 32 timings 19081 104 40 31 1 64 3 endmode
118#
119# 720x480, 60 Hz, Non-Interlaced (26.880 MHz dotclock)
120#
121# Horizontal Vertical
122# Resolution 720 480
123# Scan Frequency 30.000 kHz 60.241 Hz
124# Sync Width 2.679 us 0.099 ms
125# 9 chars 3 lines
126# Front Porch 0.595 us 0.033 ms
127# 2 chars 1 lines
128# Back Porch 3.274 us 0.462 ms
129# 11 chars 14 lines
130# Active Time 26.786 us 16.000 ms
131# 90 chars 480 lines
132# Blank Time 6.548 us 0.600 ms
133# 22 chars 18 lines
134# Polarity positive positive
135#
136 mode "720x480-60"
137# D: 26.880 MHz, H: 30.000 kHz, V: 60.24 Hz
138 geometry 720 480 720 480 32 timings 37202 88 16 14 1 72 3 endmode
139#
140# 800x480, 60 Hz, Non-Interlaced (29.581 MHz dotclock)
141#
142# Horizontal Vertical
143# Resolution 800 480
144# Scan Frequency 29.892 kHz 60.00 Hz
145# Sync Width 2.704 us 100.604 us
146# 10 chars 3 lines
147# Front Porch 0.541 us 33.535 us
148# 2 chars 1 lines
149# Back Porch 3.245 us 435.949 us
150# 12 chars 13 lines
151# Active Time 27.044 us 16.097 ms
152# 100 chars 480 lines
153# Blank Time 6.491 us 0.570 ms
154# 24 chars 17 lines
155# Polarity positive positive
156#
157 mode "800x480-60"
158# D: 29.500 MHz, H: 29.738 kHz, V: 60.00 Hz
159 geometry 800 480 800 480 32 timings 33805 96 24 10 3 72 7 endmode
160#
161# 720x576, 60 Hz, Non-Interlaced (32.668 MHz dotclock)
162#
163# Horizontal Vertical
164# Resolution 720 576
165# Scan Frequency 35.820 kHz 60.00 Hz
166# Sync Width 2.204 us 0.083 ms
167# 9 chars 3 lines
168# Front Porch 0.735 us 0.027 ms
169# 3 chars 1 lines
170# Back Porch 2.939 us 0.459 ms
171# 12 chars 17 lines
172# Active Time 22.040 us 16.080 ms
173# 90 chars 476 lines
174# Blank Time 5.877 us 0.586 ms
175# 24 chars 21 lines
176# Polarity positive positive
177#
178 mode "720x576-60"
179# D: 32.668 MHz, H: 35.820 kHz, V: 60.00 Hz
180 geometry 720 576 720 576 32 timings 30611 96 24 17 1 72 3 endmode
181#
182# 800x600, 60 Hz, Non-Interlaced (40.00 MHz dotclock)
183#
184# Horizontal Vertical
185# Resolution 800 600
186# Scan Frequency 37.879 kHz 60.32 Hz
187# Sync Width 3.200 us 0.106 ms
188# 16 chars 4 lines
189# Front Porch 1.000 us 0.026 ms
190# 5 chars 1 lines
191# Back Porch 2.200 us 0.607 ms
192# 11 chars 23 lines
193# Active Time 20.000 us 15.840 ms
194# 100 chars 600 lines
195# Blank Time 6.400 us 0.739 ms
196# 32 chars 28 lines
197# Polarity positive positive
198#
199 mode "800x600-60"
200# D: 40.00 MHz, H: 37.879 kHz, V: 60.32 Hz
201 geometry 800 600 800 600 32
202 timings 25000 88 40 23 1 128 4 hsync high vsync high endmode
203#
204# 800x600, 75 Hz, Non-Interlaced (49.50 MHz dotclock)
205#
206# Horizontal Vertical
207# Resolution 800 600
208# Scan Frequency 46.875 kHz 75.00 Hz
209# Sync Width 1.616 us 0.064 ms
210# 10 chars 3 lines
211# Front Porch 0.323 us 0.021 ms
212# 2 chars 1 lines
213# Back Porch 3.232 us 0.448 ms
214# 20 chars 21 lines
215# Active Time 16.162 us 12.800 ms
216# 100 chars 600 lines
217# Blank Time 5.172 us 0.533 ms
218# 32 chars 25 lines
219# Polarity positive positive
220#
221 mode "800x600-75"
222# D: 49.50 MHz, H: 46.875 kHz, V: 75.00 Hz
223 geometry 800 600 800 600 32
224 timings 20203 160 16 21 1 80 3 hsync high vsync high endmode
225#
226# 800x600, 85 Hz, Non-Interlaced (56.25 MHz dotclock)
227#
228# Horizontal Vertical
229# Resolution 800 600
230# Scan Frequency 53.674 kHz 85.061 Hz
231# Sync Width 1.138 us 0.056 ms
232# 8 chars 3 lines
233# Front Porch 0.569 us 0.019 ms
234# 4 chars 1 lines
235# Back Porch 2.702 us 0.503 ms
236# 19 chars 27 lines
237# Active Time 14.222 us 11.179 ms
238# 100 chars 600 lines
239# Blank Time 4.409 us 0.578 ms
240# 31 chars 31 lines
241# Polarity positive positive
242#
243 mode "800x600-85"
244# D: 56.25 MHz, H: 53.674 kHz, V: 85.061 Hz
245 geometry 800 600 800 600 32
246 timings 17777 152 32 27 1 64 3 hsync high vsync high endmode
247#
248# 800x600, 100 Hz, Non-Interlaced (67.50 MHz dotclock)
249#
250# Horizontal Vertical
251# Resolution 800 600
252# Scan Frequency 62.500 kHz 100.00 Hz
253# Sync Width 0.948 us 0.064 ms
254# 8 chars 4 lines
255# Front Porch 0.000 us 0.112 ms
256# 0 chars 7 lines
257# Back Porch 3.200 us 0.224 ms
258# 27 chars 14 lines
259# Active Time 11.852 us 9.600 ms
260# 100 chars 600 lines
261# Blank Time 4.148 us 0.400 ms
262# 35 chars 25 lines
263# Polarity positive positive
264#
265 mode "800x600-100"
266# D: 67.50 MHz, H: 62.500 kHz, V: 100.00 Hz
267 geometry 800 600 800 600 32
268 timings 14667 216 0 14 7 64 4 hsync high vsync high endmode
269#
270# 800x600, 120 Hz, Non-Interlaced (83.950 MHz dotclock)
271#
272# Horizontal Vertical
273# Resolution 800 600
274# Scan Frequency 77.160 kHz 120.00 Hz
275# Sync Width 1.048 us 0.039 ms
276# 11 chars 3 lines
277# Front Porch 0.667 us 0.013 ms
278# 7 chars 1 lines
279# Back Porch 1.715 us 0.507 ms
280# 18 chars 39 lines
281# Active Time 9.529 us 7.776 ms
282# 100 chars 600 lines
283# Blank Time 3.431 us 0.557 ms
284# 36 chars 43 lines
285# Polarity positive positive
286#
287 mode "800x600-120"
288# D: 83.950 MHz, H: 77.160 kHz, V: 120.00 Hz
289 geometry 800 600 800 600 32
290 timings 11912 144 56 39 1 88 3 hsync high vsync high endmode
291#
292# 848x480, 60 Hz, Non-Interlaced (31.490 MHz dotclock)
293#
294# Horizontal Vertical
295# Resolution 848 480
296# Scan Frequency 29.820 kHz 60.00 Hz
297# Sync Width 2.795 us 0.099 ms
298# 11 chars 3 lines
299# Front Porch 0.508 us 0.033 ms
300# 2 chars 1 lines
301# Back Porch 3.303 us 0.429 ms
302# 13 chars 13 lines
303# Active Time 26.929 us 16.097 ms
304# 106 chars 480 lines
305# Blank Time 6.605 us 0.570 ms
306# 26 chars 17 lines
307# Polarity positive positive
308#
309 mode "848x480-60"
310# D: 31.500 MHz, H: 29.830 kHz, V: 60.00 Hz
311 geometry 848 480 848 480 32
312 timings 31746 104 24 12 3 80 5 hsync high vsync high endmode
313#
314# 856x480, 60 Hz, Non-Interlaced (31.728 MHz dotclock)
315#
316# Horizontal Vertical
317# Resolution 856 480
318# Scan Frequency 29.820 kHz 60.00 Hz
319# Sync Width 2.774 us 0.099 ms
320# 11 chars 3 lines
321# Front Porch 0.504 us 0.033 ms
322# 2 chars 1 lines
323# Back Porch 3.728 us 0.429 ms
324# 13 chars 13 lines
325# Active Time 26.979 us 16.097 ms
326# 107 chars 480 lines
327# Blank Time 6.556 us 0.570 ms
328# 26 chars 17 lines
329# Polarity positive positive
330#
331 mode "856x480-60"
332# D: 31.728 MHz, H: 29.820 kHz, V: 60.00 Hz
333 geometry 856 480 856 480 32
334 timings 31518 104 16 13 1 88 3
335 hsync high vsync high endmode mode "960x600-60"
336# D: 45.250 MHz, H: 37.212 kHz, V: 60.00 Hz
337 geometry 960 600 960 600 32 timings 22099 128 32 15 3 96 6 endmode
338#
339# 1000x600, 60 Hz, Non-Interlaced (48.068 MHz dotclock)
340#
341# Horizontal Vertical
342# Resolution 1000 600
343# Scan Frequency 37.320 kHz 60.00 Hz
344# Sync Width 2.164 us 0.080 ms
345# 13 chars 3 lines
346# Front Porch 0.832 us 0.027 ms
347# 5 chars 1 lines
348# Back Porch 2.996 us 0.483 ms
349# 18 chars 18 lines
350# Active Time 20.804 us 16.077 ms
351# 125 chars 600 lines
352# Blank Time 5.991 us 0.589 ms
353# 36 chars 22 lines
354# Polarity negative positive
355#
356 mode "1000x600-60"
357# D: 48.068 MHz, H: 37.320 kHz, V: 60.00 Hz
358 geometry 1000 600 1000 600 32
359 timings 20834 144 40 18 1 104 3 endmode mode "1024x576-60"
360# D: 46.996 MHz, H: 35.820 kHz, V: 60.00 Hz
361 geometry 1024 576 1024 576 32
362 timings 21278 144 40 17 1 104 3 endmode mode "1024x600-60"
363# D: 48.964 MHz, H: 37.320 kHz, V: 60.00 Hz
364 geometry 1024 600 1024 600 32
365 timings 20461 144 40 18 1 104 3 endmode mode "1088x612-60"
366# D: 52.952 MHz, H: 38.040 kHz, V: 60.00 Hz
367 geometry 1088 612 1088 612 32 timings 18877 152 48 16 3 104 5 endmode
368#
369# 1024x512, 60 Hz, Non-Interlaced (41.291 MHz dotclock)
370#
371# Horizontal Vertical
372# Resolution 1024 512
373# Scan Frequency 31.860 kHz 60.00 Hz
374# Sync Width 2.519 us 0.094 ms
375# 13 chars 3 lines
376# Front Porch 0.775 us 0.031 ms
377# 4 chars 1 lines
378# Back Porch 3.294 us 0.465 ms
379# 17 chars 15 lines
380# Active Time 24.800 us 16.070 ms
381# 128 chars 512 lines
382# Blank Time 6.587 us 0.596 ms
383# 34 chars 19 lines
384# Polarity positive positive
385#
386 mode "1024x512-60"
387# D: 41.291 MHz, H: 31.860 kHz, V: 60.00 Hz
388 geometry 1024 512 1024 512 32
389 timings 24218 126 32 15 1 104 3 hsync high vsync high endmode
390#
391# 1024x600, 60 Hz, Non-Interlaced (48.875 MHz dotclock)
392#
393# Horizontal Vertical
394# Resolution 1024 768
395# Scan Frequency 37.252 kHz 60.00 Hz
396# Sync Width 2.128 us 80.532us
397# 13 chars 3 lines
398# Front Porch 0.818 us 26.844 us
399# 5 chars 1 lines
400# Back Porch 2.946 us 483.192 us
401# 18 chars 18 lines
402# Active Time 20.951 us 16.697 ms
403# 128 chars 622 lines
404# Blank Time 5.893 us 0.591 ms
405# 36 chars 22 lines
406# Polarity negative positive
407#
408#mode "1024x600-60"
409# # D: 48.875 MHz, H: 37.252 kHz, V: 60.00 Hz
410# geometry 1024 600 1024 600 32
411# timings 20460 144 40 18 1 104 3
412# endmode
413#
414# 1024x768, 60 Hz, Non-Interlaced (65.00 MHz dotclock)
415#
416# Horizontal Vertical
417# Resolution 1024 768
418# Scan Frequency 48.363 kHz 60.00 Hz
419# Sync Width 2.092 us 0.124 ms
420# 17 chars 6 lines
421# Front Porch 0.369 us 0.062 ms
422# 3 chars 3 lines
423# Back Porch 2.462 us 0.601 ms
424# 20 chars 29 lines
425# Active Time 15.754 us 15.880 ms
426# 128 chars 768 lines
427# Blank Time 4.923 us 0.786 ms
428# 40 chars 38 lines
429# Polarity negative negative
430#
431 mode "1024x768-60"
432# D: 65.00 MHz, H: 48.363 kHz, V: 60.00 Hz
433 geometry 1024 768 1024 768 32 timings 15385 160 24 29 3 136 6 endmode
434#
435# 1024x768, 75 Hz, Non-Interlaced (78.75 MHz dotclock)
436#
437# Horizontal Vertical
438# Resolution 1024 768
439# Scan Frequency 60.023 kHz 75.03 Hz
440# Sync Width 1.219 us 0.050 ms
441# 12 chars 3 lines
442# Front Porch 0.203 us 0.017 ms
443# 2 chars 1 lines
444# Back Porch 2.235 us 0.466 ms
445# 22 chars 28 lines
446# Active Time 13.003 us 12.795 ms
447# 128 chars 768 lines
448# Blank Time 3.657 us 0.533 ms
449# 36 chars 32 lines
450# Polarity positive positive
451#
452 mode "1024x768-75"
453# D: 78.75 MHz, H: 60.023 kHz, V: 75.03 Hz
454 geometry 1024 768 1024 768 32
455 timings 12699 176 16 28 1 96 3 hsync high vsync high endmode
456#
457# 1024x768, 85 Hz, Non-Interlaced (94.50 MHz dotclock)
458#
459# Horizontal Vertical
460# Resolution 1024 768
461# Scan Frequency 68.677 kHz 85.00 Hz
462# Sync Width 1.016 us 0.044 ms
463# 12 chars 3 lines
464# Front Porch 0.508 us 0.015 ms
465# 6 chars 1 lines
466# Back Porch 2.201 us 0.524 ms
467# 26 chars 36 lines
468# Active Time 10.836 us 11.183 ms
469# 128 chars 768 lines
470# Blank Time 3.725 us 0.582 ms
471# 44 chars 40 lines
472# Polarity positive positive
473#
474 mode "1024x768-85"
475# D: 94.50 MHz, H: 68.677 kHz, V: 85.00 Hz
476 geometry 1024 768 1024 768 32
477 timings 10582 208 48 36 1 96 3 hsync high vsync high endmode
478#
479# 1024x768, 100 Hz, Non-Interlaced (110.0 MHz dotclock)
480#
481# Horizontal Vertical
482# Resolution 1024 768
483# Scan Frequency 79.023 kHz 99.78 Hz
484# Sync Width 0.800 us 0.101 ms
485# 11 chars 8 lines
486# Front Porch 0.000 us 0.000 ms
487# 0 chars 0 lines
488# Back Porch 2.545 us 0.202 ms
489# 35 chars 16 lines
490# Active Time 9.309 us 9.719 ms
491# 128 chars 768 lines
492# Blank Time 3.345 us 0.304 ms
493# 46 chars 24 lines
494# Polarity negative negative
495#
496 mode "1024x768-100"
497# D: 113.3 MHz, H: 79.023 kHz, V: 99.78 Hz
498 geometry 1024 768 1024 768 32
499 timings 8825 280 0 16 0 88 8 endmode mode "1152x720-60"
500# D: 66.750 MHz, H: 44.859 kHz, V: 60.00 Hz
501 geometry 1152 720 1152 720 32 timings 14981 168 56 19 3 112 6 endmode
502#
503# 1152x864, 75 Hz, Non-Interlaced (110.0 MHz dotclock)
504#
505# Horizontal Vertical
506# Resolution 1152 864
507# Scan Frequency 75.137 kHz 74.99 Hz
508# Sync Width 1.309 us 0.106 ms
509# 18 chars 8 lines
510# Front Porch 0.245 us 0.599 ms
511# 3 chars 45 lines
512# Back Porch 1.282 us 1.132 ms
513# 18 chars 85 lines
514# Active Time 10.473 us 11.499 ms
515# 144 chars 864 lines
516# Blank Time 2.836 us 1.837 ms
517# 39 chars 138 lines
518# Polarity positive positive
519#
520 mode "1152x864-75"
521# D: 110.0 MHz, H: 75.137 kHz, V: 74.99 Hz
522 geometry 1152 864 1152 864 32
523 timings 9259 144 24 85 45 144 8
524 hsync high vsync high endmode mode "1200x720-60"
525# D: 70.184 MHz, H: 44.760 kHz, V: 60.00 Hz
526 geometry 1200 720 1200 720 32
527 timings 14253 184 28 22 1 128 3 endmode mode "1280x600-60"
528# D: 61.503 MHz, H: 37.320 kHz, V: 60.00 Hz
529 geometry 1280 600 1280 600 32
530 timings 16260 184 28 18 1 128 3 endmode mode "1280x720-50"
531# D: 60.466 MHz, H: 37.050 kHz, V: 50.00 Hz
532 geometry 1280 720 1280 720 32
533 timings 16538 176 48 17 1 128 3 endmode mode "1280x768-50"
534# D: 65.178 MHz, H: 39.550 kHz, V: 50.00 Hz
535 geometry 1280 768 1280 768 32 timings 15342 184 28 19 1 128 3 endmode
536#
537# 1280x768, 60 Hz, Non-Interlaced (80.136 MHz dotclock)
538#
539# Horizontal Vertical
540# Resolution 1280 768
541# Scan Frequency 47.700 kHz 60.00 Hz
542# Sync Width 1.697 us 0.063 ms
543# 17 chars 3 lines
544# Front Porch 0.799 us 0.021 ms
545# 8 chars 1 lines
546# Back Porch 2.496 us 0.483 ms
547# 25 chars 23 lines
548# Active Time 15.973 us 16.101 ms
549# 160 chars 768 lines
550# Blank Time 4.992 us 0.566 ms
551# 50 chars 27 lines
552# Polarity positive positive
553#
554 mode "1280x768-60"
555# D: 80.13 MHz, H: 47.700 kHz, V: 60.00 Hz
556 geometry 1280 768 1280 768 32
557 timings 12480 200 48 23 1 126 3 hsync high vsync high endmode
558#
559# 1280x800, 60 Hz, Non-Interlaced (83.375 MHz dotclock)
560#
561# Horizontal Vertical
562# Resolution 1280 800
563# Scan Frequency 49.628 kHz 60.00 Hz
564# Sync Width 1.631 us 60.450 us
565# 17 chars 3 lines
566# Front Porch 0.768 us 20.15 us
567# 8 chars 1 lines
568# Back Porch 2.399 us 0.483 ms
569# 25 chars 24 lines
570# Active Time 15.352 us 16.120 ms
571# 160 chars 800 lines
572# Blank Time 4.798 us 0.564 ms
573# 50 chars 28 lines
574# Polarity negtive positive
575#
576 mode "1280x800-60"
577# D: 83.500 MHz, H: 49.702 kHz, V: 60.00 Hz
578 geometry 1280 800 1280 800 32 timings 11994 200 72 22 3 128 6 endmode
579#
580# 1280x960, 60 Hz, Non-Interlaced (108.00 MHz dotclock)
581#
582# Horizontal Vertical
583# Resolution 1280 960
584# Scan Frequency 60.000 kHz 60.00 Hz
585# Sync Width 1.037 us 0.050 ms
586# 14 chars 3 lines
587# Front Porch 0.889 us 0.017 ms
588# 12 chars 1 lines
589# Back Porch 2.889 us 0.600 ms
590# 39 chars 36 lines
591# Active Time 11.852 us 16.000 ms
592# 160 chars 960 lines
593# Blank Time 4.815 us 0.667 ms
594# 65 chars 40 lines
595# Polarity positive positive
596#
597 mode "1280x960-60"
598# D: 108.00 MHz, H: 60.000 kHz, V: 60.00 Hz
599 geometry 1280 960 1280 960 32
600 timings 9259 312 96 36 1 112 3 hsync high vsync high endmode
601#
602# 1280x1024, 60 Hz, Non-Interlaced (108.00 MHz dotclock)
603#
604# Horizontal Vertical
605# Resolution 1280 1024
606# Scan Frequency 63.981 kHz 60.02 Hz
607# Sync Width 1.037 us 0.047 ms
608# 14 chars 3 lines
609# Front Porch 0.444 us 0.015 ms
610# 6 chars 1 lines
611# Back Porch 2.297 us 0.594 ms
612# 31 chars 38 lines
613# Active Time 11.852 us 16.005 ms
614# 160 chars 1024 lines
615# Blank Time 3.778 us 0.656 ms
616# 51 chars 42 lines
617# Polarity positive positive
618#
619 mode "1280x1024-60"
620# D: 108.00 MHz, H: 63.981 kHz, V: 60.02 Hz
621 geometry 1280 1024 1280 1024 32
622 timings 9260 248 48 38 1 112 3 hsync high vsync high endmode
623#
624# 1280x1024, 75 Hz, Non-Interlaced (135.00 MHz dotclock)
625#
626# Horizontal Vertical
627# Resolution 1280 1024
628# Scan Frequency 79.976 kHz 75.02 Hz
629# Sync Width 1.067 us 0.038 ms
630# 18 chars 3 lines
631# Front Porch 0.119 us 0.012 ms
632# 2 chars 1 lines
633# Back Porch 1.837 us 0.475 ms
634# 31 chars 38 lines
635# Active Time 9.481 us 12.804 ms
636# 160 chars 1024 lines
637# Blank Time 3.022 us 0.525 ms
638# 51 chars 42 lines
639# Polarity positive positive
640#
641 mode "1280x1024-75"
642# D: 135.00 MHz, H: 79.976 kHz, V: 75.02 Hz
643 geometry 1280 1024 1280 1024 32
644 timings 7408 248 16 38 1 144 3 hsync high vsync high endmode
645#
646# 1280x1024, 85 Hz, Non-Interlaced (157.50 MHz dotclock)
647#
648# Horizontal Vertical
649# Resolution 1280 1024
650# Scan Frequency 91.146 kHz 85.02 Hz
651# Sync Width 1.016 us 0.033 ms
652# 20 chars 3 lines
653# Front Porch 0.406 us 0.011 ms
654# 8 chars 1 lines
655# Back Porch 1.422 us 0.483 ms
656# 28 chars 44 lines
657# Active Time 8.127 us 11.235 ms
658# 160 chars 1024 lines
659# Blank Time 2.844 us 0.527 ms
660# 56 chars 48 lines
661# Polarity positive positive
662#
663 mode "1280x1024-85"
664# D: 157.50 MHz, H: 91.146 kHz, V: 85.02 Hz
665 geometry 1280 1024 1280 1024 32
666 timings 6349 224 64 44 1 160 3
667 hsync high vsync high endmode mode "1440x900-60"
668# D: 106.500 MHz, H: 55.935 kHz, V: 60.00 Hz
669 geometry 1440 900 1440 900 32
670 timings 9390 232 80 25 3 152 6
671 hsync high vsync high endmode mode "1440x900-75"
672# D: 136.750 MHz, H: 70.635 kHz, V: 75.00 Hz
673 geometry 1440 900 1440 900 32
674 timings 7315 248 96 33 3 152 6 hsync high vsync high endmode
675#
676# 1440x1050, 60 Hz, Non-Interlaced (125.10 MHz dotclock)
677#
678# Horizontal Vertical
679# Resolution 1440 1050
680# Scan Frequency 65.220 kHz 60.00 Hz
681# Sync Width 1.204 us 0.046 ms
682# 19 chars 3 lines
683# Front Porch 0.760 us 0.015 ms
684# 12 chars 1 lines
685# Back Porch 1.964 us 0.495 ms
686# 31 chars 33 lines
687# Active Time 11.405 us 16.099 ms
688# 180 chars 1050 lines
689# Blank Time 3.928 us 0.567 ms
690# 62 chars 37 lines
691# Polarity positive positive
692#
693 mode "1440x1050-60"
694# D: 125.10 MHz, H: 65.220 kHz, V: 60.00 Hz
695 geometry 1440 1050 1440 1050 32
696 timings 7993 248 96 33 1 152 3
697 hsync high vsync high endmode mode "1600x900-60"
698# D: 118.250 MHz, H: 55.990 kHz, V: 60.00 Hz
699 geometry 1600 900 1600 900 32
700 timings 8415 256 88 26 3 168 5 endmode mode "1600x1024-60"
701# D: 136.358 MHz, H: 63.600 kHz, V: 60.00 Hz
702 geometry 1600 1024 1600 1024 32 timings 7315 272 104 32 1 168 3 endmode
703#
704# 1600x1200, 60 Hz, Non-Interlaced (156.00 MHz dotclock)
705#
706# Horizontal Vertical
707# Resolution 1600 1200
708# Scan Frequency 76.200 kHz 60.00 Hz
709# Sync Width 1.026 us 0.105 ms
710# 20 chars 8 lines
711# Front Porch 0.205 us 0.131 ms
712# 4 chars 10 lines
713# Back Porch 1.636 us 0.682 ms
714# 32 chars 52 lines
715# Active Time 10.256 us 15.748 ms
716# 200 chars 1200 lines
717# Blank Time 2.872 us 0.866 ms
718# 56 chars 66 lines
719# Polarity negative negative
720#
721 mode "1600x1200-60"
722# D: 156.00 MHz, H: 76.200 kHz, V: 60.00 Hz
723 geometry 1600 1200 1600 1200 32 timings 6172 256 32 52 10 160 8 endmode
724#
725# 1600x1200, 75 Hz, Non-Interlaced (202.50 MHz dotclock)
726#
727# Horizontal Vertical
728# Resolution 1600 1200
729# Scan Frequency 93.750 kHz 75.00 Hz
730# Sync Width 0.948 us 0.032 ms
731# 24 chars 3 lines
732# Front Porch 0.316 us 0.011 ms
733# 8 chars 1 lines
734# Back Porch 1.501 us 0.491 ms
735# 38 chars 46 lines
736# Active Time 7.901 us 12.800 ms
737# 200 chars 1200 lines
738# Blank Time 2.765 us 0.533 ms
739# 70 chars 50 lines
740# Polarity positive positive
741#
742 mode "1600x1200-75"
743# D: 202.50 MHz, H: 93.750 kHz, V: 75.00 Hz
744 geometry 1600 1200 1600 1200 32
745 timings 4938 304 64 46 1 192 3
746 hsync high vsync high endmode mode "1680x1050-60"
747# D: 146.250 MHz, H: 65.290 kHz, V: 59.954 Hz
748 geometry 1680 1050 1680 1050 32
749 timings 6814 280 104 30 3 176 6
750 hsync high vsync high endmode mode "1680x1050-75"
751# D: 187.000 MHz, H: 82.306 kHz, V: 74.892 Hz
752 geometry 1680 1050 1680 1050 32
753 timings 5348 296 120 40 3 176 6
754 hsync high vsync high endmode mode "1792x1344-60"
755# D: 202.975 MHz, H: 83.460 kHz, V: 60.00 Hz
756 geometry 1792 1344 1792 1344 32
757 timings 4902 320 128 43 1 192 3
758 hsync high vsync high endmode mode "1856x1392-60"
759# D: 218.571 MHz, H: 86.460 kHz, V: 60.00 Hz
760 geometry 1856 1392 1856 1392 32
761 timings 4577 336 136 45 1 200 3
762 hsync high vsync high endmode mode "1920x1200-60"
763# D: 193.250 MHz, H: 74.556 kHz, V: 60.00 Hz
764 geometry 1920 1200 1920 1200 32
765 timings 5173 336 136 36 3 200 6
766 hsync high vsync high endmode mode "1920x1440-60"
767# D: 234.000 MHz, H:90.000 kHz, V: 60.00 Hz
768 geometry 1920 1440 1920 1440 32
769 timings 4274 344 128 56 1 208 3
770 hsync high vsync high endmode mode "1920x1440-75"
771# D: 297.000 MHz, H:112.500 kHz, V: 75.00 Hz
772 geometry 1920 1440 1920 1440 32
773 timings 3367 352 144 56 1 224 3
774 hsync high vsync high endmode mode "2048x1536-60"
775# D: 267.250 MHz, H: 95.446 kHz, V: 60.00 Hz
776 geometry 2048 1536 2048 1536 32
777 timings 3742 376 152 49 3 224 4 hsync high vsync high endmode
778#
779# 1280x720, 60 Hz, Non-Interlaced (74.481 MHz dotclock)
780#
781# Horizontal Vertical
782# Resolution 1280 720
783# Scan Frequency 44.760 kHz 60.00 Hz
784# Sync Width 1.826 us 67.024 ms
785# 17 chars 3 lines
786# Front Porch 0.752 us 22.341 ms
787# 7 chars 1 lines
788# Back Porch 2.578 us 491.510 ms
789# 24 chars 22 lines
790# Active Time 17.186 us 16.086 ms
791# 160 chars 720 lines
792# Blank Time 5.156 us 0.581 ms
793# 48 chars 26 lines
794# Polarity negative negative
795#
796 mode "1280x720-60"
797# D: 74.481 MHz, H: 44.760 kHz, V: 60.00 Hz
798 geometry 1280 720 1280 720 32 timings 13426 192 64 22 1 136 3 endmode
799#
800# 1920x1080, 60 Hz, Non-Interlaced (172.798 MHz dotclock)
801#
802# Horizontal Vertical
803# Resolution 1920 1080
804# Scan Frequency 67.080 kHz 60.00 Hz
805# Sync Width 1.204 us 44.723 ms
806# 26 chars 3 lines
807# Front Porch 0.694 us 14.908 ms
808# 15 chars 1 lines
809# Back Porch 1.898 us 506.857 ms
810# 41 chars 34 lines
811# Active Time 11.111 us 16.100 ms
812# 240 chars 1080 lines
813# Blank Time 3.796 us 0.566 ms
814# 82 chars 38 lines
815# Polarity negative negative
816#
817 mode "1920x1080-60"
818# D: 74.481 MHz, H: 67.080 kHz, V: 60.00 Hz
819 geometry 1920 1080 1920 1080 32 timings 5787 328 120 34 1 208 3 endmode
820#
821# 1400x1050, 60 Hz, Non-Interlaced (122.61 MHz dotclock)
822#
823# Horizontal Vertical
824# Resolution 1400 1050
825# Scan Frequency 65.218 kHz 59.99 Hz
826# Sync Width 1.037 us 0.047 ms
827# 19 chars 3 lines
828# Front Porch 0.444 us 0.015 ms
829# 11 chars 1 lines
830# Back Porch 1.185 us 0.188 ms
831# 30 chars 33 lines
832# Active Time 12.963 us 16.411 ms
833# 175 chars 1050 lines
834# Blank Time 2.667 us 0.250 ms
835# 60 chars 37 lines
836# Polarity negative positive
837#
838 mode "1400x1050-60"
839# D: 122.750 MHz, H: 65.317 kHz, V: 59.99 Hz
840 geometry 1400 1050 1408 1050 32
841 timings 8214 232 88 32 3 144 4 endmode mode "1400x1050-75"
842# D: 156.000 MHz, H: 82.278 kHz, V: 74.867 Hz
843 geometry 1400 1050 1408 1050 32 timings 6410 248 104 42 3 144 4 endmode
844#
845# 1366x768, 60 Hz, Non-Interlaced (85.86 MHz dotclock)
846#
847# Horizontal Vertical
848# Resolution 1366 768
849# Scan Frequency 47.700 kHz 60.00 Hz
850# Sync Width 1.677 us 0.063 ms
851# 18 chars 3 lines
852# Front Porch 0.839 us 0.021 ms
853# 9 chars 1 lines
854# Back Porch 2.516 us 0.482 ms
855# 27 chars 23 lines
856# Active Time 15.933 us 16.101 ms
857# 171 chars 768 lines
858# Blank Time 5.031 us 0.566 ms
859# 54 chars 27 lines
860# Polarity negative positive
861#
862 mode "1360x768-60"
863# D: 84.750 MHz, H: 47.720 kHz, V: 60.00 Hz
864 geometry 1360 768 1360 768 32
865 timings 11799 208 72 22 3 136 5 endmode mode "1366x768-60"
866# D: 85.86 MHz, H: 47.700 kHz, V: 60.00 Hz
867 geometry 1366 768 1366 768 32
868 timings 11647 216 72 23 1 144 3 endmode mode "1366x768-50"
869# D: 69,924 MHz, H: 39.550 kHz, V: 50.00 Hz
870 geometry 1366 768 1366 768 32 timings 14301 200 56 19 1 144 3 endmode
diff --git a/Documentation/fb/viafb.txt b/Documentation/fb/viafb.txt
new file mode 100644
index 000000000000..67dbf442b0b6
--- /dev/null
+++ b/Documentation/fb/viafb.txt
@@ -0,0 +1,214 @@
1
2 VIA Integration Graphic Chip Console Framebuffer Driver
3
4[Platform]
5-----------------------
6 The console framebuffer driver is for graphics chips of
7 VIA UniChrome Family(CLE266, PM800 / CN400 / CN300,
8 P4M800CE / P4M800Pro / CN700 / VN800,
9 CX700 / VX700, K8M890, P4M890,
10 CN896 / P4M900, VX800)
11
12[Driver features]
13------------------------
14 Device: CRT, LCD, DVI
15
16 Support viafb_mode:
17 CRT:
18 640x480(60, 75, 85, 100, 120 Hz), 720x480(60 Hz),
19 720x576(60 Hz), 800x600(60, 75, 85, 100, 120 Hz),
20 848x480(60 Hz), 856x480(60 Hz), 1024x512(60 Hz),
21 1024x768(60, 75, 85, 100 Hz), 1152x864(75 Hz),
22 1280x768(60 Hz), 1280x960(60 Hz), 1280x1024(60, 75, 85 Hz),
23 1440x1050(60 Hz), 1600x1200(60, 75 Hz), 1280x720(60 Hz),
24 1920x1080(60 Hz), 1400x1050(60 Hz), 800x480(60 Hz)
25
26 color depth: 8 bpp, 16 bpp, 32 bpp supports.
27
28 Support 2D hardware accelerator.
29
30[Using the viafb module]
31-- -- --------------------
32 Start viafb with default settings:
33 #modprobe viafb
34
35 Start viafb with with user options:
36 #modprobe viafb viafb_mode=800x600 viafb_bpp=16 viafb_refresh=60
37 viafb_active_dev=CRT+DVI viafb_dvi_port=DVP1
38 viafb_mode1=1024x768 viafb_bpp=16 viafb_refresh1=60
39 viafb_SAMM_ON=1
40
41 viafb_mode:
42 640x480 (default)
43 720x480
44 800x600
45 1024x768
46 ......
47
48 viafb_bpp:
49 8, 16, 32 (default:32)
50
51 viafb_refresh:
52 60, 75, 85, 100, 120 (default:60)
53
54 viafb_lcd_dsp_method:
55 0 : expansion (default)
56 1 : centering
57
58 viafb_lcd_mode:
59 0 : LCD panel with LSB data format input (default)
60 1 : LCD panel with MSB data format input
61
62 viafb_lcd_panel_id:
63 0 : Resolution: 640x480, Channel: single, Dithering: Enable
64 1 : Resolution: 800x600, Channel: single, Dithering: Enable
65 2 : Resolution: 1024x768, Channel: single, Dithering: Enable (default)
66 3 : Resolution: 1280x768, Channel: single, Dithering: Enable
67 4 : Resolution: 1280x1024, Channel: dual, Dithering: Enable
68 5 : Resolution: 1400x1050, Channel: dual, Dithering: Enable
69 6 : Resolution: 1600x1200, Channel: dual, Dithering: Enable
70
71 8 : Resolution: 800x480, Channel: single, Dithering: Enable
72 9 : Resolution: 1024x768, Channel: dual, Dithering: Enable
73 10: Resolution: 1024x768, Channel: single, Dithering: Disable
74 11: Resolution: 1024x768, Channel: dual, Dithering: Disable
75 12: Resolution: 1280x768, Channel: single, Dithering: Disable
76 13: Resolution: 1280x1024, Channel: dual, Dithering: Disable
77 14: Resolution: 1400x1050, Channel: dual, Dithering: Disable
78 15: Resolution: 1600x1200, Channel: dual, Dithering: Disable
79 16: Resolution: 1366x768, Channel: single, Dithering: Disable
80 17: Resolution: 1024x600, Channel: single, Dithering: Enable
81 18: Resolution: 1280x768, Channel: dual, Dithering: Enable
82 19: Resolution: 1280x800, Channel: single, Dithering: Enable
83
84 viafb_accel:
85 0 : No 2D Hardware Acceleration
86 1 : 2D Hardware Acceleration (default)
87
88 viafb_SAMM_ON:
89 0 : viafb_SAMM_ON disable (default)
90 1 : viafb_SAMM_ON enable
91
92 viafb_mode1: (secondary display device)
93 640x480 (default)
94 720x480
95 800x600
96 1024x768
97 ... ...
98
99 viafb_bpp1: (secondary display device)
100 8, 16, 32 (default:32)
101
102 viafb_refresh1: (secondary display device)
103 60, 75, 85, 100, 120 (default:60)
104
105 viafb_active_dev:
106 This option is used to specify active devices.(CRT, DVI, CRT+LCD...)
107 DVI stands for DVI or HDMI, E.g., If you want to enable HDMI,
108 set viafb_active_dev=DVI. In SAMM case, the previous of
109 viafb_active_dev is primary device, and the following is
110 secondary device.
111
112 For example:
113 To enable one device, such as DVI only, we can use:
114 modprobe viafb viafb_active_dev=DVI
115 To enable two devices, such as CRT+DVI:
116 modprobe viafb viafb_active_dev=CRT+DVI;
117
118 For DuoView case, we can use:
119 modprobe viafb viafb_active_dev=CRT+DVI
120 OR
121 modprobe viafb viafb_active_dev=DVI+CRT...
122
123 For SAMM case:
124 If CRT is primary and DVI is secondary, we should use:
125 modprobe viafb viafb_active_dev=CRT+DVI viafb_SAMM_ON=1...
126 If DVI is primary and CRT is secondary, we should use:
127 modprobe viafb viafb_active_dev=DVI+CRT viafb_SAMM_ON=1...
128
129 viafb_display_hardware_layout:
130 This option is used to specify display hardware layout for CX700 chip.
131 1 : LCD only
132 2 : DVI only
133 3 : LCD+DVI (default)
134 4 : LCD1+LCD2 (internal + internal)
135 16: LCD1+ExternalLCD2 (internal + external)
136
137 viafb_second_size:
138 This option is used to set second device memory size(MB) in SAMM case.
139 The minimal size is 16.
140
141 viafb_platform_epia_dvi:
142 This option is used to enable DVI on EPIA - M
143 0 : No DVI on EPIA - M (default)
144 1 : DVI on EPIA - M
145
146 viafb_bus_width:
147 When using 24 - Bit Bus Width Digital Interface,
148 this option should be set.
149 12: 12-Bit LVDS or 12-Bit TMDS (default)
150 24: 24-Bit LVDS or 24-Bit TMDS
151
152 viafb_device_lcd_dualedge:
153 When using Dual Edge Panel, this option should be set.
154 0 : No Dual Edge Panel (default)
155 1 : Dual Edge Panel
156
157 viafb_video_dev:
158 This option is used to specify video output devices(CRT, DVI, LCD) for
159 duoview case.
160 For example:
161 To output video on DVI, we should use:
162 modprobe viafb viafb_video_dev=DVI...
163
164 viafb_lcd_port:
165 This option is used to specify LCD output port,
166 available values are "DVP0" "DVP1" "DFP_HIGHLOW" "DFP_HIGH" "DFP_LOW".
167 for external LCD + external DVI on CX700(External LCD is on DVP0),
168 we should use:
169 modprobe viafb viafb_lcd_port=DVP0...
170
171Notes:
172 1. CRT may not display properly for DuoView CRT & DVI display at
173 the "640x480" PAL mode with DVI overscan enabled.
174 2. SAMM stands for single adapter multi monitors. It is different from
175 multi-head since SAMM support multi monitor at driver layers, thus fbcon
176 layer doesn't even know about it; SAMM's second screen doesn't have a
177 device node file, thus a user mode application can't access it directly.
178 When SAMM is enabled, viafb_mode and viafb_mode1, viafb_bpp and
179 viafb_bpp1, viafb_refresh and viafb_refresh1 can be different.
180 3. When console is depending on viafbinfo1, dynamically change resolution
181 and bpp, need to call VIAFB specified ioctl interface VIAFB_SET_DEVICE
182 instead of calling common ioctl function FBIOPUT_VSCREENINFO since
183 viafb doesn't support multi-head well, or it will cause screen crush.
184 4. VX800 2D accelerator hasn't been supported in this driver yet. When
185 using driver on VX800, the driver will disable the acceleration
186 function as default.
187
188
189[Configure viafb with "fbset" tool]
190-----------------------------------
191 "fbset" is an inbox utility of Linux.
192 1. Inquire current viafb information, type,
193 # fbset -i
194
195 2. Set various resolutions and viafb_refresh rates,
196 # fbset <resolution-vertical_sync>
197
198 example,
199 # fbset "1024x768-75"
200 or
201 # fbset -g 1024 768 1024 768 32
202 Check the file "/etc/fb.modes" to find display modes available.
203
204 3. Set the color depth,
205 # fbset -depth <value>
206
207 example,
208 # fbset -depth 16
209
210[Bootup with viafb]:
211--------------------
212 Add the following line to your grub.conf:
213 append = "video=viafb:viafb_mode=1024x768,viafb_bpp=32,viafb_refresh=85"
214
diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt
index 83c88cae1eda..f5f812daf9f4 100644
--- a/Documentation/feature-removal-schedule.txt
+++ b/Documentation/feature-removal-schedule.txt
@@ -6,6 +6,24 @@ be removed from this file.
6 6
7--------------------------- 7---------------------------
8 8
9What: old static regulatory information and ieee80211_regdom module parameter
10When: 2.6.29
11Why: The old regulatory infrastructure has been replaced with a new one
12 which does not require statically defined regulatory domains. We do
13 not want to keep static regulatory domains in the kernel due to the
14 the dynamic nature of regulatory law and localization. We kept around
15 the old static definitions for the regulatory domains of:
16 * US
17 * JP
18 * EU
19 and used by default the US when CONFIG_WIRELESS_OLD_REGULATORY was
20 set. We also kept around the ieee80211_regdom module parameter in case
21 some applications were relying on it. Changing regulatory domains
22 can now be done instead by using nl80211, as is done with iw.
23Who: Luis R. Rodriguez <lrodriguez@atheros.com>
24
25---------------------------
26
9What: dev->power.power_state 27What: dev->power.power_state
10When: July 2007 28When: July 2007
11Why: Broken design for runtime control over driver power states, confusing 29Why: Broken design for runtime control over driver power states, confusing
@@ -232,6 +250,9 @@ What (Why):
232 - xt_mark match revision 0 250 - xt_mark match revision 0
233 (superseded by xt_mark match revision 1) 251 (superseded by xt_mark match revision 1)
234 252
253 - xt_recent: the old ipt_recent proc dir
254 (superseded by /proc/net/xt_recent)
255
235When: January 2009 or Linux 2.7.0, whichever comes first 256When: January 2009 or Linux 2.7.0, whichever comes first
236Why: Superseded by newer revisions or modules 257Why: Superseded by newer revisions or modules
237Who: Jan Engelhardt <jengelh@computergmbh.de> 258Who: Jan Engelhardt <jengelh@computergmbh.de>
@@ -266,11 +287,19 @@ Who: Glauber Costa <gcosta@redhat.com>
266 287
267--------------------------- 288---------------------------
268 289
269What: old style serial driver for ColdFire (CONFIG_SERIAL_COLDFIRE) 290What: remove HID compat support
270When: 2.6.28 291When: 2.6.29
271Why: This driver still uses the old interface and has been replaced 292Why: needed only as a temporary solution until distros fix themselves up
272 by CONFIG_SERIAL_MCF. 293Who: Jiri Slaby <jirislaby@gmail.com>
273Who: Sebastian Siewior <sebastian@breakpoint.cc> 294
295---------------------------
296
297What: print_fn_descriptor_symbol()
298When: October 2009
299Why: The %pF vsprintf format provides the same functionality in a
300 simpler way. print_fn_descriptor_symbol() is deprecated but
301 still present to give out-of-tree modules time to change.
302Who: Bjorn Helgaas <bjorn.helgaas@hp.com>
274 303
275--------------------------- 304---------------------------
276 305
diff --git a/Documentation/filesystems/autofs4-mount-control.txt b/Documentation/filesystems/autofs4-mount-control.txt
new file mode 100644
index 000000000000..c6341745df37
--- /dev/null
+++ b/Documentation/filesystems/autofs4-mount-control.txt
@@ -0,0 +1,393 @@
1
2Miscellaneous Device control operations for the autofs4 kernel module
3====================================================================
4
5The problem
6===========
7
8There is a problem with active restarts in autofs (that is to say
9restarting autofs when there are busy mounts).
10
11During normal operation autofs uses a file descriptor opened on the
12directory that is being managed in order to be able to issue control
13operations. Using a file descriptor gives ioctl operations access to
14autofs specific information stored in the super block. The operations
15are things such as setting an autofs mount catatonic, setting the
16expire timeout and requesting expire checks. As is explained below,
17certain types of autofs triggered mounts can end up covering an autofs
18mount itself which prevents us being able to use open(2) to obtain a
19file descriptor for these operations if we don't already have one open.
20
21Currently autofs uses "umount -l" (lazy umount) to clear active mounts
22at restart. While using lazy umount works for most cases, anything that
23needs to walk back up the mount tree to construct a path, such as
24getcwd(2) and the proc file system /proc/<pid>/cwd, no longer works
25because the point from which the path is constructed has been detached
26from the mount tree.
27
28The actual problem with autofs is that it can't reconnect to existing
29mounts. Immediately one thinks of just adding the ability to remount
30autofs file systems would solve it, but alas, that can't work. This is
31because autofs direct mounts and the implementation of "on demand mount
32and expire" of nested mount trees have the file system mounted directly
33on top of the mount trigger directory dentry.
34
35For example, there are two types of automount maps, direct (in the kernel
36module source you will see a third type called an offset, which is just
37a direct mount in disguise) and indirect.
38
39Here is a master map with direct and indirect map entries:
40
41/- /etc/auto.direct
42/test /etc/auto.indirect
43
44and the corresponding map files:
45
46/etc/auto.direct:
47
48/automount/dparse/g6 budgie:/autofs/export1
49/automount/dparse/g1 shark:/autofs/export1
50and so on.
51
52/etc/auto.indirect:
53
54g1 shark:/autofs/export1
55g6 budgie:/autofs/export1
56and so on.
57
58For the above indirect map an autofs file system is mounted on /test and
59mounts are triggered for each sub-directory key by the inode lookup
60operation. So we see a mount of shark:/autofs/export1 on /test/g1, for
61example.
62
63The way that direct mounts are handled is by making an autofs mount on
64each full path, such as /automount/dparse/g1, and using it as a mount
65trigger. So when we walk on the path we mount shark:/autofs/export1 "on
66top of this mount point". Since these are always directories we can
67use the follow_link inode operation to trigger the mount.
68
69But, each entry in direct and indirect maps can have offsets (making
70them multi-mount map entries).
71
72For example, an indirect mount map entry could also be:
73
74g1 \
75 / shark:/autofs/export5/testing/test \
76 /s1 shark:/autofs/export/testing/test/s1 \
77 /s2 shark:/autofs/export5/testing/test/s2 \
78 /s1/ss1 shark:/autofs/export1 \
79 /s2/ss2 shark:/autofs/export2
80
81and a similarly a direct mount map entry could also be:
82
83/automount/dparse/g1 \
84 / shark:/autofs/export5/testing/test \
85 /s1 shark:/autofs/export/testing/test/s1 \
86 /s2 shark:/autofs/export5/testing/test/s2 \
87 /s1/ss1 shark:/autofs/export2 \
88 /s2/ss2 shark:/autofs/export2
89
90One of the issues with version 4 of autofs was that, when mounting an
91entry with a large number of offsets, possibly with nesting, we needed
92to mount and umount all of the offsets as a single unit. Not really a
93problem, except for people with a large number of offsets in map entries.
94This mechanism is used for the well known "hosts" map and we have seen
95cases (in 2.4) where the available number of mounts are exhausted or
96where the number of privileged ports available is exhausted.
97
98In version 5 we mount only as we go down the tree of offsets and
99similarly for expiring them which resolves the above problem. There is
100somewhat more detail to the implementation but it isn't needed for the
101sake of the problem explanation. The one important detail is that these
102offsets are implemented using the same mechanism as the direct mounts
103above and so the mount points can be covered by a mount.
104
105The current autofs implementation uses an ioctl file descriptor opened
106on the mount point for control operations. The references held by the
107descriptor are accounted for in checks made to determine if a mount is
108in use and is also used to access autofs file system information held
109in the mount super block. So the use of a file handle needs to be
110retained.
111
112
113The Solution
114============
115
116To be able to restart autofs leaving existing direct, indirect and
117offset mounts in place we need to be able to obtain a file handle
118for these potentially covered autofs mount points. Rather than just
119implement an isolated operation it was decided to re-implement the
120existing ioctl interface and add new operations to provide this
121functionality.
122
123In addition, to be able to reconstruct a mount tree that has busy mounts,
124the uid and gid of the last user that triggered the mount needs to be
125available because these can be used as macro substitution variables in
126autofs maps. They are recorded at mount request time and an operation
127has been added to retrieve them.
128
129Since we're re-implementing the control interface, a couple of other
130problems with the existing interface have been addressed. First, when
131a mount or expire operation completes a status is returned to the
132kernel by either a "send ready" or a "send fail" operation. The
133"send fail" operation of the ioctl interface could only ever send
134ENOENT so the re-implementation allows user space to send an actual
135status. Another expensive operation in user space, for those using
136very large maps, is discovering if a mount is present. Usually this
137involves scanning /proc/mounts and since it needs to be done quite
138often it can introduce significant overhead when there are many entries
139in the mount table. An operation to lookup the mount status of a mount
140point dentry (covered or not) has also been added.
141
142Current kernel development policy recommends avoiding the use of the
143ioctl mechanism in favor of systems such as Netlink. An implementation
144using this system was attempted to evaluate its suitability and it was
145found to be inadequate, in this case. The Generic Netlink system was
146used for this as raw Netlink would lead to a significant increase in
147complexity. There's no question that the Generic Netlink system is an
148elegant solution for common case ioctl functions but it's not a complete
149replacement probably because it's primary purpose in life is to be a
150message bus implementation rather than specifically an ioctl replacement.
151While it would be possible to work around this there is one concern
152that lead to the decision to not use it. This is that the autofs
153expire in the daemon has become far to complex because umount
154candidates are enumerated, almost for no other reason than to "count"
155the number of times to call the expire ioctl. This involves scanning
156the mount table which has proved to be a big overhead for users with
157large maps. The best way to improve this is try and get back to the
158way the expire was done long ago. That is, when an expire request is
159issued for a mount (file handle) we should continually call back to
160the daemon until we can't umount any more mounts, then return the
161appropriate status to the daemon. At the moment we just expire one
162mount at a time. A Generic Netlink implementation would exclude this
163possibility for future development due to the requirements of the
164message bus architecture.
165
166
167autofs4 Miscellaneous Device mount control interface
168====================================================
169
170The control interface is opening a device node, typically /dev/autofs.
171
172All the ioctls use a common structure to pass the needed parameter
173information and return operation results:
174
175struct autofs_dev_ioctl {
176 __u32 ver_major;
177 __u32 ver_minor;
178 __u32 size; /* total size of data passed in
179 * including this struct */
180 __s32 ioctlfd; /* automount command fd */
181
182 __u32 arg1; /* Command parameters */
183 __u32 arg2;
184
185 char path[0];
186};
187
188The ioctlfd field is a mount point file descriptor of an autofs mount
189point. It is returned by the open call and is used by all calls except
190the check for whether a given path is a mount point, where it may
191optionally be used to check a specific mount corresponding to a given
192mount point file descriptor, and when requesting the uid and gid of the
193last successful mount on a directory within the autofs file system.
194
195The fields arg1 and arg2 are used to communicate parameters and results of
196calls made as described below.
197
198The path field is used to pass a path where it is needed and the size field
199is used account for the increased structure length when translating the
200structure sent from user space.
201
202This structure can be initialized before setting specific fields by using
203the void function call init_autofs_dev_ioctl(struct autofs_dev_ioctl *).
204
205All of the ioctls perform a copy of this structure from user space to
206kernel space and return -EINVAL if the size parameter is smaller than
207the structure size itself, -ENOMEM if the kernel memory allocation fails
208or -EFAULT if the copy itself fails. Other checks include a version check
209of the compiled in user space version against the module version and a
210mismatch results in a -EINVAL return. If the size field is greater than
211the structure size then a path is assumed to be present and is checked to
212ensure it begins with a "/" and is NULL terminated, otherwise -EINVAL is
213returned. Following these checks, for all ioctl commands except
214AUTOFS_DEV_IOCTL_VERSION_CMD, AUTOFS_DEV_IOCTL_OPENMOUNT_CMD and
215AUTOFS_DEV_IOCTL_CLOSEMOUNT_CMD the ioctlfd is validated and if it is
216not a valid descriptor or doesn't correspond to an autofs mount point
217an error of -EBADF, -ENOTTY or -EINVAL (not an autofs descriptor) is
218returned.
219
220
221The ioctls
222==========
223
224An example of an implementation which uses this interface can be seen
225in autofs version 5.0.4 and later in file lib/dev-ioctl-lib.c of the
226distribution tar available for download from kernel.org in directory
227/pub/linux/daemons/autofs/v5.
228
229The device node ioctl operations implemented by this interface are:
230
231
232AUTOFS_DEV_IOCTL_VERSION
233------------------------
234
235Get the major and minor version of the autofs4 device ioctl kernel module
236implementation. It requires an initialized struct autofs_dev_ioctl as an
237input parameter and sets the version information in the passed in structure.
238It returns 0 on success or the error -EINVAL if a version mismatch is
239detected.
240
241
242AUTOFS_DEV_IOCTL_PROTOVER_CMD and AUTOFS_DEV_IOCTL_PROTOSUBVER_CMD
243------------------------------------------------------------------
244
245Get the major and minor version of the autofs4 protocol version understood
246by loaded module. This call requires an initialized struct autofs_dev_ioctl
247with the ioctlfd field set to a valid autofs mount point descriptor
248and sets the requested version number in structure field arg1. These
249commands return 0 on success or one of the negative error codes if
250validation fails.
251
252
253AUTOFS_DEV_IOCTL_OPENMOUNT and AUTOFS_DEV_IOCTL_CLOSEMOUNT
254----------------------------------------------------------
255
256Obtain and release a file descriptor for an autofs managed mount point
257path. The open call requires an initialized struct autofs_dev_ioctl with
258the the path field set and the size field adjusted appropriately as well
259as the arg1 field set to the device number of the autofs mount. The
260device number can be obtained from the mount options shown in
261/proc/mounts. The close call requires an initialized struct
262autofs_dev_ioct with the ioctlfd field set to the descriptor obtained
263from the open call. The release of the file descriptor can also be done
264with close(2) so any open descriptors will also be closed at process exit.
265The close call is included in the implemented operations largely for
266completeness and to provide for a consistent user space implementation.
267
268
269AUTOFS_DEV_IOCTL_READY_CMD and AUTOFS_DEV_IOCTL_FAIL_CMD
270--------------------------------------------------------
271
272Return mount and expire result status from user space to the kernel.
273Both of these calls require an initialized struct autofs_dev_ioctl
274with the ioctlfd field set to the descriptor obtained from the open
275call and the arg1 field set to the wait queue token number, received
276by user space in the foregoing mount or expire request. The arg2 field
277is set to the status to be returned. For the ready call this is always
2780 and for the fail call it is set to the errno of the operation.
279
280
281AUTOFS_DEV_IOCTL_SETPIPEFD_CMD
282------------------------------
283
284Set the pipe file descriptor used for kernel communication to the daemon.
285Normally this is set at mount time using an option but when reconnecting
286to a existing mount we need to use this to tell the autofs mount about
287the new kernel pipe descriptor. In order to protect mounts against
288incorrectly setting the pipe descriptor we also require that the autofs
289mount be catatonic (see next call).
290
291The call requires an initialized struct autofs_dev_ioctl with the
292ioctlfd field set to the descriptor obtained from the open call and
293the arg1 field set to descriptor of the pipe. On success the call
294also sets the process group id used to identify the controlling process
295(eg. the owning automount(8) daemon) to the process group of the caller.
296
297
298AUTOFS_DEV_IOCTL_CATATONIC_CMD
299------------------------------
300
301Make the autofs mount point catatonic. The autofs mount will no longer
302issue mount requests, the kernel communication pipe descriptor is released
303and any remaining waits in the queue released.
304
305The call requires an initialized struct autofs_dev_ioctl with the
306ioctlfd field set to the descriptor obtained from the open call.
307
308
309AUTOFS_DEV_IOCTL_TIMEOUT_CMD
310----------------------------
311
312Set the expire timeout for mounts withing an autofs mount point.
313
314The call requires an initialized struct autofs_dev_ioctl with the
315ioctlfd field set to the descriptor obtained from the open call.
316
317
318AUTOFS_DEV_IOCTL_REQUESTER_CMD
319------------------------------
320
321Return the uid and gid of the last process to successfully trigger a the
322mount on the given path dentry.
323
324The call requires an initialized struct autofs_dev_ioctl with the path
325field set to the mount point in question and the size field adjusted
326appropriately as well as the arg1 field set to the device number of the
327containing autofs mount. Upon return the struct field arg1 contains the
328uid and arg2 the gid.
329
330When reconstructing an autofs mount tree with active mounts we need to
331re-connect to mounts that may have used the original process uid and
332gid (or string variations of them) for mount lookups within the map entry.
333This call provides the ability to obtain this uid and gid so they may be
334used by user space for the mount map lookups.
335
336
337AUTOFS_DEV_IOCTL_EXPIRE_CMD
338---------------------------
339
340Issue an expire request to the kernel for an autofs mount. Typically
341this ioctl is called until no further expire candidates are found.
342
343The call requires an initialized struct autofs_dev_ioctl with the
344ioctlfd field set to the descriptor obtained from the open call. In
345addition an immediate expire, independent of the mount timeout, can be
346requested by setting the arg1 field to 1. If no expire candidates can
347be found the ioctl returns -1 with errno set to EAGAIN.
348
349This call causes the kernel module to check the mount corresponding
350to the given ioctlfd for mounts that can be expired, issues an expire
351request back to the daemon and waits for completion.
352
353AUTOFS_DEV_IOCTL_ASKUMOUNT_CMD
354------------------------------
355
356Checks if an autofs mount point is in use.
357
358The call requires an initialized struct autofs_dev_ioctl with the
359ioctlfd field set to the descriptor obtained from the open call and
360it returns the result in the arg1 field, 1 for busy and 0 otherwise.
361
362
363AUTOFS_DEV_IOCTL_ISMOUNTPOINT_CMD
364---------------------------------
365
366Check if the given path is a mountpoint.
367
368The call requires an initialized struct autofs_dev_ioctl. There are two
369possible variations. Both use the path field set to the path of the mount
370point to check and the size field adjusted appropriately. One uses the
371ioctlfd field to identify a specific mount point to check while the other
372variation uses the path and optionaly arg1 set to an autofs mount type.
373The call returns 1 if this is a mount point and sets arg1 to the device
374number of the mount and field arg2 to the relevant super block magic
375number (described below) or 0 if it isn't a mountpoint. In both cases
376the the device number (as returned by new_encode_dev()) is returned
377in field arg1.
378
379If supplied with a file descriptor we're looking for a specific mount,
380not necessarily at the top of the mounted stack. In this case the path
381the descriptor corresponds to is considered a mountpoint if it is itself
382a mountpoint or contains a mount, such as a multi-mount without a root
383mount. In this case we return 1 if the descriptor corresponds to a mount
384point and and also returns the super magic of the covering mount if there
385is one or 0 if it isn't a mountpoint.
386
387If a path is supplied (and the ioctlfd field is set to -1) then the path
388is looked up and is checked to see if it is the root of a mount. If a
389type is also given we are looking for a particular autofs mount and if
390a match isn't found a fail is returned. If the the located path is the
391root of a mount 1 is returned along with the super magic of the mount
392or 0 otherwise.
393
diff --git a/Documentation/filesystems/ext3.txt b/Documentation/filesystems/ext3.txt
index b45f3c1b8b43..295f26cd895a 100644
--- a/Documentation/filesystems/ext3.txt
+++ b/Documentation/filesystems/ext3.txt
@@ -193,6 +193,5 @@ kernel source: <file:fs/ext3/>
193programs: http://e2fsprogs.sourceforge.net/ 193programs: http://e2fsprogs.sourceforge.net/
194 http://ext2resize.sourceforge.net 194 http://ext2resize.sourceforge.net
195 195
196useful links: http://www.zip.com.au/~akpm/linux/ext3/ext3-usage.html 196useful links: http://www-106.ibm.com/developerworks/linux/library/l-fs7/
197 http://www-106.ibm.com/developerworks/linux/library/l-fs7/
198 http://www-106.ibm.com/developerworks/linux/library/l-fs8/ 197 http://www-106.ibm.com/developerworks/linux/library/l-fs8/
diff --git a/Documentation/filesystems/ext4.txt b/Documentation/filesystems/ext4.txt
index 0d5394920a31..174eaff7ded9 100644
--- a/Documentation/filesystems/ext4.txt
+++ b/Documentation/filesystems/ext4.txt
@@ -2,19 +2,24 @@
2Ext4 Filesystem 2Ext4 Filesystem
3=============== 3===============
4 4
5This is a development version of the ext4 filesystem, an advanced level 5Ext4 is an an advanced level of the ext3 filesystem which incorporates
6of the ext3 filesystem which incorporates scalability and reliability 6scalability and reliability enhancements for supporting large filesystems
7enhancements for supporting large filesystems (64 bit) in keeping with 7(64 bit) in keeping with increasing disk capacities and state-of-the-art
8increasing disk capacities and state-of-the-art feature requirements. 8feature requirements.
9 9
10Mailing list: linux-ext4@vger.kernel.org 10Mailing list: linux-ext4@vger.kernel.org
11Web site: http://ext4.wiki.kernel.org
11 12
12 13
131. Quick usage instructions: 141. Quick usage instructions:
14=========================== 15===========================
15 16
17Note: More extensive information for getting started with ext4 can be
18 found at the ext4 wiki site at the URL:
19 http://ext4.wiki.kernel.org/index.php/Ext4_Howto
20
16 - Compile and install the latest version of e2fsprogs (as of this 21 - Compile and install the latest version of e2fsprogs (as of this
17 writing version 1.41) from: 22 writing version 1.41.3) from:
18 23
19 http://sourceforge.net/project/showfiles.php?group_id=2406 24 http://sourceforge.net/project/showfiles.php?group_id=2406
20 25
@@ -32,28 +37,26 @@ Mailing list: linux-ext4@vger.kernel.org
32 you will need to merge your changes with the version from e2fsprogs 37 you will need to merge your changes with the version from e2fsprogs
33 1.41.x. 38 1.41.x.
34 39
35 - Create a new filesystem using the ext4dev filesystem type: 40 - Create a new filesystem using the ext4 filesystem type:
36 41
37 # mke2fs -t ext4dev /dev/hda1 42 # mke2fs -t ext4 /dev/hda1
38 43
39 Or configure an existing ext3 filesystem to support extents and set 44 Or to configure an existing ext3 filesystem to support extents:
40 the test_fs flag to indicate that it's ok for an in-development
41 filesystem to touch this filesystem:
42 45
43 # tune2fs -O extents -E test_fs /dev/hda1 46 # tune2fs -O extents /dev/hda1
44 47
45 If the filesystem was created with 128 byte inodes, it can be 48 If the filesystem was created with 128 byte inodes, it can be
46 converted to use 256 byte for greater efficiency via: 49 converted to use 256 byte for greater efficiency via:
47 50
48 # tune2fs -I 256 /dev/hda1 51 # tune2fs -I 256 /dev/hda1
49 52
50 (Note: we currently do not have tools to convert an ext4dev 53 (Note: we currently do not have tools to convert an ext4
51 filesystem back to ext3; so please do not do try this on production 54 filesystem back to ext3; so please do not do try this on production
52 filesystems.) 55 filesystems.)
53 56
54 - Mounting: 57 - Mounting:
55 58
56 # mount -t ext4dev /dev/hda1 /wherever 59 # mount -t ext4 /dev/hda1 /wherever
57 60
58 - When comparing performance with other filesystems, remember that 61 - When comparing performance with other filesystems, remember that
59 ext3/4 by default offers higher data integrity guarantees than most. 62 ext3/4 by default offers higher data integrity guarantees than most.
@@ -104,8 +107,8 @@ exist yet so I'm not sure they're in the near-term roadmap.
104The big performance win will come with mballoc, delalloc and flex_bg 107The big performance win will come with mballoc, delalloc and flex_bg
105grouping of bitmaps and inode tables. Some test results available here: 108grouping of bitmaps and inode tables. Some test results available here:
106 109
107 - http://www.bullopensource.org/ext4/20080530/ffsb-write-2.6.26-rc2.html 110 - http://www.bullopensource.org/ext4/20080818-ffsb/ffsb-write-2.6.27-rc1.html
108 - http://www.bullopensource.org/ext4/20080530/ffsb-readwrite-2.6.26-rc2.html 111 - http://www.bullopensource.org/ext4/20080818-ffsb/ffsb-readwrite-2.6.27-rc1.html
109 112
1103. Options 1133. Options
111========== 114==========
@@ -177,6 +180,11 @@ barrier=<0|1(*)> This enables/disables the use of write barriers in
177 your disks are battery-backed in one way or another, 180 your disks are battery-backed in one way or another,
178 disabling barriers may safely improve performance. 181 disabling barriers may safely improve performance.
179 182
183inode_readahead=n This tuning parameter controls the maximum
184 number of inode table blocks that ext4's inode
185 table readahead algorithm will pre-read into
186 the buffer cache. The default value is 32 blocks.
187
180orlov (*) This enables the new Orlov block allocator. It is 188orlov (*) This enables the new Orlov block allocator. It is
181 enabled by default. 189 enabled by default.
182 190
@@ -209,15 +217,17 @@ noreservation
209bsddf (*) Make 'df' act like BSD. 217bsddf (*) Make 'df' act like BSD.
210minixdf Make 'df' act like Minix. 218minixdf Make 'df' act like Minix.
211 219
212check=none Don't do extra checking of bitmaps on mount.
213nocheck
214
215debug Extra debugging information is sent to syslog. 220debug Extra debugging information is sent to syslog.
216 221
217errors=remount-ro(*) Remount the filesystem read-only on an error. 222errors=remount-ro(*) Remount the filesystem read-only on an error.
218errors=continue Keep going on a filesystem error. 223errors=continue Keep going on a filesystem error.
219errors=panic Panic and halt the machine if an error occurs. 224errors=panic Panic and halt the machine if an error occurs.
220 225
226data_err=ignore(*) Just print an error message if an error occurs
227 in a file data buffer in ordered mode.
228data_err=abort Abort the journal if an error occurs in a file
229 data buffer in ordered mode.
230
221grpid Give objects the same group ID as their creator. 231grpid Give objects the same group ID as their creator.
222bsdgroups 232bsdgroups
223 233
@@ -243,8 +253,6 @@ nobh (a) cache disk block mapping information
243 "nobh" option tries to avoid associating buffer 253 "nobh" option tries to avoid associating buffer
244 heads (supported only for "writeback" mode). 254 heads (supported only for "writeback" mode).
245 255
246mballoc (*) Use the multiple block allocator for block allocation
247nomballoc disabled multiple block allocator for block allocation.
248stripe=n Number of filesystem blocks that mballoc will try 256stripe=n Number of filesystem blocks that mballoc will try
249 to use for allocation size and alignment. For RAID5/6 257 to use for allocation size and alignment. For RAID5/6
250 systems this should be the number of data 258 systems this should be the number of data
@@ -252,6 +260,7 @@ stripe=n Number of filesystem blocks that mballoc will try
252delalloc (*) Deferring block allocation until write-out time. 260delalloc (*) Deferring block allocation until write-out time.
253nodelalloc Disable delayed allocation. Blocks are allocation 261nodelalloc Disable delayed allocation. Blocks are allocation
254 when data is copied from user to page cache. 262 when data is copied from user to page cache.
263
255Data Mode 264Data Mode
256========= 265=========
257There are 3 different data modes: 266There are 3 different data modes:
diff --git a/Documentation/filesystems/fiemap.txt b/Documentation/filesystems/fiemap.txt
new file mode 100644
index 000000000000..1e3defcfe50b
--- /dev/null
+++ b/Documentation/filesystems/fiemap.txt
@@ -0,0 +1,228 @@
1============
2Fiemap Ioctl
3============
4
5The fiemap ioctl is an efficient method for userspace to get file
6extent mappings. Instead of block-by-block mapping (such as bmap), fiemap
7returns a list of extents.
8
9
10Request Basics
11--------------
12
13A fiemap request is encoded within struct fiemap:
14
15struct fiemap {
16 __u64 fm_start; /* logical offset (inclusive) at
17 * which to start mapping (in) */
18 __u64 fm_length; /* logical length of mapping which
19 * userspace cares about (in) */
20 __u32 fm_flags; /* FIEMAP_FLAG_* flags for request (in/out) */
21 __u32 fm_mapped_extents; /* number of extents that were
22 * mapped (out) */
23 __u32 fm_extent_count; /* size of fm_extents array (in) */
24 __u32 fm_reserved;
25 struct fiemap_extent fm_extents[0]; /* array of mapped extents (out) */
26};
27
28
29fm_start, and fm_length specify the logical range within the file
30which the process would like mappings for. Extents returned mirror
31those on disk - that is, the logical offset of the 1st returned extent
32may start before fm_start, and the range covered by the last returned
33extent may end after fm_length. All offsets and lengths are in bytes.
34
35Certain flags to modify the way in which mappings are looked up can be
36set in fm_flags. If the kernel doesn't understand some particular
37flags, it will return EBADR and the contents of fm_flags will contain
38the set of flags which caused the error. If the kernel is compatible
39with all flags passed, the contents of fm_flags will be unmodified.
40It is up to userspace to determine whether rejection of a particular
41flag is fatal to it's operation. This scheme is intended to allow the
42fiemap interface to grow in the future but without losing
43compatibility with old software.
44
45fm_extent_count specifies the number of elements in the fm_extents[] array
46that can be used to return extents. If fm_extent_count is zero, then the
47fm_extents[] array is ignored (no extents will be returned), and the
48fm_mapped_extents count will hold the number of extents needed in
49fm_extents[] to hold the file's current mapping. Note that there is
50nothing to prevent the file from changing between calls to FIEMAP.
51
52The following flags can be set in fm_flags:
53
54* FIEMAP_FLAG_SYNC
55If this flag is set, the kernel will sync the file before mapping extents.
56
57* FIEMAP_FLAG_XATTR
58If this flag is set, the extents returned will describe the inodes
59extended attribute lookup tree, instead of it's data tree.
60
61
62Extent Mapping
63--------------
64
65Extent information is returned within the embedded fm_extents array
66which userspace must allocate along with the fiemap structure. The
67number of elements in the fiemap_extents[] array should be passed via
68fm_extent_count. The number of extents mapped by kernel will be
69returned via fm_mapped_extents. If the number of fiemap_extents
70allocated is less than would be required to map the requested range,
71the maximum number of extents that can be mapped in the fm_extent[]
72array will be returned and fm_mapped_extents will be equal to
73fm_extent_count. In that case, the last extent in the array will not
74complete the requested range and will not have the FIEMAP_EXTENT_LAST
75flag set (see the next section on extent flags).
76
77Each extent is described by a single fiemap_extent structure as
78returned in fm_extents.
79
80struct fiemap_extent {
81 __u64 fe_logical; /* logical offset in bytes for the start of
82 * the extent */
83 __u64 fe_physical; /* physical offset in bytes for the start
84 * of the extent */
85 __u64 fe_length; /* length in bytes for the extent */
86 __u64 fe_reserved64[2];
87 __u32 fe_flags; /* FIEMAP_EXTENT_* flags for this extent */
88 __u32 fe_reserved[3];
89};
90
91All offsets and lengths are in bytes and mirror those on disk. It is valid
92for an extents logical offset to start before the request or it's logical
93length to extend past the request. Unless FIEMAP_EXTENT_NOT_ALIGNED is
94returned, fe_logical, fe_physical, and fe_length will be aligned to the
95block size of the file system. With the exception of extents flagged as
96FIEMAP_EXTENT_MERGED, adjacent extents will not be merged.
97
98The fe_flags field contains flags which describe the extent returned.
99A special flag, FIEMAP_EXTENT_LAST is always set on the last extent in
100the file so that the process making fiemap calls can determine when no
101more extents are available, without having to call the ioctl again.
102
103Some flags are intentionally vague and will always be set in the
104presence of other more specific flags. This way a program looking for
105a general property does not have to know all existing and future flags
106which imply that property.
107
108For example, if FIEMAP_EXTENT_DATA_INLINE or FIEMAP_EXTENT_DATA_TAIL
109are set, FIEMAP_EXTENT_NOT_ALIGNED will also be set. A program looking
110for inline or tail-packed data can key on the specific flag. Software
111which simply cares not to try operating on non-aligned extents
112however, can just key on FIEMAP_EXTENT_NOT_ALIGNED, and not have to
113worry about all present and future flags which might imply unaligned
114data. Note that the opposite is not true - it would be valid for
115FIEMAP_EXTENT_NOT_ALIGNED to appear alone.
116
117* FIEMAP_EXTENT_LAST
118This is the last extent in the file. A mapping attempt past this
119extent will return nothing.
120
121* FIEMAP_EXTENT_UNKNOWN
122The location of this extent is currently unknown. This may indicate
123the data is stored on an inaccessible volume or that no storage has
124been allocated for the file yet.
125
126* FIEMAP_EXTENT_DELALLOC
127 - This will also set FIEMAP_EXTENT_UNKNOWN.
128Delayed allocation - while there is data for this extent, it's
129physical location has not been allocated yet.
130
131* FIEMAP_EXTENT_ENCODED
132This extent does not consist of plain filesystem blocks but is
133encoded (e.g. encrypted or compressed). Reading the data in this
134extent via I/O to the block device will have undefined results.
135
136Note that it is *always* undefined to try to update the data
137in-place by writing to the indicated location without the
138assistance of the filesystem, or to access the data using the
139information returned by the FIEMAP interface while the filesystem
140is mounted. In other words, user applications may only read the
141extent data via I/O to the block device while the filesystem is
142unmounted, and then only if the FIEMAP_EXTENT_ENCODED flag is
143clear; user applications must not try reading or writing to the
144filesystem via the block device under any other circumstances.
145
146* FIEMAP_EXTENT_DATA_ENCRYPTED
147 - This will also set FIEMAP_EXTENT_ENCODED
148The data in this extent has been encrypted by the file system.
149
150* FIEMAP_EXTENT_NOT_ALIGNED
151Extent offsets and length are not guaranteed to be block aligned.
152
153* FIEMAP_EXTENT_DATA_INLINE
154 This will also set FIEMAP_EXTENT_NOT_ALIGNED
155Data is located within a meta data block.
156
157* FIEMAP_EXTENT_DATA_TAIL
158 This will also set FIEMAP_EXTENT_NOT_ALIGNED
159Data is packed into a block with data from other files.
160
161* FIEMAP_EXTENT_UNWRITTEN
162Unwritten extent - the extent is allocated but it's data has not been
163initialized. This indicates the extent's data will be all zero if read
164through the filesystem but the contents are undefined if read directly from
165the device.
166
167* FIEMAP_EXTENT_MERGED
168This will be set when a file does not support extents, i.e., it uses a block
169based addressing scheme. Since returning an extent for each block back to
170userspace would be highly inefficient, the kernel will try to merge most
171adjacent blocks into 'extents'.
172
173
174VFS -> File System Implementation
175---------------------------------
176
177File systems wishing to support fiemap must implement a ->fiemap callback on
178their inode_operations structure. The fs ->fiemap call is responsible for
179defining it's set of supported fiemap flags, and calling a helper function on
180each discovered extent:
181
182struct inode_operations {
183 ...
184
185 int (*fiemap)(struct inode *, struct fiemap_extent_info *, u64 start,
186 u64 len);
187
188->fiemap is passed struct fiemap_extent_info which describes the
189fiemap request:
190
191struct fiemap_extent_info {
192 unsigned int fi_flags; /* Flags as passed from user */
193 unsigned int fi_extents_mapped; /* Number of mapped extents */
194 unsigned int fi_extents_max; /* Size of fiemap_extent array */
195 struct fiemap_extent *fi_extents_start; /* Start of fiemap_extent array */
196};
197
198It is intended that the file system should not need to access any of this
199structure directly.
200
201
202Flag checking should be done at the beginning of the ->fiemap callback via the
203fiemap_check_flags() helper:
204
205int fiemap_check_flags(struct fiemap_extent_info *fieinfo, u32 fs_flags);
206
207The struct fieinfo should be passed in as recieved from ioctl_fiemap(). The
208set of fiemap flags which the fs understands should be passed via fs_flags. If
209fiemap_check_flags finds invalid user flags, it will place the bad values in
210fieinfo->fi_flags and return -EBADR. If the file system gets -EBADR, from
211fiemap_check_flags(), it should immediately exit, returning that error back to
212ioctl_fiemap().
213
214
215For each extent in the request range, the file system should call
216the helper function, fiemap_fill_next_extent():
217
218int fiemap_fill_next_extent(struct fiemap_extent_info *info, u64 logical,
219 u64 phys, u64 len, u32 flags, u32 dev);
220
221fiemap_fill_next_extent() will use the passed values to populate the
222next free extent in the fm_extents array. 'General' extent flags will
223automatically be set from specific flags on behalf of the calling file
224system so that the userspace API is not broken.
225
226fiemap_fill_next_extent() returns 0 on success, and 1 when the
227user-supplied fm_extents array is full. If an error is encountered
228while copying the extent to user memory, -EFAULT will be returned.
diff --git a/Documentation/filesystems/nfsroot.txt b/Documentation/filesystems/nfsroot.txt
index 31b329172343..68baddf3c3e0 100644
--- a/Documentation/filesystems/nfsroot.txt
+++ b/Documentation/filesystems/nfsroot.txt
@@ -169,7 +169,7 @@ They depend on various facilities being available:
1693.1) Booting from a floppy using syslinux 1693.1) Booting from a floppy using syslinux
170 170
171 When building kernels, an easy way to create a boot floppy that uses 171 When building kernels, an easy way to create a boot floppy that uses
172 syslinux is to use the zdisk or bzdisk make targets which use 172 syslinux is to use the zdisk or bzdisk make targets which use zimage
173 and bzimage images respectively. Both targets accept the 173 and bzimage images respectively. Both targets accept the
174 FDARGS parameter which can be used to set the kernel command line. 174 FDARGS parameter which can be used to set the kernel command line.
175 175
diff --git a/Documentation/filesystems/ocfs2.txt b/Documentation/filesystems/ocfs2.txt
index c318a8bbb1ef..4340cc825796 100644
--- a/Documentation/filesystems/ocfs2.txt
+++ b/Documentation/filesystems/ocfs2.txt
@@ -76,3 +76,9 @@ localalloc=8(*) Allows custom localalloc size in MB. If the value is too
76 large, the fs will silently revert it to the default. 76 large, the fs will silently revert it to the default.
77 Localalloc is not enabled for local mounts. 77 Localalloc is not enabled for local mounts.
78localflocks This disables cluster aware flock. 78localflocks This disables cluster aware flock.
79inode64 Indicates that Ocfs2 is allowed to create inodes at
80 any location in the filesystem, including those which
81 will result in inode numbers occupying more than 32
82 bits of significance.
83user_xattr (*) Enables Extended User Attributes.
84nouser_xattr Disables Extended User Attributes.
diff --git a/Documentation/filesystems/proc.txt b/Documentation/filesystems/proc.txt
index f566ad9bcb7b..c032bf39e8b9 100644
--- a/Documentation/filesystems/proc.txt
+++ b/Documentation/filesystems/proc.txt
@@ -923,45 +923,44 @@ CPUs.
923The "procs_blocked" line gives the number of processes currently blocked, 923The "procs_blocked" line gives the number of processes currently blocked,
924waiting for I/O to complete. 924waiting for I/O to complete.
925 925
926
9261.9 Ext4 file system parameters 9271.9 Ext4 file system parameters
927------------------------------ 928------------------------------
928Ext4 file system have one directory per partition under /proc/fs/ext4/
929# ls /proc/fs/ext4/hdc/
930group_prealloc max_to_scan mb_groups mb_history min_to_scan order2_req
931stats stream_req
932
933mb_groups:
934This file gives the details of multiblock allocator buddy cache of free blocks
935
936mb_history:
937Multiblock allocation history.
938
939stats:
940This file indicate whether the multiblock allocator should start collecting
941statistics. The statistics are shown during unmount
942 929
943group_prealloc: 930Information about mounted ext4 file systems can be found in
944The multiblock allocator normalize the block allocation request to 931/proc/fs/ext4. Each mounted filesystem will have a directory in
945group_prealloc filesystem blocks if we don't have strip value set. 932/proc/fs/ext4 based on its device name (i.e., /proc/fs/ext4/hdc or
946The stripe value can be specified at mount time or during mke2fs. 933/proc/fs/ext4/dm-0). The files in each per-device directory are shown
934in Table 1-10, below.
947 935
948max_to_scan: 936Table 1-10: Files in /proc/fs/ext4/<devname>
949How long multiblock allocator can look for a best extent (in found extents) 937..............................................................................
950 938 File Content
951min_to_scan: 939 mb_groups details of multiblock allocator buddy cache of free blocks
952How long multiblock allocator must look for a best extent 940 mb_history multiblock allocation history
953 941 stats controls whether the multiblock allocator should start
954order2_req: 942 collecting statistics, which are shown during the unmount
955Multiblock allocator use 2^N search using buddies only for requests greater 943 group_prealloc the multiblock allocator will round up allocation
956than or equal to order2_req. The request size is specfied in file system 944 requests to a multiple of this tuning parameter if the
957blocks. A value of 2 indicate only if the requests are greater than or equal 945 stripe size is not set in the ext4 superblock
958to 4 blocks. 946 max_to_scan The maximum number of extents the multiblock allocator
947 will search to find the best extent
948 min_to_scan The minimum number of extents the multiblock allocator
949 will search to find the best extent
950 order2_req Tuning parameter which controls the minimum size for
951 requests (as a power of 2) where the buddy cache is
952 used
953 stream_req Files which have fewer blocks than this tunable
954 parameter will have their blocks allocated out of a
955 block group specific preallocation pool, so that small
956 files are packed closely together. Each large file
957 will have its blocks allocated out of its own unique
958 preallocation pool.
959inode_readahead Tuning parameter which controls the maximum number of
960 inode table blocks that ext4's inode table readahead
961 algorithm will pre-read into the buffer cache
962..............................................................................
959 963
960stream_req:
961Files smaller than stream_req are served by the stream allocator, whose
962purpose is to pack requests as close each to other as possible to
963produce smooth I/O traffic. Avalue of 16 indicate that file smaller than 16
964filesystem block size will use group based preallocation.
965 964
966------------------------------------------------------------------------------ 965------------------------------------------------------------------------------
967Summary 966Summary
@@ -1322,6 +1321,18 @@ debugging information is displayed on console.
1322NMI switch that most IA32 servers have fires unknown NMI up, for example. 1321NMI switch that most IA32 servers have fires unknown NMI up, for example.
1323If a system hangs up, try pressing the NMI switch. 1322If a system hangs up, try pressing the NMI switch.
1324 1323
1324panic_on_unrecovered_nmi
1325------------------------
1326
1327The default Linux behaviour on an NMI of either memory or unknown is to continue
1328operation. For many environments such as scientific computing it is preferable
1329that the box is taken out and the error dealt with than an uncorrected
1330parity/ECC error get propogated.
1331
1332A small number of systems do generate NMI's for bizarre random reasons such as
1333power management so the default is off. That sysctl works like the existing
1334panic controls already in that directory.
1335
1325nmi_watchdog 1336nmi_watchdog
1326------------ 1337------------
1327 1338
@@ -1332,13 +1343,6 @@ determine whether or not they are still functioning properly.
1332Because the NMI watchdog shares registers with oprofile, by disabling the NMI 1343Because the NMI watchdog shares registers with oprofile, by disabling the NMI
1333watchdog, oprofile may have more registers to utilize. 1344watchdog, oprofile may have more registers to utilize.
1334 1345
1335maps_protect
1336------------
1337
1338Enables/Disables the protection of the per-process proc entries "maps" and
1339"smaps". When enabled, the contents of these files are visible only to
1340readers that are allowed to ptrace() the given process.
1341
1342msgmni 1346msgmni
1343------ 1347------
1344 1348
diff --git a/Documentation/filesystems/ramfs-rootfs-initramfs.txt b/Documentation/filesystems/ramfs-rootfs-initramfs.txt
index 7be232b44ee4..62fe9b1e0890 100644
--- a/Documentation/filesystems/ramfs-rootfs-initramfs.txt
+++ b/Documentation/filesystems/ramfs-rootfs-initramfs.txt
@@ -263,7 +263,7 @@ User Mode Linux, like so:
263 sleep(999999999); 263 sleep(999999999);
264 } 264 }
265 EOF 265 EOF
266 gcc -static hello2.c -o init 266 gcc -static hello.c -o init
267 echo init | cpio -o -H newc | gzip > test.cpio.gz 267 echo init | cpio -o -H newc | gzip > test.cpio.gz
268 # Testing external initramfs using the initrd loading mechanism. 268 # Testing external initramfs using the initrd loading mechanism.
269 qemu -kernel /boot/vmlinuz -initrd test.cpio.gz /dev/zero 269 qemu -kernel /boot/vmlinuz -initrd test.cpio.gz /dev/zero
diff --git a/Documentation/gpio.txt b/Documentation/gpio.txt
index 18022e249c53..b1b988701247 100644
--- a/Documentation/gpio.txt
+++ b/Documentation/gpio.txt
@@ -240,6 +240,10 @@ signal, or (b) something wrongly believes it's safe to remove drivers
240needed to manage a signal that's in active use. That is, requesting a 240needed to manage a signal that's in active use. That is, requesting a
241GPIO can serve as a kind of lock. 241GPIO can serve as a kind of lock.
242 242
243Some platforms may also use knowledge about what GPIOs are active for
244power management, such as by powering down unused chip sectors and, more
245easily, gating off unused clocks.
246
243These two calls are optional because not not all current Linux platforms 247These two calls are optional because not not all current Linux platforms
244offer such functionality in their GPIO support; a valid implementation 248offer such functionality in their GPIO support; a valid implementation
245could return success for all gpio_request() calls. Unlike the other calls, 249could return success for all gpio_request() calls. Unlike the other calls,
@@ -264,7 +268,7 @@ map between them using calls like:
264 /* map GPIO numbers to IRQ numbers */ 268 /* map GPIO numbers to IRQ numbers */
265 int gpio_to_irq(unsigned gpio); 269 int gpio_to_irq(unsigned gpio);
266 270
267 /* map IRQ numbers to GPIO numbers */ 271 /* map IRQ numbers to GPIO numbers (avoid using this) */
268 int irq_to_gpio(unsigned irq); 272 int irq_to_gpio(unsigned irq);
269 273
270Those return either the corresponding number in the other namespace, or 274Those return either the corresponding number in the other namespace, or
@@ -284,7 +288,8 @@ system wakeup capabilities.
284 288
285Non-error values returned from irq_to_gpio() would most commonly be used 289Non-error values returned from irq_to_gpio() would most commonly be used
286with gpio_get_value(), for example to initialize or update driver state 290with gpio_get_value(), for example to initialize or update driver state
287when the IRQ is edge-triggered. 291when the IRQ is edge-triggered. Note that some platforms don't support
292this reverse mapping, so you should avoid using it.
288 293
289 294
290Emulating Open Drain Signals 295Emulating Open Drain Signals
diff --git a/Documentation/hwmon/adt7470 b/Documentation/hwmon/adt7470
new file mode 100644
index 000000000000..75d13ca147cc
--- /dev/null
+++ b/Documentation/hwmon/adt7470
@@ -0,0 +1,76 @@
1Kernel driver adt7470
2=====================
3
4Supported chips:
5 * Analog Devices ADT7470
6 Prefix: 'adt7470'
7 Addresses scanned: I2C 0x2C, 0x2E, 0x2F
8 Datasheet: Publicly available at the Analog Devices website
9
10Author: Darrick J. Wong
11
12Description
13-----------
14
15This driver implements support for the Analog Devices ADT7470 chip. There may
16be other chips that implement this interface.
17
18The ADT7470 uses the 2-wire interface compatible with the SMBus 2.0
19specification. Using an analog to digital converter it measures up to ten (10)
20external temperatures. It has four (4) 16-bit counters for measuring fan speed.
21There are four (4) PWM outputs that can be used to control fan speed.
22
23A sophisticated control system for the PWM outputs is designed into the ADT7470
24that allows fan speed to be adjusted automatically based on any of the ten
25temperature sensors. Each PWM output is individually adjustable and
26programmable. Once configured, the ADT7470 will adjust the PWM outputs in
27response to the measured temperatures with further host intervention. This
28feature can also be disabled for manual control of the PWM's.
29
30Each of the measured inputs (temperature, fan speed) has corresponding high/low
31limit values. The ADT7470 will signal an ALARM if any measured value exceeds
32either limit.
33
34The ADT7470 DOES NOT sample all inputs continuously. A single pin on the
35ADT7470 is connected to a multitude of thermal diodes, but the chip must be
36instructed explicitly to read the multitude of diodes. If you want to use
37automatic fan control mode, you must manually read any of the temperature
38sensors or the fan control algorithm will not run. The chip WILL NOT DO THIS
39AUTOMATICALLY; this must be done from userspace. This may be a bug in the chip
40design, given that many other AD chips take care of this. The driver will not
41read the registers more often than once every 5 seconds. Further,
42configuration data is only read once per minute.
43
44Special Features
45----------------
46
47The ADT7470 has a 8-bit ADC and is capable of measuring temperatures with 1
48degC resolution.
49
50The Analog Devices datasheet is very detailed and describes a procedure for
51determining an optimal configuration for the automatic PWM control.
52
53Configuration Notes
54-------------------
55
56Besides standard interfaces driver adds the following:
57
58* PWM Control
59
60* pwm#_auto_point1_pwm and pwm#_auto_point1_temp and
61* pwm#_auto_point2_pwm and pwm#_auto_point2_temp -
62
63point1: Set the pwm speed at a lower temperature bound.
64point2: Set the pwm speed at a higher temperature bound.
65
66The ADT7470 will scale the pwm between the lower and higher pwm speed when
67the temperature is between the two temperature boundaries. PWM values range
68from 0 (off) to 255 (full speed). Fan speed will be set to maximum when the
69temperature sensor associated with the PWM control exceeds
70pwm#_auto_point2_temp.
71
72Notes
73-----
74
75As stated above, the temperature inputs must be read periodically from
76userspace in order for the automatic pwm algorithm to run.
diff --git a/Documentation/hwmon/it87 b/Documentation/hwmon/it87
index 3496b7020e7c..042c0415140b 100644
--- a/Documentation/hwmon/it87
+++ b/Documentation/hwmon/it87
@@ -136,10 +136,10 @@ once-only alarms.
136The IT87xx only updates its values each 1.5 seconds; reading it more often 136The IT87xx only updates its values each 1.5 seconds; reading it more often
137will do no harm, but will return 'old' values. 137will do no harm, but will return 'old' values.
138 138
139To change sensor N to a thermistor, 'echo 2 > tempN_type' where N is 1, 2, 139To change sensor N to a thermistor, 'echo 4 > tempN_type' where N is 1, 2,
140or 3. To change sensor N to a thermal diode, 'echo 3 > tempN_type'. 140or 3. To change sensor N to a thermal diode, 'echo 3 > tempN_type'.
141Give 0 for unused sensor. Any other value is invalid. To configure this at 141Give 0 for unused sensor. Any other value is invalid. To configure this at
142startup, consult lm_sensors's /etc/sensors.conf. (2 = thermistor; 142startup, consult lm_sensors's /etc/sensors.conf. (4 = thermistor;
1433 = thermal diode) 1433 = thermal diode)
144 144
145 145
diff --git a/Documentation/hwmon/lm85 b/Documentation/hwmon/lm85
index 6d41db7f17f8..400620741290 100644
--- a/Documentation/hwmon/lm85
+++ b/Documentation/hwmon/lm85
@@ -163,16 +163,6 @@ configured individually according to the following options.
163* pwm#_auto_pwm_min - this specifies the PWM value for temp#_auto_temp_off 163* pwm#_auto_pwm_min - this specifies the PWM value for temp#_auto_temp_off
164 temperature. (PWM value from 0 to 255) 164 temperature. (PWM value from 0 to 255)
165 165
166* pwm#_auto_pwm_freq - select base frequency of PWM output. You can select
167 in range of 10.0 to 94.0 Hz in .1 Hz units.
168 (Values 100 to 940).
169
170The pwm#_auto_pwm_freq can be set to one of the following 8 values. Setting the
171frequency to a value not on this list, will result in the next higher frequency
172being selected. The actual device frequency may vary slightly from this
173specification as designed by the manufacturer. Consult the datasheet for more
174details. (PWM Frequency values: 100, 150, 230, 300, 380, 470, 620, 940)
175
176* pwm#_auto_pwm_minctl - this flags selects for temp#_auto_temp_off temperature 166* pwm#_auto_pwm_minctl - this flags selects for temp#_auto_temp_off temperature
177 the bahaviour of fans. Write 1 to let fans spinning at 167 the bahaviour of fans. Write 1 to let fans spinning at
178 pwm#_auto_pwm_min or write 0 to let them off. 168 pwm#_auto_pwm_min or write 0 to let them off.
diff --git a/Documentation/hwmon/lm87 b/Documentation/hwmon/lm87
index ec27aa1b94cb..6b47b67fd968 100644
--- a/Documentation/hwmon/lm87
+++ b/Documentation/hwmon/lm87
@@ -65,11 +65,10 @@ The LM87 has four pins which can serve one of two possible functions,
65depending on the hardware configuration. 65depending on the hardware configuration.
66 66
67Some functions share pins, so not all functions are available at the same 67Some functions share pins, so not all functions are available at the same
68time. Which are depends on the hardware setup. This driver assumes that 68time. Which are depends on the hardware setup. This driver normally
69the BIOS configured the chip correctly. In that respect, it differs from 69assumes that firmware configured the chip correctly. Where this is not
70the original driver (from lm_sensors for Linux 2.4), which would force the 70the case, platform code must set the I2C client's platform_data to point
71LM87 to an arbitrary, compile-time chosen mode, regardless of the actual 71to a u8 value to be written to the channel register.
72chipset wiring.
73 72
74For reference, here is the list of exclusive functions: 73For reference, here is the list of exclusive functions:
75 - in0+in5 (default) or temp3 74 - in0+in5 (default) or temp3
diff --git a/Documentation/hwmon/lm90 b/Documentation/hwmon/lm90
index aa4a0ec20081..e0d5206d1de3 100644
--- a/Documentation/hwmon/lm90
+++ b/Documentation/hwmon/lm90
@@ -11,7 +11,7 @@ Supported chips:
11 Prefix: 'lm99' 11 Prefix: 'lm99'
12 Addresses scanned: I2C 0x4c and 0x4d 12 Addresses scanned: I2C 0x4c and 0x4d
13 Datasheet: Publicly available at the National Semiconductor website 13 Datasheet: Publicly available at the National Semiconductor website
14 http://www.national.com/pf/LM/LM89.html 14 http://www.national.com/mpf/LM/LM89.html
15 * National Semiconductor LM99 15 * National Semiconductor LM99
16 Prefix: 'lm99' 16 Prefix: 'lm99'
17 Addresses scanned: I2C 0x4c and 0x4d 17 Addresses scanned: I2C 0x4c and 0x4d
@@ -21,18 +21,32 @@ Supported chips:
21 Prefix: 'lm86' 21 Prefix: 'lm86'
22 Addresses scanned: I2C 0x4c 22 Addresses scanned: I2C 0x4c
23 Datasheet: Publicly available at the National Semiconductor website 23 Datasheet: Publicly available at the National Semiconductor website
24 http://www.national.com/pf/LM/LM86.html 24 http://www.national.com/mpf/LM/LM86.html
25 * Analog Devices ADM1032 25 * Analog Devices ADM1032
26 Prefix: 'adm1032' 26 Prefix: 'adm1032'
27 Addresses scanned: I2C 0x4c and 0x4d 27 Addresses scanned: I2C 0x4c and 0x4d
28 Datasheet: Publicly available at the Analog Devices website 28 Datasheet: Publicly available at the ON Semiconductor website
29 http://www.analog.com/en/prod/0,2877,ADM1032,00.html 29 http://www.onsemi.com/PowerSolutions/product.do?id=ADM1032
30 * Analog Devices ADT7461 30 * Analog Devices ADT7461
31 Prefix: 'adt7461' 31 Prefix: 'adt7461'
32 Addresses scanned: I2C 0x4c and 0x4d 32 Addresses scanned: I2C 0x4c and 0x4d
33 Datasheet: Publicly available at the Analog Devices website 33 Datasheet: Publicly available at the ON Semiconductor website
34 http://www.analog.com/en/prod/0,2877,ADT7461,00.html 34 http://www.onsemi.com/PowerSolutions/product.do?id=ADT7461
35 Note: Only if in ADM1032 compatibility mode 35 * Maxim MAX6646
36 Prefix: 'max6646'
37 Addresses scanned: I2C 0x4d
38 Datasheet: Publicly available at the Maxim website
39 http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3497
40 * Maxim MAX6647
41 Prefix: 'max6646'
42 Addresses scanned: I2C 0x4e
43 Datasheet: Publicly available at the Maxim website
44 http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3497
45 * Maxim MAX6649
46 Prefix: 'max6646'
47 Addresses scanned: I2C 0x4c
48 Datasheet: Publicly available at the Maxim website
49 http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3497
36 * Maxim MAX6657 50 * Maxim MAX6657
37 Prefix: 'max6657' 51 Prefix: 'max6657'
38 Addresses scanned: I2C 0x4c 52 Addresses scanned: I2C 0x4c
@@ -70,25 +84,21 @@ Description
70 84
71The LM90 is a digital temperature sensor. It senses its own temperature as 85The LM90 is a digital temperature sensor. It senses its own temperature as
72well as the temperature of up to one external diode. It is compatible 86well as the temperature of up to one external diode. It is compatible
73with many other devices such as the LM86, the LM89, the LM99, the ADM1032, 87with many other devices, many of which are supported by this driver.
74the MAX6657, MAX6658, MAX6659, MAX6680 and the MAX6681 all of which are
75supported by this driver.
76 88
77Note that there is no easy way to differentiate between the MAX6657, 89Note that there is no easy way to differentiate between the MAX6657,
78MAX6658 and MAX6659 variants. The extra address and features of the 90MAX6658 and MAX6659 variants. The extra address and features of the
79MAX6659 are not supported by this driver. The MAX6680 and MAX6681 only 91MAX6659 are not supported by this driver. The MAX6680 and MAX6681 only
80differ in their pinout, therefore they obviously can't (and don't need to) 92differ in their pinout, therefore they obviously can't (and don't need to)
81be distinguished. Additionally, the ADT7461 is supported if found in 93be distinguished.
82ADM1032 compatibility mode.
83 94
84The specificity of this family of chipsets over the ADM1021/LM84 95The specificity of this family of chipsets over the ADM1021/LM84
85family is that it features critical limits with hysteresis, and an 96family is that it features critical limits with hysteresis, and an
86increased resolution of the remote temperature measurement. 97increased resolution of the remote temperature measurement.
87 98
88The different chipsets of the family are not strictly identical, although 99The different chipsets of the family are not strictly identical, although
89very similar. This driver doesn't handle any specific feature for now, 100very similar. For reference, here comes a non-exhaustive list of specific
90with the exception of SMBus PEC. For reference, here comes a non-exhaustive 101features:
91list of specific features:
92 102
93LM90: 103LM90:
94 * Filter and alert configuration register at 0xBF. 104 * Filter and alert configuration register at 0xBF.
@@ -114,9 +124,11 @@ ADT7461:
114 * Lower resolution for remote temperature 124 * Lower resolution for remote temperature
115 125
116MAX6657 and MAX6658: 126MAX6657 and MAX6658:
127 * Better local resolution
117 * Remote sensor type selection 128 * Remote sensor type selection
118 129
119MAX6659: 130MAX6659:
131 * Better local resolution
120 * Selectable address 132 * Selectable address
121 * Second critical temperature limit 133 * Second critical temperature limit
122 * Remote sensor type selection 134 * Remote sensor type selection
@@ -127,7 +139,8 @@ MAX6680 and MAX6681:
127 139
128All temperature values are given in degrees Celsius. Resolution 140All temperature values are given in degrees Celsius. Resolution
129is 1.0 degree for the local temperature, 0.125 degree for the remote 141is 1.0 degree for the local temperature, 0.125 degree for the remote
130temperature. 142temperature, except for the MAX6657, MAX6658 and MAX6659 which have a
143resolution of 0.125 degree for both temperatures.
131 144
132Each sensor has its own high and low limits, plus a critical limit. 145Each sensor has its own high and low limits, plus a critical limit.
133Additionally, there is a relative hysteresis value common to both critical 146Additionally, there is a relative hysteresis value common to both critical
diff --git a/Documentation/hwmon/pc87360 b/Documentation/hwmon/pc87360
index 89a8fcfa78df..cbac32b59c8c 100644
--- a/Documentation/hwmon/pc87360
+++ b/Documentation/hwmon/pc87360
@@ -5,12 +5,7 @@ Supported chips:
5 * National Semiconductor PC87360, PC87363, PC87364, PC87365 and PC87366 5 * National Semiconductor PC87360, PC87363, PC87364, PC87365 and PC87366
6 Prefixes: 'pc87360', 'pc87363', 'pc87364', 'pc87365', 'pc87366' 6 Prefixes: 'pc87360', 'pc87363', 'pc87364', 'pc87365', 'pc87366'
7 Addresses scanned: none, address read from Super I/O config space 7 Addresses scanned: none, address read from Super I/O config space
8 Datasheets: 8 Datasheets: No longer available
9 http://www.national.com/pf/PC/PC87360.html
10 http://www.national.com/pf/PC/PC87363.html
11 http://www.national.com/pf/PC/PC87364.html
12 http://www.national.com/pf/PC/PC87365.html
13 http://www.national.com/pf/PC/PC87366.html
14 9
15Authors: Jean Delvare <khali@linux-fr.org> 10Authors: Jean Delvare <khali@linux-fr.org>
16 11
diff --git a/Documentation/hwmon/pc87427 b/Documentation/hwmon/pc87427
index 9a0708f9f49e..d1ebbe510f35 100644
--- a/Documentation/hwmon/pc87427
+++ b/Documentation/hwmon/pc87427
@@ -5,7 +5,7 @@ Supported chips:
5 * National Semiconductor PC87427 5 * National Semiconductor PC87427
6 Prefix: 'pc87427' 6 Prefix: 'pc87427'
7 Addresses scanned: none, address read from Super I/O config space 7 Addresses scanned: none, address read from Super I/O config space
8 Datasheet: http://www.winbond.com.tw/E-WINBONDHTM/partner/apc_007.html 8 Datasheet: No longer available
9 9
10Author: Jean Delvare <khali@linux-fr.org> 10Author: Jean Delvare <khali@linux-fr.org>
11 11
diff --git a/Documentation/hwmon/w83781d b/Documentation/hwmon/w83781d
index 6f800a0283e9..c91e0b63ea1d 100644
--- a/Documentation/hwmon/w83781d
+++ b/Documentation/hwmon/w83781d
@@ -353,7 +353,7 @@ in6=255
353 353
354# PWM 354# PWM
355 355
356Additional info about PWM on the AS99127F (may apply to other Asus 356* Additional info about PWM on the AS99127F (may apply to other Asus
357chips as well) by Jean Delvare as of 2004-04-09: 357chips as well) by Jean Delvare as of 2004-04-09:
358 358
359AS99127F revision 2 seems to have two PWM registers at 0x59 and 0x5A, 359AS99127F revision 2 seems to have two PWM registers at 0x59 and 0x5A,
@@ -396,7 +396,7 @@ Please contact us if you can figure out how it is supposed to work. As
396long as we don't know more, the w83781d driver doesn't handle PWM on 396long as we don't know more, the w83781d driver doesn't handle PWM on
397AS99127F chips at all. 397AS99127F chips at all.
398 398
399Additional info about PWM on the AS99127F rev.1 by Hector Martin: 399* Additional info about PWM on the AS99127F rev.1 by Hector Martin:
400 400
401I've been fiddling around with the (in)famous 0x59 register and 401I've been fiddling around with the (in)famous 0x59 register and
402found out the following values do work as a form of coarse pwm: 402found out the following values do work as a form of coarse pwm:
@@ -418,3 +418,36 @@ change.
418My mobo is an ASUS A7V266-E. This behavior is similar to what I got 418My mobo is an ASUS A7V266-E. This behavior is similar to what I got
419with speedfan under Windows, where 0-15% would be off, 15-2x% (can't 419with speedfan under Windows, where 0-15% would be off, 15-2x% (can't
420remember the exact value) would be 70% and higher would be full on. 420remember the exact value) would be 70% and higher would be full on.
421
422* Additional info about PWM on the AS99127F rev.1 from lm-sensors
423 ticket #2350:
424
425I conducted some experiment on Asus P3B-F motherboard with AS99127F
426(Ver. 1).
427
428I confirm that 0x59 register control the CPU_Fan Header on this
429motherboard, and 0x5a register control PWR_Fan.
430
431In order to reduce the dependency of specific fan, the measurement is
432conducted with a digital scope without fan connected. I found out that
433P3B-F actually output variable DC voltage on fan header center pin,
434looks like PWM is filtered on this motherboard.
435
436Here are some of measurements:
437
4380x80 20 mV
4390x81 20 mV
4400x82 232 mV
4410x83 1.2 V
4420x84 2.31 V
4430x85 3.44 V
4440x86 4.62 V
4450x87 5.81 V
4460x88 7.01 V
4479x89 8.22 V
4480x8a 9.42 V
4490x8b 10.6 V
4500x8c 11.9 V
4510x8d 12.4 V
4520x8e 12.4 V
4530x8f 12.4 V
diff --git a/Documentation/hwmon/w83791d b/Documentation/hwmon/w83791d
index a67d3b7a7098..5663e491655c 100644
--- a/Documentation/hwmon/w83791d
+++ b/Documentation/hwmon/w83791d
@@ -58,29 +58,35 @@ internal state that allows no clean access (Bank with ID register is not
58currently selected). If you know the address of the chip, use a 'force' 58currently selected). If you know the address of the chip, use a 'force'
59parameter; this will put it into a more well-behaved state first. 59parameter; this will put it into a more well-behaved state first.
60 60
61The driver implements three temperature sensors, five fan rotation speed 61The driver implements three temperature sensors, ten voltage sensors,
62sensors, and ten voltage sensors. 62five fan rotation speed sensors and manual PWM control of each fan.
63 63
64Temperatures are measured in degrees Celsius and measurement resolution is 1 64Temperatures are measured in degrees Celsius and measurement resolution is 1
65degC for temp1 and 0.5 degC for temp2 and temp3. An alarm is triggered when 65degC for temp1 and 0.5 degC for temp2 and temp3. An alarm is triggered when
66the temperature gets higher than the Overtemperature Shutdown value; it stays 66the temperature gets higher than the Overtemperature Shutdown value; it stays
67on until the temperature falls below the Hysteresis value. 67on until the temperature falls below the Hysteresis value.
68 68
69Voltage sensors (also known as IN sensors) report their values in millivolts.
70An alarm is triggered if the voltage has crossed a programmable minimum
71or maximum limit.
72
69Fan rotation speeds are reported in RPM (rotations per minute). An alarm is 73Fan rotation speeds are reported in RPM (rotations per minute). An alarm is
70triggered if the rotation speed has dropped below a programmable limit. Fan 74triggered if the rotation speed has dropped below a programmable limit. Fan
71readings can be divided by a programmable divider (1, 2, 4, 8, 16, 75readings can be divided by a programmable divider (1, 2, 4, 8, 16,
7232, 64 or 128 for all fans) to give the readings more range or accuracy. 7632, 64 or 128 for all fans) to give the readings more range or accuracy.
73 77
74Voltage sensors (also known as IN sensors) report their values in millivolts. 78Each fan controlled is controlled by PWM. The PWM duty cycle can be read and
75An alarm is triggered if the voltage has crossed a programmable minimum 79set for each fan separately. Valid values range from 0 (stop) to 255 (full).
76or maximum limit. 80PWM 1-3 support Thermal Cruise mode, in which the PWMs are automatically
81regulated to keep respectively temp 1-3 at a certain target temperature.
82See below for the description of the sysfs-interface.
77 83
78The w83791d has a global bit used to enable beeping from the speaker when an 84The w83791d has a global bit used to enable beeping from the speaker when an
79alarm is triggered as well as a bitmask to enable or disable the beep for 85alarm is triggered as well as a bitmask to enable or disable the beep for
80specific alarms. You need both the global beep enable bit and the 86specific alarms. You need both the global beep enable bit and the
81corresponding beep bit to be on for a triggered alarm to sound a beep. 87corresponding beep bit to be on for a triggered alarm to sound a beep.
82 88
83The sysfs interface to the gloabal enable is via the sysfs beep_enable file. 89The sysfs interface to the global enable is via the sysfs beep_enable file.
84This file is used for both legacy and new code. 90This file is used for both legacy and new code.
85 91
86The sysfs interface to the beep bitmask has migrated from the original legacy 92The sysfs interface to the beep bitmask has migrated from the original legacy
@@ -105,6 +111,27 @@ going forward.
105The driver reads the hardware chip values at most once every three seconds. 111The driver reads the hardware chip values at most once every three seconds.
106User mode code requesting values more often will receive cached values. 112User mode code requesting values more often will receive cached values.
107 113
114/sys files
115----------
116The sysfs-interface is documented in the 'sysfs-interface' file. Only
117chip-specific options are documented here.
118
119pwm[1-3]_enable - this file controls mode of fan/temperature control for
120 fan 1-3. Fan/PWM 4-5 only support manual mode.
121 * 1 Manual mode
122 * 2 Thermal Cruise mode
123 * 3 Fan Speed Cruise mode (no further support)
124
125temp[1-3]_target - defines the target temperature for Thermal Cruise mode.
126 Unit: millidegree Celsius
127 RW
128
129temp[1-3]_tolerance - temperature tolerance for Thermal Cruise mode.
130 Specifies an interval around the target temperature
131 in which the fan speed is not changed.
132 Unit: millidegree Celsius
133 RW
134
108Alarms bitmap vs. beep_mask bitmask 135Alarms bitmap vs. beep_mask bitmask
109------------------------------------ 136------------------------------------
110For legacy code using the alarms and beep_mask files: 137For legacy code using the alarms and beep_mask files:
@@ -132,7 +159,3 @@ tart2 : alarms: 0x020000 beep_mask: 0x080000 <== mismatch
132tart3 : alarms: 0x040000 beep_mask: 0x100000 <== mismatch 159tart3 : alarms: 0x040000 beep_mask: 0x100000 <== mismatch
133case_open : alarms: 0x001000 beep_mask: 0x001000 160case_open : alarms: 0x001000 beep_mask: 0x001000
134global_enable: alarms: -------- beep_mask: 0x800000 (modified via beep_enable) 161global_enable: alarms: -------- beep_mask: 0x800000 (modified via beep_enable)
135
136W83791D TODO:
137---------------
138Provide a patch for smart-fan control (still need appropriate motherboard/fans)
diff --git a/Documentation/i2c/busses/i2c-viapro b/Documentation/i2c/busses/i2c-viapro
index 1405fb69984c..22efedf60c87 100644
--- a/Documentation/i2c/busses/i2c-viapro
+++ b/Documentation/i2c/busses/i2c-viapro
@@ -16,6 +16,9 @@ Supported adapters:
16 * VIA Technologies, Inc. CX700 16 * VIA Technologies, Inc. CX700
17 Datasheet: available on request and under NDA from VIA 17 Datasheet: available on request and under NDA from VIA
18 18
19 * VIA Technologies, Inc. VX800/VX820
20 Datasheet: available on http://linux.via.com.tw
21
19Authors: 22Authors:
20 Kyösti Mälkki <kmalkki@cc.hut.fi>, 23 Kyösti Mälkki <kmalkki@cc.hut.fi>,
21 Mark D. Studebaker <mdsxyz123@yahoo.com>, 24 Mark D. Studebaker <mdsxyz123@yahoo.com>,
@@ -49,6 +52,7 @@ Your lspci -n listing must show one of these :
49 device 1106:3372 (VT8237S) 52 device 1106:3372 (VT8237S)
50 device 1106:3287 (VT8251) 53 device 1106:3287 (VT8251)
51 device 1106:8324 (CX700) 54 device 1106:8324 (CX700)
55 device 1106:8353 (VX800/VX820)
52 56
53If none of these show up, you should look in the BIOS for settings like 57If none of these show up, you should look in the BIOS for settings like
54enable ACPI / SMBus or even USB. 58enable ACPI / SMBus or even USB.
@@ -57,5 +61,5 @@ Except for the oldest chips (VT82C596A/B, VT82C686A and most probably
57VT8231), this driver supports I2C block transactions. Such transactions 61VT8231), this driver supports I2C block transactions. Such transactions
58are mainly useful to read from and write to EEPROMs. 62are mainly useful to read from and write to EEPROMs.
59 63
60The CX700 additionally appears to support SMBus PEC, although this driver 64The CX700/VX800/VX820 additionally appears to support SMBus PEC, although
61doesn't implement it yet. 65this driver doesn't implement it yet.
diff --git a/Documentation/i2c/dev-interface b/Documentation/i2c/dev-interface
index 9dd79123ddd9..3e742ba25536 100644
--- a/Documentation/i2c/dev-interface
+++ b/Documentation/i2c/dev-interface
@@ -4,6 +4,10 @@ the /dev interface. You need to load module i2c-dev for this.
4 4
5Each registered i2c adapter gets a number, counting from 0. You can 5Each registered i2c adapter gets a number, counting from 0. You can
6examine /sys/class/i2c-dev/ to see what number corresponds to which adapter. 6examine /sys/class/i2c-dev/ to see what number corresponds to which adapter.
7Alternatively, you can run "i2cdetect -l" to obtain a formated list of all
8i2c adapters present on your system at a given time. i2cdetect is part of
9the i2c-tools package.
10
7I2C device files are character device files with major device number 89 11I2C device files are character device files with major device number 89
8and a minor device number corresponding to the number assigned as 12and a minor device number corresponding to the number assigned as
9explained above. They should be called "i2c-%d" (i2c-0, i2c-1, ..., 13explained above. They should be called "i2c-%d" (i2c-0, i2c-1, ...,
@@ -17,30 +21,34 @@ So let's say you want to access an i2c adapter from a C program. The
17first thing to do is "#include <linux/i2c-dev.h>". Please note that 21first thing to do is "#include <linux/i2c-dev.h>". Please note that
18there are two files named "i2c-dev.h" out there, one is distributed 22there are two files named "i2c-dev.h" out there, one is distributed
19with the Linux kernel and is meant to be included from kernel 23with the Linux kernel and is meant to be included from kernel
20driver code, the other one is distributed with lm_sensors and is 24driver code, the other one is distributed with i2c-tools and is
21meant to be included from user-space programs. You obviously want 25meant to be included from user-space programs. You obviously want
22the second one here. 26the second one here.
23 27
24Now, you have to decide which adapter you want to access. You should 28Now, you have to decide which adapter you want to access. You should
25inspect /sys/class/i2c-dev/ to decide this. Adapter numbers are assigned 29inspect /sys/class/i2c-dev/ or run "i2cdetect -l" to decide this.
26somewhat dynamically, so you can not even assume /dev/i2c-0 is the 30Adapter numbers are assigned somewhat dynamically, so you can not
27first adapter. 31assume much about them. They can even change from one boot to the next.
28 32
29Next thing, open the device file, as follows: 33Next thing, open the device file, as follows:
34
30 int file; 35 int file;
31 int adapter_nr = 2; /* probably dynamically determined */ 36 int adapter_nr = 2; /* probably dynamically determined */
32 char filename[20]; 37 char filename[20];
33 38
34 sprintf(filename,"/dev/i2c-%d",adapter_nr); 39 snprintf(filename, 19, "/dev/i2c-%d", adapter_nr);
35 if ((file = open(filename,O_RDWR)) < 0) { 40 file = open(filename, O_RDWR);
41 if (file < 0) {
36 /* ERROR HANDLING; you can check errno to see what went wrong */ 42 /* ERROR HANDLING; you can check errno to see what went wrong */
37 exit(1); 43 exit(1);
38 } 44 }
39 45
40When you have opened the device, you must specify with what device 46When you have opened the device, you must specify with what device
41address you want to communicate: 47address you want to communicate:
48
42 int addr = 0x40; /* The I2C address */ 49 int addr = 0x40; /* The I2C address */
43 if (ioctl(file,I2C_SLAVE,addr) < 0) { 50
51 if (ioctl(file, I2C_SLAVE, addr) < 0) {
44 /* ERROR HANDLING; you can check errno to see what went wrong */ 52 /* ERROR HANDLING; you can check errno to see what went wrong */
45 exit(1); 53 exit(1);
46 } 54 }
@@ -48,31 +56,41 @@ address you want to communicate:
48Well, you are all set up now. You can now use SMBus commands or plain 56Well, you are all set up now. You can now use SMBus commands or plain
49I2C to communicate with your device. SMBus commands are preferred if 57I2C to communicate with your device. SMBus commands are preferred if
50the device supports them. Both are illustrated below. 58the device supports them. Both are illustrated below.
59
51 __u8 register = 0x10; /* Device register to access */ 60 __u8 register = 0x10; /* Device register to access */
52 __s32 res; 61 __s32 res;
53 char buf[10]; 62 char buf[10];
63
54 /* Using SMBus commands */ 64 /* Using SMBus commands */
55 res = i2c_smbus_read_word_data(file,register); 65 res = i2c_smbus_read_word_data(file, register);
56 if (res < 0) { 66 if (res < 0) {
57 /* ERROR HANDLING: i2c transaction failed */ 67 /* ERROR HANDLING: i2c transaction failed */
58 } else { 68 } else {
59 /* res contains the read word */ 69 /* res contains the read word */
60 } 70 }
71
61 /* Using I2C Write, equivalent of 72 /* Using I2C Write, equivalent of
62 i2c_smbus_write_word_data(file,register,0x6543) */ 73 i2c_smbus_write_word_data(file, register, 0x6543) */
63 buf[0] = register; 74 buf[0] = register;
64 buf[1] = 0x43; 75 buf[1] = 0x43;
65 buf[2] = 0x65; 76 buf[2] = 0x65;
66 if ( write(file,buf,3) != 3) { 77 if (write(file, buf, 3) ! =3) {
67 /* ERROR HANDLING: i2c transaction failed */ 78 /* ERROR HANDLING: i2c transaction failed */
68 } 79 }
80
69 /* Using I2C Read, equivalent of i2c_smbus_read_byte(file) */ 81 /* Using I2C Read, equivalent of i2c_smbus_read_byte(file) */
70 if (read(file,buf,1) != 1) { 82 if (read(file, buf, 1) != 1) {
71 /* ERROR HANDLING: i2c transaction failed */ 83 /* ERROR HANDLING: i2c transaction failed */
72 } else { 84 } else {
73 /* buf[0] contains the read byte */ 85 /* buf[0] contains the read byte */
74 } 86 }
75 87
88Note that only a subset of the I2C and SMBus protocols can be achieved by
89the means of read() and write() calls. In particular, so-called combined
90transactions (mixing read and write messages in the same transaction)
91aren't supported. For this reason, this interface is almost never used by
92user-space programs.
93
76IMPORTANT: because of the use of inline functions, you *have* to use 94IMPORTANT: because of the use of inline functions, you *have* to use
77'-O' or some variation when you compile your program! 95'-O' or some variation when you compile your program!
78 96
@@ -80,31 +98,29 @@ IMPORTANT: because of the use of inline functions, you *have* to use
80Full interface description 98Full interface description
81========================== 99==========================
82 100
83The following IOCTLs are defined and fully supported 101The following IOCTLs are defined:
84(see also i2c-dev.h):
85 102
86ioctl(file,I2C_SLAVE,long addr) 103ioctl(file, I2C_SLAVE, long addr)
87 Change slave address. The address is passed in the 7 lower bits of the 104 Change slave address. The address is passed in the 7 lower bits of the
88 argument (except for 10 bit addresses, passed in the 10 lower bits in this 105 argument (except for 10 bit addresses, passed in the 10 lower bits in this
89 case). 106 case).
90 107
91ioctl(file,I2C_TENBIT,long select) 108ioctl(file, I2C_TENBIT, long select)
92 Selects ten bit addresses if select not equals 0, selects normal 7 bit 109 Selects ten bit addresses if select not equals 0, selects normal 7 bit
93 addresses if select equals 0. Default 0. This request is only valid 110 addresses if select equals 0. Default 0. This request is only valid
94 if the adapter has I2C_FUNC_10BIT_ADDR. 111 if the adapter has I2C_FUNC_10BIT_ADDR.
95 112
96ioctl(file,I2C_PEC,long select) 113ioctl(file, I2C_PEC, long select)
97 Selects SMBus PEC (packet error checking) generation and verification 114 Selects SMBus PEC (packet error checking) generation and verification
98 if select not equals 0, disables if select equals 0. Default 0. 115 if select not equals 0, disables if select equals 0. Default 0.
99 Used only for SMBus transactions. This request only has an effect if the 116 Used only for SMBus transactions. This request only has an effect if the
100 the adapter has I2C_FUNC_SMBUS_PEC; it is still safe if not, it just 117 the adapter has I2C_FUNC_SMBUS_PEC; it is still safe if not, it just
101 doesn't have any effect. 118 doesn't have any effect.
102 119
103ioctl(file,I2C_FUNCS,unsigned long *funcs) 120ioctl(file, I2C_FUNCS, unsigned long *funcs)
104 Gets the adapter functionality and puts it in *funcs. 121 Gets the adapter functionality and puts it in *funcs.
105 122
106ioctl(file,I2C_RDWR,struct i2c_rdwr_ioctl_data *msgset) 123ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)
107
108 Do combined read/write transaction without stop in between. 124 Do combined read/write transaction without stop in between.
109 Only valid if the adapter has I2C_FUNC_I2C. The argument is 125 Only valid if the adapter has I2C_FUNC_I2C. The argument is
110 a pointer to a 126 a pointer to a
@@ -120,10 +136,9 @@ ioctl(file,I2C_RDWR,struct i2c_rdwr_ioctl_data *msgset)
120 The slave address and whether to use ten bit address mode has to be 136 The slave address and whether to use ten bit address mode has to be
121 set in each message, overriding the values set with the above ioctl's. 137 set in each message, overriding the values set with the above ioctl's.
122 138
123 139ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args)
124Other values are NOT supported at this moment, except for I2C_SMBUS, 140 Not meant to be called directly; instead, use the access functions
125which you should never directly call; instead, use the access functions 141 below.
126below.
127 142
128You can do plain i2c transactions by using read(2) and write(2) calls. 143You can do plain i2c transactions by using read(2) and write(2) calls.
129You do not need to pass the address byte; instead, set it through 144You do not need to pass the address byte; instead, set it through
@@ -148,7 +163,52 @@ what happened. The 'write' transactions return 0 on success; the
148returns the number of values read. The block buffers need not be longer 163returns the number of values read. The block buffers need not be longer
149than 32 bytes. 164than 32 bytes.
150 165
151The above functions are all macros, that resolve to calls to the 166The above functions are all inline functions, that resolve to calls to
152i2c_smbus_access function, that on its turn calls a specific ioctl 167the i2c_smbus_access function, that on its turn calls a specific ioctl
153with the data in a specific format. Read the source code if you 168with the data in a specific format. Read the source code if you
154want to know what happens behind the screens. 169want to know what happens behind the screens.
170
171
172Implementation details
173======================
174
175For the interested, here's the code flow which happens inside the kernel
176when you use the /dev interface to I2C:
177
1781* Your program opens /dev/i2c-N and calls ioctl() on it, as described in
179section "C example" above.
180
1812* These open() and ioctl() calls are handled by the i2c-dev kernel
182driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(),
183respectively. You can think of i2c-dev as a generic I2C chip driver
184that can be programmed from user-space.
185
1863* Some ioctl() calls are for administrative tasks and are handled by
187i2c-dev directly. Examples include I2C_SLAVE (set the address of the
188device you want to access) and I2C_PEC (enable or disable SMBus error
189checking on future transactions.)
190
1914* Other ioctl() calls are converted to in-kernel function calls by
192i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter
193functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which
194performs an SMBus transaction using i2c-core.c:i2c_smbus_xfer().
195
196The i2c-dev driver is responsible for checking all the parameters that
197come from user-space for validity. After this point, there is no
198difference between these calls that came from user-space through i2c-dev
199and calls that would have been performed by kernel I2C chip drivers
200directly. This means that I2C bus drivers don't need to implement
201anything special to support access from user-space.
202
2035* These i2c-core.c/i2c.h functions are wrappers to the actual
204implementation of your I2C bus driver. Each adapter must declare
205callback functions implementing these standard calls.
206i2c.h:i2c_get_functionality() calls i2c_adapter.algo->functionality(),
207while i2c-core.c:i2c_smbus_xfer() calls either
208adapter.algo->smbus_xfer() if it is implemented, or if not,
209i2c-core.c:i2c_smbus_xfer_emulated() which in turn calls
210i2c_adapter.algo->master_xfer().
211
212After your I2C bus driver has processed these requests, execution runs
213up the call chain, with almost no processing done, except by i2c-dev to
214package the returned data, if any, in suitable format for the ioctl.
diff --git a/Documentation/i2c/smbus-protocol b/Documentation/i2c/smbus-protocol
index 24bfb65da17d..9df47441f0e7 100644
--- a/Documentation/i2c/smbus-protocol
+++ b/Documentation/i2c/smbus-protocol
@@ -109,8 +109,8 @@ specified through the Comm byte.
109S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P 109S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P
110 110
111 111
112SMBus Process Call 112SMBus Process Call: i2c_smbus_process_call()
113================== 113=============================================
114 114
115This command selects a device register (through the Comm byte), sends 115This command selects a device register (through the Comm byte), sends
11616 bits of data to it, and reads 16 bits of data in return. 11616 bits of data to it, and reads 16 bits of data in return.
diff --git a/Documentation/i2c/writing-clients b/Documentation/i2c/writing-clients
index 6b61b3a2e90b..d73ee117a8ca 100644
--- a/Documentation/i2c/writing-clients
+++ b/Documentation/i2c/writing-clients
@@ -606,6 +606,8 @@ SMBus communication
606 extern s32 i2c_smbus_read_word_data(struct i2c_client * client, u8 command); 606 extern s32 i2c_smbus_read_word_data(struct i2c_client * client, u8 command);
607 extern s32 i2c_smbus_write_word_data(struct i2c_client * client, 607 extern s32 i2c_smbus_write_word_data(struct i2c_client * client,
608 u8 command, u16 value); 608 u8 command, u16 value);
609 extern s32 i2c_smbus_process_call(struct i2c_client *client,
610 u8 command, u16 value);
609 extern s32 i2c_smbus_read_block_data(struct i2c_client * client, 611 extern s32 i2c_smbus_read_block_data(struct i2c_client * client,
610 u8 command, u8 *values); 612 u8 command, u8 *values);
611 extern s32 i2c_smbus_write_block_data(struct i2c_client * client, 613 extern s32 i2c_smbus_write_block_data(struct i2c_client * client,
@@ -621,8 +623,6 @@ These ones were removed from i2c-core because they had no users, but could
621be added back later if needed: 623be added back later if needed:
622 624
623 extern s32 i2c_smbus_write_quick(struct i2c_client * client, u8 value); 625 extern s32 i2c_smbus_write_quick(struct i2c_client * client, u8 value);
624 extern s32 i2c_smbus_process_call(struct i2c_client * client,
625 u8 command, u16 value);
626 extern s32 i2c_smbus_block_process_call(struct i2c_client *client, 626 extern s32 i2c_smbus_block_process_call(struct i2c_client *client,
627 u8 command, u8 length, 627 u8 command, u8 length,
628 u8 *values) 628 u8 *values)
diff --git a/Documentation/ia64/kvm.txt b/Documentation/ia64/kvm.txt
index 914d07f49268..84f7cb3d5bec 100644
--- a/Documentation/ia64/kvm.txt
+++ b/Documentation/ia64/kvm.txt
@@ -1,7 +1,8 @@
1Currently, kvm module in EXPERIMENTAL stage on IA64. This means that 1Currently, kvm module is in EXPERIMENTAL stage on IA64. This means that
2interfaces are not stable enough to use. So, plase had better don't run 2interfaces are not stable enough to use. So, please don't run critical
3critical applications in virtual machine. We will try our best to make it 3applications in virtual machine.
4strong in future versions! 4We will try our best to improve it in future versions!
5
5 Guide: How to boot up guests on kvm/ia64 6 Guide: How to boot up guests on kvm/ia64
6 7
7This guide is to describe how to enable kvm support for IA-64 systems. 8This guide is to describe how to enable kvm support for IA-64 systems.
diff --git a/Documentation/ioctl-number.txt b/Documentation/ioctl-number.txt
index 1c6b545635a2..b880ce5dbd33 100644
--- a/Documentation/ioctl-number.txt
+++ b/Documentation/ioctl-number.txt
@@ -92,6 +92,7 @@ Code Seq# Include File Comments
92'J' 00-1F drivers/scsi/gdth_ioctl.h 92'J' 00-1F drivers/scsi/gdth_ioctl.h
93'K' all linux/kd.h 93'K' all linux/kd.h
94'L' 00-1F linux/loop.h 94'L' 00-1F linux/loop.h
95'L' 20-2F driver/usb/misc/vstusb.h
95'L' E0-FF linux/ppdd.h encrypted disk device driver 96'L' E0-FF linux/ppdd.h encrypted disk device driver
96 <http://linux01.gwdg.de/~alatham/ppdd.html> 97 <http://linux01.gwdg.de/~alatham/ppdd.html>
97'M' all linux/soundcard.h 98'M' all linux/soundcard.h
@@ -110,6 +111,8 @@ Code Seq# Include File Comments
110'W' 00-1F linux/wanrouter.h conflict! 111'W' 00-1F linux/wanrouter.h conflict!
111'X' all linux/xfs_fs.h 112'X' all linux/xfs_fs.h
112'Y' all linux/cyclades.h 113'Y' all linux/cyclades.h
114'[' 00-07 linux/usb/usbtmc.h USB Test and Measurement Devices
115 <mailto:gregkh@suse.de>
113'a' all ATM on linux 116'a' all ATM on linux
114 <http://lrcwww.epfl.ch/linux-atm/magic.html> 117 <http://lrcwww.epfl.ch/linux-atm/magic.html>
115'b' 00-FF bit3 vme host bridge 118'b' 00-FF bit3 vme host bridge
diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt
index 0bd32748a467..c6841eee9598 100644
--- a/Documentation/kernel-doc-nano-HOWTO.txt
+++ b/Documentation/kernel-doc-nano-HOWTO.txt
@@ -168,10 +168,10 @@ if ($#ARGV < 0) {
168mkdir $ARGV[0],0777; 168mkdir $ARGV[0],0777;
169$state = 0; 169$state = 0;
170while (<STDIN>) { 170while (<STDIN>) {
171 if (/^\.TH \"[^\"]*\" 4 \"([^\"]*)\"/) { 171 if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) {
172 if ($state == 1) { close OUT } 172 if ($state == 1) { close OUT }
173 $state = 1; 173 $state = 1;
174 $fn = "$ARGV[0]/$1.4"; 174 $fn = "$ARGV[0]/$1.9";
175 print STDERR "Creating $fn\n"; 175 print STDERR "Creating $fn\n";
176 open OUT, ">$fn" or die "can't open $fn: $!\n"; 176 open OUT, ">$fn" or die "can't open $fn: $!\n";
177 print OUT $_; 177 print OUT $_;
diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt
index 1150444a21ab..d4f4875fc7c6 100644
--- a/Documentation/kernel-parameters.txt
+++ b/Documentation/kernel-parameters.txt
@@ -284,6 +284,11 @@ and is between 256 and 4096 characters. It is defined in the file
284 isolate - enable device isolation (each device, as far 284 isolate - enable device isolation (each device, as far
285 as possible, will get its own protection 285 as possible, will get its own protection
286 domain) 286 domain)
287 fullflush - enable flushing of IO/TLB entries when
288 they are unmapped. Otherwise they are
289 flushed before they will be reused, which
290 is a lot of faster
291
287 amd_iommu_size= [HW,X86-64] 292 amd_iommu_size= [HW,X86-64]
288 Define the size of the aperture for the AMD IOMMU 293 Define the size of the aperture for the AMD IOMMU
289 driver. Possible values are: 294 driver. Possible values are:
@@ -463,12 +468,6 @@ and is between 256 and 4096 characters. It is defined in the file
463 Range: 0 - 8192 468 Range: 0 - 8192
464 Default: 64 469 Default: 64
465 470
466 disable_8254_timer
467 enable_8254_timer
468 [IA32/X86_64] Disable/Enable interrupt 0 timer routing
469 over the 8254 in addition to over the IO-APIC. The
470 kernel tries to set a sensible default.
471
472 hpet= [X86-32,HPET] option to control HPET usage 471 hpet= [X86-32,HPET] option to control HPET usage
473 Format: { enable (default) | disable | force } 472 Format: { enable (default) | disable | force }
474 disable: disable HPET and use PIT instead 473 disable: disable HPET and use PIT instead
@@ -659,11 +658,12 @@ and is between 256 and 4096 characters. It is defined in the file
659 earlyprintk= [X86-32,X86-64,SH,BLACKFIN] 658 earlyprintk= [X86-32,X86-64,SH,BLACKFIN]
660 earlyprintk=vga 659 earlyprintk=vga
661 earlyprintk=serial[,ttySn[,baudrate]] 660 earlyprintk=serial[,ttySn[,baudrate]]
661 earlyprintk=dbgp
662 662
663 Append ",keep" to not disable it when the real console 663 Append ",keep" to not disable it when the real console
664 takes over. 664 takes over.
665 665
666 Only vga or serial at a time, not both. 666 Only vga or serial or usb debug port at a time.
667 667
668 Currently only ttyS0 and ttyS1 are supported. 668 Currently only ttyS0 and ttyS1 are supported.
669 669
@@ -796,6 +796,7 @@ and is between 256 and 4096 characters. It is defined in the file
796 Defaults to the default architecture's huge page size 796 Defaults to the default architecture's huge page size
797 if not specified. 797 if not specified.
798 798
799 i8042.debug [HW] Toggle i8042 debug mode
799 i8042.direct [HW] Put keyboard port into non-translated mode 800 i8042.direct [HW] Put keyboard port into non-translated mode
800 i8042.dumbkbd [HW] Pretend that controller can only read data from 801 i8042.dumbkbd [HW] Pretend that controller can only read data from
801 keyboard and cannot control its state 802 keyboard and cannot control its state
@@ -1020,6 +1021,10 @@ and is between 256 and 4096 characters. It is defined in the file
1020 (only serial suported for now) 1021 (only serial suported for now)
1021 Format: <serial_device>[,baud] 1022 Format: <serial_device>[,baud]
1022 1023
1024 kmac= [MIPS] korina ethernet MAC address.
1025 Configure the RouterBoard 532 series on-chip
1026 Ethernet adapter MAC address.
1027
1023 l2cr= [PPC] 1028 l2cr= [PPC]
1024 1029
1025 l3cr= [PPC] 1030 l3cr= [PPC]
@@ -1228,6 +1233,29 @@ and is between 256 and 4096 characters. It is defined in the file
1228 or 1233 or
1229 memmap=0x10000$0x18690000 1234 memmap=0x10000$0x18690000
1230 1235
1236 memory_corruption_check=0/1 [X86]
1237 Some BIOSes seem to corrupt the first 64k of
1238 memory when doing things like suspend/resume.
1239 Setting this option will scan the memory
1240 looking for corruption. Enabling this will
1241 both detect corruption and prevent the kernel
1242 from using the memory being corrupted.
1243 However, its intended as a diagnostic tool; if
1244 repeatable BIOS-originated corruption always
1245 affects the same memory, you can use memmap=
1246 to prevent the kernel from using that memory.
1247
1248 memory_corruption_check_size=size [X86]
1249 By default it checks for corruption in the low
1250 64k, making this memory unavailable for normal
1251 use. Use this parameter to scan for
1252 corruption in more or less memory.
1253
1254 memory_corruption_check_period=seconds [X86]
1255 By default it checks for corruption every 60
1256 seconds. Use this parameter to check at some
1257 other rate. 0 disables periodic checking.
1258
1231 memtest= [KNL,X86] Enable memtest 1259 memtest= [KNL,X86] Enable memtest
1232 Format: <integer> 1260 Format: <integer>
1233 range: 0,4 : pattern number 1261 range: 0,4 : pattern number
@@ -1425,6 +1453,12 @@ and is between 256 and 4096 characters. It is defined in the file
1425 1453
1426 nolapic_timer [X86-32,APIC] Do not use the local APIC timer. 1454 nolapic_timer [X86-32,APIC] Do not use the local APIC timer.
1427 1455
1456 nox2apic [X86-64,APIC] Do not enable x2APIC mode.
1457
1458 x2apic_phys [X86-64,APIC] Use x2apic physical mode instead of
1459 default x2apic cluster mode on platforms
1460 supporting x2apic.
1461
1428 noltlbs [PPC] Do not use large page/tlb entries for kernel 1462 noltlbs [PPC] Do not use large page/tlb entries for kernel
1429 lowmem mapping on PPC40x. 1463 lowmem mapping on PPC40x.
1430 1464
@@ -1680,6 +1714,11 @@ and is between 256 and 4096 characters. It is defined in the file
1680 autoconfiguration. 1714 autoconfiguration.
1681 Ranges are in pairs (memory base and size). 1715 Ranges are in pairs (memory base and size).
1682 1716
1717 dynamic_printk
1718 Enables pr_debug()/dev_dbg() calls if
1719 CONFIG_DYNAMIC_PRINTK_DEBUG has been enabled. These can also
1720 be switched on/off via <debugfs>/dynamic_printk/modules
1721
1683 print-fatal-signals= 1722 print-fatal-signals=
1684 [KNL] debug: print fatal signals 1723 [KNL] debug: print fatal signals
1685 print-fatal-signals=1: print segfault info to 1724 print-fatal-signals=1: print segfault info to
@@ -1882,6 +1921,12 @@ and is between 256 and 4096 characters. It is defined in the file
1882 shapers= [NET] 1921 shapers= [NET]
1883 Maximal number of shapers. 1922 Maximal number of shapers.
1884 1923
1924 show_msr= [x86] show boot-time MSR settings
1925 Format: { <integer> }
1926 Show boot-time (BIOS-initialized) MSR settings.
1927 The parameter means the number of CPUs to show,
1928 for example 1 means boot CPU only.
1929
1885 sim710= [SCSI,HW] 1930 sim710= [SCSI,HW]
1886 See header of drivers/scsi/sim710.c. 1931 See header of drivers/scsi/sim710.c.
1887 1932
@@ -2208,6 +2253,25 @@ and is between 256 and 4096 characters. It is defined in the file
2208 autosuspended. Devices for which the delay is set 2253 autosuspended. Devices for which the delay is set
2209 to a negative value won't be autosuspended at all. 2254 to a negative value won't be autosuspended at all.
2210 2255
2256 usbcore.usbfs_snoop=
2257 [USB] Set to log all usbfs traffic (default 0 = off).
2258
2259 usbcore.blinkenlights=
2260 [USB] Set to cycle leds on hubs (default 0 = off).
2261
2262 usbcore.old_scheme_first=
2263 [USB] Start with the old device initialization
2264 scheme (default 0 = off).
2265
2266 usbcore.use_both_schemes=
2267 [USB] Try the other device initialization scheme
2268 if the first one fails (default 1 = enabled).
2269
2270 usbcore.initial_descriptor_timeout=
2271 [USB] Specifies timeout for the initial 64-byte
2272 USB_REQ_GET_DESCRIPTOR request in milliseconds
2273 (default 5000 = 5.0 seconds).
2274
2211 usbhid.mousepoll= 2275 usbhid.mousepoll=
2212 [USBHID] The interval which mice are to be polled at. 2276 [USBHID] The interval which mice are to be polled at.
2213 2277
diff --git a/Documentation/kobject.txt b/Documentation/kobject.txt
index 51a8021ee532..f5d2aad65a67 100644
--- a/Documentation/kobject.txt
+++ b/Documentation/kobject.txt
@@ -118,6 +118,10 @@ the name of the kobject, call kobject_rename():
118 118
119 int kobject_rename(struct kobject *kobj, const char *new_name); 119 int kobject_rename(struct kobject *kobj, const char *new_name);
120 120
121Note kobject_rename does perform any locking or have a solid notion of
122what names are valid so the provide must provide their own sanity checking
123and serialization.
124
121There is a function called kobject_set_name() but that is legacy cruft and 125There is a function called kobject_set_name() but that is legacy cruft and
122is being removed. If your code needs to call this function, it is 126is being removed. If your code needs to call this function, it is
123incorrect and needs to be fixed. 127incorrect and needs to be fixed.
diff --git a/Documentation/laptops/disk-shock-protection.txt b/Documentation/laptops/disk-shock-protection.txt
new file mode 100644
index 000000000000..0e6ba2663834
--- /dev/null
+++ b/Documentation/laptops/disk-shock-protection.txt
@@ -0,0 +1,149 @@
1Hard disk shock protection
2==========================
3
4Author: Elias Oltmanns <eo@nebensachen.de>
5Last modified: 2008-10-03
6
7
80. Contents
9-----------
10
111. Intro
122. The interface
133. References
144. CREDITS
15
16
171. Intro
18--------
19
20ATA/ATAPI-7 specifies the IDLE IMMEDIATE command with unload feature.
21Issuing this command should cause the drive to switch to idle mode and
22unload disk heads. This feature is being used in modern laptops in
23conjunction with accelerometers and appropriate software to implement
24a shock protection facility. The idea is to stop all I/O operations on
25the internal hard drive and park its heads on the ramp when critical
26situations are anticipated. The desire to have such a feature
27available on GNU/Linux systems has been the original motivation to
28implement a generic disk head parking interface in the Linux kernel.
29Please note, however, that other components have to be set up on your
30system in order to get disk shock protection working (see
31section 3. References below for pointers to more information about
32that).
33
34
352. The interface
36----------------
37
38For each ATA device, the kernel exports the file
39block/*/device/unload_heads in sysfs (here assumed to be mounted under
40/sys). Access to /sys/block/*/device/unload_heads is denied with
41-EOPNOTSUPP if the device does not support the unload feature.
42Otherwise, writing an integer value to this file will take the heads
43of the respective drive off the platter and block all I/O operations
44for the specified number of milliseconds. When the timeout expires and
45no further disk head park request has been issued in the meantime,
46normal operation will be resumed. The maximal value accepted for a
47timeout is 30000 milliseconds. Exceeding this limit will return
48-EOVERFLOW, but heads will be parked anyway and the timeout will be
49set to 30 seconds. However, you can always change a timeout to any
50value between 0 and 30000 by issuing a subsequent head park request
51before the timeout of the previous one has expired. In particular, the
52total timeout can exceed 30 seconds and, more importantly, you can
53cancel a previously set timeout and resume normal operation
54immediately by specifying a timeout of 0. Values below -2 are rejected
55with -EINVAL (see below for the special meaning of -1 and -2). If the
56timeout specified for a recent head park request has not yet expired,
57reading from /sys/block/*/device/unload_heads will report the number
58of milliseconds remaining until normal operation will be resumed;
59otherwise, reading the unload_heads attribute will return 0.
60
61For example, do the following in order to park the heads of drive
62/dev/sda and stop all I/O operations for five seconds:
63
64# echo 5000 > /sys/block/sda/device/unload_heads
65
66A simple
67
68# cat /sys/block/sda/device/unload_heads
69
70will show you how many milliseconds are left before normal operation
71will be resumed.
72
73A word of caution: The fact that the interface operates on a basis of
74milliseconds may raise expectations that cannot be satisfied in
75reality. In fact, the ATA specs clearly state that the time for an
76unload operation to complete is vendor specific. The hint in ATA-7
77that this will typically be within 500 milliseconds apparently has
78been dropped in ATA-8.
79
80There is a technical detail of this implementation that may cause some
81confusion and should be discussed here. When a head park request has
82been issued to a device successfully, all I/O operations on the
83controller port this device is attached to will be deferred. That is
84to say, any other device that may be connected to the same port will
85be affected too. The only exception is that a subsequent head unload
86request to that other device will be executed immediately. Further
87operations on that port will be deferred until the timeout specified
88for either device on the port has expired. As far as PATA (old style
89IDE) configurations are concerned, there can only be two devices
90attached to any single port. In SATA world we have port multipliers
91which means that a user-issued head parking request to one device may
92actually result in stopping I/O to a whole bunch of devices. However,
93since this feature is supposed to be used on laptops and does not seem
94to be very useful in any other environment, there will be mostly one
95device per port. Even if the CD/DVD writer happens to be connected to
96the same port as the hard drive, it generally *should* recover just
97fine from the occasional buffer under-run incurred by a head park
98request to the HD. Actually, when you are using an ide driver rather
99than its libata counterpart (i.e. your disk is called /dev/hda
100instead of /dev/sda), then parking the heads of one drive (drive X)
101will generally not affect the mode of operation of another drive
102(drive Y) on the same port as described above. It is only when a port
103reset is required to recover from an exception on drive Y that further
104I/O operations on that drive (and the reset itself) will be delayed
105until drive X is no longer in the parked state.
106
107Finally, there are some hard drives that only comply with an earlier
108version of the ATA standard than ATA-7, but do support the unload
109feature nonetheless. Unfortunately, there is no safe way Linux can
110detect these devices, so you won't be able to write to the
111unload_heads attribute. If you know that your device really does
112support the unload feature (for instance, because the vendor of your
113laptop or the hard drive itself told you so), then you can tell the
114kernel to enable the usage of this feature for that drive by writing
115the special value -1 to the unload_heads attribute:
116
117# echo -1 > /sys/block/sda/device/unload_heads
118
119will enable the feature for /dev/sda, and giving -2 instead of -1 will
120disable it again.
121
122
1233. References
124-------------
125
126There are several laptops from different vendors featuring shock
127protection capabilities. As manufacturers have refused to support open
128source development of the required software components so far, Linux
129support for shock protection varies considerably between different
130hardware implementations. Ideally, this section should contain a list
131of pointers at different projects aiming at an implementation of shock
132protection on different systems. Unfortunately, I only know of a
133single project which, although still considered experimental, is fit
134for use. Please feel free to add projects that have been the victims
135of my ignorance.
136
137- http://www.thinkwiki.org/wiki/HDAPS
138 See this page for information about Linux support of the hard disk
139 active protection system as implemented in IBM/Lenovo Thinkpads.
140
141
1424. CREDITS
143----------
144
145This implementation of disk head parking has been inspired by a patch
146originally published by Jon Escombe <lists@dresco.co.uk>. My efforts
147to develop an implementation of this feature that is fit to be merged
148into mainline have been aided by various kernel developers, in
149particular by Tejun Heo and Bartlomiej Zolnierkiewicz.
diff --git a/Documentation/networking/LICENSE.qlge b/Documentation/networking/LICENSE.qlge
new file mode 100644
index 000000000000..123b6edd7f18
--- /dev/null
+++ b/Documentation/networking/LICENSE.qlge
@@ -0,0 +1,46 @@
1Copyright (c) 2003-2008 QLogic Corporation
2QLogic Linux Networking HBA Driver
3
4This program includes a device driver for Linux 2.6 that may be
5distributed with QLogic hardware specific firmware binary file.
6You may modify and redistribute the device driver code under the
7GNU General Public License as published by the Free Software
8Foundation (version 2 or a later version).
9
10You may redistribute the hardware specific firmware binary file
11under the following terms:
12
13 1. Redistribution of source code (only if applicable),
14 must retain the above copyright notice, this list of
15 conditions and the following disclaimer.
16
17 2. Redistribution in binary form must reproduce the above
18 copyright notice, this list of conditions and the
19 following disclaimer in the documentation and/or other
20 materials provided with the distribution.
21
22 3. The name of QLogic Corporation may not be used to
23 endorse or promote products derived from this software
24 without specific prior written permission
25
26REGARDLESS OF WHAT LICENSING MECHANISM IS USED OR APPLICABLE,
27THIS PROGRAM IS PROVIDED BY QLOGIC CORPORATION "AS IS'' AND ANY
28EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
29IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
30PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR
31BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
32EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
33TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
34DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
35ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
36OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
37OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
38POSSIBILITY OF SUCH DAMAGE.
39
40USER ACKNOWLEDGES AND AGREES THAT USE OF THIS PROGRAM WILL NOT
41CREATE OR GIVE GROUNDS FOR A LICENSE BY IMPLICATION, ESTOPPEL, OR
42OTHERWISE IN ANY INTELLECTUAL PROPERTY RIGHTS (PATENT, COPYRIGHT,
43TRADE SECRET, MASK WORK, OR OTHER PROPRIETARY RIGHT) EMBODIED IN
44ANY OTHER QLOGIC HARDWARE OR SOFTWARE EITHER SOLELY OR IN
45COMBINATION WITH THIS PROGRAM.
46
diff --git a/Documentation/networking/can.txt b/Documentation/networking/can.txt
index 297ba7b1ccaf..2035bc4932f2 100644
--- a/Documentation/networking/can.txt
+++ b/Documentation/networking/can.txt
@@ -35,8 +35,9 @@ This file contains
35 6.1 general settings 35 6.1 general settings
36 6.2 local loopback of sent frames 36 6.2 local loopback of sent frames
37 6.3 CAN controller hardware filters 37 6.3 CAN controller hardware filters
38 6.4 currently supported CAN hardware 38 6.4 The virtual CAN driver (vcan)
39 6.5 todo 39 6.5 currently supported CAN hardware
40 6.6 todo
40 41
41 7 Credits 42 7 Credits
42 43
@@ -584,7 +585,42 @@ solution for a couple of reasons:
584 @133MHz with four SJA1000 CAN controllers from 2002 under heavy bus 585 @133MHz with four SJA1000 CAN controllers from 2002 under heavy bus
585 load without any problems ... 586 load without any problems ...
586 587
587 6.4 currently supported CAN hardware (September 2007) 588 6.4 The virtual CAN driver (vcan)
589
590 Similar to the network loopback devices, vcan offers a virtual local
591 CAN interface. A full qualified address on CAN consists of
592
593 - a unique CAN Identifier (CAN ID)
594 - the CAN bus this CAN ID is transmitted on (e.g. can0)
595
596 so in common use cases more than one virtual CAN interface is needed.
597
598 The virtual CAN interfaces allow the transmission and reception of CAN
599 frames without real CAN controller hardware. Virtual CAN network
600 devices are usually named 'vcanX', like vcan0 vcan1 vcan2 ...
601 When compiled as a module the virtual CAN driver module is called vcan.ko
602
603 Since Linux Kernel version 2.6.24 the vcan driver supports the Kernel
604 netlink interface to create vcan network devices. The creation and
605 removal of vcan network devices can be managed with the ip(8) tool:
606
607 - Create a virtual CAN network interface:
608 ip link add type vcan
609
610 - Create a virtual CAN network interface with a specific name 'vcan42':
611 ip link add dev vcan42 type vcan
612
613 - Remove a (virtual CAN) network interface 'vcan42':
614 ip link del vcan42
615
616 The tool 'vcan' from the SocketCAN SVN repository on BerliOS is obsolete.
617
618 Virtual CAN network device creation in older Kernels:
619 In Linux Kernel versions < 2.6.24 the vcan driver creates 4 vcan
620 netdevices at module load time by default. This value can be changed
621 with the module parameter 'numdev'. E.g. 'modprobe vcan numdev=8'
622
623 6.5 currently supported CAN hardware
588 624
589 On the project website http://developer.berlios.de/projects/socketcan 625 On the project website http://developer.berlios.de/projects/socketcan
590 there are different drivers available: 626 there are different drivers available:
@@ -603,7 +639,7 @@ solution for a couple of reasons:
603 639
604 Please check the Mailing Lists on the berlios OSS project website. 640 Please check the Mailing Lists on the berlios OSS project website.
605 641
606 6.5 todo (September 2007) 642 6.6 todo
607 643
608 The configuration interface for CAN network drivers is still an open 644 The configuration interface for CAN network drivers is still an open
609 issue that has not been finalized in the socketcan project. Also the 645 issue that has not been finalized in the socketcan project. Also the
diff --git a/Documentation/networking/cs89x0.txt b/Documentation/networking/cs89x0.txt
index 6387d3decf85..c725d33b316f 100644
--- a/Documentation/networking/cs89x0.txt
+++ b/Documentation/networking/cs89x0.txt
@@ -3,7 +3,7 @@ NOTE
3---- 3----
4 4
5This document was contributed by Cirrus Logic for kernel 2.2.5. This version 5This document was contributed by Cirrus Logic for kernel 2.2.5. This version
6has been updated for 2.3.48 by Andrew Morton <andrewm@uow.edu.au> 6has been updated for 2.3.48 by Andrew Morton.
7 7
8Cirrus make a copy of this driver available at their website, as 8Cirrus make a copy of this driver available at their website, as
9described below. In general, you should use the driver version which 9described below. In general, you should use the driver version which
@@ -690,7 +690,7 @@ latest drivers and technical publications.
6906.4 Current maintainer 6906.4 Current maintainer
691 691
692In February 2000 the maintenance of this driver was assumed by Andrew 692In February 2000 the maintenance of this driver was assumed by Andrew
693Morton <akpm@zip.com.au> 693Morton.
694 694
6956.5 Kernel module parameters 6956.5 Kernel module parameters
696 696
diff --git a/Documentation/networking/multiqueue.txt b/Documentation/networking/multiqueue.txt
index d391ea631141..4caa0e314cc2 100644
--- a/Documentation/networking/multiqueue.txt
+++ b/Documentation/networking/multiqueue.txt
@@ -24,4 +24,56 @@ netif_{start|stop|wake}_subqueue() functions to manage each queue while the
24device is still operational. netdev->queue_lock is still used when the device 24device is still operational. netdev->queue_lock is still used when the device
25comes online or when it's completely shut down (unregister_netdev(), etc.). 25comes online or when it's completely shut down (unregister_netdev(), etc.).
26 26
27Author: Peter P. Waskiewicz Jr. <peter.p.waskiewicz.jr@intel.com> 27
28Section 2: Qdisc support for multiqueue devices
29
30-----------------------------------------------
31
32Currently two qdiscs are optimized for multiqueue devices. The first is the
33default pfifo_fast qdisc. This qdisc supports one qdisc per hardware queue.
34A new round-robin qdisc, sch_multiq also supports multiple hardware queues. The
35qdisc is responsible for classifying the skb's and then directing the skb's to
36bands and queues based on the value in skb->queue_mapping. Use this field in
37the base driver to determine which queue to send the skb to.
38
39sch_multiq has been added for hardware that wishes to avoid head-of-line
40blocking. It will cycle though the bands and verify that the hardware queue
41associated with the band is not stopped prior to dequeuing a packet.
42
43On qdisc load, the number of bands is based on the number of queues on the
44hardware. Once the association is made, any skb with skb->queue_mapping set,
45will be queued to the band associated with the hardware queue.
46
47
48Section 3: Brief howto using MULTIQ for multiqueue devices
49---------------------------------------------------------------
50
51The userspace command 'tc,' part of the iproute2 package, is used to configure
52qdiscs. To add the MULTIQ qdisc to your network device, assuming the device
53is called eth0, run the following command:
54
55# tc qdisc add dev eth0 root handle 1: multiq
56
57The qdisc will allocate the number of bands to equal the number of queues that
58the device reports, and bring the qdisc online. Assuming eth0 has 4 Tx
59queues, the band mapping would look like:
60
61band 0 => queue 0
62band 1 => queue 1
63band 2 => queue 2
64band 3 => queue 3
65
66Traffic will begin flowing through each queue based on either the simple_tx_hash
67function or based on netdev->select_queue() if you have it defined.
68
69The behavior of tc filters remains the same. However a new tc action,
70skbedit, has been added. Assuming you wanted to route all traffic to a
71specific host, for example 192.168.0.3, through a specific queue you could use
72this action and establish a filter such as:
73
74tc filter add dev eth0 parent 1: protocol ip prio 1 u32 \
75 match ip dst 192.168.0.3 \
76 action skbedit queue_mapping 3
77
78Author: Alexander Duyck <alexander.h.duyck@intel.com>
79Original Author: Peter P. Waskiewicz Jr. <peter.p.waskiewicz.jr@intel.com>
diff --git a/Documentation/networking/phonet.txt b/Documentation/networking/phonet.txt
new file mode 100644
index 000000000000..6a07e45d4a93
--- /dev/null
+++ b/Documentation/networking/phonet.txt
@@ -0,0 +1,175 @@
1Linux Phonet protocol family
2============================
3
4Introduction
5------------
6
7Phonet is a packet protocol used by Nokia cellular modems for both IPC
8and RPC. With the Linux Phonet socket family, Linux host processes can
9receive and send messages from/to the modem, or any other external
10device attached to the modem. The modem takes care of routing.
11
12Phonet packets can be exchanged through various hardware connections
13depending on the device, such as:
14 - USB with the CDC Phonet interface,
15 - infrared,
16 - Bluetooth,
17 - an RS232 serial port (with a dedicated "FBUS" line discipline),
18 - the SSI bus with some TI OMAP processors.
19
20
21Packets format
22--------------
23
24Phonet packets have a common header as follows:
25
26 struct phonethdr {
27 uint8_t pn_media; /* Media type (link-layer identifier) */
28 uint8_t pn_rdev; /* Receiver device ID */
29 uint8_t pn_sdev; /* Sender device ID */
30 uint8_t pn_res; /* Resource ID or function */
31 uint16_t pn_length; /* Big-endian message byte length (minus 6) */
32 uint8_t pn_robj; /* Receiver object ID */
33 uint8_t pn_sobj; /* Sender object ID */
34 };
35
36On Linux, the link-layer header includes the pn_media byte (see below).
37The next 7 bytes are part of the network-layer header.
38
39The device ID is split: the 6 higher-order bits consitute the device
40address, while the 2 lower-order bits are used for multiplexing, as are
41the 8-bit object identifiers. As such, Phonet can be considered as a
42network layer with 6 bits of address space and 10 bits for transport
43protocol (much like port numbers in IP world).
44
45The modem always has address number zero. All other device have a their
46own 6-bit address.
47
48
49Link layer
50----------
51
52Phonet links are always point-to-point links. The link layer header
53consists of a single Phonet media type byte. It uniquely identifies the
54link through which the packet is transmitted, from the modem's
55perspective. Each Phonet network device shall prepend and set the media
56type byte as appropriate. For convenience, a common phonet_header_ops
57link-layer header operations structure is provided. It sets the
58media type according to the network device hardware address.
59
60Linux Phonet network interfaces support a dedicated link layer packets
61type (ETH_P_PHONET) which is out of the Ethernet type range. They can
62only send and receive Phonet packets.
63
64The virtual TUN tunnel device driver can also be used for Phonet. This
65requires IFF_TUN mode, _without_ the IFF_NO_PI flag. In this case,
66there is no link-layer header, so there is no Phonet media type byte.
67
68Note that Phonet interfaces are not allowed to re-order packets, so
69only the (default) Linux FIFO qdisc should be used with them.
70
71
72Network layer
73-------------
74
75The Phonet socket address family maps the Phonet packet header:
76
77 struct sockaddr_pn {
78 sa_family_t spn_family; /* AF_PHONET */
79 uint8_t spn_obj; /* Object ID */
80 uint8_t spn_dev; /* Device ID */
81 uint8_t spn_resource; /* Resource or function */
82 uint8_t spn_zero[...]; /* Padding */
83 };
84
85The resource field is only used when sending and receiving;
86It is ignored by bind() and getsockname().
87
88
89Low-level datagram protocol
90---------------------------
91
92Applications can send Phonet messages using the Phonet datagram socket
93protocol from the PF_PHONET family. Each socket is bound to one of the
942^10 object IDs available, and can send and receive packets with any
95other peer.
96
97 struct sockaddr_pn addr = { .spn_family = AF_PHONET, };
98 ssize_t len;
99 socklen_t addrlen = sizeof(addr);
100 int fd;
101
102 fd = socket(PF_PHONET, SOCK_DGRAM, 0);
103 bind(fd, (struct sockaddr *)&addr, sizeof(addr));
104 /* ... */
105
106 sendto(fd, msg, msglen, 0, (struct sockaddr *)&addr, sizeof(addr));
107 len = recvfrom(fd, buf, sizeof(buf), 0,
108 (struct sockaddr *)&addr, &addrlen);
109
110This protocol follows the SOCK_DGRAM connection-less semantics.
111However, connect() and getpeername() are not supported, as they did
112not seem useful with Phonet usages (could be added easily).
113
114
115Phonet Pipe protocol
116--------------------
117
118The Phonet Pipe protocol is a simple sequenced packets protocol
119with end-to-end congestion control. It uses the passive listening
120socket paradigm. The listening socket is bound to an unique free object
121ID. Each listening socket can handle up to 255 simultaneous
122connections, one per accept()'d socket.
123
124 int lfd, cfd;
125
126 lfd = socket(PF_PHONET, SOCK_SEQPACKET, PN_PROTO_PIPE);
127 listen (lfd, INT_MAX);
128
129 /* ... */
130 cfd = accept(lfd, NULL, NULL);
131 for (;;)
132 {
133 char buf[...];
134 ssize_t len = read(cfd, buf, sizeof(buf));
135
136 /* ... */
137
138 write(cfd, msg, msglen);
139 }
140
141Connections are established between two endpoints by a "third party"
142application. This means that both endpoints are passive; so connect()
143is not possible.
144
145WARNING:
146When polling a connected pipe socket for writability, there is an
147intrinsic race condition whereby writability might be lost between the
148polling and the writing system calls. In this case, the socket will
149block until write becomes possible again, unless non-blocking mode
150is enabled.
151
152
153The pipe protocol provides two socket options at the SOL_PNPIPE level:
154
155 PNPIPE_ENCAP accepts one integer value (int) of:
156
157 PNPIPE_ENCAP_NONE: The socket operates normally (default).
158
159 PNPIPE_ENCAP_IP: The socket is used as a backend for a virtual IP
160 interface. This requires CAP_NET_ADMIN capability. GPRS data
161 support on Nokia modems can use this. Note that the socket cannot
162 be reliably poll()'d or read() from while in this mode.
163
164 PNPIPE_IFINDEX is a read-only integer value. It contains the
165 interface index of the network interface created by PNPIPE_ENCAP,
166 or zero if encapsulation is off.
167
168
169Authors
170-------
171
172Linux Phonet was initially written by Sakari Ailus.
173Other contributors include Mikä Liljeberg, Andras Domokos,
174Carlos Chinea and Rémi Denis-Courmont.
175Copyright (C) 2008 Nokia Corporation.
diff --git a/Documentation/networking/regulatory.txt b/Documentation/networking/regulatory.txt
new file mode 100644
index 000000000000..a96989a8ff35
--- /dev/null
+++ b/Documentation/networking/regulatory.txt
@@ -0,0 +1,194 @@
1Linux wireless regulatory documentation
2---------------------------------------
3
4This document gives a brief review over how the Linux wireless
5regulatory infrastructure works.
6
7More up to date information can be obtained at the project's web page:
8
9http://wireless.kernel.org/en/developers/Regulatory
10
11Keeping regulatory domains in userspace
12---------------------------------------
13
14Due to the dynamic nature of regulatory domains we keep them
15in userspace and provide a framework for userspace to upload
16to the kernel one regulatory domain to be used as the central
17core regulatory domain all wireless devices should adhere to.
18
19How to get regulatory domains to the kernel
20-------------------------------------------
21
22Userspace gets a regulatory domain in the kernel by having
23a userspace agent build it and send it via nl80211. Only
24expected regulatory domains will be respected by the kernel.
25
26A currently available userspace agent which can accomplish this
27is CRDA - central regulatory domain agent. Its documented here:
28
29http://wireless.kernel.org/en/developers/Regulatory/CRDA
30
31Essentially the kernel will send a udev event when it knows
32it needs a new regulatory domain. A udev rule can be put in place
33to trigger crda to send the respective regulatory domain for a
34specific ISO/IEC 3166 alpha2.
35
36Below is an example udev rule which can be used:
37
38# Example file, should be put in /etc/udev/rules.d/regulatory.rules
39KERNEL=="regulatory*", ACTION=="change", SUBSYSTEM=="platform", RUN+="/sbin/crda"
40
41The alpha2 is passed as an environment variable under the variable COUNTRY.
42
43Who asks for regulatory domains?
44--------------------------------
45
46* Users
47
48Users can use iw:
49
50http://wireless.kernel.org/en/users/Documentation/iw
51
52An example:
53
54 # set regulatory domain to "Costa Rica"
55 iw reg set CR
56
57This will request the kernel to set the regulatory domain to
58the specificied alpha2. The kernel in turn will then ask userspace
59to provide a regulatory domain for the alpha2 specified by the user
60by sending a uevent.
61
62* Wireless subsystems for Country Information elements
63
64The kernel will send a uevent to inform userspace a new
65regulatory domain is required. More on this to be added
66as its integration is added.
67
68* Drivers
69
70If drivers determine they need a specific regulatory domain
71set they can inform the wireless core using regulatory_hint().
72They have two options -- they either provide an alpha2 so that
73crda can provide back a regulatory domain for that country or
74they can build their own regulatory domain based on internal
75custom knowledge so the wireless core can respect it.
76
77*Most* drivers will rely on the first mechanism of providing a
78regulatory hint with an alpha2. For these drivers there is an additional
79check that can be used to ensure compliance based on custom EEPROM
80regulatory data. This additional check can be used by drivers by
81registering on its struct wiphy a reg_notifier() callback. This notifier
82is called when the core's regulatory domain has been changed. The driver
83can use this to review the changes made and also review who made them
84(driver, user, country IE) and determine what to allow based on its
85internal EEPROM data. Devices drivers wishing to be capable of world
86roaming should use this callback. More on world roaming will be
87added to this document when its support is enabled.
88
89Device drivers who provide their own built regulatory domain
90do not need a callback as the channels registered by them are
91the only ones that will be allowed and therefore *additional*
92cannels cannot be enabled.
93
94Example code - drivers hinting an alpha2:
95------------------------------------------
96
97This example comes from the zd1211rw device driver. You can start
98by having a mapping of your device's EEPROM country/regulatory
99domain value to to a specific alpha2 as follows:
100
101static struct zd_reg_alpha2_map reg_alpha2_map[] = {
102 { ZD_REGDOMAIN_FCC, "US" },
103 { ZD_REGDOMAIN_IC, "CA" },
104 { ZD_REGDOMAIN_ETSI, "DE" }, /* Generic ETSI, use most restrictive */
105 { ZD_REGDOMAIN_JAPAN, "JP" },
106 { ZD_REGDOMAIN_JAPAN_ADD, "JP" },
107 { ZD_REGDOMAIN_SPAIN, "ES" },
108 { ZD_REGDOMAIN_FRANCE, "FR" },
109
110Then you can define a routine to map your read EEPROM value to an alpha2,
111as follows:
112
113static int zd_reg2alpha2(u8 regdomain, char *alpha2)
114{
115 unsigned int i;
116 struct zd_reg_alpha2_map *reg_map;
117 for (i = 0; i < ARRAY_SIZE(reg_alpha2_map); i++) {
118 reg_map = &reg_alpha2_map[i];
119 if (regdomain == reg_map->reg) {
120 alpha2[0] = reg_map->alpha2[0];
121 alpha2[1] = reg_map->alpha2[1];
122 return 0;
123 }
124 }
125 return 1;
126}
127
128Lastly, you can then hint to the core of your discovered alpha2, if a match
129was found. You need to do this after you have registered your wiphy. You
130are expected to do this during initialization.
131
132 r = zd_reg2alpha2(mac->regdomain, alpha2);
133 if (!r)
134 regulatory_hint(hw->wiphy, alpha2, NULL);
135
136Example code - drivers providing a built in regulatory domain:
137--------------------------------------------------------------
138
139If you have regulatory information you can obtain from your
140driver and you *need* to use this we let you build a regulatory domain
141structure and pass it to the wireless core. To do this you should
142kmalloc() a structure big enough to hold your regulatory domain
143structure and you should then fill it with your data. Finally you simply
144call regulatory_hint() with the regulatory domain structure in it.
145
146Bellow is a simple example, with a regulatory domain cached using the stack.
147Your implementation may vary (read EEPROM cache instead, for example).
148
149Example cache of some regulatory domain
150
151struct ieee80211_regdomain mydriver_jp_regdom = {
152 .n_reg_rules = 3,
153 .alpha2 = "JP",
154 //.alpha2 = "99", /* If I have no alpha2 to map it to */
155 .reg_rules = {
156 /* IEEE 802.11b/g, channels 1..14 */
157 REG_RULE(2412-20, 2484+20, 40, 6, 20, 0),
158 /* IEEE 802.11a, channels 34..48 */
159 REG_RULE(5170-20, 5240+20, 40, 6, 20,
160 NL80211_RRF_PASSIVE_SCAN),
161 /* IEEE 802.11a, channels 52..64 */
162 REG_RULE(5260-20, 5320+20, 40, 6, 20,
163 NL80211_RRF_NO_IBSS |
164 NL80211_RRF_DFS),
165 }
166};
167
168Then in some part of your code after your wiphy has been registered:
169
170 int r;
171 struct ieee80211_regdomain *rd;
172 int size_of_regd;
173 int num_rules = mydriver_jp_regdom.n_reg_rules;
174 unsigned int i;
175
176 size_of_regd = sizeof(struct ieee80211_regdomain) +
177 (num_rules * sizeof(struct ieee80211_reg_rule));
178
179 rd = kzalloc(size_of_regd, GFP_KERNEL);
180 if (!rd)
181 return -ENOMEM;
182
183 memcpy(rd, &mydriver_jp_regdom, sizeof(struct ieee80211_regdomain));
184
185 for (i=0; i < num_rules; i++) {
186 memcpy(&rd->reg_rules[i], &mydriver_jp_regdom.reg_rules[i],
187 sizeof(struct ieee80211_reg_rule));
188 }
189 r = regulatory_hint(hw->wiphy, NULL, rd);
190 if (r) {
191 kfree(rd);
192 return r;
193 }
194
diff --git a/Documentation/networking/tproxy.txt b/Documentation/networking/tproxy.txt
new file mode 100644
index 000000000000..7b5996d9357e
--- /dev/null
+++ b/Documentation/networking/tproxy.txt
@@ -0,0 +1,85 @@
1Transparent proxy support
2=========================
3
4This feature adds Linux 2.2-like transparent proxy support to current kernels.
5To use it, enable NETFILTER_TPROXY, the socket match and the TPROXY target in
6your kernel config. You will need policy routing too, so be sure to enable that
7as well.
8
9
101. Making non-local sockets work
11================================
12
13The idea is that you identify packets with destination address matching a local
14socket on your box, set the packet mark to a certain value, and then match on that
15value using policy routing to have those packets delivered locally:
16
17# iptables -t mangle -N DIVERT
18# iptables -t mangle -A PREROUTING -p tcp -m socket -j DIVERT
19# iptables -t mangle -A DIVERT -j MARK --set-mark 1
20# iptables -t mangle -A DIVERT -j ACCEPT
21
22# ip rule add fwmark 1 lookup 100
23# ip route add local 0.0.0.0/0 dev lo table 100
24
25Because of certain restrictions in the IPv4 routing output code you'll have to
26modify your application to allow it to send datagrams _from_ non-local IP
27addresses. All you have to do is enable the (SOL_IP, IP_TRANSPARENT) socket
28option before calling bind:
29
30fd = socket(AF_INET, SOCK_STREAM, 0);
31/* - 8< -*/
32int value = 1;
33setsockopt(fd, SOL_IP, IP_TRANSPARENT, &value, sizeof(value));
34/* - 8< -*/
35name.sin_family = AF_INET;
36name.sin_port = htons(0xCAFE);
37name.sin_addr.s_addr = htonl(0xDEADBEEF);
38bind(fd, &name, sizeof(name));
39
40A trivial patch for netcat is available here:
41http://people.netfilter.org/hidden/tproxy/netcat-ip_transparent-support.patch
42
43
442. Redirecting traffic
45======================
46
47Transparent proxying often involves "intercepting" traffic on a router. This is
48usually done with the iptables REDIRECT target; however, there are serious
49limitations of that method. One of the major issues is that it actually
50modifies the packets to change the destination address -- which might not be
51acceptable in certain situations. (Think of proxying UDP for example: you won't
52be able to find out the original destination address. Even in case of TCP
53getting the original destination address is racy.)
54
55The 'TPROXY' target provides similar functionality without relying on NAT. Simply
56add rules like this to the iptables ruleset above:
57
58# iptables -t mangle -A PREROUTING -p tcp --dport 80 -j TPROXY \
59 --tproxy-mark 0x1/0x1 --on-port 50080
60
61Note that for this to work you'll have to modify the proxy to enable (SOL_IP,
62IP_TRANSPARENT) for the listening socket.
63
64
653. Iptables extensions
66======================
67
68To use tproxy you'll need to have the 'socket' and 'TPROXY' modules
69compiled for iptables. A patched version of iptables is available
70here: http://git.balabit.hu/?p=bazsi/iptables-tproxy.git
71
72
734. Application support
74======================
75
764.1. Squid
77----------
78
79Squid 3.HEAD has support built-in. To use it, pass
80'--enable-linux-netfilter' to configure and set the 'tproxy' option on
81the HTTP listener you redirect traffic to with the TPROXY iptables
82target.
83
84For more information please consult the following page on the Squid
85wiki: http://wiki.squid-cache.org/Features/Tproxy4
diff --git a/Documentation/networking/vortex.txt b/Documentation/networking/vortex.txt
index 6356d3faed36..bd70976b8160 100644
--- a/Documentation/networking/vortex.txt
+++ b/Documentation/networking/vortex.txt
@@ -1,5 +1,5 @@
1Documentation/networking/vortex.txt 1Documentation/networking/vortex.txt
2Andrew Morton <andrewm@uow.edu.au> 2Andrew Morton
330 April 2000 330 April 2000
4 4
5 5
@@ -11,7 +11,7 @@ The driver was written by Donald Becker <becker@scyld.com>
11Don is no longer the prime maintainer of this version of the driver. 11Don is no longer the prime maintainer of this version of the driver.
12Please report problems to one or more of: 12Please report problems to one or more of:
13 13
14 Andrew Morton <akpm@osdl.org> 14 Andrew Morton
15 Netdev mailing list <netdev@vger.kernel.org> 15 Netdev mailing list <netdev@vger.kernel.org>
16 Linux kernel mailing list <linux-kernel@vger.kernel.org> 16 Linux kernel mailing list <linux-kernel@vger.kernel.org>
17 17
@@ -305,11 +305,6 @@ Donald's wake-on-LAN page:
305 305
306 ftp://ftp.3com.com/pub/nic/3c90x/3c90xx2.exe 306 ftp://ftp.3com.com/pub/nic/3c90x/3c90xx2.exe
307 307
308Driver updates and a detailed changelog for the modifications which
309were made for the 2.3/2,4 series kernel is available at
310
311 http://www.zip.com.au/~akpm/linux/#3c59x-bc
312
313 308
314Autonegotiation notes 309Autonegotiation notes
315--------------------- 310---------------------
diff --git a/Documentation/pcmcia/driver-changes.txt b/Documentation/pcmcia/driver-changes.txt
index 96f155e68750..059934363caf 100644
--- a/Documentation/pcmcia/driver-changes.txt
+++ b/Documentation/pcmcia/driver-changes.txt
@@ -1,5 +1,11 @@
1This file details changes in 2.6 which affect PCMCIA card driver authors: 1This file details changes in 2.6 which affect PCMCIA card driver authors:
2 2
3* New configuration loop helper (as of 2.6.28)
4 By calling pcmcia_loop_config(), a driver can iterate over all available
5 configuration options. During a driver's probe() phase, one doesn't need
6 to use pcmcia_get_{first,next}_tuple, pcmcia_get_tuple_data and
7 pcmcia_parse_tuple directly in most if not all cases.
8
3* New release helper (as of 2.6.17) 9* New release helper (as of 2.6.17)
4 Instead of calling pcmcia_release_{configuration,io,irq,win}, all that's 10 Instead of calling pcmcia_release_{configuration,io,irq,win}, all that's
5 necessary now is calling pcmcia_disable_device. As there is no valid 11 necessary now is calling pcmcia_disable_device. As there is no valid
diff --git a/Documentation/power/regulator/machine.txt b/Documentation/power/regulator/machine.txt
index c9a35665cf70..ce3487d99abe 100644
--- a/Documentation/power/regulator/machine.txt
+++ b/Documentation/power/regulator/machine.txt
@@ -2,17 +2,8 @@ Regulator Machine Driver Interface
2=================================== 2===================================
3 3
4The regulator machine driver interface is intended for board/machine specific 4The regulator machine driver interface is intended for board/machine specific
5initialisation code to configure the regulator subsystem. Typical things that 5initialisation code to configure the regulator subsystem.
6machine drivers would do are :-
7 6
8 1. Regulator -> Device mapping.
9 2. Regulator supply configuration.
10 3. Power Domain constraint setting.
11
12
13
141. Regulator -> device mapping
15==============================
16Consider the following machine :- 7Consider the following machine :-
17 8
18 Regulator-1 -+-> Regulator-2 --> [Consumer A @ 1.8 - 2.0V] 9 Regulator-1 -+-> Regulator-2 --> [Consumer A @ 1.8 - 2.0V]
@@ -21,81 +12,82 @@ Consider the following machine :-
21 12
22The drivers for consumers A & B must be mapped to the correct regulator in 13The drivers for consumers A & B must be mapped to the correct regulator in
23order to control their power supply. This mapping can be achieved in machine 14order to control their power supply. This mapping can be achieved in machine
24initialisation code by calling :- 15initialisation code by creating a struct regulator_consumer_supply for
16each regulator.
17
18struct regulator_consumer_supply {
19 struct device *dev; /* consumer */
20 const char *supply; /* consumer supply - e.g. "vcc" */
21};
25 22
26int regulator_set_device_supply(const char *regulator, struct device *dev, 23e.g. for the machine above
27 const char *supply);
28 24
29and is shown with the following code :- 25static struct regulator_consumer_supply regulator1_consumers[] = {
26{
27 .dev = &platform_consumerB_device.dev,
28 .supply = "Vcc",
29},};
30 30
31regulator_set_device_supply("Regulator-1", devB, "Vcc"); 31static struct regulator_consumer_supply regulator2_consumers[] = {
32regulator_set_device_supply("Regulator-2", devA, "Vcc"); 32{
33 .dev = &platform_consumerA_device.dev,
34 .supply = "Vcc",
35},};
33 36
34This maps Regulator-1 to the 'Vcc' supply for Consumer B and maps Regulator-2 37This maps Regulator-1 to the 'Vcc' supply for Consumer B and maps Regulator-2
35to the 'Vcc' supply for Consumer A. 38to the 'Vcc' supply for Consumer A.
36 39
37 40Constraints can now be registered by defining a struct regulator_init_data
382. Regulator supply configuration. 41for each regulator power domain. This structure also maps the consumers
39================================== 42to their supply regulator :-
40Consider the following machine (again) :- 43
41 44static struct regulator_init_data regulator1_data = {
42 Regulator-1 -+-> Regulator-2 --> [Consumer A @ 1.8 - 2.0V] 45 .constraints = {
43 | 46 .min_uV = 3300000,
44 +-> [Consumer B @ 3.3V] 47 .max_uV = 3300000,
48 .valid_modes_mask = REGULATOR_MODE_NORMAL,
49 },
50 .num_consumer_supplies = ARRAY_SIZE(regulator1_consumers),
51 .consumer_supplies = regulator1_consumers,
52};
45 53
46Regulator-1 supplies power to Regulator-2. This relationship must be registered 54Regulator-1 supplies power to Regulator-2. This relationship must be registered
47with the core so that Regulator-1 is also enabled when Consumer A enables it's 55with the core so that Regulator-1 is also enabled when Consumer A enables it's
48supply (Regulator-2). 56supply (Regulator-2). The supply regulator is set by the supply_regulator_dev
49 57field below:-
50This relationship can be register with the core via :- 58
51 59static struct regulator_init_data regulator2_data = {
52int regulator_set_supply(const char *regulator, const char *regulator_supply); 60 .supply_regulator_dev = &platform_regulator1_device.dev,
53 61 .constraints = {
54In this example we would use the following code :- 62 .min_uV = 1800000,
55 63 .max_uV = 2000000,
56regulator_set_supply("Regulator-2", "Regulator-1"); 64 .valid_ops_mask = REGULATOR_CHANGE_VOLTAGE,
57 65 .valid_modes_mask = REGULATOR_MODE_NORMAL,
58Relationships can be queried by calling :- 66 },
59 67 .num_consumer_supplies = ARRAY_SIZE(regulator2_consumers),
60const char *regulator_get_supply(const char *regulator); 68 .consumer_supplies = regulator2_consumers,
61
62
633. Power Domain constraint setting.
64===================================
65Each power domain within a system has physical constraints on voltage and
66current. This must be defined in software so that the power domain is always
67operated within specifications.
68
69Consider the following machine (again) :-
70
71 Regulator-1 -+-> Regulator-2 --> [Consumer A @ 1.8 - 2.0V]
72 |
73 +-> [Consumer B @ 3.3V]
74
75This gives us two regulators and two power domains:
76
77 Domain 1: Regulator-2, Consumer B.
78 Domain 2: Consumer A.
79
80Constraints can be registered by calling :-
81
82int regulator_set_platform_constraints(const char *regulator,
83 struct regulation_constraints *constraints);
84
85The example is defined as follows :-
86
87struct regulation_constraints domain_1 = {
88 .min_uV = 3300000,
89 .max_uV = 3300000,
90 .valid_modes_mask = REGULATOR_MODE_NORMAL,
91}; 69};
92 70
93struct regulation_constraints domain_2 = { 71Finally the regulator devices must be registered in the usual manner.
94 .min_uV = 1800000, 72
95 .max_uV = 2000000, 73static struct platform_device regulator_devices[] = {
96 .valid_ops_mask = REGULATOR_CHANGE_VOLTAGE, 74{
97 .valid_modes_mask = REGULATOR_MODE_NORMAL, 75 .name = "regulator",
76 .id = DCDC_1,
77 .dev = {
78 .platform_data = &regulator1_data,
79 },
80},
81{
82 .name = "regulator",
83 .id = DCDC_2,
84 .dev = {
85 .platform_data = &regulator2_data,
86 },
87},
98}; 88};
89/* register regulator 1 device */
90platform_device_register(&wm8350_regulator_devices[0]);
99 91
100regulator_set_platform_constraints("Regulator-1", &domain_1); 92/* register regulator 2 device */
101regulator_set_platform_constraints("Regulator-2", &domain_2); 93platform_device_register(&wm8350_regulator_devices[1]);
diff --git a/Documentation/power/regulator/regulator.txt b/Documentation/power/regulator/regulator.txt
index a69050143592..4200accb9bba 100644
--- a/Documentation/power/regulator/regulator.txt
+++ b/Documentation/power/regulator/regulator.txt
@@ -10,11 +10,11 @@ Registration
10 10
11Drivers can register a regulator by calling :- 11Drivers can register a regulator by calling :-
12 12
13struct regulator_dev *regulator_register(struct regulator_desc *regulator_desc, 13struct regulator_dev *regulator_register(struct device *dev,
14 void *reg_data); 14 struct regulator_desc *regulator_desc);
15 15
16This will register the regulators capabilities and operations the regulator 16This will register the regulators capabilities and operations to the regulator
17core. The core does not touch reg_data (private to regulator driver). 17core.
18 18
19Regulators can be unregistered by calling :- 19Regulators can be unregistered by calling :-
20 20
diff --git a/Documentation/power/s2ram.txt b/Documentation/power/s2ram.txt
index b05f512130ea..2ebdc6091ce1 100644
--- a/Documentation/power/s2ram.txt
+++ b/Documentation/power/s2ram.txt
@@ -54,3 +54,21 @@ used to run with "radeonfb" (it's an ATI Radeon mobility). It turns out
54that "radeonfb" simply cannot resume that device - it tries to set the 54that "radeonfb" simply cannot resume that device - it tries to set the
55PLL's, and it just _hangs_. Using the regular VGA console and letting X 55PLL's, and it just _hangs_. Using the regular VGA console and letting X
56resume it instead works fine. 56resume it instead works fine.
57
58NOTE
59====
60pm_trace uses the system's Real Time Clock (RTC) to save the magic number.
61Reason for this is that the RTC is the only reliably available piece of
62hardware during resume operations where a value can be set that will
63survive a reboot.
64
65Consequence is that after a resume (even if it is successful) your system
66clock will have a value corresponding to the magic mumber instead of the
67correct date/time! It is therefore advisable to use a program like ntp-date
68or rdate to reset the correct date/time from an external time source when
69using this trace option.
70
71As the clock keeps ticking it is also essential that the reboot is done
72quickly after the resume failure. The trace option does not use the seconds
73or the low order bits of the minutes of the RTC, but a too long delay will
74corrupt the magic value.
diff --git a/Documentation/powerpc/00-INDEX b/Documentation/powerpc/00-INDEX
index 29d839ce7327..e3960b8c8689 100644
--- a/Documentation/powerpc/00-INDEX
+++ b/Documentation/powerpc/00-INDEX
@@ -18,10 +18,6 @@ mpc52xx.txt
18 - Linux 2.6.x on MPC52xx family 18 - Linux 2.6.x on MPC52xx family
19mpc52xx-device-tree-bindings.txt 19mpc52xx-device-tree-bindings.txt
20 - MPC5200 Device Tree Bindings 20 - MPC5200 Device Tree Bindings
21ppc_htab.txt
22 - info about the Linux/PPC /proc/ppc_htab entry
23smp.txt
24 - use and state info about Linux/PPC on MP machines
25sound.txt 21sound.txt
26 - info on sound support under Linux/PPC 22 - info on sound support under Linux/PPC
27zImage_layout.txt 23zImage_layout.txt
diff --git a/Documentation/powerpc/dts-bindings/fsl/83xx-512x-pci.txt b/Documentation/powerpc/dts-bindings/fsl/83xx-512x-pci.txt
new file mode 100644
index 000000000000..35a465362408
--- /dev/null
+++ b/Documentation/powerpc/dts-bindings/fsl/83xx-512x-pci.txt
@@ -0,0 +1,40 @@
1* Freescale 83xx and 512x PCI bridges
2
3Freescale 83xx and 512x SOCs include the same pci bridge core.
4
583xx/512x specific notes:
6- reg: should contain two address length tuples
7 The first is for the internal pci bridge registers
8 The second is for the pci config space access registers
9
10Example (MPC8313ERDB)
11 pci0: pci@e0008500 {
12 cell-index = <1>;
13 interrupt-map-mask = <0xf800 0x0 0x0 0x7>;
14 interrupt-map = <
15 /* IDSEL 0x0E -mini PCI */
16 0x7000 0x0 0x0 0x1 &ipic 18 0x8
17 0x7000 0x0 0x0 0x2 &ipic 18 0x8
18 0x7000 0x0 0x0 0x3 &ipic 18 0x8
19 0x7000 0x0 0x0 0x4 &ipic 18 0x8
20
21 /* IDSEL 0x0F - PCI slot */
22 0x7800 0x0 0x0 0x1 &ipic 17 0x8
23 0x7800 0x0 0x0 0x2 &ipic 18 0x8
24 0x7800 0x0 0x0 0x3 &ipic 17 0x8
25 0x7800 0x0 0x0 0x4 &ipic 18 0x8>;
26 interrupt-parent = <&ipic>;
27 interrupts = <66 0x8>;
28 bus-range = <0x0 0x0>;
29 ranges = <0x02000000 0x0 0x90000000 0x90000000 0x0 0x10000000
30 0x42000000 0x0 0x80000000 0x80000000 0x0 0x10000000
31 0x01000000 0x0 0x00000000 0xe2000000 0x0 0x00100000>;
32 clock-frequency = <66666666>;
33 #interrupt-cells = <1>;
34 #size-cells = <2>;
35 #address-cells = <3>;
36 reg = <0xe0008500 0x100 /* internal registers */
37 0xe0008300 0x8>; /* config space access registers */
38 compatible = "fsl,mpc8349-pci";
39 device_type = "pci";
40 };
diff --git a/Documentation/powerpc/dts-bindings/fsl/8xxx_gpio.txt b/Documentation/powerpc/dts-bindings/fsl/8xxx_gpio.txt
new file mode 100644
index 000000000000..d015dcec4011
--- /dev/null
+++ b/Documentation/powerpc/dts-bindings/fsl/8xxx_gpio.txt
@@ -0,0 +1,40 @@
1GPIO controllers on MPC8xxx SoCs
2
3This is for the non-QE/CPM/GUTs GPIO controllers as found on
48349, 8572, 8610 and compatible.
5
6Every GPIO controller node must have #gpio-cells property defined,
7this information will be used to translate gpio-specifiers.
8
9Required properties:
10- compatible : "fsl,<CHIP>-gpio" followed by "fsl,mpc8349-gpio" for
11 83xx, "fsl,mpc8572-gpio" for 85xx and "fsl,mpc8610-gpio" for 86xx.
12- #gpio-cells : Should be two. The first cell is the pin number and the
13 second cell is used to specify optional parameters (currently unused).
14 - interrupts : Interrupt mapping for GPIO IRQ (currently unused).
15 - interrupt-parent : Phandle for the interrupt controller that
16 services interrupts for this device.
17- gpio-controller : Marks the port as GPIO controller.
18
19Example of gpio-controller nodes for a MPC8347 SoC:
20
21 gpio1: gpio-controller@c00 {
22 #gpio-cells = <2>;
23 compatible = "fsl,mpc8347-gpio", "fsl,mpc8349-gpio";
24 reg = <0xc00 0x100>;
25 interrupts = <74 0x8>;
26 interrupt-parent = <&ipic>;
27 gpio-controller;
28 };
29
30 gpio2: gpio-controller@d00 {
31 #gpio-cells = <2>;
32 compatible = "fsl,mpc8347-gpio", "fsl,mpc8349-gpio";
33 reg = <0xd00 0x100>;
34 interrupts = <75 0x8>;
35 interrupt-parent = <&ipic>;
36 gpio-controller;
37 };
38
39See booting-without-of.txt for details of how to specify GPIO
40information for devices.
diff --git a/Documentation/powerpc/dts-bindings/fsl/dma.txt b/Documentation/powerpc/dts-bindings/fsl/dma.txt
index 86826df00e64..cc453110fc46 100644
--- a/Documentation/powerpc/dts-bindings/fsl/dma.txt
+++ b/Documentation/powerpc/dts-bindings/fsl/dma.txt
@@ -20,7 +20,7 @@ Required properties:
20 - compatible : compatible list, contains 2 entries, first is 20 - compatible : compatible list, contains 2 entries, first is
21 "fsl,CHIP-dma-channel", where CHIP is the processor 21 "fsl,CHIP-dma-channel", where CHIP is the processor
22 (mpc8349, mpc8350, etc.) and the second is 22 (mpc8349, mpc8350, etc.) and the second is
23 "fsl,elo-dma-channel" 23 "fsl,elo-dma-channel". However, see note below.
24 - reg : <registers mapping for channel> 24 - reg : <registers mapping for channel>
25 - cell-index : dma channel index starts at 0. 25 - cell-index : dma channel index starts at 0.
26 26
@@ -82,7 +82,7 @@ Required properties:
82 - compatible : compatible list, contains 2 entries, first is 82 - compatible : compatible list, contains 2 entries, first is
83 "fsl,CHIP-dma-channel", where CHIP is the processor 83 "fsl,CHIP-dma-channel", where CHIP is the processor
84 (mpc8540, mpc8560, etc.) and the second is 84 (mpc8540, mpc8560, etc.) and the second is
85 "fsl,eloplus-dma-channel" 85 "fsl,eloplus-dma-channel". However, see note below.
86 - cell-index : dma channel index starts at 0. 86 - cell-index : dma channel index starts at 0.
87 - reg : <registers mapping for channel> 87 - reg : <registers mapping for channel>
88 - interrupts : <interrupt mapping for DMA channel IRQ> 88 - interrupts : <interrupt mapping for DMA channel IRQ>
@@ -125,3 +125,12 @@ Example:
125 interrupts = <17 2>; 125 interrupts = <17 2>;
126 }; 126 };
127 }; 127 };
128
129Note on DMA channel compatible properties: The compatible property must say
130"fsl,elo-dma-channel" or "fsl,eloplus-dma-channel" to be used by the Elo DMA
131driver (fsldma). Any DMA channel used by fsldma cannot be used by another
132DMA driver, such as the SSI sound drivers for the MPC8610. Therefore, any DMA
133channel that should be used for another driver should not use
134"fsl,elo-dma-channel" or "fsl,eloplus-dma-channel". For the SSI drivers, for
135example, the compatible property should be "fsl,ssi-dma-channel". See ssi.txt
136for more information.
diff --git a/Documentation/powerpc/dts-bindings/fsl/ssi.txt b/Documentation/powerpc/dts-bindings/fsl/ssi.txt
index d100555d488a..a2d963998a65 100644
--- a/Documentation/powerpc/dts-bindings/fsl/ssi.txt
+++ b/Documentation/powerpc/dts-bindings/fsl/ssi.txt
@@ -24,6 +24,12 @@ Required properties:
24 "rj-master" - r.j., SSI is clock master 24 "rj-master" - r.j., SSI is clock master
25 "ac97-slave" - AC97 mode, SSI is clock slave 25 "ac97-slave" - AC97 mode, SSI is clock slave
26 "ac97-master" - AC97 mode, SSI is clock master 26 "ac97-master" - AC97 mode, SSI is clock master
27- fsl,playback-dma: phandle to a node for the DMA channel to use for
28 playback of audio. This is typically dictated by SOC
29 design. See the notes below.
30- fsl,capture-dma: phandle to a node for the DMA channel to use for
31 capture (recording) of audio. This is typically dictated
32 by SOC design. See the notes below.
27 33
28Optional properties: 34Optional properties:
29- codec-handle : phandle to a 'codec' node that defines an audio 35- codec-handle : phandle to a 'codec' node that defines an audio
@@ -36,3 +42,20 @@ Child 'codec' node required properties:
36Child 'codec' node optional properties: 42Child 'codec' node optional properties:
37- clock-frequency : The frequency of the input clock, which typically 43- clock-frequency : The frequency of the input clock, which typically
38 comes from an on-board dedicated oscillator. 44 comes from an on-board dedicated oscillator.
45
46Notes on fsl,playback-dma and fsl,capture-dma:
47
48On SOCs that have an SSI, specific DMA channels are hard-wired for playback
49and capture. On the MPC8610, for example, SSI1 must use DMA channel 0 for
50playback and DMA channel 1 for capture. SSI2 must use DMA channel 2 for
51playback and DMA channel 3 for capture. The developer can choose which
52DMA controller to use, but the channels themselves are hard-wired. The
53purpose of these two properties is to represent this hardware design.
54
55The device tree nodes for the DMA channels that are referenced by
56"fsl,playback-dma" and "fsl,capture-dma" must be marked as compatible with
57"fsl,ssi-dma-channel". The SOC-specific compatible string (e.g.
58"fsl,mpc8610-dma-channel") can remain. If these nodes are left as
59"fsl,elo-dma-channel" or "fsl,eloplus-dma-channel", then the generic Elo DMA
60drivers (fsldma) will attempt to use them, and it will conflict with the
61sound drivers.
diff --git a/Documentation/powerpc/ppc_htab.txt b/Documentation/powerpc/ppc_htab.txt
deleted file mode 100644
index 8b8c7df29fa9..000000000000
--- a/Documentation/powerpc/ppc_htab.txt
+++ /dev/null
@@ -1,118 +0,0 @@
1 Information about /proc/ppc_htab
2=====================================================================
3
4This document and the related code was written by me (Cort Dougan), please
5email me (cort@fsmlabs.com) if you have questions, comments or corrections.
6
7Last Change: 2.16.98
8
9This entry in the proc directory is readable by all users but only
10writable by root.
11
12The ppc_htab interface is a user level way of accessing the
13performance monitoring registers as well as providing information
14about the PTE hash table.
15
161. Reading
17
18 Reading this file will give you information about the memory management
19 hash table that serves as an extended tlb for page translation on the
20 powerpc. It will also give you information about performance measurement
21 specific to the cpu that you are using.
22
23 Explanation of the 604 Performance Monitoring Fields:
24 MMCR0 - the current value of the MMCR0 register
25 PMC1
26 PMC2 - the value of the performance counters and a
27 description of what events they are counting
28 which are based on MMCR0 bit settings.
29 Explanation of the PTE Hash Table fields:
30
31 Size - hash table size in Kb.
32 Buckets - number of buckets in the table.
33 Address - the virtual kernel address of the hash table base.
34 Entries - the number of ptes that can be stored in the hash table.
35 User/Kernel - how many pte's are in use by the kernel or user at that time.
36 Overflows - How many of the entries are in their secondary hash location.
37 Percent full - ratio of free pte entries to in use entries.
38 Reloads - Count of how many hash table misses have occurred
39 that were fixed with a reload from the linux tables.
40 Should always be 0 on 603 based machines.
41 Non-error Misses - Count of how many hash table misses have occurred
42 that were completed with the creation of a pte in the linux
43 tables with a call to do_page_fault().
44 Error Misses - Number of misses due to errors such as bad address
45 and permission violations. This includes kernel access of
46 bad user addresses that are fixed up by the trap handler.
47
48 Note that calculation of the data displayed from /proc/ppc_htab takes
49 a long time and spends a great deal of time in the kernel. It would
50 be quite hard on performance to read this file constantly. In time
51 there may be a counter in the kernel that allows successive reads from
52 this file only after a given amount of time has passed to reduce the
53 possibility of a user slowing the system by reading this file.
54
552. Writing
56
57 Writing to the ppc_htab allows you to change the characteristics of
58 the powerpc PTE hash table and setup performance monitoring.
59
60 Resizing the PTE hash table is not enabled right now due to many
61 complications with moving the hash table, rehashing the entries
62 and many many SMP issues that would have to be dealt with.
63
64 Write options to ppc_htab:
65
66 - To set the size of the hash table to 64Kb:
67
68 echo 'size 64' > /proc/ppc_htab
69
70 The size must be a multiple of 64 and must be greater than or equal to
71 64.
72
73 - To turn off performance monitoring:
74
75 echo 'off' > /proc/ppc_htab
76
77 - To reset the counters without changing what they're counting:
78
79 echo 'reset' > /proc/ppc_htab
80
81 Note that counting will continue after the reset if it is enabled.
82
83 - To count only events in user mode or only in kernel mode:
84
85 echo 'user' > /proc/ppc_htab
86 ...or...
87 echo 'kernel' > /proc/ppc_htab
88
89 Note that these two options are exclusive of one another and the
90 lack of either of these options counts user and kernel.
91 Using 'reset' and 'off' reset these flags.
92
93 - The 604 has 2 performance counters which can each count events from
94 a specific set of events. These sets are disjoint so it is not
95 possible to count _any_ combination of 2 events. One event can
96 be counted by PMC1 and one by PMC2.
97
98 To start counting a particular event use:
99
100 echo 'event' > /proc/ppc_htab
101
102 and choose from these events:
103
104 PMC1
105 ----
106 'ic miss' - instruction cache misses
107 'dtlb' - data tlb misses (not hash table misses)
108
109 PMC2
110 ----
111 'dc miss' - data cache misses
112 'itlb' - instruction tlb misses (not hash table misses)
113 'load miss time' - cycles to complete a load miss
114
1153. Bugs
116
117 The PMC1 and PMC2 counters can overflow and give no indication of that
118 in /proc/ppc_htab.
diff --git a/Documentation/powerpc/smp.txt b/Documentation/powerpc/smp.txt
deleted file mode 100644
index 5b581b849ff7..000000000000
--- a/Documentation/powerpc/smp.txt
+++ /dev/null
@@ -1,34 +0,0 @@
1 Information about Linux/PPC SMP mode
2=====================================================================
3
4This document and the related code was written by me
5(Cort Dougan, cort@fsmlabs.com) please email me if you have questions,
6comments or corrections.
7
8Last Change: 3.31.99
9
10If you want to help by writing code or testing different hardware please
11email me!
12
131. State of Supported Hardware
14
15 PowerSurge Architecture - tested on UMAX s900, Apple 9600
16 The second processor on this machine boots up just fine and
17 enters its idle loop. Hopefully a completely working SMP kernel
18 on this machine will be done shortly.
19
20 The code makes the assumption of only two processors. The changes
21 necessary to work with any number would not be overly difficult but
22 I don't have any machines with >2 processors so it's not high on my
23 list of priorities. If anyone else would like do to the work email
24 me and I can point out the places that need changed. If you have >2
25 processors and don't want to add support yourself let me know and I
26 can take a look into it.
27
28 BeBox
29 BeBox support hasn't been added to the 2.1.X kernels from 2.0.X
30 but work is being done and SMP support for BeBox is in the works.
31
32 CHRP
33 CHRP SMP works and is fairly solid. It's been tested on the IBM F50
34 with 4 processors for quite some time now.
diff --git a/Documentation/rfkill.txt b/Documentation/rfkill.txt
index 6fcb3060dec5..b65f0799df48 100644
--- a/Documentation/rfkill.txt
+++ b/Documentation/rfkill.txt
@@ -341,6 +341,8 @@ key that does nothing by itself, as well as any hot key that is type-specific
3413.1 Guidelines for wireless device drivers 3413.1 Guidelines for wireless device drivers
342------------------------------------------ 342------------------------------------------
343 343
344(in this text, rfkill->foo means the foo field of struct rfkill).
345
3441. Each independent transmitter in a wireless device (usually there is only one 3461. Each independent transmitter in a wireless device (usually there is only one
345transmitter per device) should have a SINGLE rfkill class attached to it. 347transmitter per device) should have a SINGLE rfkill class attached to it.
346 348
@@ -363,10 +365,32 @@ This rule exists because users of the rfkill subsystem expect to get (and set,
363when possible) the overall transmitter rfkill state, not of a particular rfkill 365when possible) the overall transmitter rfkill state, not of a particular rfkill
364line. 366line.
365 367
3665. During suspend, the rfkill class will attempt to soft-block the radio 3685. The wireless device driver MUST NOT leave the transmitter enabled during
367through a call to rfkill->toggle_radio, and will try to restore its previous 369suspend and hibernation unless:
368state during resume. After a rfkill class is suspended, it will *not* call 370
369rfkill->toggle_radio until it is resumed. 371 5.1. The transmitter has to be enabled for some sort of functionality
372 like wake-on-wireless-packet or autonomous packed forwarding in a mesh
373 network, and that functionality is enabled for this suspend/hibernation
374 cycle.
375
376AND
377
378 5.2. The device was not on a user-requested BLOCKED state before
379 the suspend (i.e. the driver must NOT unblock a device, not even
380 to support wake-on-wireless-packet or remain in the mesh).
381
382In other words, there is absolutely no allowed scenario where a driver can
383automatically take action to unblock a rfkill controller (obviously, this deals
384with scenarios where soft-blocking or both soft and hard blocking is happening.
385Scenarios where hardware rfkill lines are the only ones blocking the
386transmitter are outside of this rule, since the wireless device driver does not
387control its input hardware rfkill lines in the first place).
388
3896. During resume, rfkill will try to restore its previous state.
390
3917. After a rfkill class is suspended, it will *not* call rfkill->toggle_radio
392until it is resumed.
393
370 394
371Example of a WLAN wireless driver connected to the rfkill subsystem: 395Example of a WLAN wireless driver connected to the rfkill subsystem:
372-------------------------------------------------------------------- 396--------------------------------------------------------------------
diff --git a/Documentation/s390/CommonIO b/Documentation/s390/CommonIO
index bf0baa19ec24..339207d11d95 100644
--- a/Documentation/s390/CommonIO
+++ b/Documentation/s390/CommonIO
@@ -70,13 +70,19 @@ Command line parameters
70 70
71 Note: While already known devices can be added to the list of devices to be 71 Note: While already known devices can be added to the list of devices to be
72 ignored, there will be no effect on then. However, if such a device 72 ignored, there will be no effect on then. However, if such a device
73 disappears and then reappears, it will then be ignored. 73 disappears and then reappears, it will then be ignored. To make
74 known devices go away, you need the "purge" command (see below).
74 75
75 For example, 76 For example,
76 "echo add 0.0.a000-0.0.accc, 0.0.af00-0.0.afff > /proc/cio_ignore" 77 "echo add 0.0.a000-0.0.accc, 0.0.af00-0.0.afff > /proc/cio_ignore"
77 will add 0.0.a000-0.0.accc and 0.0.af00-0.0.afff to the list of ignored 78 will add 0.0.a000-0.0.accc and 0.0.af00-0.0.afff to the list of ignored
78 devices. 79 devices.
79 80
81 You can remove already known but now ignored devices via
82 "echo purge > /proc/cio_ignore"
83 All devices ignored but still registered and not online (= not in use)
84 will be deregistered and thus removed from the system.
85
80 The devices can be specified either by bus id (0.x.abcd) or, for 2.4 backward 86 The devices can be specified either by bus id (0.x.abcd) or, for 2.4 backward
81 compatibility, by the device number in hexadecimal (0xabcd or abcd). Device 87 compatibility, by the device number in hexadecimal (0xabcd or abcd). Device
82 numbers given as 0xabcd will be interpreted as 0.0.abcd. 88 numbers given as 0xabcd will be interpreted as 0.0.abcd.
@@ -98,8 +104,7 @@ debugfs entries
98 handling). 104 handling).
99 105
100 - /sys/kernel/debug/s390dbf/cio_msg/sprintf 106 - /sys/kernel/debug/s390dbf/cio_msg/sprintf
101 Various debug messages from the common I/O-layer, including messages 107 Various debug messages from the common I/O-layer.
102 printed when cio_msg=yes.
103 108
104 - /sys/kernel/debug/s390dbf/cio_trace/hex_ascii 109 - /sys/kernel/debug/s390dbf/cio_trace/hex_ascii
105 Logs the calling of functions in the common I/O-layer and, if applicable, 110 Logs the calling of functions in the common I/O-layer and, if applicable,
diff --git a/Documentation/scheduler/sched-design-CFS.txt b/Documentation/scheduler/sched-design-CFS.txt
index 88bcb8767335..9d8eb553884c 100644
--- a/Documentation/scheduler/sched-design-CFS.txt
+++ b/Documentation/scheduler/sched-design-CFS.txt
@@ -1,151 +1,242 @@
1 =============
2 CFS Scheduler
3 =============
1 4
2This is the CFS scheduler.
3
480% of CFS's design can be summed up in a single sentence: CFS basically
5models an "ideal, precise multi-tasking CPU" on real hardware.
6
7"Ideal multi-tasking CPU" is a (non-existent :-)) CPU that has 100%
8physical power and which can run each task at precise equal speed, in
9parallel, each at 1/nr_running speed. For example: if there are 2 tasks
10running then it runs each at 50% physical power - totally in parallel.
11
12On real hardware, we can run only a single task at once, so while that
13one task runs, the other tasks that are waiting for the CPU are at a
14disadvantage - the current task gets an unfair amount of CPU time. In
15CFS this fairness imbalance is expressed and tracked via the per-task
16p->wait_runtime (nanosec-unit) value. "wait_runtime" is the amount of
17time the task should now run on the CPU for it to become completely fair
18and balanced.
19
20( small detail: on 'ideal' hardware, the p->wait_runtime value would
21 always be zero - no task would ever get 'out of balance' from the
22 'ideal' share of CPU time. )
23
24CFS's task picking logic is based on this p->wait_runtime value and it
25is thus very simple: it always tries to run the task with the largest
26p->wait_runtime value. In other words, CFS tries to run the task with
27the 'gravest need' for more CPU time. So CFS always tries to split up
28CPU time between runnable tasks as close to 'ideal multitasking
29hardware' as possible.
30
31Most of the rest of CFS's design just falls out of this really simple
32concept, with a few add-on embellishments like nice levels,
33multiprocessing and various algorithm variants to recognize sleepers.
34
35In practice it works like this: the system runs a task a bit, and when
36the task schedules (or a scheduler tick happens) the task's CPU usage is
37'accounted for': the (small) time it just spent using the physical CPU
38is deducted from p->wait_runtime. [minus the 'fair share' it would have
39gotten anyway]. Once p->wait_runtime gets low enough so that another
40task becomes the 'leftmost task' of the time-ordered rbtree it maintains
41(plus a small amount of 'granularity' distance relative to the leftmost
42task so that we do not over-schedule tasks and trash the cache) then the
43new leftmost task is picked and the current task is preempted.
44
45The rq->fair_clock value tracks the 'CPU time a runnable task would have
46fairly gotten, had it been runnable during that time'. So by using
47rq->fair_clock values we can accurately timestamp and measure the
48'expected CPU time' a task should have gotten. All runnable tasks are
49sorted in the rbtree by the "rq->fair_clock - p->wait_runtime" key, and
50CFS picks the 'leftmost' task and sticks to it. As the system progresses
51forwards, newly woken tasks are put into the tree more and more to the
52right - slowly but surely giving a chance for every task to become the
53'leftmost task' and thus get on the CPU within a deterministic amount of
54time.
55
56Some implementation details:
57
58 - the introduction of Scheduling Classes: an extensible hierarchy of
59 scheduler modules. These modules encapsulate scheduling policy
60 details and are handled by the scheduler core without the core
61 code assuming about them too much.
62
63 - sched_fair.c implements the 'CFS desktop scheduler': it is a
64 replacement for the vanilla scheduler's SCHED_OTHER interactivity
65 code.
66
67 I'd like to give credit to Con Kolivas for the general approach here:
68 he has proven via RSDL/SD that 'fair scheduling' is possible and that
69 it results in better desktop scheduling. Kudos Con!
70
71 The CFS patch uses a completely different approach and implementation
72 from RSDL/SD. My goal was to make CFS's interactivity quality exceed
73 that of RSDL/SD, which is a high standard to meet :-) Testing
74 feedback is welcome to decide this one way or another. [ and, in any
75 case, all of SD's logic could be added via a kernel/sched_sd.c module
76 as well, if Con is interested in such an approach. ]
77
78 CFS's design is quite radical: it does not use runqueues, it uses a
79 time-ordered rbtree to build a 'timeline' of future task execution,
80 and thus has no 'array switch' artifacts (by which both the vanilla
81 scheduler and RSDL/SD are affected).
82
83 CFS uses nanosecond granularity accounting and does not rely on any
84 jiffies or other HZ detail. Thus the CFS scheduler has no notion of
85 'timeslices' and has no heuristics whatsoever. There is only one
86 central tunable (you have to switch on CONFIG_SCHED_DEBUG):
87
88 /proc/sys/kernel/sched_granularity_ns
89
90 which can be used to tune the scheduler from 'desktop' (low
91 latencies) to 'server' (good batching) workloads. It defaults to a
92 setting suitable for desktop workloads. SCHED_BATCH is handled by the
93 CFS scheduler module too.
94
95 Due to its design, the CFS scheduler is not prone to any of the
96 'attacks' that exist today against the heuristics of the stock
97 scheduler: fiftyp.c, thud.c, chew.c, ring-test.c, massive_intr.c all
98 work fine and do not impact interactivity and produce the expected
99 behavior.
100
101 the CFS scheduler has a much stronger handling of nice levels and
102 SCHED_BATCH: both types of workloads should be isolated much more
103 agressively than under the vanilla scheduler.
104
105 ( another detail: due to nanosec accounting and timeline sorting,
106 sched_yield() support is very simple under CFS, and in fact under
107 CFS sched_yield() behaves much better than under any other
108 scheduler i have tested so far. )
109
110 - sched_rt.c implements SCHED_FIFO and SCHED_RR semantics, in a simpler
111 way than the vanilla scheduler does. It uses 100 runqueues (for all
112 100 RT priority levels, instead of 140 in the vanilla scheduler)
113 and it needs no expired array.
114
115 - reworked/sanitized SMP load-balancing: the runqueue-walking
116 assumptions are gone from the load-balancing code now, and
117 iterators of the scheduling modules are used. The balancing code got
118 quite a bit simpler as a result.
119
120
121Group scheduler extension to CFS
122================================
123
124Normally the scheduler operates on individual tasks and strives to provide
125fair CPU time to each task. Sometimes, it may be desirable to group tasks
126and provide fair CPU time to each such task group. For example, it may
127be desirable to first provide fair CPU time to each user on the system
128and then to each task belonging to a user.
129
130CONFIG_FAIR_GROUP_SCHED strives to achieve exactly that. It lets
131SCHED_NORMAL/BATCH tasks be be grouped and divides CPU time fairly among such
132groups. At present, there are two (mutually exclusive) mechanisms to group
133tasks for CPU bandwidth control purpose:
134
135 - Based on user id (CONFIG_FAIR_USER_SCHED)
136 In this option, tasks are grouped according to their user id.
137 - Based on "cgroup" pseudo filesystem (CONFIG_FAIR_CGROUP_SCHED)
138 This options lets the administrator create arbitrary groups
139 of tasks, using the "cgroup" pseudo filesystem. See
140 Documentation/cgroups.txt for more information about this
141 filesystem.
142 5
143Only one of these options to group tasks can be chosen and not both. 61. OVERVIEW
7
8CFS stands for "Completely Fair Scheduler," and is the new "desktop" process
9scheduler implemented by Ingo Molnar and merged in Linux 2.6.23. It is the
10replacement for the previous vanilla scheduler's SCHED_OTHER interactivity
11code.
12
1380% of CFS's design can be summed up in a single sentence: CFS basically models
14an "ideal, precise multi-tasking CPU" on real hardware.
15
16"Ideal multi-tasking CPU" is a (non-existent :-)) CPU that has 100% physical
17power and which can run each task at precise equal speed, in parallel, each at
181/nr_running speed. For example: if there are 2 tasks running, then it runs
19each at 50% physical power --- i.e., actually in parallel.
20
21On real hardware, we can run only a single task at once, so we have to
22introduce the concept of "virtual runtime." The virtual runtime of a task
23specifies when its next timeslice would start execution on the ideal
24multi-tasking CPU described above. In practice, the virtual runtime of a task
25is its actual runtime normalized to the total number of running tasks.
26
27
28
292. FEW IMPLEMENTATION DETAILS
30
31In CFS the virtual runtime is expressed and tracked via the per-task
32p->se.vruntime (nanosec-unit) value. This way, it's possible to accurately
33timestamp and measure the "expected CPU time" a task should have gotten.
34
35[ small detail: on "ideal" hardware, at any time all tasks would have the same
36 p->se.vruntime value --- i.e., tasks would execute simultaneously and no task
37 would ever get "out of balance" from the "ideal" share of CPU time. ]
38
39CFS's task picking logic is based on this p->se.vruntime value and it is thus
40very simple: it always tries to run the task with the smallest p->se.vruntime
41value (i.e., the task which executed least so far). CFS always tries to split
42up CPU time between runnable tasks as close to "ideal multitasking hardware" as
43possible.
44
45Most of the rest of CFS's design just falls out of this really simple concept,
46with a few add-on embellishments like nice levels, multiprocessing and various
47algorithm variants to recognize sleepers.
48
49
50
513. THE RBTREE
52
53CFS's design is quite radical: it does not use the old data structures for the
54runqueues, but it uses a time-ordered rbtree to build a "timeline" of future
55task execution, and thus has no "array switch" artifacts (by which both the
56previous vanilla scheduler and RSDL/SD are affected).
57
58CFS also maintains the rq->cfs.min_vruntime value, which is a monotonic
59increasing value tracking the smallest vruntime among all tasks in the
60runqueue. The total amount of work done by the system is tracked using
61min_vruntime; that value is used to place newly activated entities on the left
62side of the tree as much as possible.
63
64The total number of running tasks in the runqueue is accounted through the
65rq->cfs.load value, which is the sum of the weights of the tasks queued on the
66runqueue.
67
68CFS maintains a time-ordered rbtree, where all runnable tasks are sorted by the
69p->se.vruntime key (there is a subtraction using rq->cfs.min_vruntime to
70account for possible wraparounds). CFS picks the "leftmost" task from this
71tree and sticks to it.
72As the system progresses forwards, the executed tasks are put into the tree
73more and more to the right --- slowly but surely giving a chance for every task
74to become the "leftmost task" and thus get on the CPU within a deterministic
75amount of time.
76
77Summing up, CFS works like this: it runs a task a bit, and when the task
78schedules (or a scheduler tick happens) the task's CPU usage is "accounted
79for": the (small) time it just spent using the physical CPU is added to
80p->se.vruntime. Once p->se.vruntime gets high enough so that another task
81becomes the "leftmost task" of the time-ordered rbtree it maintains (plus a
82small amount of "granularity" distance relative to the leftmost task so that we
83do not over-schedule tasks and trash the cache), then the new leftmost task is
84picked and the current task is preempted.
85
86
87
884. SOME FEATURES OF CFS
89
90CFS uses nanosecond granularity accounting and does not rely on any jiffies or
91other HZ detail. Thus the CFS scheduler has no notion of "timeslices" in the
92way the previous scheduler had, and has no heuristics whatsoever. There is
93only one central tunable (you have to switch on CONFIG_SCHED_DEBUG):
94
95 /proc/sys/kernel/sched_granularity_ns
96
97which can be used to tune the scheduler from "desktop" (i.e., low latencies) to
98"server" (i.e., good batching) workloads. It defaults to a setting suitable
99for desktop workloads. SCHED_BATCH is handled by the CFS scheduler module too.
100
101Due to its design, the CFS scheduler is not prone to any of the "attacks" that
102exist today against the heuristics of the stock scheduler: fiftyp.c, thud.c,
103chew.c, ring-test.c, massive_intr.c all work fine and do not impact
104interactivity and produce the expected behavior.
105
106The CFS scheduler has a much stronger handling of nice levels and SCHED_BATCH
107than the previous vanilla scheduler: both types of workloads are isolated much
108more aggressively.
109
110SMP load-balancing has been reworked/sanitized: the runqueue-walking
111assumptions are gone from the load-balancing code now, and iterators of the
112scheduling modules are used. The balancing code got quite a bit simpler as a
113result.
114
115
116
1175. Scheduling policies
118
119CFS implements three scheduling policies:
120
121 - SCHED_NORMAL (traditionally called SCHED_OTHER): The scheduling
122 policy that is used for regular tasks.
123
124 - SCHED_BATCH: Does not preempt nearly as often as regular tasks
125 would, thereby allowing tasks to run longer and make better use of
126 caches but at the cost of interactivity. This is well suited for
127 batch jobs.
128
129 - SCHED_IDLE: This is even weaker than nice 19, but its not a true
130 idle timer scheduler in order to avoid to get into priority
131 inversion problems which would deadlock the machine.
132
133SCHED_FIFO/_RR are implemented in sched_rt.c and are as specified by
134POSIX.
135
136The command chrt from util-linux-ng 2.13.1.1 can set all of these except
137SCHED_IDLE.
144 138
145Group scheduler tunables:
146 139
147When CONFIG_FAIR_USER_SCHED is defined, a directory is created in sysfs for 140
148each new user and a "cpu_share" file is added in that directory. 1416. SCHEDULING CLASSES
142
143The new CFS scheduler has been designed in such a way to introduce "Scheduling
144Classes," an extensible hierarchy of scheduler modules. These modules
145encapsulate scheduling policy details and are handled by the scheduler core
146without the core code assuming too much about them.
147
148sched_fair.c implements the CFS scheduler described above.
149
150sched_rt.c implements SCHED_FIFO and SCHED_RR semantics, in a simpler way than
151the previous vanilla scheduler did. It uses 100 runqueues (for all 100 RT
152priority levels, instead of 140 in the previous scheduler) and it needs no
153expired array.
154
155Scheduling classes are implemented through the sched_class structure, which
156contains hooks to functions that must be called whenever an interesting event
157occurs.
158
159This is the (partial) list of the hooks:
160
161 - enqueue_task(...)
162
163 Called when a task enters a runnable state.
164 It puts the scheduling entity (task) into the red-black tree and
165 increments the nr_running variable.
166
167 - dequeue_tree(...)
168
169 When a task is no longer runnable, this function is called to keep the
170 corresponding scheduling entity out of the red-black tree. It decrements
171 the nr_running variable.
172
173 - yield_task(...)
174
175 This function is basically just a dequeue followed by an enqueue, unless the
176 compat_yield sysctl is turned on; in that case, it places the scheduling
177 entity at the right-most end of the red-black tree.
178
179 - check_preempt_curr(...)
180
181 This function checks if a task that entered the runnable state should
182 preempt the currently running task.
183
184 - pick_next_task(...)
185
186 This function chooses the most appropriate task eligible to run next.
187
188 - set_curr_task(...)
189
190 This function is called when a task changes its scheduling class or changes
191 its task group.
192
193 - task_tick(...)
194
195 This function is mostly called from time tick functions; it might lead to
196 process switch. This drives the running preemption.
197
198 - task_new(...)
199
200 The core scheduler gives the scheduling module an opportunity to manage new
201 task startup. The CFS scheduling module uses it for group scheduling, while
202 the scheduling module for a real-time task does not use it.
203
204
205
2067. GROUP SCHEDULER EXTENSIONS TO CFS
207
208Normally, the scheduler operates on individual tasks and strives to provide
209fair CPU time to each task. Sometimes, it may be desirable to group tasks and
210provide fair CPU time to each such task group. For example, it may be
211desirable to first provide fair CPU time to each user on the system and then to
212each task belonging to a user.
213
214CONFIG_GROUP_SCHED strives to achieve exactly that. It lets tasks to be
215grouped and divides CPU time fairly among such groups.
216
217CONFIG_RT_GROUP_SCHED permits to group real-time (i.e., SCHED_FIFO and
218SCHED_RR) tasks.
219
220CONFIG_FAIR_GROUP_SCHED permits to group CFS (i.e., SCHED_NORMAL and
221SCHED_BATCH) tasks.
222
223At present, there are two (mutually exclusive) mechanisms to group tasks for
224CPU bandwidth control purposes:
225
226 - Based on user id (CONFIG_USER_SCHED)
227
228 With this option, tasks are grouped according to their user id.
229
230 - Based on "cgroup" pseudo filesystem (CONFIG_CGROUP_SCHED)
231
232 This options needs CONFIG_CGROUPS to be defined, and lets the administrator
233 create arbitrary groups of tasks, using the "cgroup" pseudo filesystem. See
234 Documentation/cgroups.txt for more information about this filesystem.
235
236Only one of these options to group tasks can be chosen and not both.
237
238When CONFIG_USER_SCHED is defined, a directory is created in sysfs for each new
239user and a "cpu_share" file is added in that directory.
149 240
150 # cd /sys/kernel/uids 241 # cd /sys/kernel/uids
151 # cat 512/cpu_share # Display user 512's CPU share 242 # cat 512/cpu_share # Display user 512's CPU share
@@ -155,16 +246,14 @@ each new user and a "cpu_share" file is added in that directory.
155 2048 246 2048
156 # 247 #
157 248
158CPU bandwidth between two users are divided in the ratio of their CPU shares. 249CPU bandwidth between two users is divided in the ratio of their CPU shares.
159For ex: if you would like user "root" to get twice the bandwidth of user 250For example: if you would like user "root" to get twice the bandwidth of user
160"guest", then set the cpu_share for both the users such that "root"'s 251"guest," then set the cpu_share for both the users such that "root"'s cpu_share
161cpu_share is twice "guest"'s cpu_share 252is twice "guest"'s cpu_share.
162
163 253
164When CONFIG_FAIR_CGROUP_SCHED is defined, a "cpu.shares" file is created 254When CONFIG_CGROUP_SCHED is defined, a "cpu.shares" file is created for each
165for each group created using the pseudo filesystem. See example steps 255group created using the pseudo filesystem. See example steps below to create
166below to create task groups and modify their CPU share using the "cgroups" 256task groups and modify their CPU share using the "cgroups" pseudo filesystem.
167pseudo filesystem
168 257
169 # mkdir /dev/cpuctl 258 # mkdir /dev/cpuctl
170 # mount -t cgroup -ocpu none /dev/cpuctl 259 # mount -t cgroup -ocpu none /dev/cpuctl
diff --git a/Documentation/scsi/ChangeLog.megaraid b/Documentation/scsi/ChangeLog.megaraid
index 37796fe45bd0..eaa4801f2ce6 100644
--- a/Documentation/scsi/ChangeLog.megaraid
+++ b/Documentation/scsi/ChangeLog.megaraid
@@ -409,7 +409,7 @@ i. Function reordering so that inline functions are defined before they
409 megaraid_mbox_prepare_pthru, megaraid_mbox_prepare_epthru, 409 megaraid_mbox_prepare_pthru, megaraid_mbox_prepare_epthru,
410 megaraid_busywait_mbox 410 megaraid_busywait_mbox
411 411
412 - Andrew Morton <akpm@osdl.org>, 08.19.2004 412 - Andrew Morton, 08.19.2004
413 linux-scsi mailing list 413 linux-scsi mailing list
414 414
415 "Something else to clean up after inclusion: every instance of an 415 "Something else to clean up after inclusion: every instance of an
@@ -471,13 +471,13 @@ vi. Add support for 64-bit applications. Current drivers assume only
471vii. Move the function declarations for the management module from 471vii. Move the function declarations for the management module from
472 megaraid_mm.h to megaraid_mm.c 472 megaraid_mm.h to megaraid_mm.c
473 473
474 - Andrew Morton <akpm@osdl.org>, 08.19.2004 474 - Andrew Morton, 08.19.2004
475 linux-scsi mailing list 475 linux-scsi mailing list
476 476
477viii. Change default values for MEGARAID_NEWGEN, MEGARAID_MM, and 477viii. Change default values for MEGARAID_NEWGEN, MEGARAID_MM, and
478 MEGARAID_MAILBOX to 'n' in Kconfig.megaraid 478 MEGARAID_MAILBOX to 'n' in Kconfig.megaraid
479 479
480 - Andrew Morton <akpm@osdl.org>, 08.19.2004 480 - Andrew Morton, 08.19.2004
481 linux-scsi mailing list 481 linux-scsi mailing list
482 482
483ix. replace udelay with msleep 483ix. replace udelay with msleep
diff --git a/Documentation/scsi/scsi_fc_transport.txt b/Documentation/scsi/scsi_fc_transport.txt
index 75143f0c23b6..38d324d62b25 100644
--- a/Documentation/scsi/scsi_fc_transport.txt
+++ b/Documentation/scsi/scsi_fc_transport.txt
@@ -436,6 +436,42 @@ Other:
436 was updated to remove all vports for the fc_host as well. 436 was updated to remove all vports for the fc_host as well.
437 437
438 438
439Transport supplied functions
440----------------------------
441
442The following functions are supplied by the FC-transport for use by LLDs.
443
444 fc_vport_create - create a vport
445 fc_vport_terminate - detach and remove a vport
446
447Details:
448
449/**
450 * fc_vport_create - Admin App or LLDD requests creation of a vport
451 * @shost: scsi host the virtual port is connected to.
452 * @ids: The world wide names, FC4 port roles, etc for
453 * the virtual port.
454 *
455 * Notes:
456 * This routine assumes no locks are held on entry.
457 */
458struct fc_vport *
459fc_vport_create(struct Scsi_Host *shost, struct fc_vport_identifiers *ids)
460
461/**
462 * fc_vport_terminate - Admin App or LLDD requests termination of a vport
463 * @vport: fc_vport to be terminated
464 *
465 * Calls the LLDD vport_delete() function, then deallocates and removes
466 * the vport from the shost and object tree.
467 *
468 * Notes:
469 * This routine assumes no locks are held on entry.
470 */
471int
472fc_vport_terminate(struct fc_vport *vport)
473
474
439Credits 475Credits
440======= 476=======
441The following people have contributed to this document: 477The following people have contributed to this document:
diff --git a/Documentation/sound/alsa/ALSA-Configuration.txt b/Documentation/sound/alsa/ALSA-Configuration.txt
index b117e42a6166..e0e54a27fc10 100644
--- a/Documentation/sound/alsa/ALSA-Configuration.txt
+++ b/Documentation/sound/alsa/ALSA-Configuration.txt
@@ -746,8 +746,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
746 Module snd-hda-intel 746 Module snd-hda-intel
747 -------------------- 747 --------------------
748 748
749 Module for Intel HD Audio (ICH6, ICH6M, ESB2, ICH7, ICH8), 749 Module for Intel HD Audio (ICH6, ICH6M, ESB2, ICH7, ICH8, ICH9, ICH10,
750 ATI SB450, SB600, RS600, 750 PCH, SCH),
751 ATI SB450, SB600, R600, RS600, RS690, RS780, RV610, RV620,
752 RV630, RV635, RV670, RV770,
751 VIA VT8251/VT8237A, 753 VIA VT8251/VT8237A,
752 SIS966, ULI M5461 754 SIS966, ULI M5461
753 755
@@ -807,6 +809,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
807 ALC260 809 ALC260
808 hp HP machines 810 hp HP machines
809 hp-3013 HP machines (3013-variant) 811 hp-3013 HP machines (3013-variant)
812 hp-dc7600 HP DC7600
810 fujitsu Fujitsu S7020 813 fujitsu Fujitsu S7020
811 acer Acer TravelMate 814 acer Acer TravelMate
812 will Will laptops (PB V7900) 815 will Will laptops (PB V7900)
@@ -828,8 +831,11 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
828 hippo Hippo (ATI) with jack detection, Sony UX-90s 831 hippo Hippo (ATI) with jack detection, Sony UX-90s
829 hippo_1 Hippo (Benq) with jack detection 832 hippo_1 Hippo (Benq) with jack detection
830 sony-assamd Sony ASSAMD 833 sony-assamd Sony ASSAMD
834 toshiba-s06 Toshiba S06
835 toshiba-rx1 Toshiba RX1
831 ultra Samsung Q1 Ultra Vista model 836 ultra Samsung Q1 Ultra Vista model
832 lenovo-3000 Lenovo 3000 y410 837 lenovo-3000 Lenovo 3000 y410
838 nec NEC Versa S9100
833 basic fixed pin assignment w/o SPDIF 839 basic fixed pin assignment w/o SPDIF
834 auto auto-config reading BIOS (default) 840 auto auto-config reading BIOS (default)
835 841
@@ -838,6 +844,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
838 3stack 3-stack model 844 3stack 3-stack model
839 toshiba Toshiba A205 845 toshiba Toshiba A205
840 acer Acer laptops 846 acer Acer laptops
847 acer-aspire Acer Aspire One
841 dell Dell OEM laptops (Vostro 1200) 848 dell Dell OEM laptops (Vostro 1200)
842 zepto Zepto laptops 849 zepto Zepto laptops
843 test for testing/debugging purpose, almost all controls can 850 test for testing/debugging purpose, almost all controls can
@@ -847,6 +854,9 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
847 854
848 ALC269 855 ALC269
849 basic Basic preset 856 basic Basic preset
857 quanta Quanta FL1
858 eeepc-p703 ASUS Eeepc P703 P900A
859 eeepc-p901 ASUS Eeepc P901 S101
850 860
851 ALC662/663 861 ALC662/663
852 3stack-dig 3-stack (2-channel) with SPDIF 862 3stack-dig 3-stack (2-channel) with SPDIF
@@ -856,10 +866,17 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
856 lenovo-101e Lenovo laptop 866 lenovo-101e Lenovo laptop
857 eeepc-p701 ASUS Eeepc P701 867 eeepc-p701 ASUS Eeepc P701
858 eeepc-ep20 ASUS Eeepc EP20 868 eeepc-ep20 ASUS Eeepc EP20
869 ecs ECS/Foxconn mobo
859 m51va ASUS M51VA 870 m51va ASUS M51VA
860 g71v ASUS G71V 871 g71v ASUS G71V
861 h13 ASUS H13 872 h13 ASUS H13
862 g50v ASUS G50V 873 g50v ASUS G50V
874 asus-mode1 ASUS
875 asus-mode2 ASUS
876 asus-mode3 ASUS
877 asus-mode4 ASUS
878 asus-mode5 ASUS
879 asus-mode6 ASUS
863 auto auto-config reading BIOS (default) 880 auto auto-config reading BIOS (default)
864 881
865 ALC882/885 882 ALC882/885
@@ -891,12 +908,14 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
891 lenovo-101e Lenovo 101E 908 lenovo-101e Lenovo 101E
892 lenovo-nb0763 Lenovo NB0763 909 lenovo-nb0763 Lenovo NB0763
893 lenovo-ms7195-dig Lenovo MS7195 910 lenovo-ms7195-dig Lenovo MS7195
911 lenovo-sky Lenovo Sky
894 haier-w66 Haier W66 912 haier-w66 Haier W66
895 3stack-hp HP machines with 3stack (Lucknow, Samba boards) 913 3stack-hp HP machines with 3stack (Lucknow, Samba boards)
896 6stack-dell Dell machines with 6stack (Inspiron 530) 914 6stack-dell Dell machines with 6stack (Inspiron 530)
897 mitac Mitac 8252D 915 mitac Mitac 8252D
898 clevo-m720 Clevo M720 laptop series 916 clevo-m720 Clevo M720 laptop series
899 fujitsu-pi2515 Fujitsu AMILO Pi2515 917 fujitsu-pi2515 Fujitsu AMILO Pi2515
918 3stack-6ch-intel Intel DG33* boards
900 auto auto-config reading BIOS (default) 919 auto auto-config reading BIOS (default)
901 920
902 ALC861/660 921 ALC861/660
@@ -929,7 +948,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
929 allout 5-jack in back, 2-jack in front, SPDIF out 948 allout 5-jack in back, 2-jack in front, SPDIF out
930 auto auto-config reading BIOS (default) 949 auto auto-config reading BIOS (default)
931 950
932 AD1882 951 AD1882 / AD1882A
933 3stack 3-stack mode (default) 952 3stack 3-stack mode (default)
934 6stack 6-stack mode 953 6stack 6-stack mode
935 954
@@ -1079,7 +1098,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
1079 register value without FIFO size correction as the current 1098 register value without FIFO size correction as the current
1080 DMA pointer. position_fix=2 will make the driver to use 1099 DMA pointer. position_fix=2 will make the driver to use
1081 the position buffer instead of reading SD_LPIB register. 1100 the position buffer instead of reading SD_LPIB register.
1082 (Usually SD_LPLIB register is more accurate than the 1101 (Usually SD_LPIB register is more accurate than the
1083 position buffer.) 1102 position buffer.)
1084 1103
1085 NB: If you get many "azx_get_response timeout" messages at 1104 NB: If you get many "azx_get_response timeout" messages at
@@ -1166,6 +1185,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
1166 * Event Electronics, EZ8 1185 * Event Electronics, EZ8
1167 * Digigram VX442 1186 * Digigram VX442
1168 * Lionstracs, Mediastaton 1187 * Lionstracs, Mediastaton
1188 * Terrasoniq TS 88
1169 1189
1170 model - Use the given board model, one of the following: 1190 model - Use the given board model, one of the following:
1171 delta1010, dio2496, delta66, delta44, audiophile, delta410, 1191 delta1010, dio2496, delta66, delta44, audiophile, delta410,
@@ -1200,7 +1220,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
1200 * TerraTec Phase 22 1220 * TerraTec Phase 22
1201 * TerraTec Phase 28 1221 * TerraTec Phase 28
1202 * AudioTrak Prodigy 7.1 1222 * AudioTrak Prodigy 7.1
1203 * AudioTrak Prodigy 7.1LT 1223 * AudioTrak Prodigy 7.1 LT
1224 * AudioTrak Prodigy 7.1 XT
1225 * AudioTrak Prodigy 7.1 HIFI
1226 * AudioTrak Prodigy 7.1 HD2
1204 * AudioTrak Prodigy 192 1227 * AudioTrak Prodigy 192
1205 * Pontis MS300 1228 * Pontis MS300
1206 * Albatron K8X800 Pro II 1229 * Albatron K8X800 Pro II
@@ -1211,12 +1234,16 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
1211 * Shuttle SN25P 1234 * Shuttle SN25P
1212 * Onkyo SE-90PCI 1235 * Onkyo SE-90PCI
1213 * Onkyo SE-200PCI 1236 * Onkyo SE-200PCI
1237 * ESI Juli@
1238 * Hercules Fortissimo IV
1239 * EGO-SYS WaveTerminal 192M
1214 1240
1215 model - Use the given board model, one of the following: 1241 model - Use the given board model, one of the following:
1216 revo51, revo71, amp2000, prodigy71, prodigy71lt, 1242 revo51, revo71, amp2000, prodigy71, prodigy71lt,
1217 prodigy192, aureon51, aureon71, universe, ap192, 1243 prodigy71xt, prodigy71hifi, prodigyhd2, prodigy192,
1218 k8x800, phase22, phase28, ms300, av710, se200pci, 1244 juli, aureon51, aureon71, universe, ap192, k8x800,
1219 se90pci 1245 phase22, phase28, ms300, av710, se200pci, se90pci,
1246 fortissimo4, sn25p, WT192M
1220 1247
1221 This module supports multiple cards and autoprobe. 1248 This module supports multiple cards and autoprobe.
1222 1249
@@ -1255,7 +1282,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
1255 1282
1256 Module for AC'97 motherboards from Intel and compatibles. 1283 Module for AC'97 motherboards from Intel and compatibles.
1257 * Intel i810/810E, i815, i820, i830, i84x, MX440 1284 * Intel i810/810E, i815, i820, i830, i84x, MX440
1258 ICH5, ICH6, ICH7, ESB2 1285 ICH5, ICH6, ICH7, 6300ESB, ESB2
1259 * SiS 7012 (SiS 735) 1286 * SiS 7012 (SiS 735)
1260 * NVidia NForce, NForce2, NForce3, MCP04, CK804 1287 * NVidia NForce, NForce2, NForce3, MCP04, CK804
1261 CK8, CK8S, MCP501 1288 CK8, CK8S, MCP501
@@ -1951,6 +1978,8 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
1951 * CHIC True Sound 4Dwave 1978 * CHIC True Sound 4Dwave
1952 * Shark Predator4D-PCI 1979 * Shark Predator4D-PCI
1953 * Jaton SonicWave 4D 1980 * Jaton SonicWave 4D
1981 * SiS SI7018 PCI Audio
1982 * Hoontech SoundTrack Digital 4DWave NX
1954 1983
1955 pcm_channels - max channels (voices) reserved for PCM 1984 pcm_channels - max channels (voices) reserved for PCM
1956 wavetable_size - max wavetable size in kB (4-?kb) 1985 wavetable_size - max wavetable size in kB (4-?kb)
@@ -1966,12 +1995,25 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
1966 1995
1967 vid - Vendor ID for the device (optional) 1996 vid - Vendor ID for the device (optional)
1968 pid - Product ID for the device (optional) 1997 pid - Product ID for the device (optional)
1998 nrpacks - Max. number of packets per URB (default: 8)
1999 async_unlink - Use async unlink mode (default: yes)
1969 device_setup - Device specific magic number (optional) 2000 device_setup - Device specific magic number (optional)
1970 - Influence depends on the device 2001 - Influence depends on the device
1971 - Default: 0x0000 2002 - Default: 0x0000
2003 ignore_ctl_error - Ignore any USB-controller regarding mixer
2004 interface (default: no)
1972 2005
1973 This module supports multiple devices, autoprobe and hotplugging. 2006 This module supports multiple devices, autoprobe and hotplugging.
1974 2007
2008 NB: nrpacks parameter can be modified dynamically via sysfs.
2009 Don't put the value over 20. Changing via sysfs has no sanity
2010 check.
2011 NB: async_unlink=0 would cause Oops. It remains just for
2012 debugging purpose (if any).
2013 NB: ignore_ctl_error=1 may help when you get an error at accessing
2014 the mixer element such as URB error -22. This happens on some
2015 buggy USB device or the controller.
2016
1975 Module snd-usb-caiaq 2017 Module snd-usb-caiaq
1976 -------------------- 2018 --------------------
1977 2019
@@ -2078,7 +2120,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed.
2078 ------------------- 2120 -------------------
2079 2121
2080 Module for sound cards based on the Asus AV100/AV200 chips, 2122 Module for sound cards based on the Asus AV100/AV200 chips,
2081 i.e., Xonar D1, DX, D2 and D2X. 2123 i.e., Xonar D1, DX, D2, D2X and HDAV1.3 (Deluxe).
2082 2124
2083 This module supports autoprobe and multiple cards. 2125 This module supports autoprobe and multiple cards.
2084 2126
diff --git a/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl b/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl
index e13c4e67029f..87a7c07ab658 100644
--- a/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl
+++ b/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl
@@ -5073,8 +5073,7 @@ struct _snd_pcm_runtime {
5073 with <constant>SNDRV_DMA_TYPE_CONTINUOUS</constant> type and the 5073 with <constant>SNDRV_DMA_TYPE_CONTINUOUS</constant> type and the
5074 <function>snd_dma_continuous_data(GFP_KERNEL)</function> device pointer, 5074 <function>snd_dma_continuous_data(GFP_KERNEL)</function> device pointer,
5075 where <constant>GFP_KERNEL</constant> is the kernel allocation flag to 5075 where <constant>GFP_KERNEL</constant> is the kernel allocation flag to
5076 use. For the SBUS, <constant>SNDRV_DMA_TYPE_SBUS</constant> and 5076 use.
5077 <function>snd_dma_sbus_data(sbus_dev)</function> are used instead.
5078 For the PCI scatter-gather buffers, use 5077 For the PCI scatter-gather buffers, use
5079 <constant>SNDRV_DMA_TYPE_DEV_SG</constant> with 5078 <constant>SNDRV_DMA_TYPE_DEV_SG</constant> with
5080 <function>snd_dma_pci_data(pci)</function> 5079 <function>snd_dma_pci_data(pci)</function>
@@ -6135,44 +6134,58 @@ struct _snd_pcm_runtime {
6135 </para> 6134 </para>
6136 </section> 6135 </section>
6137 6136
6138 <section id="useful-functions-snd-assert"> 6137 <section id="useful-functions-snd-bug">
6139 <title><function>snd_assert()</function></title> 6138 <title><function>snd_BUG()</function></title>
6140 <para> 6139 <para>
6141 <function>snd_assert()</function> macro is similar with the 6140 It shows the <computeroutput>BUG?</computeroutput> message and
6142 normal <function>assert()</function> macro. For example, 6141 stack trace as well as <function>snd_BUG_ON</function> at the point.
6142 It's useful to show that a fatal error happens there.
6143 </para>
6144 <para>
6145 When no debug flag is set, this macro is ignored.
6146 </para>
6147 </section>
6148
6149 <section id="useful-functions-snd-bug-on">
6150 <title><function>snd_BUG_ON()</function></title>
6151 <para>
6152 <function>snd_BUG_ON()</function> macro is similar with
6153 <function>WARN_ON()</function> macro. For example,
6143 6154
6144 <informalexample> 6155 <informalexample>
6145 <programlisting> 6156 <programlisting>
6146<![CDATA[ 6157<![CDATA[
6147 snd_assert(pointer != NULL, return -EINVAL); 6158 snd_BUG_ON(!pointer);
6148]]> 6159]]>
6149 </programlisting> 6160 </programlisting>
6150 </informalexample> 6161 </informalexample>
6151 </para>
6152 6162
6153 <para> 6163 or it can be used as the condition,
6154 The first argument is the expression to evaluate, and the 6164 <informalexample>
6155 second argument is the action if it fails. When 6165 <programlisting>
6156 <constant>CONFIG_SND_DEBUG</constant>, is set, it will show an 6166<![CDATA[
6157 error message such as <computeroutput>BUG? (xxx)</computeroutput> 6167 if (snd_BUG_ON(non_zero_is_bug))
6158 together with stack trace. 6168 return -EINVAL;
6159 </para> 6169]]>
6160 <para> 6170 </programlisting>
6161 When no debug flag is set, this macro is ignored. 6171 </informalexample>
6162 </para>
6163 </section>
6164 6172
6165 <section id="useful-functions-snd-bug">
6166 <title><function>snd_BUG()</function></title>
6167 <para>
6168 It shows the <computeroutput>BUG?</computeroutput> message and
6169 stack trace as well as <function>snd_assert</function> at the point.
6170 It's useful to show that a fatal error happens there.
6171 </para> 6173 </para>
6174
6172 <para> 6175 <para>
6173 When no debug flag is set, this macro is ignored. 6176 The macro takes an conditional expression to evaluate.
6177 When <constant>CONFIG_SND_DEBUG</constant>, is set, the
6178 expression is actually evaluated. If it's non-zero, it shows
6179 the warning message such as
6180 <computeroutput>BUG? (xxx)</computeroutput>
6181 normally followed by stack trace. It returns the evaluated
6182 value.
6183 When no <constant>CONFIG_SND_DEBUG</constant> is set, this
6184 macro always returns zero.
6174 </para> 6185 </para>
6186
6175 </section> 6187 </section>
6188
6176 </chapter> 6189 </chapter>
6177 6190
6178 6191
diff --git a/Documentation/sound/alsa/soc/dapm.txt b/Documentation/sound/alsa/soc/dapm.txt
index b2ed6983f40d..46f9684d0b29 100644
--- a/Documentation/sound/alsa/soc/dapm.txt
+++ b/Documentation/sound/alsa/soc/dapm.txt
@@ -135,11 +135,7 @@ when the Mic is inserted:-
135 135
136static int spitz_mic_bias(struct snd_soc_dapm_widget* w, int event) 136static int spitz_mic_bias(struct snd_soc_dapm_widget* w, int event)
137{ 137{
138 if(SND_SOC_DAPM_EVENT_ON(event)) 138 gpio_set_value(SPITZ_GPIO_MIC_BIAS, 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; 139 return 0;
144} 140}
145 141
@@ -269,11 +265,7 @@ powered only when the spk is in use.
269/* turn speaker amplifier on/off depending on use */ 265/* turn speaker amplifier on/off depending on use */
270static int corgi_amp_event(struct snd_soc_dapm_widget *w, int event) 266static int corgi_amp_event(struct snd_soc_dapm_widget *w, int event)
271{ 267{
272 if (SND_SOC_DAPM_EVENT_ON(event)) 268 gpio_set_value(CORGI_GPIO_APM_ON, SND_SOC_DAPM_EVENT_ON(event));
273 set_scoop_gpio(&corgiscoop_device.dev, CORGI_SCP_APM_ON);
274 else
275 reset_scoop_gpio(&corgiscoop_device.dev, CORGI_SCP_APM_ON);
276
277 return 0; 269 return 0;
278} 270}
279 271
diff --git a/Documentation/sparc/sbus_drivers.txt b/Documentation/sparc/sbus_drivers.txt
deleted file mode 100644
index eb1e28ad8822..000000000000
--- a/Documentation/sparc/sbus_drivers.txt
+++ /dev/null
@@ -1,309 +0,0 @@
1
2 Writing SBUS Drivers
3
4 David S. Miller (davem@redhat.com)
5
6 The SBUS driver interfaces of the Linux kernel have been
7revamped completely for 2.4.x for several reasons. Foremost were
8performance and complexity concerns. This document details these
9new interfaces and how they are used to write an SBUS device driver.
10
11 SBUS drivers need to include <asm/sbus.h> to get access
12to functions and structures described here.
13
14 Probing and Detection
15
16 Each SBUS device inside the machine is described by a
17structure called "struct sbus_dev". Likewise, each SBUS bus
18found in the system is described by a "struct sbus_bus". For
19each SBUS bus, the devices underneath are hung in a tree-like
20fashion off of the bus structure.
21
22 The SBUS device structure contains enough information
23for you to implement your device probing algorithm and obtain
24the bits necessary to run your device. The most commonly
25used members of this structure, and their typical usage,
26will be detailed below.
27
28 Here is a piece of skeleton code for performing a device
29probe in an SBUS driver under Linux:
30
31 static int __devinit mydevice_probe_one(struct sbus_dev *sdev)
32 {
33 struct mysdevice *mp = kzalloc(sizeof(*mp), GFP_KERNEL);
34
35 if (!mp)
36 return -ENODEV;
37
38 ...
39 dev_set_drvdata(&sdev->ofdev.dev, mp);
40 return 0;
41 ...
42 }
43
44 static int __devinit mydevice_probe(struct of_device *dev,
45 const struct of_device_id *match)
46 {
47 struct sbus_dev *sdev = to_sbus_device(&dev->dev);
48
49 return mydevice_probe_one(sdev);
50 }
51
52 static int __devexit mydevice_remove(struct of_device *dev)
53 {
54 struct sbus_dev *sdev = to_sbus_device(&dev->dev);
55 struct mydevice *mp = dev_get_drvdata(&dev->dev);
56
57 return mydevice_remove_one(sdev, mp);
58 }
59
60 static struct of_device_id mydevice_match[] = {
61 {
62 .name = "mydevice",
63 },
64 {},
65 };
66
67 MODULE_DEVICE_TABLE(of, mydevice_match);
68
69 static struct of_platform_driver mydevice_driver = {
70 .match_table = mydevice_match,
71 .probe = mydevice_probe,
72 .remove = __devexit_p(mydevice_remove),
73 .driver = {
74 .name = "mydevice",
75 },
76 };
77
78 static int __init mydevice_init(void)
79 {
80 return of_register_driver(&mydevice_driver, &sbus_bus_type);
81 }
82
83 static void __exit mydevice_exit(void)
84 {
85 of_unregister_driver(&mydevice_driver);
86 }
87
88 module_init(mydevice_init);
89 module_exit(mydevice_exit);
90
91 The mydevice_match table is a series of entries which
92describes what SBUS devices your driver is meant for. In the
93simplest case you specify a string for the 'name' field. Every
94SBUS device with a 'name' property matching your string will
95be passed one-by-one to your .probe method.
96
97 You should store away your device private state structure
98pointer in the drvdata area so that you can retrieve it later on
99in your .remove method.
100
101 Any memory allocated, registers mapped, IRQs registered,
102etc. must be undone by your .remove method so that all resources
103of your device are released by the time it returns.
104
105 You should _NOT_ use the for_each_sbus(), for_each_sbusdev(),
106and for_all_sbusdev() interfaces. They are deprecated, will be
107removed, and no new driver should reference them ever.
108
109 Mapping and Accessing I/O Registers
110
111 Each SBUS device structure contains an array of descriptors
112which describe each register set. We abuse struct resource for that.
113They each correspond to the "reg" properties provided by the OBP firmware.
114
115 Before you can access your device's registers you must map
116them. And later if you wish to shutdown your driver (for module
117unload or similar) you must unmap them. You must treat them as
118a resource, which you allocate (map) before using and free up
119(unmap) when you are done with it.
120
121 The mapping information is stored in an opaque value
122typed as an "unsigned long". This is the type of the return value
123of the mapping interface, and the arguments to the unmapping
124interface. Let's say you want to map the first set of registers.
125Perhaps part of your driver software state structure looks like:
126
127 struct mydevice {
128 unsigned long control_regs;
129 ...
130 struct sbus_dev *sdev;
131 ...
132 };
133
134 At initialization time you then use the sbus_ioremap
135interface to map in your registers, like so:
136
137 static void init_one_mydevice(struct sbus_dev *sdev)
138 {
139 struct mydevice *mp;
140 ...
141
142 mp->control_regs = sbus_ioremap(&sdev->resource[0], 0,
143 CONTROL_REGS_SIZE, "mydevice regs");
144 if (!mp->control_regs) {
145 /* Failure, cleanup and return. */
146 }
147 }
148
149 Second argument to sbus_ioremap is an offset for
150cranky devices with broken OBP PROM. The sbus_ioremap uses only
151a start address and flags from the resource structure.
152Therefore it is possible to use the same resource to map
153several sets of registers or even to fabricate a resource
154structure if driver gets physical address from some private place.
155This practice is discouraged though. Use whatever OBP PROM
156provided to you.
157
158 And here is how you might unmap these registers later at
159driver shutdown or module unload time, using the sbus_iounmap
160interface:
161
162 static void mydevice_unmap_regs(struct mydevice *mp)
163 {
164 sbus_iounmap(mp->control_regs, CONTROL_REGS_SIZE);
165 }
166
167 Finally, to actually access your registers there are 6
168interface routines at your disposal. Accesses are byte (8 bit),
169word (16 bit), or longword (32 bit) sized. Here they are:
170
171 u8 sbus_readb(unsigned long reg) /* read byte */
172 u16 sbus_readw(unsigned long reg) /* read word */
173 u32 sbus_readl(unsigned long reg) /* read longword */
174 void sbus_writeb(u8 value, unsigned long reg) /* write byte */
175 void sbus_writew(u16 value, unsigned long reg) /* write word */
176 void sbus_writel(u32 value, unsigned long reg) /* write longword */
177
178 So, let's say your device has a control register of some sort
179at offset zero. The following might implement resetting your device:
180
181 #define CONTROL 0x00UL
182
183 #define CONTROL_RESET 0x00000001 /* Reset hardware */
184
185 static void mydevice_reset(struct mydevice *mp)
186 {
187 sbus_writel(CONTROL_RESET, mp->regs + CONTROL);
188 }
189
190 Or perhaps there is a data port register at an offset of
19116 bytes which allows you to read bytes from a fifo in the device:
192
193 #define DATA 0x10UL
194
195 static u8 mydevice_get_byte(struct mydevice *mp)
196 {
197 return sbus_readb(mp->regs + DATA);
198 }
199
200 It's pretty straightforward, and clueful readers may have
201noticed that these interfaces mimick the PCI interfaces of the
202Linux kernel. This was not by accident.
203
204 WARNING:
205
206 DO NOT try to treat these opaque register mapping
207 values as a memory mapped pointer to some structure
208 which you can dereference.
209
210 It may be memory mapped, it may not be. In fact it
211 could be a physical address, or it could be the time
212 of day xor'd with 0xdeadbeef. :-)
213
214 Whatever it is, it's an implementation detail. The
215 interface was done this way to shield the driver
216 author from such complexities.
217
218 Doing DVMA
219
220 SBUS devices can perform DMA transactions in a way similar
221to PCI but dissimilar to ISA, e.g. DMA masters supply address.
222In contrast to PCI, however, that address (a bus address) is
223translated by IOMMU before a memory access is performed and therefore
224it is virtual. Sun calls this procedure DVMA.
225
226 Linux supports two styles of using SBUS DVMA: "consistent memory"
227and "streaming DVMA". CPU view of consistent memory chunk is, well,
228consistent with a view of a device. Think of it as an uncached memory.
229Typically this way of doing DVMA is not very fast and drivers use it
230mostly for control blocks or queues. On some CPUs we cannot flush or
231invalidate individual pages or cache lines and doing explicit flushing
232over ever little byte in every control block would be wasteful.
233
234Streaming DVMA is a preferred way to transfer large amounts of data.
235This process works in the following way:
2361. a CPU stops accessing a certain part of memory,
237 flushes its caches covering that memory;
2382. a device does DVMA accesses, then posts an interrupt;
2393. CPU invalidates its caches and starts to access the memory.
240
241A single streaming DVMA operation can touch several discontiguous
242regions of a virtual bus address space. This is called a scatter-gather
243DVMA.
244
245[TBD: Why do not we neither Solaris attempt to map disjoint pages
246into a single virtual chunk with the help of IOMMU, so that non SG
247DVMA masters would do SG? It'd be very helpful for RAID.]
248
249 In order to perform a consistent DVMA a driver does something
250like the following:
251
252 char *mem; /* Address in the CPU space */
253 u32 busa; /* Address in the SBus space */
254
255 mem = (char *) sbus_alloc_consistent(sdev, MYMEMSIZE, &busa);
256
257 Then mem is used when CPU accesses this memory and u32
258is fed to the device so that it can do DVMA. This is typically
259done with an sbus_writel() into some device register.
260
261 Do not forget to free the DVMA resources once you are done:
262
263 sbus_free_consistent(sdev, MYMEMSIZE, mem, busa);
264
265 Streaming DVMA is more interesting. First you allocate some
266memory suitable for it or pin down some user pages. Then it all works
267like this:
268
269 char *mem = argumen1;
270 unsigned int size = argument2;
271 u32 busa; /* Address in the SBus space */
272
273 *mem = 1; /* CPU can access */
274 busa = sbus_map_single(sdev, mem, size);
275 if (busa == 0) .......
276
277 /* Tell the device to use busa here */
278 /* CPU cannot access the memory without sbus_dma_sync_single() */
279
280 sbus_unmap_single(sdev, busa, size);
281 if (*mem == 0) .... /* CPU can access again */
282
283 It is possible to retain mappings and ask the device to
284access data again and again without calling sbus_unmap_single.
285However, CPU caches must be invalidated with sbus_dma_sync_single
286before such access.
287
288[TBD but what about writeback caches here... do we have any?]
289
290 There is an equivalent set of functions doing the same thing
291only with several memory segments at once for devices capable of
292scatter-gather transfers. Use the Source, Luke.
293
294 Examples
295
296 drivers/net/sunhme.c
297 This is a complicated driver which illustrates many concepts
298discussed above and plus it handles both PCI and SBUS boards.
299
300 drivers/scsi/esp.c
301 Check it out for scatter-gather DVMA.
302
303 drivers/sbus/char/bpp.c
304 A non-DVMA device.
305
306 drivers/net/sunlance.c
307 Lance driver abuses consistent mappings for data transfer.
308It is a nifty trick which we do not particularly recommend...
309Just check it out and know that it's legal.
diff --git a/Documentation/spi/pxa2xx b/Documentation/spi/pxa2xx
index bbe8dee681a5..6bb916d57c95 100644
--- a/Documentation/spi/pxa2xx
+++ b/Documentation/spi/pxa2xx
@@ -96,7 +96,7 @@ Each slave device attached to the PXA must provide slave specific configuration
96information via the structure "pxa2xx_spi_chip" found in 96information via the structure "pxa2xx_spi_chip" found in
97"arch/arm/mach-pxa/include/mach/pxa2xx_spi.h". The pxa2xx_spi master controller driver 97"arch/arm/mach-pxa/include/mach/pxa2xx_spi.h". The pxa2xx_spi master controller driver
98will uses the configuration whenever the driver communicates with the slave 98will uses the configuration whenever the driver communicates with the slave
99device. 99device. All fields are optional.
100 100
101struct pxa2xx_spi_chip { 101struct pxa2xx_spi_chip {
102 u8 tx_threshold; 102 u8 tx_threshold;
@@ -112,14 +112,17 @@ used to configure the SSP hardware fifo. These fields are critical to the
112performance of pxa2xx_spi driver and misconfiguration will result in rx 112performance of pxa2xx_spi driver and misconfiguration will result in rx
113fifo overruns (especially in PIO mode transfers). Good default values are 113fifo overruns (especially in PIO mode transfers). Good default values are
114 114
115 .tx_threshold = 12, 115 .tx_threshold = 8,
116 .rx_threshold = 4, 116 .rx_threshold = 8,
117
118The range is 1 to 16 where zero indicates "use default".
117 119
118The "pxa2xx_spi_chip.dma_burst_size" field is used to configure PXA2xx DMA 120The "pxa2xx_spi_chip.dma_burst_size" field is used to configure PXA2xx DMA
119engine and is related the "spi_device.bits_per_word" field. Read and understand 121engine and is related the "spi_device.bits_per_word" field. Read and understand
120the PXA2xx "Developer Manual" sections on the DMA controller and SSP Controllers 122the PXA2xx "Developer Manual" sections on the DMA controller and SSP Controllers
121to determine the correct value. An SSP configured for byte-wide transfers would 123to determine the correct value. An SSP configured for byte-wide transfers would
122use a value of 8. 124use a value of 8. The driver will determine a reasonable default if
125dma_burst_size == 0.
123 126
124The "pxa2xx_spi_chip.timeout" fields is used to efficiently handle 127The "pxa2xx_spi_chip.timeout" fields is used to efficiently handle
125trailing bytes in the SSP receiver fifo. The correct value for this field is 128trailing bytes in the SSP receiver fifo. The correct value for this field is
@@ -137,7 +140,13 @@ function for asserting/deasserting a slave device chip select. If the field is
137NULL, the pxa2xx_spi master controller driver assumes that the SSP port is 140NULL, the pxa2xx_spi master controller driver assumes that the SSP port is
138configured to use SSPFRM instead. 141configured to use SSPFRM instead.
139 142
140NSSP SALVE SAMPLE 143NOTE: the SPI driver cannot control the chip select if SSPFRM is used, so the
144chipselect is dropped after each spi_transfer. Most devices need chip select
145asserted around the complete message. Use SSPFRM as a GPIO (through cs_control)
146to accomodate these chips.
147
148
149NSSP SLAVE SAMPLE
141----------------- 150-----------------
142The pxa2xx_spi_chip structure is passed to the pxa2xx_spi driver in the 151The pxa2xx_spi_chip structure is passed to the pxa2xx_spi driver in the
143"spi_board_info.controller_data" field. Below is a sample configuration using 152"spi_board_info.controller_data" field. Below is a sample configuration using
@@ -206,18 +215,21 @@ static void __init streetracer_init(void)
206 215
207DMA and PIO I/O Support 216DMA and PIO I/O Support
208----------------------- 217-----------------------
209The pxa2xx_spi driver support both DMA and interrupt driven PIO message 218The pxa2xx_spi driver supports both DMA and interrupt driven PIO message
210transfers. The driver defaults to PIO mode and DMA transfers must enabled by 219transfers. The driver defaults to PIO mode and DMA transfers must be enabled
211setting the "enable_dma" flag in the "pxa2xx_spi_master" structure and 220by setting the "enable_dma" flag in the "pxa2xx_spi_master" structure. The DMA
212ensuring that the "pxa2xx_spi_chip.dma_burst_size" field is non-zero. The DMA 221mode supports both coherent and stream based DMA mappings.
213mode support both coherent and stream based DMA mappings.
214 222
215The following logic is used to determine the type of I/O to be used on 223The following logic is used to determine the type of I/O to be used on
216a per "spi_transfer" basis: 224a per "spi_transfer" basis:
217 225
218if !enable_dma or dma_burst_size == 0 then 226if !enable_dma then
219 always use PIO transfers 227 always use PIO transfers
220 228
229if spi_message.len > 8191 then
230 print "rate limited" warning
231 use PIO transfers
232
221if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then 233if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then
222 use coherent DMA mode 234 use coherent DMA mode
223 235
diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt
index e1ff0d920a5c..bde799e06598 100644
--- a/Documentation/sysctl/kernel.txt
+++ b/Documentation/sysctl/kernel.txt
@@ -369,4 +369,5 @@ can be ORed together:
369 2 - A module was force loaded by insmod -f. 369 2 - A module was force loaded by insmod -f.
370 Set by modutils >= 2.4.9 and module-init-tools. 370 Set by modutils >= 2.4.9 and module-init-tools.
371 4 - Unsafe SMP processors: SMP with CPUs not designed for SMP. 371 4 - Unsafe SMP processors: SMP with CPUs not designed for SMP.
372 64 - A module from drivers/staging was loaded.
372 373
diff --git a/Documentation/timers/00-INDEX b/Documentation/timers/00-INDEX
new file mode 100644
index 000000000000..397dc35e1323
--- /dev/null
+++ b/Documentation/timers/00-INDEX
@@ -0,0 +1,10 @@
100-INDEX
2 - this file
3highres.txt
4 - High resolution timers and dynamic ticks design notes
5hpet.txt
6 - High Precision Event Timer Driver for Linux
7hrtimers.txt
8 - subsystem for high-resolution kernel timers
9timer_stats.txt
10 - timer usage statistics
diff --git a/Documentation/hpet.txt b/Documentation/timers/hpet.txt
index 6ad52d9dad6c..e7c09abcfab4 100644
--- a/Documentation/hpet.txt
+++ b/Documentation/timers/hpet.txt
@@ -1,21 +1,32 @@
1 High Precision Event Timer Driver for Linux 1 High Precision Event Timer Driver for Linux
2 2
3The High Precision Event Timer (HPET) hardware is the future replacement 3The High Precision Event Timer (HPET) hardware follows a specification
4for the 8254 and Real Time Clock (RTC) periodic timer functionality. 4by Intel and Microsoft which can be found at
5Each HPET can have up to 32 timers. It is possible to configure the 5
6first two timers as legacy replacements for 8254 and RTC periodic timers. 6 http://www.intel.com/technology/architecture/hpetspec.htm
7A specification done by Intel and Microsoft can be found at 7
8<http://www.intel.com/technology/architecture/hpetspec.htm>. 8Each HPET has one fixed-rate counter (at 10+ MHz, hence "High Precision")
9and up to 32 comparators. Normally three or more comparators are provided,
10each of which can generate oneshot interupts and at least one of which has
11additional hardware to support periodic interrupts. The comparators are
12also called "timers", which can be misleading since usually timers are
13independent of each other ... these share a counter, complicating resets.
14
15HPET devices can support two interrupt routing modes. In one mode, the
16comparators are additional interrupt sources with no particular system
17role. Many x86 BIOS writers don't route HPET interrupts at all, which
18prevents use of that mode. They support the other "legacy replacement"
19mode where the first two comparators block interrupts from 8254 timers
20and from the RTC.
9 21
10The driver supports detection of HPET driver allocation and initialization 22The driver supports detection of HPET driver allocation and initialization
11of the HPET before the driver module_init routine is called. This enables 23of the HPET before the driver module_init routine is called. This enables
12platform code which uses timer 0 or 1 as the main timer to intercept HPET 24platform code which uses timer 0 or 1 as the main timer to intercept HPET
13initialization. An example of this initialization can be found in 25initialization. An example of this initialization can be found in
14arch/i386/kernel/time_hpet.c. 26arch/x86/kernel/hpet.c.
15 27
16The driver provides two APIs which are very similar to the API found in 28The driver provides a userspace API which resembles the API found in the
17the rtc.c driver. There is a user space API and a kernel space API. 29RTC driver framework. An example user space program is provided below.
18An example user space program is provided below.
19 30
20#include <stdio.h> 31#include <stdio.h>
21#include <stdlib.h> 32#include <stdlib.h>
@@ -286,15 +297,3 @@ out:
286 297
287 return; 298 return;
288} 299}
289
290The kernel API has three interfaces exported from the driver:
291
292 hpet_register(struct hpet_task *tp, int periodic)
293 hpet_unregister(struct hpet_task *tp)
294 hpet_control(struct hpet_task *tp, unsigned int cmd, unsigned long arg)
295
296The kernel module using this interface fills in the ht_func and ht_data
297members of the hpet_task structure before calling hpet_register.
298hpet_control simply vectors to the hpet_ioctl routine and has the same
299commands and respective arguments as the user API. hpet_unregister
300is used to terminate usage of the HPET timer reserved by hpet_register.
diff --git a/Documentation/usb/anchors.txt b/Documentation/usb/anchors.txt
index 5e6b64c20d25..6f24f566955a 100644
--- a/Documentation/usb/anchors.txt
+++ b/Documentation/usb/anchors.txt
@@ -52,6 +52,11 @@ Therefore no guarantee is made that the URBs have been unlinked when
52the call returns. They may be unlinked later but will be unlinked in 52the call returns. They may be unlinked later but will be unlinked in
53finite time. 53finite time.
54 54
55usb_scuttle_anchored_urbs()
56---------------------------
57
58All URBs of an anchor are unanchored en masse.
59
55usb_wait_anchor_empty_timeout() 60usb_wait_anchor_empty_timeout()
56------------------------------- 61-------------------------------
57 62
@@ -59,4 +64,16 @@ This function waits for all URBs associated with an anchor to finish
59or a timeout, whichever comes first. Its return value will tell you 64or a timeout, whichever comes first. Its return value will tell you
60whether the timeout was reached. 65whether the timeout was reached.
61 66
67usb_anchor_empty()
68------------------
69
70Returns true if no URBs are associated with an anchor. Locking
71is the caller's responsibility.
72
73usb_get_from_anchor()
74---------------------
62 75
76Returns the oldest anchored URB of an anchor. The URB is unanchored
77and returned with a reference. As you may mix URBs to several
78destinations in one anchor you have no guarantee the chronologically
79first submitted URB is returned. \ No newline at end of file
diff --git a/Documentation/usb/misc_usbsevseg.txt b/Documentation/usb/misc_usbsevseg.txt
new file mode 100644
index 000000000000..0f6be4f9930b
--- /dev/null
+++ b/Documentation/usb/misc_usbsevseg.txt
@@ -0,0 +1,46 @@
1USB 7-Segment Numeric Display
2Manufactured by Delcom Engineering
3
4Device Information
5------------------
6USB VENDOR_ID 0x0fc5
7USB PRODUCT_ID 0x1227
8Both the 6 character and 8 character displays have PRODUCT_ID,
9and according to Delcom Engineering no queryable information
10can be obtained from the device to tell them apart.
11
12Device Modes
13------------
14By default, the driver assumes the display is only 6 characters
15The mode for 6 characters is:
16 MSB 0x06; LSB 0x3f
17For the 8 character display:
18 MSB 0x08; LSB 0xff
19The device can accept "text" either in raw, hex, or ascii textmode.
20raw controls each segment manually,
21hex expects a value between 0-15 per character,
22ascii expects a value between '0'-'9' and 'A'-'F'.
23The default is ascii.
24
25Device Operation
26----------------
271. Turn on the device:
28 echo 1 > /sys/bus/usb/.../powered
292. Set the device's mode:
30 echo $mode_msb > /sys/bus/usb/.../mode_msb
31 echo $mode_lsb > /sys/bus/usb/.../mode_lsb
323. Set the textmode:
33 echo $textmode > /sys/bus/usb/.../textmode
344. set the text (for example):
35 echo "123ABC" > /sys/bus/usb/.../text (ascii)
36 echo "A1B2" > /sys/bus/usb/.../text (ascii)
37 echo -ne "\x01\x02\x03" > /sys/bus/usb/.../text (hex)
385. Set the decimal places.
39 The device has either 6 or 8 decimal points.
40 to set the nth decimal place calculate 10 ** n
41 and echo it in to /sys/bus/usb/.../decimals
42 To set multiple decimals points sum up each power.
43 For example, to set the 0th and 3rd decimal place
44 echo 1001 > /sys/bus/usb/.../decimals
45
46
diff --git a/Documentation/usb/power-management.txt b/Documentation/usb/power-management.txt
index 9d31140e3f5b..e48ea1d51010 100644
--- a/Documentation/usb/power-management.txt
+++ b/Documentation/usb/power-management.txt
@@ -350,12 +350,12 @@ without holding the mutex.
350 350
351There also are a couple of utility routines drivers can use: 351There also are a couple of utility routines drivers can use:
352 352
353 usb_autopm_enable() sets pm_usage_cnt to 1 and then calls 353 usb_autopm_enable() sets pm_usage_cnt to 0 and then calls
354 usb_autopm_set_interface(), which will attempt an autoresume.
355
356 usb_autopm_disable() sets pm_usage_cnt to 0 and then calls
357 usb_autopm_set_interface(), which will attempt an autosuspend. 354 usb_autopm_set_interface(), which will attempt an autosuspend.
358 355
356 usb_autopm_disable() sets pm_usage_cnt to 1 and then calls
357 usb_autopm_set_interface(), which will attempt an autoresume.
358
359The conventional usage pattern is that a driver calls 359The conventional usage pattern is that a driver calls
360usb_autopm_get_interface() in its open routine and 360usb_autopm_get_interface() in its open routine and
361usb_autopm_put_interface() in its close or release routine. But 361usb_autopm_put_interface() in its close or release routine. But
diff --git a/Documentation/video4linux/CARDLIST.au0828 b/Documentation/video4linux/CARDLIST.au0828
index aa05e5bb22fb..d5cb4ea287b2 100644
--- a/Documentation/video4linux/CARDLIST.au0828
+++ b/Documentation/video4linux/CARDLIST.au0828
@@ -1,5 +1,5 @@
1 0 -> Unknown board (au0828) 1 0 -> Unknown board (au0828)
2 1 -> Hauppauge HVR950Q (au0828) [2040:7200,2040:7210,2040:7217,2040:721b,2040:721f,2040:7280,0fd9:0008] 2 1 -> Hauppauge HVR950Q (au0828) [2040:7200,2040:7210,2040:7217,2040:721b,2040:721e,2040:721f,2040:7280,0fd9:0008]
3 2 -> Hauppauge HVR850 (au0828) [2040:7240] 3 2 -> Hauppauge HVR850 (au0828) [2040:7240]
4 3 -> DViCO FusionHDTV USB (au0828) [0fe9:d620] 4 3 -> DViCO FusionHDTV USB (au0828) [0fe9:d620]
5 4 -> Hauppauge HVR950Q rev xxF8 (au0828) [2040:7201,2040:7211,2040:7281] 5 4 -> Hauppauge HVR950Q rev xxF8 (au0828) [2040:7201,2040:7211,2040:7281]
diff --git a/Documentation/video4linux/CARDLIST.bttv b/Documentation/video4linux/CARDLIST.bttv
index f32efb6fb12c..60ba66836038 100644
--- a/Documentation/video4linux/CARDLIST.bttv
+++ b/Documentation/video4linux/CARDLIST.bttv
@@ -150,3 +150,4 @@
150149 -> Typhoon TV-Tuner PCI (50684) 150149 -> Typhoon TV-Tuner PCI (50684)
151150 -> Geovision GV-600 [008a:763c] 151150 -> Geovision GV-600 [008a:763c]
152151 -> Kozumi KTV-01C 152151 -> Kozumi KTV-01C
153152 -> Encore ENL TV-FM-2 [1000:1801]
diff --git a/Documentation/video4linux/CARDLIST.cx23885 b/Documentation/video4linux/CARDLIST.cx23885
index f0e613ba55b8..64823ccacd69 100644
--- a/Documentation/video4linux/CARDLIST.cx23885
+++ b/Documentation/video4linux/CARDLIST.cx23885
@@ -9,3 +9,5 @@
9 8 -> Hauppauge WinTV-HVR1700 [0070:8101] 9 8 -> Hauppauge WinTV-HVR1700 [0070:8101]
10 9 -> Hauppauge WinTV-HVR1400 [0070:8010] 10 9 -> Hauppauge WinTV-HVR1400 [0070:8010]
11 10 -> DViCO FusionHDTV7 Dual Express [18ac:d618] 11 10 -> DViCO FusionHDTV7 Dual Express [18ac:d618]
12 11 -> DViCO FusionHDTV DVB-T Dual Express [18ac:db78]
13 12 -> Leadtek Winfast PxDVR3200 H [107d:6681]
diff --git a/Documentation/video4linux/CARDLIST.cx88 b/Documentation/video4linux/CARDLIST.cx88
index 7cf5685d3645..a5227e308f4a 100644
--- a/Documentation/video4linux/CARDLIST.cx88
+++ b/Documentation/video4linux/CARDLIST.cx88
@@ -66,3 +66,11 @@
66 65 -> DViCO FusionHDTV 7 Gold [18ac:d610] 66 65 -> DViCO FusionHDTV 7 Gold [18ac:d610]
67 66 -> Prolink Pixelview MPEG 8000GT [1554:4935] 67 66 -> Prolink Pixelview MPEG 8000GT [1554:4935]
68 67 -> Kworld PlusTV HD PCI 120 (ATSC 120) [17de:08c1] 68 67 -> Kworld PlusTV HD PCI 120 (ATSC 120) [17de:08c1]
69 68 -> Hauppauge WinTV-HVR4000 DVB-S/S2/T/Hybrid [0070:6900,0070:6904,0070:6902]
70 69 -> Hauppauge WinTV-HVR4000(Lite) DVB-S/S2 [0070:6905,0070:6906]
71 70 -> TeVii S460 DVB-S/S2 [d460:9022]
72 71 -> Omicom SS4 DVB-S/S2 PCI [A044:2011]
73 72 -> TBS 8920 DVB-S/S2 [8920:8888]
74 73 -> TeVii S420 DVB-S [d420:9022]
75 74 -> Prolink Pixelview Global Extreme [1554:4976]
76 75 -> PROF 7300 DVB-S/S2 [B033:3033]
diff --git a/Documentation/video4linux/CARDLIST.em28xx b/Documentation/video4linux/CARDLIST.em28xx
index 53449cb99b17..187cc48d0924 100644
--- a/Documentation/video4linux/CARDLIST.em28xx
+++ b/Documentation/video4linux/CARDLIST.em28xx
@@ -1,5 +1,5 @@
1 0 -> Unknown EM2800 video grabber (em2800) [eb1a:2800] 1 0 -> Unknown EM2800 video grabber (em2800) [eb1a:2800]
2 1 -> Unknown EM2750/28xx video grabber (em2820/em2840) [eb1a:2820,eb1a:2821,eb1a:2860,eb1a:2861,eb1a:2870,eb1a:2881,eb1a:2883] 2 1 -> Unknown EM2750/28xx video grabber (em2820/em2840) [eb1a:2820,eb1a:2860,eb1a:2861,eb1a:2870,eb1a:2881,eb1a:2883]
3 2 -> Terratec Cinergy 250 USB (em2820/em2840) [0ccd:0036] 3 2 -> Terratec Cinergy 250 USB (em2820/em2840) [0ccd:0036]
4 3 -> Pinnacle PCTV USB 2 (em2820/em2840) [2304:0208] 4 3 -> Pinnacle PCTV USB 2 (em2820/em2840) [2304:0208]
5 4 -> Hauppauge WinTV USB 2 (em2820/em2840) [2040:4200,2040:4201] 5 4 -> Hauppauge WinTV USB 2 (em2820/em2840) [2040:4200,2040:4201]
@@ -12,7 +12,7 @@
12 11 -> Terratec Hybrid XS (em2880) [0ccd:0042] 12 11 -> Terratec Hybrid XS (em2880) [0ccd:0042]
13 12 -> Kworld PVR TV 2800 RF (em2820/em2840) 13 12 -> Kworld PVR TV 2800 RF (em2820/em2840)
14 13 -> Terratec Prodigy XS (em2880) [0ccd:0047] 14 13 -> Terratec Prodigy XS (em2880) [0ccd:0047]
15 14 -> Pixelview Prolink PlayTV USB 2.0 (em2820/em2840) 15 14 -> Pixelview Prolink PlayTV USB 2.0 (em2820/em2840) [eb1a:2821]
16 15 -> V-Gear PocketTV (em2800) 16 15 -> V-Gear PocketTV (em2800)
17 16 -> Hauppauge WinTV HVR 950 (em2883) [2040:6513,2040:6517,2040:651b,2040:651f] 17 16 -> Hauppauge WinTV HVR 950 (em2883) [2040:6513,2040:6517,2040:651b,2040:651f]
18 17 -> Pinnacle PCTV HD Pro Stick (em2880) [2304:0227] 18 17 -> Pinnacle PCTV HD Pro Stick (em2880) [2304:0227]
diff --git a/Documentation/video4linux/CARDLIST.saa7134 b/Documentation/video4linux/CARDLIST.saa7134
index 39868af9cf9f..dc67eef38ff9 100644
--- a/Documentation/video4linux/CARDLIST.saa7134
+++ b/Documentation/video4linux/CARDLIST.saa7134
@@ -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:4857] 79 78 -> ASUSTeK P7131 Dual [1043:4862]
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]
@@ -145,3 +145,9 @@
145144 -> Beholder BeholdTV M6 Extra [5ace:6193] 145144 -> Beholder BeholdTV M6 Extra [5ace:6193]
146145 -> AVerMedia MiniPCI DVB-T Hybrid M103 [1461:f636] 146145 -> AVerMedia MiniPCI DVB-T Hybrid M103 [1461:f636]
147146 -> ASUSTeK P7131 Analog 147146 -> ASUSTeK P7131 Analog
148147 -> Asus Tiger 3in1 [1043:4878]
149148 -> Encore ENLTV-FM v5.3 [1a7f:2008]
150149 -> Avermedia PCI pure analog (M135A) [1461:f11d]
151150 -> Zogis Real Angel 220
152151 -> ADS Tech Instant HDTV [1421:0380]
153152 -> Asus Tiger Rev:1.00 [1043:4857]
diff --git a/Documentation/video4linux/CARDLIST.tuner b/Documentation/video4linux/CARDLIST.tuner
index 0e2394695bb8..691d2f37dc57 100644
--- a/Documentation/video4linux/CARDLIST.tuner
+++ b/Documentation/video4linux/CARDLIST.tuner
@@ -74,3 +74,5 @@ tuner=72 - Thomson FE6600
74tuner=73 - Samsung TCPG 6121P30A 74tuner=73 - Samsung TCPG 6121P30A
75tuner=75 - Philips TEA5761 FM Radio 75tuner=75 - Philips TEA5761 FM Radio
76tuner=76 - Xceive 5000 tuner 76tuner=76 - Xceive 5000 tuner
77tuner=77 - TCL tuner MF02GIP-5N-E
78tuner=78 - Philips FMD1216MEX MK3 Hybrid Tuner
diff --git a/Documentation/video4linux/gspca.txt b/Documentation/video4linux/gspca.txt
index 9a3e4d797fa8..004818fab040 100644
--- a/Documentation/video4linux/gspca.txt
+++ b/Documentation/video4linux/gspca.txt
@@ -7,6 +7,7 @@ The modules are:
7xxxx vend:prod 7xxxx vend:prod
8---- 8----
9spca501 0000:0000 MystFromOri Unknow Camera 9spca501 0000:0000 MystFromOri Unknow Camera
10m5602 0402:5602 ALi Video Camera Controller
10spca501 040a:0002 Kodak DVC-325 11spca501 040a:0002 Kodak DVC-325
11spca500 040a:0300 Kodak EZ200 12spca500 040a:0300 Kodak EZ200
12zc3xx 041e:041e Creative WebCam Live! 13zc3xx 041e:041e Creative WebCam Live!
@@ -42,6 +43,7 @@ zc3xx 0458:7007 Genius VideoCam V2
42zc3xx 0458:700c Genius VideoCam V3 43zc3xx 0458:700c Genius VideoCam V3
43zc3xx 0458:700f Genius VideoCam Web V2 44zc3xx 0458:700f Genius VideoCam Web V2
44sonixj 0458:7025 Genius Eye 311Q 45sonixj 0458:7025 Genius Eye 311Q
46sonixj 0458:702e Genius Slim 310 NB
45sonixj 045e:00f5 MicroSoft VX3000 47sonixj 045e:00f5 MicroSoft VX3000
46sonixj 045e:00f7 MicroSoft VX1000 48sonixj 045e:00f7 MicroSoft VX1000
47ov519 045e:028c Micro$oft xbox cam 49ov519 045e:028c Micro$oft xbox cam
@@ -81,7 +83,7 @@ spca561 046d:092b Labtec Webcam Plus
81spca561 046d:092c Logitech QC chat Elch2 83spca561 046d:092c Logitech QC chat Elch2
82spca561 046d:092d Logitech QC Elch2 84spca561 046d:092d Logitech QC Elch2
83spca561 046d:092e Logitech QC Elch2 85spca561 046d:092e Logitech QC Elch2
84spca561 046d:092f Logitech QC Elch2 86spca561 046d:092f Logitech QuickCam Express Plus
85sunplus 046d:0960 Logitech ClickSmart 420 87sunplus 046d:0960 Logitech ClickSmart 420
86sunplus 0471:0322 Philips DMVC1300K 88sunplus 0471:0322 Philips DMVC1300K
87zc3xx 0471:0325 Philips SPC 200 NC 89zc3xx 0471:0325 Philips SPC 200 NC
@@ -96,6 +98,29 @@ sunplus 04a5:3003 Benq DC 1300
96sunplus 04a5:3008 Benq DC 1500 98sunplus 04a5:3008 Benq DC 1500
97sunplus 04a5:300a Benq DC 3410 99sunplus 04a5:300a Benq DC 3410
98spca500 04a5:300c Benq DC 1016 100spca500 04a5:300c Benq DC 1016
101finepix 04cb:0104 Fujifilm FinePix 4800
102finepix 04cb:0109 Fujifilm FinePix A202
103finepix 04cb:010b Fujifilm FinePix A203
104finepix 04cb:010f Fujifilm FinePix A204
105finepix 04cb:0111 Fujifilm FinePix A205
106finepix 04cb:0113 Fujifilm FinePix A210
107finepix 04cb:0115 Fujifilm FinePix A303
108finepix 04cb:0117 Fujifilm FinePix A310
109finepix 04cb:0119 Fujifilm FinePix F401
110finepix 04cb:011b Fujifilm FinePix F402
111finepix 04cb:011d Fujifilm FinePix F410
112finepix 04cb:0121 Fujifilm FinePix F601
113finepix 04cb:0123 Fujifilm FinePix F700
114finepix 04cb:0125 Fujifilm FinePix M603
115finepix 04cb:0127 Fujifilm FinePix S300
116finepix 04cb:0129 Fujifilm FinePix S304
117finepix 04cb:012b Fujifilm FinePix S500
118finepix 04cb:012d Fujifilm FinePix S602
119finepix 04cb:012f Fujifilm FinePix S700
120finepix 04cb:0131 Fujifilm FinePix unknown model
121finepix 04cb:013b Fujifilm FinePix unknown model
122finepix 04cb:013d Fujifilm FinePix unknown model
123finepix 04cb:013f Fujifilm FinePix F420
99sunplus 04f1:1001 JVC GC A50 124sunplus 04f1:1001 JVC GC A50
100spca561 04fc:0561 Flexcam 100 125spca561 04fc:0561 Flexcam 100
101sunplus 04fc:500c Sunplus CA500C 126sunplus 04fc:500c Sunplus CA500C
@@ -181,6 +206,7 @@ pac207 093a:2468 PAC207
181pac207 093a:2470 Genius GF112 206pac207 093a:2470 Genius GF112
182pac207 093a:2471 Genius VideoCam ge111 207pac207 093a:2471 Genius VideoCam ge111
183pac207 093a:2472 Genius VideoCam ge110 208pac207 093a:2472 Genius VideoCam ge110
209pac207 093a:2476 Genius e-Messenger 112
184pac7311 093a:2600 PAC7311 Typhoon 210pac7311 093a:2600 PAC7311 Typhoon
185pac7311 093a:2601 Philips SPC 610 NC 211pac7311 093a:2601 Philips SPC 610 NC
186pac7311 093a:2603 PAC7312 212pac7311 093a:2603 PAC7312
diff --git a/Documentation/video4linux/m5602.txt b/Documentation/video4linux/m5602.txt
new file mode 100644
index 000000000000..4450ab13f37b
--- /dev/null
+++ b/Documentation/video4linux/m5602.txt
@@ -0,0 +1,12 @@
1This document describes the ALi m5602 bridge connected
2to the following supported sensors:
3OmniVision OV9650,
4Samsung s5k83a,
5Samsung s5k4aa,
6Micron mt9m111,
7Pixel plus PO1030
8
9This driver mimics the windows drivers, which have a braindead implementation sending bayer-encoded frames at VGA resolution.
10In a perfect world we should be able to reprogram the m5602 and the connected sensor in hardware instead, supporting a range of resolutions and pixelformats
11
12Anyway, have fun and please report any bugs to m560x-driver-devel@lists.sourceforge.net
diff --git a/Documentation/video4linux/soc-camera.txt b/Documentation/video4linux/soc-camera.txt
new file mode 100644
index 000000000000..178ef3c5e579
--- /dev/null
+++ b/Documentation/video4linux/soc-camera.txt
@@ -0,0 +1,120 @@
1 Soc-Camera Subsystem
2 ====================
3
4Terminology
5-----------
6
7The following terms are used in this document:
8 - camera / camera device / camera sensor - a video-camera sensor chip, capable
9 of connecting to a variety of systems and interfaces, typically uses i2c for
10 control and configuration, and a parallel or a serial bus for data.
11 - camera host - an interface, to which a camera is connected. Typically a
12 specialised interface, present on many SoCs, e.g., PXA27x and PXA3xx, SuperH,
13 AVR32, i.MX27, i.MX31.
14 - camera host bus - a connection between a camera host and a camera. Can be
15 parallel or serial, consists of data and control lines, e.g., clock, vertical
16 and horizontal synchronization signals.
17
18Purpose of the soc-camera subsystem
19-----------------------------------
20
21The soc-camera subsystem provides a unified API between camera host drivers and
22camera sensor drivers. It implements a V4L2 interface to the user, currently
23only the mmap method is supported.
24
25This subsystem has been written to connect drivers for System-on-Chip (SoC)
26video capture interfaces with drivers for CMOS camera sensor chips to enable
27the reuse of sensor drivers with various hosts. The subsystem has been designed
28to support multiple camera host interfaces and multiple cameras per interface,
29although most applications have only one camera sensor.
30
31Existing drivers
32----------------
33
34As of 2.6.27-rc4 there are two host drivers in the mainline: pxa_camera.c for
35PXA27x SoCs and sh_mobile_ceu_camera.c for SuperH SoCs, and four sensor drivers:
36mt9m001.c, mt9m111.c, mt9v022.c and a generic soc_camera_platform.c driver. This
37list is not supposed to be updated, look for more examples in your tree.
38
39Camera host API
40---------------
41
42A host camera driver is registered using the
43
44soc_camera_host_register(struct soc_camera_host *);
45
46function. The host object can be initialized as follows:
47
48static struct soc_camera_host pxa_soc_camera_host = {
49 .drv_name = PXA_CAM_DRV_NAME,
50 .ops = &pxa_soc_camera_host_ops,
51};
52
53All camera host methods are passed in a struct soc_camera_host_ops:
54
55static struct soc_camera_host_ops pxa_soc_camera_host_ops = {
56 .owner = THIS_MODULE,
57 .add = pxa_camera_add_device,
58 .remove = pxa_camera_remove_device,
59 .suspend = pxa_camera_suspend,
60 .resume = pxa_camera_resume,
61 .set_fmt_cap = pxa_camera_set_fmt_cap,
62 .try_fmt_cap = pxa_camera_try_fmt_cap,
63 .init_videobuf = pxa_camera_init_videobuf,
64 .reqbufs = pxa_camera_reqbufs,
65 .poll = pxa_camera_poll,
66 .querycap = pxa_camera_querycap,
67 .try_bus_param = pxa_camera_try_bus_param,
68 .set_bus_param = pxa_camera_set_bus_param,
69};
70
71.add and .remove methods are called when a sensor is attached to or detached
72from the host, apart from performing host-internal tasks they shall also call
73sensor driver's .init and .release methods respectively. .suspend and .resume
74methods implement host's power-management functionality and its their
75responsibility to call respective sensor's methods. .try_bus_param and
76.set_bus_param are used to negotiate physical connection parameters between the
77host and the sensor. .init_videobuf is called by soc-camera core when a
78video-device is opened, further video-buffer management is implemented completely
79by the specific camera host driver. The rest of the methods are called from
80respective V4L2 operations.
81
82Camera API
83----------
84
85Sensor drivers can use struct soc_camera_link, typically provided by the
86platform, and used to specify to which camera host bus the sensor is connected,
87and arbitrarily provide platform .power and .reset methods for the camera.
88soc_camera_device_register() and soc_camera_device_unregister() functions are
89used to add a sensor driver to or remove one from the system. The registration
90function takes a pointer to struct soc_camera_device as the only parameter.
91This struct can be initialized as follows:
92
93 /* link to driver operations */
94 icd->ops = &mt9m001_ops;
95 /* link to the underlying physical (e.g., i2c) device */
96 icd->control = &client->dev;
97 /* window geometry */
98 icd->x_min = 20;
99 icd->y_min = 12;
100 icd->x_current = 20;
101 icd->y_current = 12;
102 icd->width_min = 48;
103 icd->width_max = 1280;
104 icd->height_min = 32;
105 icd->height_max = 1024;
106 icd->y_skip_top = 1;
107 /* camera bus ID, typically obtained from platform data */
108 icd->iface = icl->bus_id;
109
110struct soc_camera_ops provides .probe and .remove methods, which are called by
111the soc-camera core, when a camera is matched against or removed from a camera
112host bus, .init, .release, .suspend, and .resume are called from the camera host
113driver as discussed above. Other members of this struct provide respective V4L2
114functionality.
115
116struct soc_camera_device also links to an array of struct soc_camera_data_format,
117listing pixel formats, supported by the camera.
118
119--
120Author: Guennadi Liakhovetski <g.liakhovetski@gmx.de>
diff --git a/Documentation/w1/00-INDEX b/Documentation/w1/00-INDEX
index 5270cf4cb109..cb49802745dc 100644
--- a/Documentation/w1/00-INDEX
+++ b/Documentation/w1/00-INDEX
@@ -1,5 +1,7 @@
100-INDEX 100-INDEX
2 - This file 2 - This file
3slaves/
4 - Drivers that provide support for specific family codes.
3masters/ 5masters/
4 - Individual chips providing 1-wire busses. 6 - Individual chips providing 1-wire busses.
5w1.generic 7w1.generic
diff --git a/Documentation/w1/masters/ds2490 b/Documentation/w1/masters/ds2490
index 239f9ae01843..28176def3d6f 100644
--- a/Documentation/w1/masters/ds2490
+++ b/Documentation/w1/masters/ds2490
@@ -16,3 +16,55 @@ which allows to build USB <-> W1 bridges.
16DS9490(R) is a USB <-> W1 bus master device 16DS9490(R) is a USB <-> W1 bus master device
17which has 0x81 family ID integrated chip and DS2490 17which has 0x81 family ID integrated chip and DS2490
18low-level operational chip. 18low-level operational chip.
19
20Notes and limitations.
21- The weak pullup current is a minimum of 0.9mA and maximum of 6.0mA.
22- The 5V strong pullup is supported with a minimum of 5.9mA and a
23 maximum of 30.4 mA. (From DS2490.pdf)
24- While the ds2490 supports a hardware search the code doesn't take
25 advantage of it (in tested case it only returned first device).
26- The hardware will detect when devices are attached to the bus on the
27 next bus (reset?) operation, however only a message is printed as
28 the core w1 code doesn't make use of the information. Connecting
29 one device tends to give multiple new device notifications.
30- The number of USB bus transactions could be reduced if w1_reset_send
31 was added to the API. The name is just a suggestion. It would take
32 a write buffer and a read buffer (along with sizes) as arguments.
33 The ds2490 block I/O command supports reset, write buffer, read
34 buffer, and strong pullup all in one command, instead of the current
35 1 reset bus, 2 write the match rom command and slave rom id, 3 block
36 write and read data. The write buffer needs to have the match rom
37 command and slave rom id prepended to the front of the requested
38 write buffer, both of which are known to the driver.
39- The hardware supports normal, flexible, and overdrive bus
40 communication speeds, but only the normal is supported.
41- The registered w1_bus_master functions don't define error
42 conditions. If a bus search is in progress and the ds2490 is
43 removed it can produce a good amount of error output before the bus
44 search finishes.
45- The hardware supports detecting some error conditions, such as
46 short, alarming presence on reset, and no presence on reset, but the
47 driver doesn't query those values.
48- The ds2490 specification doesn't cover short bulk in reads in
49 detail, but my observation is if fewer bytes are requested than are
50 available, the bulk read will return an error and the hardware will
51 clear the entire bulk in buffer. It would be possible to read the
52 maximum buffer size to not run into this error condition, only extra
53 bytes in the buffer is a logic error in the driver. The code should
54 should match reads and writes as well as data sizes. Reads and
55 writes are serialized and the status verifies that the chip is idle
56 (and data is available) before the read is executed, so it should
57 not happen.
58- Running x86_64 2.6.24 UHCI under qemu 0.9.0 under x86_64 2.6.22-rc6
59 with a OHCI controller, ds2490 running in the guest would operate
60 normally the first time the module was loaded after qemu attached
61 the ds2490 hardware, but if the module was unloaded, then reloaded
62 most of the time one of the bulk out or in, and usually the bulk in
63 would fail. qemu sets a 50ms timeout and the bulk in would timeout
64 even when the status shows data available. A bulk out write would
65 show a successful completion, but the ds2490 status register would
66 show 0 bytes written. Detaching qemu from the ds2490 hardware and
67 reattaching would clear the problem. usbmon output in the guest and
68 host did not explain the problem. My guess is a bug in either qemu
69 or the host OS and more likely the host OS.
70-- 03-06-2008 David Fries <David@Fries.net>
diff --git a/Documentation/w1/slaves/00-INDEX b/Documentation/w1/slaves/00-INDEX
new file mode 100644
index 000000000000..f8101d6b07b7
--- /dev/null
+++ b/Documentation/w1/slaves/00-INDEX
@@ -0,0 +1,4 @@
100-INDEX
2 - This file
3w1_therm
4 - The Maxim/Dallas Semiconductor ds18*20 temperature sensor.
diff --git a/Documentation/w1/slaves/w1_therm b/Documentation/w1/slaves/w1_therm
new file mode 100644
index 000000000000..0403aaaba878
--- /dev/null
+++ b/Documentation/w1/slaves/w1_therm
@@ -0,0 +1,41 @@
1Kernel driver w1_therm
2====================
3
4Supported chips:
5 * Maxim ds18*20 based temperature sensors.
6
7Author: Evgeniy Polyakov <johnpol@2ka.mipt.ru>
8
9
10Description
11-----------
12
13w1_therm provides basic temperature conversion for ds18*20 devices.
14supported family codes:
15W1_THERM_DS18S20 0x10
16W1_THERM_DS1822 0x22
17W1_THERM_DS18B20 0x28
18
19Support is provided through the sysfs w1_slave file. Each open and
20read sequence will initiate a temperature conversion then provide two
21lines of ASCII output. The first line contains the nine hex bytes
22read along with a calculated crc value and YES or NO if it matched.
23If the crc matched the returned values are retained. The second line
24displays the retained values along with a temperature in millidegrees
25Centigrade after t=.
26
27Parasite powered devices are limited to one slave performing a
28temperature conversion at a time. If none of the devices are parasite
29powered it would be possible to convert all the devices at the same
30time and then go back to read individual sensors. That isn't
31currently supported. The driver also doesn't support reduced
32precision (which would also reduce the conversion time).
33
34The module parameter strong_pullup can be set to 0 to disable the
35strong pullup or 1 to enable. If enabled the 5V strong pullup will be
36enabled when the conversion is taking place provided the master driver
37must support the strong pullup (or it falls back to a pullup
38resistor). The DS18b20 temperature sensor specification lists a
39maximum current draw of 1.5mA and that a 5k pullup resistor is not
40sufficient. The strong pullup is designed to provide the additional
41current required.
diff --git a/Documentation/w1/w1.generic b/Documentation/w1/w1.generic
index 4c6509dd4789..e3333eec4320 100644
--- a/Documentation/w1/w1.generic
+++ b/Documentation/w1/w1.generic
@@ -79,10 +79,13 @@ w1 master sysfs interface
79<xx-xxxxxxxxxxxxx> - a directory for a found device. The format is family-serial 79<xx-xxxxxxxxxxxxx> - a directory for a found device. The format is family-serial
80bus - (standard) symlink to the w1 bus 80bus - (standard) symlink to the w1 bus
81driver - (standard) symlink to the w1 driver 81driver - (standard) symlink to the w1 driver
82w1_master_add - Manually register a slave device
82w1_master_attempts - the number of times a search was attempted 83w1_master_attempts - the number of times a search was attempted
83w1_master_max_slave_count 84w1_master_max_slave_count
84 - the maximum slaves that may be attached to a master 85 - the maximum slaves that may be attached to a master
85w1_master_name - the name of the device (w1_bus_masterX) 86w1_master_name - the name of the device (w1_bus_masterX)
87w1_master_pullup - 5V strong pullup 0 enabled, 1 disabled
88w1_master_remove - Manually remove a slave device
86w1_master_search - the number of searches left to do, -1=continual (default) 89w1_master_search - the number of searches left to do, -1=continual (default)
87w1_master_slave_count 90w1_master_slave_count
88 - the number of slaves found 91 - the number of slaves found
@@ -90,7 +93,13 @@ w1_master_slaves - the names of the slaves, one per line
90w1_master_timeout - the delay in seconds between searches 93w1_master_timeout - the delay in seconds between searches
91 94
92If you have a w1 bus that never changes (you don't add or remove devices), 95If you have a w1 bus that never changes (you don't add or remove devices),
93you can set w1_master_search to a positive value to disable searches. 96you can set the module parameter search_count to a small positive number
97for an initially small number of bus searches. Alternatively it could be
98set to zero, then manually add the slave device serial numbers by
99w1_master_add device file. The w1_master_add and w1_master_remove files
100generally only make sense when searching is disabled, as a search will
101redetect manually removed devices that are present and timeout manually
102added devices that aren't on the bus.
94 103
95 104
96w1 slave sysfs interface 105w1 slave sysfs interface
diff --git a/Documentation/x86/00-INDEX b/Documentation/x86/00-INDEX
new file mode 100644
index 000000000000..dbe3377754af
--- /dev/null
+++ b/Documentation/x86/00-INDEX
@@ -0,0 +1,4 @@
100-INDEX
2 - this file
3mtrr.txt
4 - how to use x86 Memory Type Range Registers to increase performance
diff --git a/Documentation/x86/i386/boot.txt b/Documentation/x86/boot.txt
index 147bfe511cdd..83c0033ee9e0 100644
--- a/Documentation/x86/i386/boot.txt
+++ b/Documentation/x86/boot.txt
@@ -308,7 +308,7 @@ Protocol: 2.00+
308 308
309Field name: start_sys 309Field name: start_sys
310Type: read 310Type: read
311Offset/size: 0x20c/4 311Offset/size: 0x20c/2
312Protocol: 2.00+ 312Protocol: 2.00+
313 313
314 The load low segment (0x1000). Obsolete. 314 The load low segment (0x1000). Obsolete.
diff --git a/Documentation/mtrr.txt b/Documentation/x86/mtrr.txt
index c39ac395970e..cc071dc333c2 100644
--- a/Documentation/mtrr.txt
+++ b/Documentation/x86/mtrr.txt
@@ -18,7 +18,7 @@ Richard Gooch
18 The AMD K6-2 (stepping 8 and above) and K6-3 processors have two 18 The AMD K6-2 (stepping 8 and above) and K6-3 processors have two
19 MTRRs. These are supported. The AMD Athlon family provide 8 Intel 19 MTRRs. These are supported. The AMD Athlon family provide 8 Intel
20 style MTRRs. 20 style MTRRs.
21 21
22 The Centaur C6 (WinChip) has 8 MCRs, allowing write-combining. These 22 The Centaur C6 (WinChip) has 8 MCRs, allowing write-combining. These
23 are supported. 23 are supported.
24 24
@@ -87,7 +87,7 @@ reg00: base=0x00000000 ( 0MB), size= 64MB: write-back, count=1
87reg01: base=0xfb000000 (4016MB), size= 16MB: write-combining, count=1 87reg01: base=0xfb000000 (4016MB), size= 16MB: write-combining, count=1
88reg02: base=0xfb000000 (4016MB), size= 4kB: uncachable, count=1 88reg02: base=0xfb000000 (4016MB), size= 4kB: uncachable, count=1
89 89
90Some cards (especially Voodoo Graphics boards) need this 4 kB area 90Some cards (especially Voodoo Graphics boards) need this 4 kB area
91excluded from the beginning of the region because it is used for 91excluded from the beginning of the region because it is used for
92registers. 92registers.
93 93
diff --git a/Documentation/x86/pat.txt b/Documentation/x86/pat.txt
index 17965f927c15..c93ff5f4c0dd 100644
--- a/Documentation/x86/pat.txt
+++ b/Documentation/x86/pat.txt
@@ -14,6 +14,10 @@ PAT allows for different types of memory attributes. The most commonly used
14ones that will be supported at this time are Write-back, Uncached, 14ones that will be supported at this time are Write-back, Uncached,
15Write-combined and Uncached Minus. 15Write-combined and Uncached Minus.
16 16
17
18PAT APIs
19--------
20
17There are many different APIs in the kernel that allows setting of memory 21There are many different APIs in the kernel that allows setting of memory
18attributes at the page level. In order to avoid aliasing, these interfaces 22attributes at the page level. In order to avoid aliasing, these interfaces
19should be used thoughtfully. Below is a table of interfaces available, 23should be used thoughtfully. Below is a table of interfaces available,
@@ -26,38 +30,38 @@ address range to avoid any aliasing.
26API | RAM | ACPI,... | Reserved/Holes | 30API | RAM | ACPI,... | Reserved/Holes |
27-----------------------|----------|------------|------------------| 31-----------------------|----------|------------|------------------|
28 | | | | 32 | | | |
29ioremap | -- | UC | UC | 33ioremap | -- | UC- | UC- |
30 | | | | 34 | | | |
31ioremap_cache | -- | WB | WB | 35ioremap_cache | -- | WB | WB |
32 | | | | 36 | | | |
33ioremap_nocache | -- | UC | UC | 37ioremap_nocache | -- | UC- | UC- |
34 | | | | 38 | | | |
35ioremap_wc | -- | -- | WC | 39ioremap_wc | -- | -- | WC |
36 | | | | 40 | | | |
37set_memory_uc | UC | -- | -- | 41set_memory_uc | UC- | -- | -- |
38 set_memory_wb | | | | 42 set_memory_wb | | | |
39 | | | | 43 | | | |
40set_memory_wc | WC | -- | -- | 44set_memory_wc | WC | -- | -- |
41 set_memory_wb | | | | 45 set_memory_wb | | | |
42 | | | | 46 | | | |
43pci sysfs resource | -- | -- | UC | 47pci sysfs resource | -- | -- | UC- |
44 | | | | 48 | | | |
45pci sysfs resource_wc | -- | -- | WC | 49pci sysfs resource_wc | -- | -- | WC |
46 is IORESOURCE_PREFETCH| | | | 50 is IORESOURCE_PREFETCH| | | |
47 | | | | 51 | | | |
48pci proc | -- | -- | UC | 52pci proc | -- | -- | UC- |
49 !PCIIOC_WRITE_COMBINE | | | | 53 !PCIIOC_WRITE_COMBINE | | | |
50 | | | | 54 | | | |
51pci proc | -- | -- | WC | 55pci proc | -- | -- | WC |
52 PCIIOC_WRITE_COMBINE | | | | 56 PCIIOC_WRITE_COMBINE | | | |
53 | | | | 57 | | | |
54/dev/mem | -- | UC | UC | 58/dev/mem | -- | WB/WC/UC- | WB/WC/UC- |
55 read-write | | | | 59 read-write | | | |
56 | | | | 60 | | | |
57/dev/mem | -- | UC | UC | 61/dev/mem | -- | UC- | UC- |
58 mmap SYNC flag | | | | 62 mmap SYNC flag | | | |
59 | | | | 63 | | | |
60/dev/mem | -- | WB/WC/UC | WB/WC/UC | 64/dev/mem | -- | WB/WC/UC- | WB/WC/UC- |
61 mmap !SYNC flag | |(from exist-| (from exist- | 65 mmap !SYNC flag | |(from exist-| (from exist- |
62 and | | ing alias)| ing alias) | 66 and | | ing alias)| ing alias) |
63 any alias to this area| | | | 67 any alias to this area| | | |
@@ -68,7 +72,7 @@ pci proc | -- | -- | WC |
68 and | | | | 72 and | | | |
69 MTRR says WB | | | | 73 MTRR says WB | | | |
70 | | | | 74 | | | |
71/dev/mem | -- | -- | UC_MINUS | 75/dev/mem | -- | -- | UC- |
72 mmap !SYNC flag | | | | 76 mmap !SYNC flag | | | |
73 no alias to this area | | | | 77 no alias to this area | | | |
74 and | | | | 78 and | | | |
@@ -98,3 +102,35 @@ types.
98 102
99Drivers should use set_memory_[uc|wc] to set access type for RAM ranges. 103Drivers should use set_memory_[uc|wc] to set access type for RAM ranges.
100 104
105
106PAT debugging
107-------------
108
109With CONFIG_DEBUG_FS enabled, PAT memtype list can be examined by
110
111# mount -t debugfs debugfs /sys/kernel/debug
112# cat /sys/kernel/debug/x86/pat_memtype_list
113PAT memtype list:
114uncached-minus @ 0x7fadf000-0x7fae0000
115uncached-minus @ 0x7fb19000-0x7fb1a000
116uncached-minus @ 0x7fb1a000-0x7fb1b000
117uncached-minus @ 0x7fb1b000-0x7fb1c000
118uncached-minus @ 0x7fb1c000-0x7fb1d000
119uncached-minus @ 0x7fb1d000-0x7fb1e000
120uncached-minus @ 0x7fb1e000-0x7fb25000
121uncached-minus @ 0x7fb25000-0x7fb26000
122uncached-minus @ 0x7fb26000-0x7fb27000
123uncached-minus @ 0x7fb27000-0x7fb28000
124uncached-minus @ 0x7fb28000-0x7fb2e000
125uncached-minus @ 0x7fb2e000-0x7fb2f000
126uncached-minus @ 0x7fb2f000-0x7fb30000
127uncached-minus @ 0x7fb31000-0x7fb32000
128uncached-minus @ 0x80000000-0x90000000
129
130This list shows physical address ranges and various PAT settings used to
131access those physical address ranges.
132
133Another, more verbose way of getting PAT related debug messages is with
134"debugpat" boot parameter. With this parameter, various debug messages are
135printed to dmesg log.
136
diff --git a/Documentation/x86/i386/usb-legacy-support.txt b/Documentation/x86/usb-legacy-support.txt
index 1894cdfc69d9..1894cdfc69d9 100644
--- a/Documentation/x86/i386/usb-legacy-support.txt
+++ b/Documentation/x86/usb-legacy-support.txt
diff --git a/Documentation/x86/x86_64/boot-options.txt b/Documentation/x86/x86_64/boot-options.txt
index b0c7b6c4abda..72ffb5373ec7 100644
--- a/Documentation/x86/x86_64/boot-options.txt
+++ b/Documentation/x86/x86_64/boot-options.txt
@@ -54,10 +54,6 @@ APICs
54 apicmaintimer. Useful when your PIT timer is totally 54 apicmaintimer. Useful when your PIT timer is totally
55 broken. 55 broken.
56 56
57 disable_8254_timer / enable_8254_timer
58 Enable interrupt 0 timer routing over the 8254 in addition to over
59 the IO-APIC. The kernel tries to set a sensible default.
60
61Early Console 57Early Console
62 58
63 syntax: earlyprintk=vga 59 syntax: earlyprintk=vga
diff --git a/Documentation/x86/i386/zero-page.txt b/Documentation/x86/zero-page.txt
index 169ad423a3d1..169ad423a3d1 100644
--- a/Documentation/x86/i386/zero-page.txt
+++ b/Documentation/x86/zero-page.txt